核心导读与中文摘要
完整演示如何用 `@modelcontextprotocol/sdk` 在 15 分钟内写出支持 Tool 与 Resource 的本地 MCP Server,并无缝接入 Cursor、Claude Code 与 Cherry Studio。
为什么要自己写 MCP Server?
Cursor、Claude Code 和 Cherry Studio 都已原生支持 MCP (Model Context Protocol)。当你希望 AI 直接查询公司内部数据库只读视图、读取飞书/Notion 文档、或调用定制脚本时,写一个几十行的本地 stdio MCP Server 是成本最低、复用率最高的解法。
第一步:初始化项目并安装官方 SDK
bash
mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx
第二步:编写核心 Tool(src/index.ts)
[!IMPORTANT] 注意
stdio模式下的日志坑:标准输出stdout严格用于 JSON-RPC 协议通信,调试日志必须打印到console.error()(stderr),否则客户端会直接断连报错。
typescript
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';
const server = new McpServer({
name: 'team-docs-helper',
version: '1.0.0',
});
server.tool(
'search_internal_faq',
'按关键词检索团队内部规范与接口文档',
{
keyword: z.string().min(1).describe('搜索关键词,例如 auth 或 deploy'),
},
async ({ keyword }) => {
// 这里替换为真实数据库、本地 Markdown 检索或内网 API 调用
const mockResult = `找到与 "${keyword}" 相关的 2 条团队规范:部署前必须通过 tsc 与 lint。`;
return {
content: [{ type: 'text', text: mockResult }],
};
}
);
async function main() {
const transport = new StdioServerTransport();
await server.connect(transport);
console.error('team-docs-helper MCP server running on stdio');
}
main().catch((err) => {
console.error(err);
process.exit(1);
});
第三步:挂载到客户端(以 Cursor / Claude Code 为例)
在 .cursor/mcp.json 或 Claude Code 配置文件中添加如下配置,重启或刷新工具列表即可调用:
json
{
"mcpServers": {
"team-docs-helper": {
"command": "npx",
"args": ["tsx", "/绝对路径/my-mcp-server/src/index.ts"]
}
}
}
生产安全建议
- 只读优先:对外暴露查询类工具前默认开启只读权限,写操作单独拆分并增加确认参数。
- 用 Zod 写清参数描述:
describe()里的中文说明会直接喂给大模型,越清晰越不容易传错参数。
