Model Context Protocol（MCP）

什么是 MCP？

Model Context Protocol（模型上下文协议） 是由 Anthropic 发起、现由社区维护的 开放标准，用于让 AI 应用（Host） 以统一方式连接 外部数据源与工具（通过 MCP Server）。

可以把它理解成 AI 时代的 「USB-C」：

以前：每个 IDE / Agent 都要为 Notion、Jira、数据库、内部 API 各写一套插件
有了 MCP：按同一套协议实现一次 Server，任何支持 MCP 的 Client（如 Cursor、Claude Desktop）都能接入

架构角色

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  MCP Host   │────▶│  MCP Client │────▶│  MCP Server │
│ (Cursor等)  │     │ (协议客户端) │     │ (你的服务)   │
└─────────────┘     └─────────────┘     └─────────────┘
                                              │
                                              ▼
                                        外部 API / DB / 文件

角色	职责
Host	承载 LLM 的应用（Cursor、Claude Desktop 等）
Client	Host 内嵌组件，按 MCP 协议与 Server 通信
Server	你实现的服务，向 AI 暴露可调用的能力

MCP 的作用

1. 标准化「AI 能用什么」

MCP 定义了三类核心能力（Primitives）：

能力	含义	典型场景
Tools	可执行的操作（函数）	查工单、创建 Issue、调 REST API
Resources	可读的数据源（URI 模板）	读文档、配置文件、数据库记录
Prompts	预置提示词模板	标准化「写 PR 描述」「生成测试用例」

Agent 的典型路径：发现（list）→ 调用（call）→ 读结果。

2. 解耦 AI 与业务系统

Server 侧：只关心如何把 Jira / 内部 OA 封装成 Tools
Host 侧：只关心如何展示、调度、鉴权
团队可独立维护 MCP Server，无需等 IDE 厂商逐个适配

3. 对 AI-Native 团队的价值

在 Rules + Skills 跑顺之后，MCP 适合接入：

需求 / 缺陷系统（自动拉 Story、更新状态）
设计稿（Figma MCP）
知识库（Notion、内部 Wiki）
自建内部 API 网关

本仓库的 mcp-builder Skill 指导 如何写好 MCP Server（工具命名、分页、错误信息要对 Agent 友好等）。

4. 传输层

传输	场景
stdio	本地子进程；Cursor 配置 `command` + `args` 启动
Streamable HTTP / SSE	远程服务、多客户端共享、企业内网部署

官方 SDK 概览

语言	官方仓库	安装
Python	modelcontextprotocol/python-sdk	`pip install mcp`
Java	modelcontextprotocol/java-sdk	Maven `mcp-bom` / `mcp`
C#	modelcontextprotocol/csharp-sdk	NuGet `ModelContextProtocol`
TypeScript	modelcontextprotocol/typescript-sdk	`npm i @modelcontextprotocol/sdk`

规范与概念文档：modelcontextprotocol.io

Python 实现

Python 侧推荐 FastMCP（官方 SDK 内置的高层框架）：装饰器注册 Tool，Pydantic 做入参校验，docstring 自动生成 schema。

最小 Server 示例

# pip install mcp
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("order_mcp")

@mcp.tool()
async def get_order(order_id: str) -> str:
    """按订单号查询订单详情。"""
    order = await fetch_order_from_db(order_id)
    return order.to_json()

if __name__ == "__main__":
    mcp.run()  # 默认 stdio，供 Cursor 子进程拉起

Cursor 配置示例

~/.cursor/mcp.json 或项目级配置：

{
  "mcpServers": {
    "order": {
      "command": "python",
      "args": ["C:/path/to/order_mcp_server.py"]
    }
  }
}

特点

上手最快，适合脚本型、API 封装型 Server
支持 Context（进度上报、日志、elicit 向用户索取敏感输入）
本仓库参考：.cursor/skills/mcp-builder/reference/python_mcp_server.md

Java 实现

官方 Java SDK 与 Spring AI 团队协作维护，基于 Project Reactor（响应式）。

模块划分

模块	说明
`mcp-bom`	统一版本 BOM
`mcp-core`	核心协议、STDIO、JDK HttpClient
`mcp-json-jackson2` / `mcp-json-jackson3`	JSON 绑定实现
`mcp`	便捷包（core + Jackson 3）

Maven 依赖（示意）

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>io.modelcontextprotocol.sdk</groupId>
      <artifactId>mcp-bom</artifactId>
      <version><!-- 以官方最新为准 --></version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp</artifactId>
  </dependency>
</dependencies>

典型用法

创建 McpServer 实例
注册 Tool / Resource / Prompt 处理器
选择 STDIO 或 Servlet / HTTP 传输

若已使用 Spring Boot + Spring AI，可用 MCP Starter 简化 WebFlux / WebMVC 下的 HTTP Server 配置（部分传输模块已迁入 org.springframework.ai）。

适合场景

企业已有 Spring 技术栈
与现有 Service / Repository 层复用
远程 HTTP MCP、与网关鉴权集成

文档：java.sdk.modelcontextprotocol.io

C# 实现

微软与 Anthropic 共同维护，通过 NuGet 分发，与 .NET Hosting / DI 深度集成。

NuGet 包选择

包	适用场景
`ModelContextProtocol.Core`	仅 Client 或底层 API，依赖最少
`ModelContextProtocol`	大多数项目：stdio Server + 特性发现
`ModelContextProtocol.AspNetCore`	ASP.NET Core HTTP MCP Server

stdio Server 示例

// dotnet add package ModelContextProtocol
// dotnet add package Microsoft.Extensions.Hosting
using System.ComponentModel;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using ModelContextProtocol.Server;

var builder = Host.CreateApplicationBuilder(args);
builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithToolsFromAssembly();  // 扫描 [McpServerTool]

await builder.Build().RunAsync();

[McpServerToolType]
public static class OrderTools
{
    [McpServerTool, Description("按订单号查询订单")]
    public static async Task<string> GetOrder(string orderId)
    {
        var order = await OrderService.FetchAsync(orderId);
        return order.ToJson();
    }
}

HTTP Server

换用 ModelContextProtocol.AspNetCore，在 Program.cs 配置 Streamable HTTP 传输，适合内网统一部署、多 Host 共享。

Client 侧

McpClient.CreateAsync 连接任意 MCP Server
ListToolsAsync 返回的工具可对接 Microsoft.Extensions.AI 的 IChatClient

文档：csharp.sdk.modelcontextprotocol.io

语言选型建议

场景	推荐
快速封装脚本 / 数据科学 / 小工具	Python（FastMCP）
现有 Spring 微服务、Java 后端团队	Java（mcp + Spring AI）
.NET 内部系统、Azure 部署	C#（ModelContextProtocol.AspNetCore）
前端团队、全栈 TypeScript	TypeScript SDK

设计原则（写给 Agent 的 Server）

无论使用哪种语言，建议遵循 mcp-builder Skill 中的约定：

Tool 名带服务前缀：jira_create_issue，而非 create_issue
描述写给 Agent：说明何时用、参数含义、返回值结构
分页与过滤：避免一次返回海量 JSON
可行动的错误信息：告诉 Agent 下一步怎么做，而非仅抛异常栈
命名规范：Python Server 建议 {service}_mcp（如 github_mcp）

与 Cursor 工具链的关系

Rules   → 常开约束（技术栈、禁止项）
Skills  → 流程剧本（规划、Review、TDD…）
MCP     → 外部世界（Notion、Figma、内部 API…）

在 Cursor 中配置的 MCP 服务器，即 Host 通过 Client 连接各语言实现的 MCP Server。Agent 在对话中 自动发现工具 schema，再决定是否调用。

posted @ 2026-06-25 15:52 一个老码农阅读(31) 评论(0) 收藏举报

刷新页面返回顶部