什么是 MCP

痛点：很多开发者看到“Model Context Protocol”这个名字，却不知道它到底能干什么甚至怀疑是否值得投入时间。

MCP是 Anthropic 提出的开放协议，让 AI 助手能够连接外部工具和数据源。你可以把它理解为 AI 世界的 USB 接口——只要实现这个协议，Claude、Cursor 等客户端就能调用你的功能。

协议主要只有三个角色：

• Server提供能力的一方，暴露若干 Tool、Resource、Prompt。
• Client发起调用的一方。按理说，
• Transport通信层。负责在 Client 和 Server 之间传递 JSON‑RPC 消息。说起来，

这篇文章聚焦最常见的用法：用 TypeScript 写一个 MCP Server。通过 stdio 传输层暴露自定义工具，让 Claude Code 能够调用你写的函数。

安装依赖

痛点：依赖冲突或缺少类型定义经常让新手卡在这一步。

npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node

@modelcontextprotocol/sdk 是官方 TypeScript SDK，内部封装了 JSON‑RPC 通信、协议握手、能力协商等细节。zod 用于定义工具参数的类型约束——MCP 协议要求工具参数必须有 JSON Schema，zod 能自动生成。

创建 MCP Server 实例

痛点：不清楚到底需要哪些必填字段，怕写错导致握手失败。老实说，

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';const server = new McpServer({
name这方面，'my-first-mcp'。// 在协议握手阶段展示给 Client 的标识
version: '.',// 任意字符串，推荐使用 semver 或 '.' 表示本地开发版
});

注册 Tool

痛点：Tool 定义不完整会导致 Claude 看不到或调用时报错；参数描述不明确时 AI 难以填充正确值。

Tool 基础结构

最小示例 – 加法工具

import { z } from 'zod';server.tool(
'add','Add two numbers toger.',{
a: z.number.describe。b: z.number.describe,},async => {
return {
content:,};},)，

The signature is:

server.tool;

• The .describe call on each Zod field is **mandatory** – Claude relies on it to generate correct arguments.
• The handler must return an object containing a content. Each item can be:
  • { type: 'text',text: '...' } – plain text
  • { type: 'image',data: '...',mimeType: '...' } – base64 image payloads{ type: 'resource',... } – reference to a registered Resource.

    用 Zod 定义复杂参数

    If you only use primitive types you’ll quickly hit limits when your tool needs richer input. Zod can express almost any JSON‑compatible shape.

    // 可选 + 默认值
    {
    至于query。z.string.describe,limit: z.number.optional.default.describe
    }
    // 枚举
    {
    再看source，z.enum.describe
    }
    // 嵌套对象
    {
    task这方面，z.object({
    从goal来看，z.string,files: z.array).optional,})
    }
    // 数组
    {
    再看tags，z.array).describe
    }
    

    A real‑world example from ChatCrystal – recall_for_task tool – shows how to reuse a pre‑defined Zod shape:

    import { RecallForTaskRequestShape } from '../../services/memory/schemas.js';server.tool(
    'recall_for_task','Recall project‑first and global‑supplement memories for a task.'。RecallForTaskRequestShape,async => {
    const data = await client.recallForTask;不过，return {
    content:,};},)，

    The advantage of extracting schema into its own file:

    • MCP registration and HTTP route handlers share exact same validation logic.No duplication → fewer bugs when contract changes.Easily unit‑test schema independent of server runtime.

    StdioServerTransport：标准输入输出通信

    MCP 支持多种 Transport。最常用的是 stdio——通过进程的 stdin/stdout 把 JSON‑RPC 消息一行一条地传递给 Claude Code。

    const transport = new StdioServerTransport;await server.connect;话说回来，

    • No network port needed → avoids firewall / port clash issues.The client launches your server as a child process and automatically shuts it down.The message format is strict JSON‑RPC;each line is a complete request/response pair.

    The handshake performed by .connect: Client sends an "initialize"。Server replies with its name/version and list of Tools it supports,n enters normal message loop.

    完整启动函数示例：

    export async function startMcpServer {
    const client = new CrystalClient;const server = new McpServer({
    name : 'chatcrystal'。version : '.',});// 注册多个工具...
    server.tool;server.tool，// ...更多 tool
    const transport = new StdioServerTransport;
    await server.connect;}
    

    The handler functions are async;y can call external APIs,query databases or read files. In ChatCrystal MCP layer merely forwards calls to an existing REST API via CrystalClient,keeping protocol layer thin and stateless.

    配置 Claude Code 与你的 Server

    Create or edit .claude/settings.json .

    {
    "mcpServers": {
    "chatcrystal": {
    "command": "npx"。"args":
    }
    }}
    }

    • If you publish an npm CLI,you can use its command directly:

    {
    "mcpServers": {
    "chatcrystal": {
    "command":"crystal","args":
    }
    }
    }

    After restarting Claude Code you should see your server under “/mcp”. The UI will list all registered tools;Claude will automatically decide when to invoke m based on your prompts.

    调试技巧

    查看原始 JSON‑RPC 消息

    The only safe place for log output is stderr ;writing anything to stdout corrupts RPC stream.

    console.error);` 

    MCP Inspector

    npx @modelcontextprotocol/inspector npx tsx src/mcp-server.ts
    ` 

    The inspector opens a web UI showing every registered tool,lets you manually supply arguments and view raw request/response objects.

    常见问题 & 对策

    • Tool 不出现在 Claude 中 :确保已调用 server.connect而且 settings.json 方法与命令正确无误。重启 Claude 后 检查 “/mcp”。
    • 参数校验失败 :每个 Zod 字段必须使用 .describe提供人类可读说明；缺失描述会导致 AI 无法生成符合 schema 的值。不过，
    • 超时 / 长耗时操作 :handler 应尽量保持轻量。如果需要耗时处理，可先返回 “处理中” 文本。并通过轮询或回调方式获取结果。

    从 ChatCrystal 学到的设计模式

    • MCP 层保持无状态 :所有业务状态放在后端服务，MCP Server 可以随时重启而不丢失数据。
    • Schema 重用 :把 Zod shape 抽离到独立文件，实现 MCP 注册与 HTTP 路由共用同一套校验逻辑。
    • 统一返回结构 :所有 Tool 都返回 { content: }。虽然协议支持图片、资源等类型，但文本是最通用且最易被 AI 理解的形式。
    • 使用 .describe 替代注释 :这些描述直接送给 Claude 阅读，是提高调用准确率的关键所在。

    完整最小示例

    // mcp-server.ts
    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    : 'hello-mcp'。version : '.',});

    server.tool( 'greet','Greet someone by name.',{ name       : z.string.describe。language   : z.enum.optional.default .describe },async => { const greeting = language === 'zh' 你好，${name}！ : Hello,${name}!话说回来，;不过，return { content : };},)，

    const transport = new StdioServerTransport;await server.connect;`

    说到执行命令。

    bash npx tsx mcp-server.ts

    在 Claude Code 的 settings.json 中加入对应配置后你可以在对话里说「用 greet 工具跟张三打个招呼」，Claude 会自动调用你的服务器并返回中文问候。

    接下来探索方向

    • Resource :让 Server 暴露文件或二进制数据，以供 Client 主动读取。
    • Prompt :预先注册 Prompt 模板。让 AI 在需要时直接引用，提高一致性。
    • SSE Transport :如果要远程部署。可改用 HTTP Server‑Sent Events 替代 stdio，实现跨机器通信。
    • 多工具协作案例 :参考 ChatCrystal 中八个互补工具的组合，实现「检索 → 缓存 → 写入」闭环。

    MCP 协议规范持续更新，请关注  还有 SDK 的 GitHub 文档。

    如有疑问欢迎在 GitHub Issues 或私信交流，我很乐意方便你上手！按理说，