Vfan Docs

主题

MCP ​

什么是 MCP？ ​

MCP（Model Context Protocol，模型上下文协议）是一套开放协议，用于让 AI 应用连接外部工具、数据源和服务。

它不是某个 Agent 工具的专有能力。支持 MCP 的客户端、IDE、CLI Agent 或桌面应用可以复用同一类 MCP Server；不支持 MCP 的工具，也可能通过插件、内置工具、API 集成或企业网关实现类似能力。

通过 MCP，AI 可以获取项目仓库之外的实时信息，或执行受控操作，例如：

  • 查询 GitHub Issue、Pull Request、代码历史和 CI 状态
  • 读取内部文档、接口规范、设计系统或知识库
  • 查询数据库 Schema、测试数据或服务状态
  • 调用内部 API、工单系统、消息系统等服务

MCP 的目标是提供统一的连接方式，减少每个 AI 工具都要为每个外部服务单独开发集成的成本。

MCP 的基本组成 ​

MCP 通常包含三部分：

  • Host：用户实际使用的 AI 应用、IDE 或 Agent 平台。
  • Client：Host 内部用于连接 MCP Server 的组件。
  • Server：向 AI 提供外部数据或操作能力的服务。

一个 MCP Server 通常可提供：

  • Tools：可执行操作，例如搜索 Issue、查询数据库、创建工单。
  • Resources：可读取内容，例如文档、Schema、配置或知识库数据。
  • Prompts：可复用的任务模板或预设指令。

适合使用 MCP 的场景 ​

MCP 适合处理“重要信息不在当前仓库中”的情况，例如：

  • 项目规范存放在内部文档平台。
  • API 契约、数据库结构需要实时查询。
  • 开发任务依赖 Issue、PR、CI 或发布状态。
  • 需要访问设计系统、工单系统或企业内部服务。
  • 团队希望多个 AI 工具复用同一类外部能力。

如果信息已经稳定地存放在仓库内，优先使用 README.md、AGENTS.md、SKILL.md 或普通项目文档，不需要为了读取本地规则而引入 MCP。

与 AGENTS.md、SKILL.md 的区别 ​

bash
项目规则与长期约束  -> AGENTS.md
特定任务的执行流程  -> SKILL.md
外部服务与实时信息  -> MCP
  • AGENTS.md：项目内长期有效的规则、目录导航和开发约束。
  • SKILL.md：针对某一类任务的可复用流程。
  • MCP：访问项目外部的工具、数据和服务。

MCP 不替代项目文档，而是补充仓库无法提供的外部上下文和可调用能力。

通信基础 ​

stdio ​

stdio 是标准输入输出流。MCP 客户端启动本地 Server 后，可通过标准输入发送消息、从标准输出读取响应。

stdio 通信示意

js
process.stdin.setEncoding('utf-8')
process.stdin.on('data', (data) => {
  const request = JSON.parse(data)
  const response = {
    jsonrpc: '2.0',
    id: request.id,
    result: { ok: true },
  }
  process.stdout.write(`${JSON.stringify(response)}\n`)
})

JSON-RPC ​

MCP 使用 JSON-RPC 格式传递请求与响应。请求包含 jsonrpc、id、method 和可选的 params；响应通过相同的 id 关联结果或错误。

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

在不同 AI 工具中的使用方式 ​

MCP 是通用协议，可被支持 MCP 的 AI 客户端、IDE、桌面应用或 Agent 平台接入。

不同工具的配置入口、认证方式、权限管理方式和可调用能力可能不同，但 MCP Server 通常可以复用。团队不应假设一份客户端配置能够直接复制到所有工具中，而应分别按各工具的配置规范接入。

如果同时使用多个 Agent 工具，建议把“服务用途、权限范围、安全边界”写成工具无关的文档，再为每个具体工具补充接入方式。

项目中建议保留统一的 MCP 使用说明：

bash
repo/
  AGENTS.md
  docs/
    mcp.md

其中：

  • AGENTS.md：说明哪些任务需要使用外部工具，以及使用边界。
  • docs/mcp.md：记录团队允许使用的 MCP Server、用途、权限范围和认证方式。
  • Token、私有地址、账号信息等敏感配置不应提交到仓库。

在 AGENTS.md 中描述 MCP ​

AGENTS.md 不需要包含 MCP 的完整配置，只需说明何时使用以及允许的操作范围。

md
## External tools

- 查询 Issue、Pull Request、代码历史或 CI 状态时，使用 GitHub MCP。
- 查询接口定义、服务契约或内部开发规范时，使用 Docs MCP。
- 查询数据库 Schema 时，使用 Database MCP；默认只读。
- 不要通过 MCP 读取密钥、个人数据或生产环境数据。
- 写入、删除、发布或触发部署前，必须先展示计划并获得确认。

团队 MCP 文档示例 ​

可以在 docs/mcp.md 中维护团队认可的服务列表：

md
# MCP Services

## GitHub MCP

用途：查询 Issue、PR、代码历史和 CI 状态。

权限：默认只读；创建 Issue、评论或修改 PR 前需要确认。

## Database MCP

用途：查询测试环境 Schema 和脱敏测试数据。

权限：仅测试环境，只读；不允许执行 DDL 或 DML。

## Internal Docs MCP

用途：读取接口规范、架构文档和发布流程。

权限：只读；不允许访问人事、财务或客户敏感文档。

安全原则 ​

MCP Server 可能拥有读取数据、修改记录、执行命令或调用外部 API 的能力，应按最小权限原则配置。

  • 优先使用只读权限。
  • 开发、测试、生产环境使用不同凭据和不同 MCP Server。
  • 不将 API Key、Token、Cookie、数据库密码写入仓库、AGENTS.md 或 Skill 文件。
  • 不要随意安装来源不明的 MCP Server。
  • 对写入、删除、发送消息、发布、部署、支付等高风险操作保留人工确认。
  • 定期检查 MCP Server 的权限范围、依赖版本和日志。
  • 对 Tool 的名称、描述和参数保持审查，防止恶意工具描述或提示注入误导 Agent。

MCP 的工具调用可以触发外部操作，因此接入高权限 Server 时应特别谨慎。官方安全指南强调应实施最小权限、明确授权与安全认证。

编写原则 ​

  • 一个 MCP Server 只提供边界清晰的能力。
  • 优先暴露只读查询，再考虑写入能力。
  • 工具名称和参数应清晰、可审计。
  • 高风险操作应要求用户确认。
  • 不在 MCP 中混入与任务无关的大量工具。
  • 对生产环境、敏感数据和密钥建立独立权限边界。
  • 定期清理不再使用的 MCP Server 和凭据。

总结 ​

bash
AGENTS.md  -> 全局规则与项目导航
SKILL.md   -> 特定任务的执行流程
MCP        -> 外部服务、实时数据与可调用工具

MCP 的价值不在于替代文档，而在于让 AI 在需要时，以受控方式访问仓库之外的真实系统与实时信息。

基于 MIT 许可发布

版权所有 © 2026 Vfan Lee