MCP 工具介绍及编写指南

一、什么是 MCP？

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

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

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

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

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

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

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

工具名称：明确 AI 调用该工具时使用的标识
工具描述：清晰说明工具的功能，让 AI 理解其用途
入参定义：规定 AI 调用工具时，需要传递的参数信息
执行逻辑：工具实现具体功能的核心代码

四、MCP 编写模板（TS 版）

TypeScript 复制代码

// 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

TypeScript 复制代码

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() 异步函数
返回值只能是对象或字符串，不可返回其他类型
函数内部需做好异常处理，禁止出现报错，确保工具稳定运行