一、什么是 MCP?
MCP 全称 Model Context Protocol（模型上下文协议） ，是一套面向 AI 大模型的标准化外部能力调用协议。
我们可以简单理解：AI 大模型本身是「纯逻辑、纯文本的大脑」，天生不具备操作系统读写、数据库查询、网络请求、本地文件操作等外部能力。
而 MCP 的核心作用：统一 AI 与本地环境、第三方服务的通信标准，为大模型提供可扩展的外部工具能力，打通 AI 和本地项目、系统资源、远程接口的壁垒。
在没有 MCP 之前：不同编辑器、不同 AI 客户端、不同工具的调用规则各不相同，适配繁琐、兼容性差、无法通用。
有了 MCP 之后：一次编写，全生态通用，所有兼容 MCP 协议的 AI 客户端（Cursor、IDE AI 插件等）均可自动识别、智能调用自定义工具。
常见可拓展能力全覆盖：
- 本地操作：读取/写入项目文件、遍历目录、执行本地终端命令
- 数据操作：查询本地/远程数据库、解析配置文件
- 网络能力：调用第三方业务接口、接口调试、数据同步
- 工程能力：代码解析、文件格式化、项目结构扫描
二、MCP 适合用什么语言编写？
MCP 属于跨语言协议，主流编程语言均支持，但不同语言的生态适配、开发成本、运行性能、IDE 兼容性差距极大，是开发选型核心依据。
1. TypeScript（TS/JS）—— 官方首选、全能推荐
是 MCP 官方标准开发语言，也是工业级主流选型。
- 优势：语法轻量化、样板代码极少、异步语法优雅、适配所有 MCP 生态（尤其是 Windsurf）
- 特点：无需复杂环境配置，专注工具业务逻辑，开发效率最高
- 适用人群：新手、所有 MCP 日常开发、通用工具封装
2. Python —— 兼容可用，适配一般
- 优势：语法简单，适合数据处理、脚本类 MCP 工具
- 劣势：在 Windsurf 核心生态适配不完善，部分高阶协议特性不兼容，容易出现调用失败、识别异常
- 适用场景：仅用于纯数据处理、脚本自动化工具，不推荐通用业务工具
3. Java —— 兼容但极不推荐
- 劣势：面向对象语法繁琐、模板代码量大、启动速度慢、协议封装厚重
- 问题：开发成本极高，且无生态优势，完全违背 MCP「轻量化拓展 AI 能力」的设计初衷
- 适用场景：仅老旧 Java 项目内嵌工具，不作为首选
总结选型原则：通用场景首选 TS；数据脚本可选 Python；Java 非必要绝不使用。
三、MCP 工具固定核心结构
所有 MCP 自定义工具，无论功能复杂与否，强制由 4 个核心模块组成，缺一不可，这是协议硬性规范，缺失任意模块会导致 AI 无法识别、工具调用报错。
- 工具声明：通过
mcp.tool()注册当前自定义工具，告知 AI 客户端「这是一个可调用的 MCP 工具」 - 工具元信息：包含工具名称、描述，用于 AI 智能决策是否调用当前工具（AI 唯一识别依据）
- 参数模型（parameters） ：定义工具入参结构、类型、描述、是否必填，相当于工具的入参校验规则，约束 AI 传参格式
- 执行逻辑（execute） ：工具核心业务逻辑，异步函数，承载所有真实功能，处理参数、执行业务、返回结果
核心底层逻辑：元信息负责让 AI「看懂工具」，参数模型负责让 AI「传对参数」，execute 负责「真正干活」。
四、MCP 标准编写模板
// 1. 全局注册、定义一个全新的 MCP 工具
mcp.tool({
// ======================
// 2. 工具元信息（AI 识别入口，至关重要）
// ======================
// 唯一工具标识，全局不可重复，协议强制规范
name: "my_first_tool",
// 工具功能描述：精准描述工具用途、使用场景
// 注意：描述越精准，AI 调用准确率越高
description: "我的第一个MCP工具，用于接收用户姓名和年龄并返回格式化问候信息",
// ======================
// 3. 入参模型（结构化参数校验层）
// ======================
parameters: {
// 自定义参数字段
name: {
// 限定参数数据类型
type: "string",
// 参数释义：帮助AI理解参数作用、传参规则
description: "用户名称，不能为空字符串",
// 是否为必填参数
required: true
},
age: {
type: "number",
description: "用户年龄，支持正整数",
required: false
}
},
// ======================
// 4. 异步执行逻辑（工具核心业务层）
// ======================
// 必须为 async 异步函数，适配 IO 阻塞操作（文件、网络、数据库）
async execute({ name, age }) {
// 自定义业务逻辑
return `你好 ${name}，你的年龄是 ${age}`;
}
});
五、实战案例：读取 Java 文件 MCP 工具
本案例为用于 AI 自动读取项目 Java 源码，实现代码解析、复盘、改错，完全遵循官方协议规范。
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");
// 返回结构化数据，便于AI解析处理
return {
path: filePath,
content: content
};
}
});
拓展说明：工具返回结构化对象而非纯文本，是生产最佳实践，方便 AI 后续二次加工、解析数据、联动其他工具。
六、MCP 官方强制编写规范
所有规范并非格式约束，而是协议底层强制校验规则，不遵守会导致工具无法注册、AI 不调用、调用报错、参数解析失败等问题。
1. 工具名命名规范
协议硬性要求，工具 name 必须同时满足：全小写、英文下划线分隔、无中文、无大小写混合、无特殊符号
底层原因：MCP 协议工具名作为全局唯一标识，区分大小写，中文和驼峰会导致 AI 客户端解析失败。
正误对比：
- 规范正确：
read_java_file、query_user_info、export_project_log - 错误：
ReadJavaFile（驼峰大小写混合）读取java文件（包含中文）read-java-file（短横线分隔，协议不识别）
2. 参数类型规范
所有参数必须显式声明 type 类型，禁止隐式类型，AI 依赖类型字段做参数校验和参数生成。
MCP 标准支持 4 种基础通用类型，覆盖全部开发场景：
- string：字符串（文件路径、备注、文本内容）
- number：数字（页码、大小、超时时间、ID）
- boolean：布尔值（是否覆盖文件、是否开启校验）
- object：复杂对象（多层结构化参数）
额外规范：所有参数必须配置 description 字段，否则 AI 无法理解参数语义，导致传参错误。
3. 执行函数 execute 规范
execute 是工具核心执行入口，拥有三条不可违反的协议规则：
- 必须是 async 异步函数：MCP 工具绝大多数用于文件读写、网络请求等 IO 操作，同步函数会阻塞 AI 上下文线程，导致调用超时
- 必须有返回值：禁止无 return，否则 AI 获取不到工具执行结果，无法继续后续推理
- 支持异常捕获：生产工具必须增加 try/catch，避免单工具报错导致 AI 对话中断
七、个人理解易错总结
- description 不是备注，是AI 调用决策依据，描述越模糊，工具越容易不触发、误触发
- 参数 required 不写默认 false，非必填参数需要做好空值兼容
- 工具名全局唯一，同一项目禁止重复工具名，会造成工具覆盖冲突
- execute 必须异步，同步函数 100% 概率出现 IDE 调用超时异常
- 优先返回结构化 JSON 对象，而非纯文本，适配 AI 二次解析
