Octocode 插件开发指南：构建自定义 MCP 工具的完整流程

【免费下载链接】octocodeCode research platform for AI agents; find, understand, and prove context across your code and all of GitHub, in a fraction of the tokens. One toolset, MCP or CLI项目地址: https://gitcode.com/gh_mirrors/oc/octocode

Octocode 是一款强大的代码研究平台，专为 AI 代理设计，能够帮助开发者快速查找、理解和验证代码上下文。本指南将带你逐步完成自定义 MCP 工具的开发流程，从环境搭建到工具发布，让你轻松扩展 Octocode 的功能。

准备工作：环境搭建与项目结构

在开始开发自定义 MCP 工具之前，需要先搭建好开发环境并了解项目结构。首先，克隆 Octocode 仓库到本地：

git clone https://gitcode.com/gh_mirrors/oc/octocode

Octocode 采用 monorepo 结构，核心代码位于packages目录下。与 MCP 工具开发相关的主要目录包括：

• packages/octocode-mcp：MCP 服务器核心代码
• packages/octocode-tools-core：工具核心实现
• packages/octocode-engine：原生搜索、安全等基础功能

Octocode 架构概览，展示了 MCP 工具与其他模块的关系

第一步：了解 MCP 工具基础

MCP（Modular Code Platform）工具是 Octocode 的核心组件，用于实现各种代码研究功能。在开发自定义工具前，建议先熟悉现有工具的实现方式。官方工具文档位于 docs/OCTOCODE_TOOLS.md，其中详细介绍了工具的分类、参数和使用方法。

Octocode 的 MCP 工具主要分为以下几类：

• GitHub 工具：如ghSearchCode、ghGetFileContent等
• 本地代码工具：如localSearchCode、localViewStructure等
• LSP 工具：如lspGetSemantics

每个工具都有定义好的输入输出 schema，位于对应工具的scheme.ts文件中。例如，GitHub 搜索工具的 schema 位于 packages/octocode-tools-core/src/tools/github_search_code/scheme.ts。

第二步：创建工具定义与 Schema

开发自定义 MCP 工具的第一步是创建工具定义和 schema。schema 用于验证工具的输入输出，确保数据格式正确。

1. 在packages/octocode-tools-core/src/tools目录下创建新的工具目录，例如my_custom_tool。
2. 在该目录下创建scheme.ts文件，定义工具的输入输出 schema。

schema 定义示例：

import { z } from 'zod'; export const MyCustomToolInputSchema = z.object({ query: z.string().describe('搜索查询字符串'), limit: z.number().int().min(1).max(100).default(20).describe('返回结果数量限制') }); export const MyCustomToolOutputSchema = z.object({ results: z.array(z.object({ id: z.string(), content: z.string(), score: z.number() })) });

3. 创建工具实现文件index.ts，实现工具的核心逻辑。

第三步：实现工具逻辑

工具逻辑是自定义 MCP 工具的核心，负责处理输入并生成输出。以下是一个简单的工具实现示例：

import { Tool } from '@octocodeai/octocode-tools-core'; import { MyCustomToolInputSchema, MyCustomToolOutputSchema } from './scheme'; export const myCustomTool: Tool = { name: 'myCustomTool', description: '我的自定义 MCP 工具', inputSchema: MyCustomToolInputSchema, outputSchema: MyCustomToolOutputSchema, async execute(input, context) { // 实现工具逻辑 const results = await fetchData(input.query, input.limit); return { results: results.map(item => ({ id: item.id, content: item.content, score: item.score })) }; } };

在实现工具逻辑时，可以利用 Octocode 提供的各种工具和服务，例如：

• 文件系统操作：packages/octocode/src/utils/fs.ts
• 安全相关功能：packages/octocode-engine/src/security/
• 日志工具：packages/octocode/src/utils/context.ts

第四步：注册工具与测试

完成工具实现后，需要将其注册到 Octocode 系统中，并进行测试。

1. 在packages/octocode-tools-core/src/tools/toolConfig.ts文件中注册新工具：

import { myCustomTool } from './my_custom_tool'; export const ALL_TOOLS = [ // ... 其他工具 myCustomTool ];

2. 编写测试用例，位于packages/octocode-mcp/tests/tools/目录下。

测试示例：

import { test } from 'vitest'; import { executeTool } from '@octocodeai/octocode-mcp'; test('myCustomTool 应该返回正确结果', async () => { const result = await executeTool('myCustomTool', { query: 'test', limit: 10 }); expect(result.results).toBeInstanceOf(Array); expect(result.results.length).toBeLessThanOrEqual(10); });

3. 运行测试：

yarn test packages/octocode-mcp/tests/tools/my-custom-tool.test.ts

第五步：工具验证与优化

为确保工具质量，需要进行全面的验证。Octocode 提供了工具验证指南，位于 docs/OCTOCODE_TOOLS.md#tool-verification-playbook。主要验证点包括：

• 注册验证：工具是否正确注册到系统中
• 输入输出验证：是否符合 schema 定义
• 错误处理：是否能正确处理各种错误情况
• 性能验证：工具执行效率是否满足要求

Octocode MCP 工具请求流程示意图

根据验证结果，对工具进行优化，例如：

• 优化查询逻辑，提高执行效率
• 完善错误处理，提供更友好的错误提示
• 增加缓存机制，减少重复计算

发布与分享：贡献自定义工具

完成自定义工具开发后，可以通过以下方式分享你的成果：

1. 提交 Pull Request 到 Octocode 主仓库
2. 在skills/目录下创建工具文档，参考现有技能文档格式
3. 参与社区讨论，获取反馈并持续改进

Octocode 社区欢迎各种创新工具，你的贡献可能会帮助到许多开发者！

总结与下一步

通过本指南，你已经了解了开发 Octocode 自定义 MCP 工具的完整流程。从环境搭建到工具发布，每个步骤都至关重要。建议进一步深入学习以下内容：

• MCP 工具质量与代理工作流
• Octocode 引擎文档
• LSP 服务器生命周期

现在，开始动手开发你的第一个自定义 MCP 工具吧！如有任何问题，欢迎在社区中提问。

【免费下载链接】octocodeCode research platform for AI agents; find, understand, and prove context across your code and all of GitHub, in a fraction of the tokens. One toolset, MCP or CLI项目地址: https://gitcode.com/gh_mirrors/oc/octocode