MCP Server TypeScript v2七步全实战

graph TB
    subgraph Host["MCP Host（宿主）"]
        A["Claude Code"]
        B["Claude Desktop"]
        C["Cursor IDE"]
        D["Windsurf"]
    end

    subgraph Client["MCP Client（客户端）"]
        E["内置于Host中<br/>管理连接生命周期"]
    end

    subgraph Server["MCP Server（你的Server）"]
        F["Tools<br/>可调用的函数"]
        G["Resources<br/>可读取的数据"]
        H["Prompts<br/>预置的提示模板"]
    end

    Host -->|"JSON-RPC 2.0"| Client
    Client -->|"stdio / HTTP"| Server

    Server --> F
    Server --> G
    Server --> H

node --version   # v22.x.x 或更高
npm --version    # v10.x.x 或更高
claude --version # 确认Claude Code已安装

mkdir markdown-toolkit && cd markdown-toolkit

{
  "name": "markdown-toolkit",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "npx tsc --watch",
    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js"
  },
  "dependencies": {
    "@modelcontextprotocol/server": "^2.0.0",
    "zod": "^3.25.0"
  },
  "devDependencies": {
    "typescript": "^5.8.3",
    "@types/node": "^22.0.0"
  }
}

npm install

added 120 packages in 2s
found 0 vulnerabilities

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"]
}

mkdir src

import { McpServer } from "@modelcontextprotocol/server";
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";

// 初始化Server
const server = new McpServer({
  name: "markdown-toolkit",
  version: "1.0.0",
});

// ========== Tools ==========

// Tool 1: 字数统计
server.registerTool(
  "word_count",
  {
    description:
      "统计Markdown文本的字数、段落数、标题数。" +
      "返回结构化的统计数据，适合文档分析。",
    inputSchema: z.object({
      markdown: z.string().describe("要分析的Markdown文本"),
    }),
  },
  async ({ markdown }) => {
    const lines = markdown.split("\n");
    const headings = lines.filter((l) => l.startsWith("#"));
    const paragraphs = lines.filter(
      (l) => l.trim() !== "" && !l.startsWith("#")
    );
    const words = markdown
      .replace(/[#*_`>\[\]()!-]/g, " ")
      .split(/\s+/)
      .filter(Boolean);

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            {
              totalWords: words.length,
              totalLines: lines.length,
              headings: headings.length,
              headingList: headings.map((h) => h.trim()),
              paragraphs: paragraphs.length,
            },
            null,
            2
          ),
        },
      ],
    };
  }
);

// Tool 2: 提取目录
server.registerTool(
  "extract_toc",
  {
    description:
      "从Markdown文本中提取层级目录结构。" +
      "返回带缩进的目录树，含标题级别和锚点链接。",
    inputSchema: z.object({
      markdown: z.string().describe("要提取目录的Markdown文本"),
      maxDepth: z
        .number()
        .min(1)
        .max(6)
        .optional()
        .describe("最大标题深度，默认6（包含所有级别）"),
    }),
  },
  async ({ markdown, maxDepth }) => {
    const depth = maxDepth ?? 6;
    const headingRegex = /^(#{1,6})\s+(.+)$/gm;
    const toc: string[] = [];
    let match;

    while ((match = headingRegex.exec(markdown)) !== null) {
      const level = match[1].length;
      if (level > depth) continue;
      const title = match[2].trim();
      const anchor = title
        .toLowerCase()
        .replace(/[^a-z0-9\u4e00-\u9fff\s-]/g, "")
        .replace(/\s+/g, "-");
      const indent = "  ".repeat(level - 1);
      toc.push(`${indent}- [${title}](#${anchor})`);
    }

    if (toc.length === 0) {
      return {
        content: [
          { type: "text", text: "未找到标题。请确保文本包含 # 标题。" },
        ],
      };
    }

    return {
      content: [
        {
          type: "text",
          text: `## 目录\n\n${toc.join("\n")}\n\n共 ${toc.length} 个标题。`,
        },
      ],
    };
  }
);

// Tool 3: 链接检查
server.registerTool(
  "check_links",
  {
    description:
      "检查Markdown文本中的链接格式是否规范。" +
      "检测空链接、重复锚点、格式异常等问题。",
    inputSchema: z.object({
      markdown: z.string().describe("要检查链接的Markdown文本"),
    }),
  },
  async ({ markdown }) => {
    const linkRegex = /\[([^\]]*)\]\(([^)]*)\)/g;
    const issues: string[] = [];
    const anchors = new Set<string>();
    let match;
    let linkCount = 0;

    while ((match = linkRegex.exec(markdown)) !== null) {
      linkCount++;
      const text = match[1];
      const href = match[2];

      if (!text.trim()) {
        issues.push(`链接 #${linkCount}: 链接文本为空 → ${match[0]}`);
      }
      if (!href.trim()) {
        issues.push(`链接 #${linkCount}: href为空 → ${match[0]}`);
      }
      if (href.startsWith("#")) {
        if (anchors.has(href)) {
          issues.push(`链接 #${linkCount}: 重复锚点 → ${href}`);
        }
        anchors.add(href);
      }
      if (href.includes(" ") && !href.startsWith("http")) {
        issues.push(`链接 #${linkCount}: href包含空格 → ${match[0]}`);
      }
    }

    const result = {
      totalLinks: linkCount,
      issuesFound: issues.length,
      issues: issues.length > 0 ? issues : ["所有链接格式正常 ✓"],
    };

    return {
      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
    };
  }
);

// ========== Resources ==========

server.resource(
  "readme-template",
  "templates://readme",
  async (uri) => ({
    contents: [
      {
        uri: uri.href,
        mimeType: "text/markdown",
        text: `# 项目名称

> 一句话描述你的项目

## 功能特性

- 特性一
- 特性二
- 特性三

## 快速开始

\`\`\`bash
npm install your-package
\`\`\`

## 使用方法

\`\`\`typescript
import { something } from 'your-package';
\`\`\`

## 贡献指南

欢迎提交 Issue 和 Pull Request。

## 许可证

MIT License
`,
      },
    ],
  })
);

// ========== Prompts ==========

server.prompt(
  "review_markdown",
  "审查Markdown文档的质量和规范性",
  { document: z.string().describe("要审查的Markdown文档内容") },
  async ({ document }) => ({
    messages: [
      {
        role: "user",
        content: {
          type: "text",
          text: `请审查以下Markdown文档，从以下维度评分（1-10）：

1. **结构层次**：标题层级是否合理，是否缺少必要章节
2. **链接完整性**：所有链接是否有效，锚点是否正确
3. **代码示例**：代码块是否有语言标注，示例是否可运行
4. **格式规范**：列表缩进、空行使用、表格格式
5. **可读性**：段落长度、语言风格、专业术语使用

文档内容：

${document}

请给出具体评分和改进建议。`,
        },
      },
    ],
  })
);

// ========== 启动Server ==========

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("[markdown-toolkit] MCP Server已启动（stdio模式）");
}

main().catch((err) => {
  console.error("Server启动失败:", err);
  process.exit(1);
});

server.registerTool(name, { description, inputSchema }, handler)

npx tsc

ls dist/
# index.js  index.js.map（如果启用了sourcemap）

// test.mjs
import { spawn } from "child_process";

const proc = spawn("node", ["dist/index.js"], {
  stdio: ["pipe", "pipe", "pipe"],
});

const messages = [
  {
    jsonrpc: "2.0",
    id: 1,
    method: "initialize",
    params: {
      protocolVersion: "2024-11-05",
      capabilities: {},
      clientInfo: { name: "test-client", version: "1.0" },
    },
  },
  { jsonrpc: "2.0", method: "notifications/initialized", params: {} },
  { jsonrpc: "2.0", id: 2, method: "tools/list", params: {} },
  {
    jsonrpc: "2.0",
    id: 3,
    method: "tools/call",
    params: {
      name: "word_count",
      arguments: { markdown: "# 标题\n\nHello World from MCP\n\n## 二级标题\n\nAnother paragraph" },
    },
  },
  {
    jsonrpc: "2.0",
    id: 4,
    method: "resources/list",
    params: {},
  },
];

let output = "";
proc.stdout.on("data", (d) => {
  output += d;
});

messages.forEach((m) => proc.stdin.write(JSON.stringify(m) + "\n"));

setTimeout(() => {
  proc.kill();
  output
    .trim()
    .split("\n")
    .forEach((line) => {
      try {
        const { id, result } = JSON.parse(line);
        console.log(`[${id}]`, JSON.stringify(result).slice(0, 150));
      } catch {}
    });
}, 2000);

node test.mjs

[1] {"protocolVersion":"2024-11-05","capabilities":{"tools":{"listChanged":true},"resources":{"listChanged":true},"prompts":{"listChanged":true}},"serverInfo":{"name":"markdown-toolkit","version":"1.0.0"}}
[2] {"tools":[{"name":"word_count","description":"统计Markdown文本的字数、段落数、标题数..."},{"name":"extract_toc",...},{"name":"check_links",...}]}
[3] {"content":[{"type":"text","text":"{\n  \"totalWords\": 8,\n  \"totalLines\": 7,\n  \"headings\": 2,..."}]}
[4] {"resources":[{"uri":"templates://readme","name":"readme-template","mimeType":"text/markdown"}]}

npx @modelcontextprotocol/inspector node dist/index.js

graph LR
    subgraph Inspector["MCP Inspector UI"]
        A["Tools面板<br/>列出所有Tool<br/>在线填写参数<br/>查看返回结果"]
        B["Resources面板<br/>浏览可用资源<br/>预览资源内容"]
        C["Prompts面板<br/>查看提示模板<br/>测试参数渲染"]
        D["Connection面板<br/>查看握手信息<br/>协议版本<br/>能力协商"]
    end

    subgraph Server["你的MCP Server"]
        E["stdio进程"]
    end

    Inspector -->|"JSON-RPC"| Server

claude mcp add --transport stdio markdown-toolkit -- node /absolute/path/to/markdown-toolkit/dist/index.js

claude mcp list

markdown-toolkit: node /absolute/path/to/markdown-toolkit/dist/index.js (stdio)

{
  "mcpServers": {
    "markdown-toolkit": {
      "type": "stdio",
      "command": "node",
      "args": ["${CLAUDE_PROJECT_DIR}/dist/index.js"]
    }
  }
}

claude

> 统计以下Markdown的字数：# 标题\n\n这是测试段落
> （Claude会调用word_count工具）

> 帮我提取这个文档的目录结构
> （Claude会调用extract_toc工具）

> 检查我的README中的链接格式
> （Claude会调用check_links工具）

> @markdown-toolkit 读取README模板

> /markdown-toolkit:review_markdown

npm install @modelcontextprotocol/node

import { McpServer } from "@modelcontextprotocol/server";
import { createServer } from "http";
import { randomUUID } from "crypto";
import { z } from "zod";

const server = new McpServer({
  name: "markdown-toolkit",
  version: "1.0.0",
});

// 注册相同的Tools（复用逻辑）
server.registerTool(
  "word_count",
  {
    description: "统计Markdown文本的字数、段落数、标题数",
    inputSchema: z.object({
      markdown: z.string().describe("要分析的Markdown文本"),
    }),
  },
  async ({ markdown }) => {
    const words = markdown
      .replace(/[#*_`>\[\]()!-]/g, " ")
      .split(/\s+/)
      .filter(Boolean);
    return {
      content: [
        { type: "text", text: JSON.stringify({ totalWords: words.length }) },
      ],
    };
  }
);

// HTTP Transport处理
const httpServer = createServer(async (req, res) => {
  if (req.method === "POST") {
    const body = await new Promise<string>((resolve) => {
      let data = "";
      req.on("data", (chunk) => (data += chunk));
      req.on("end", () => resolve(data));
    });

    const message = JSON.parse(body);
    const response = await server.handleMessage(message, {
      sessionId: randomUUID(),
    });

    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify(response));
  }
});

const PORT = process.env.PORT || 3001;
httpServer.listen(PORT, () => {
  console.log(`MCP Server running on http://localhost:${PORT}/mcp`);
});

claude mcp add --transport http markdown-toolkit-remote http://your-server:3001/mcp

claude mcp add --transport http \
  --header "Authorization: Bearer your-token" \
  markdown-toolkit-remote \
  https://api.your-domain.com/mcp

flowchart TD
    A["创建项目<br/>npm init + type:module"] --> B["安装SDK<br/>@modelcontextprotocol/server"]
    B --> C["实现Tools/Resources/Prompts<br/>registerTool / resource / prompt"]
    C --> D["编译TypeScript<br/>npx tsc"]
    D --> E["本地JSON-RPC测试<br/>test.mjs"]
    E --> F{"测试通过?"}
    F -->|No| C
    F -->|Yes| G["MCP Inspector<br/>可视化调试"]
    G --> H{"功能正确?"}
    H -->|No| C
    H -->|Yes| I["注册到Claude Code<br/>claude mcp add"]
    I --> J["集成测试<br/>Claude Code对话调用"]
    J --> K{"联调通过?"}
    K -->|No| C
    K -->|Yes| L["选择部署方式"]
    L --> M["stdio模式<br/>本地/团队使用"]
    L --> N["HTTP模式<br/>远程/多用户"]
    M --> O["配置.mcp.json<br/>项目级共享"]
    N --> P["部署到服务器<br/>claude mcp add --transport http"]

// v2 API（推荐）
server.registerTool(
  name: string,
  options: {
    description: string;
    inputSchema: ZodSchema;  // 使用Zod，SDK自动转JSON Schema
  },
  handler: (args) => Promise<{
    content: Array<{ type: "text"; text: string } | { type: "image"; data: string; mimeType: string }>;
    isError?: boolean;
  }>
);

server.resource(
  name: string,
  uri: string,          // 如 "templates://readme"
  handler: (uri: URL) => Promise<{
    contents: Array<{
      uri: string;
      text?: string;
      blob?: string;
      mimeType?: string;
    }>;
  }>
);

server.prompt(
  name: string,
  description: string,
  argsSchema: Record<string, ZodSchema>,
  handler: (args) => Promise<{
    messages: Array<{
      role: "user" | "assistant";
      content: { type: "text"; text: string };
    }>;
  }>
);

return {
  content: [
    { type: "text", text: "分析结果如下：" },
    {
      type: "image",
      data: base64EncodedImage,
      mimeType: "image/png",
    },
  ],
};

server.registerTool(
  "safe_tool",
  { description: "带错误处理的Tool", inputSchema: z.object({ url: z.string().url() }) },
  async ({ url }) => {
    try {
      const data = await fetchData(url);
      return { content: [{ type: "text", text: JSON.stringify(data) }] };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `错误：${error instanceof Error ? error.message : String(error)}`,
          },
        ],
        isError: true, // 标记为错误响应
      };
    }
  }
);

// ❌ 差的描述
{ description: "统计字数" }

// ✅ 好的描述
{
  description:
    "统计Markdown文本的字数、段落数、标题数。" +
    "返回结构化的统计数据，适合文档分析。" +
    "输入为原始Markdown文本，输出为JSON格式的统计结果。"
}

// .mcp.json中使用环境变量
{
  "mcpServers": {
    "my-api-server": {
      "type": "stdio",
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "API_KEY": "${MY_API_KEY}",
        "PROJECT_DIR": "${CLAUDE_PROJECT_DIR:-.}"
      }
    }
  }
}

// 对于耗时操作，考虑缓存
const cache = new Map<string, { data: unknown; expiry: number }>();

function withCache<T>(key: string, ttl: number, fn: () => Promise<T>): Promise<T> {
  const cached = cache.get(key);
  if (cached && Date.now() < cached.expiry) {
    return Promise.resolve(cached.data as T);
  }
  return fn().then((data) => {
    cache.set(key, { data, expiry: Date.now() + ttl });
    return data;
  });
}