深入理解 Model Context Protocol (MCP) 架构与自定义开发
深入解析 Model Context Protocol (MCP) 核心架构:JSON-RPC 协议、stdio 与 SSE 传输、工具与资源机制,并通过 TypeScript 打造自定义 MCP Server。
在 AI Agent(智能体)与辅助编程工具蓬勃发展的今天,软件工程界面临着一个长期存在的架构挑战:如何让大语言模型(LLM)安全、可控地连接内部知识库、本地文件系统及各种企业 API,而无需针对每个模型重复编写专属插件?
Anthropic 推出的开放协议 Model Context Protocol (MCP) 正是解决这一痛点的关键架构——它通过标准化的通用接口,重新定义了 AI 应用与外部数据工具的交互方式。
为什么需要 MCP?#
在 MCP 诞生之前,AI 生态深陷 的集成困境:
- 存在 个 AI 客户端(如 Claude Desktop、Cursor、VS Code、终端 Agent 等)
- 存在 个数据源与外部工具(如 PostgreSQL、GitHub、Slack、本地文件系统、Jira 等)
- 开发者必须维护 个各自独立的定制化对接插件。
每当新的大模型问世或外部 API 变更结构,所有插件往往都需要推倒重构。
[!NOTE] MCP 从根本上解决了这一问题:它将复杂的 关系简化为 。MCP 就如同 AI 领域的 USB-C 接口标准。只要 AI 客户端支持 MCP,即可即插即用地连接任何符合协议的 MCP Server。
深入浅出理解 MCP 概念(ELI5)#
不妨把大语言模型想象为一位身居密室、学识渊博却无法直接接触外界的“学者”:
- Host 与 Client(传达室秘书):类似 Claude Desktop 或 IDE,负责在学者身旁转达外部指令与需求。
- MCP Server(连通外部的专用抽屉):每个 MCP 挂载服务都是通向真实世界的一个抽屉。一个抽屉装着本地文档,一个抽屉连着计算器,另一个抽屉连接 GitHub 代码仓库。
- JSON-RPC(统一格式的申请单):学者想要获取数据或执行指令时,就会填写一张标准协议申请单,外部抽屉处理后按约定格式返回精准结果。
MCP 的三大核心原语(Primitives)#
MCP 协议规范定义了服务端能够向客户端暴露的三种核心基础能力:
1. Tools(模型自主调用的操作)#
由大语言模型主动决策并调用的可执行函数(如查询数据库、执行 Shell 命令、发送通知)。模型根据服务提供的 JSON Schema 动态决定调用时机与传参内容。
2. Resources(应用控制的只读资源)#
具有标准 URI 标识的只读上下文数据(如 file:///var/logs/app.log 或 postgres://users/schema)。用户或宿主客户端可将其直接附带到对话上下文中,为模型提供确切的业务依据。
3. Prompts(用户控制的交互模板)#
预设的带参提示词模板,用于帮助用户快速发起高频工作流(例如“代码安全审查”或“故障日志根因分析”)。
传输协议(Transports)#
MCP 目前主要支持两种基础通信方式:
- stdio(标准输入/输出):专为本地进程间通信打造。客户端将 Server 作为子进程启动,通过
stdin发送请求并监听stdout获取响应。其特点是零网络延迟、天然安全隔离,极为适合桌面客户端与本地开发者工具。 - SSE(Server-Sent Events)基于 HTTP:专为远程云端部署场景设计。客户端通过 HTTP POST 提交请求,并通过持久化的 SSE 连接接收服务端流式响应。
动手构建一个完整的 TypeScript MCP Server#
以下示例使用官方 SDK @modelcontextprotocol/sdk 创建了一个立即可运行的 MCP Server。该服务注册了:
- 一个读取项目配置的资源 (
config://app-info) - 一个统计工作区文件的工具 (
analyze_workspace)
1. 初始化项目#
mkdir my-custom-mcp-server
cd my-custom-mcp-server
bun init -y
bun add @modelcontextprotocol/sdk zodbash2. 编写服务端代码#
新建 src/index.ts:
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
CallToolRequestSchema,
ListResourcesRequestSchema,
ListToolsRequestSchema,
ReadResourceRequestSchema,
} from '@modelcontextprotocol/sdk/types.js';
import { z } from 'zod';
// 初始化 MCP Server 并声明元数据
const server = new Server(
{
name: 'project-analytics-server',
version: '1.0.0',
},
{
capabilities: {
resources: {},
tools: {},
},
},
);
// 1. 注册可用资源列表
server.setRequestHandler(ListResourcesRequestSchema, async () => {
return {
resources: [
{
uri: 'config://app-info',
name: '项目运行环境配置',
mimeType: 'application/json',
},
],
};
});
// 处理读取资源请求
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
if (request.params.uri === 'config://app-info') {
return {
contents: [
{
uri: 'config://app-info',
mimeType: 'application/json',
text: JSON.stringify(
{
projectName: 'Dopana Engineering Hub',
environment: 'production',
supportedEngines: ['Bun', 'Node.js', 'Rust'],
},
null,
2,
),
},
],
};
}
throw new Error(`找不到请求的资源: ${request.params.uri}`);
});
// 2. 注册可用工具列表
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [
{
name: 'analyze_workspace',
description: '分析工作区中指定扩展名文件的统计信息',
inputSchema: {
type: 'object',
properties: {
fileExtension: {
type: 'string',
description: '待分析的文件后缀 (例如: ts, rs, py)',
},
},
required: ['fileExtension'],
},
},
],
};
});
// 处理工具调用执行
server.setRequestHandler(CallToolRequestSchema, async (request) => {
if (request.params.name === 'analyze_workspace') {
const ext = String(request.params.arguments?.fileExtension || 'ts');
return {
content: [
{
type: 'text',
text: JSON.stringify({
targetExtension: ext,
totalFilesFound: 42,
status: 'healthy',
summary: `已成功完成 .${ext} 后缀代码文件统计分析`,
}),
},
],
};
}
throw new Error(`未知工具指令: ${request.params.name}`);
});
// 使用 stdio 传输协议连接并监听
async function main() {
const transport = new StdioServerTransport();
await server.connect(transport);
console.error('MCP Server 已通过 stdio 成功连接并启动');
}
main().catch((err) => {
console.error('服务启动发生致命错误:', err);
process.exit(1);
});typescript[!TIP] 使用 Stdio 传输时的关键避坑准则:切勿将自定义调试日志输出至
stdout(console.log)。在 stdio 模式下,stdout专门用于交换协议 JSON-RPC 数据包;若输出任何非规范文本,客户端解析器将直接抛出 JSON 解析异常。所有日志必须输出到stderr(console.error)。
3. 配置连接至 Claude Desktop#
在客户端配置文件 claude_desktop_config.json 中添加如下项:
{
"mcpServers": {
"project-analytics": {
"command": "bun",
"args": ["run", "/absolute/path/to/my-custom-mcp-server/src/index.ts"]
}
}
}json保存并重启客户端,界面即会出现全新的工具标识,模型将能在对话中根据场景自主调用 analyze_workspace。
总结#
Model Context Protocol (MCP) 代表了 AI 基础设施标准化的重要演进。通过将核心模型能力与领域数据工具彻底解耦,开发者可以以最小的成本,构建跨平台、可复用且具备高安全性的企业级 AI 工具链。