MCP 工具介绍及编写指南

一、什么是 MCP？

MCP 即 Model Context Protocol（模型上下文协议），是给 AI 提供的标准化工具接口。通过这个接口，AI 可以实现多种操作，比如读取文件、查询数据库、执行命令、调用接口以及访问各类服务。

二、MCP 适合用什么语言编写？

官方首选语言是 TypeScript（简称 TS/JS），上手便捷、适配性最佳。

Java 也可编写，但代码结构复杂、体量较重，不推荐新手使用。

Python 同样支持编写，但在 Windsurf 生态的适配性上，不如 TS 完善。

三、MCP 工具的固定编写结构

无论是什么功能的 MCP 工具，核心都只有 4 个部分，缺一不可：

1. 工具名称：明确 AI 调用该工具时使用的标识

2. 工具描述：清晰说明工具的功能，让 AI 理解其用途

3. 入参定义：规定 AI 调用工具时，需要传递的参数信息

4. 执行逻辑：工具实现具体功能的核心代码

四、MCP 编写模板（TS 版）

// 1. 定义 MCP 工具 mcp.tool({ // ====================== // 2. 工具基本信息 // ====================== name: "my_first_tool", // 工具名（英文小写，下划线） description: "我的第一个MCP工具", // 给AI看的说明 // ====================== // 3. 入参（AI 必须传的参数） // ====================== parameters: { name: { type: "string", description: "用户名称", required: true }, age: { type: "number", description: "年龄" } }, // ====================== // 4. 执行逻辑（真正干活） // ====================== async execute({ name, age }) { // 这里写业务代码 return `你好 ${name}，你的年龄是 ${age}`; } });

五、实际案例：读取 Java 文件的 MCP

mcp.tool({ name: "read_java_file", description: "读取项目中的Java文件", parameters: { filePath: { type: "string", description: "Java文件路径", required: true } }, async execute({ filePath }) { // 真实代码：读取文件 const content = fs.readFileSync(filePath, "utf-8"); return { path: filePath, content: content }; } });

六、MCP 编写规则

编写 MCP 工具需严格遵循以下规则，确保 AI 能正常调用、工具稳定运行：

1. 工具名规范

必须满足以下三点，缺一不可：

• 全部为小写字母

• 单词之间用下划线连接

• 禁止包含空格、中文及特殊字符

示例：

正确：read_java_file

错误：ReadJavaFile（大小写混合）

错误：读取文件（包含中文）

2. 参数类型规范

参数必须明确标注类型，常用类型如下：

• string：字符串类型

• number：数字类型

• boolean：布尔类型（true/false）

• array：数组类型

3. 执行函数规范

执行逻辑的函数必须满足：

• 必须定义为 async execute() 异步函数

• 返回值只能是对象或字符串，不可返回其他类型

• 函数内部需做好异常处理，禁止出现报错，确保工具稳定运行