MCP工具开发：从Inspector调试到本地发布实战

// src/server.ts —— 只负责"造服务器"，不碰 stdio
import { McpServer } from "@modelcontextprotocol/sdk/mcp.js";
import { z } from "zod";
import fs from "node:fs/promises";

export function createServer(): McpServer {
  const server = new McpServer({ name: "md-linkcheck", version: "1.0.0" });

  server.tool(
    "check_url",
    "检查单个 URL 的 HTTP 状态码",
    { url: z.string().url() },
    async ({ url }) => {
      const status = await head(url);
      return { content: [{ type: "text" as const, text: `${url} -> ${status}` }] };
    }
  );
  return server;
}

export async function head(url: string, timeoutMs = 5000): Promise<number> {
  const ctrl = new AbortController();
  const t = setTimeout(() => ctrl.abort(), timeoutMs);
  try {
    const res = await fetch(url, { method: "GET", redirect: "follow", signal: ctrl.signal });
    return res.status;
  } catch {
    return 0; // 0 = 网络/超时
  } finally {
    clearTimeout(t);
  }
}

// src/index.ts —— 生产入口，连接 stdio
import { StdioServerTransport } from "@modelcontextprotocol/sdk/stdio.js";
import { createServer } from "./server.js";

async function main() {
  const server = createServer();
  await server.connect(new StdioServerTransport());
}
main();

# 指定你的服务器入口，Inspector 会作为父进程拉起它
npx @modelcontextprotocol/inspector node ./build/index.js

// test/contract.test.ts
import { describe, it, expect } from "vitest";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
import { createServer } from "../src/server.js";

async function connect() {
  const server = createServer();
  const client = new Client({ name: "test", version: "1.0" }, { capabilities: {} });
  const [clientSide, serverSide] = InMemoryTransport.createLinkedPair();
  await Promise.all([client.connect(clientSide), server.connect(serverSide)]);
  return client;
}

describe("md-linkcheck 契约", () => {
  it("暴露 check_url 工具", async () => {
    const client = await connect();
    const { tools } = await client.listTools();
    expect(tools.map((t) => t.name)).toContain("check_url");
  });

  it("check_url 返回 example.com 状态码", async () => {
    const client = await connect();
    const res = await client.callTool({ name: "check_url", arguments: { url: "https://example.com" } });
    const text = (res.content as any[])[0].text;
    expect(text).toMatch(/example\.com -> \d+/);
  });

  it("非法 URL 触发协议级错误", async () => {
    const client = await connect();
    const res = await client.callTool({ name: "check_url", arguments: { url: "not-a-url" } });
    expect(res.isError).toBe(true);
  });
});

{
  "type": "module",
  "scripts": { "build": "tsc", "test": "vitest run" },
  "dependencies": { "@modelcontextprotocol/sdk": "^1.0.0", "zod": "^3.23.0" },
  "devDependencies": { "typescript": "^5.4.0", "vitest": "^1.6.0" }
}

// 仓库根目录 .mcp.json
{
  "mcpServers": {
    "md-linkcheck": {
      "command": "node",
      "args": ["./mcp-servers/md-linkcheck/build/index.js"],
      "env": { "USER_AGENT": "md-linkcheck/1.0" }
    }
  }
}

# --scope project 写入 .mcp.json；--scope user 全局；--scope local 仅本机
claude mcp add md-linkcheck --scope project -- node ./mcp-servers/md-linkcheck/build/index.js

claude mcp list                 # 列出所有已配置
claude mcp get md-linkcheck     # 查看单个配置与最近一次连接状态

# .github/workflows/mcp.yml（节选）
- run: npm ci && npm run build && npm test
- name: smoke
  run: |
    node ./build/index.js < /dev/null &
    PID=$!
    sleep 1
    kill -0 $PID && echo "server alive"

server.tool(
  "check_links",
  "检查 Markdown 文件内所有外链可达性，返回每个 URL 状态码",
  {
    file: z.string().describe("Markdown 文件路径"),
    timeout: z.number().default(5000).describe("单 URL 超时毫秒"),
  },
  async ({ file, timeout }) => {
    const md = await fs.readFile(file, "utf8");
    const urls = [...new Set([...md.matchAll(/\]\((https?:\/\/[^)\s]+)/g)].map((m) => m[1]))];
    const results = await Promise.all(urls.map(async (url) => ({ url, status: await head(url, timeout) })));
    const broken = results.filter((r) => r.status === 0 || r.status >= 400);
    return {
      content: [{
        type: "text" as const,
        text: `共 ${urls.length} 条外链，异常 ${broken.length} 条：\n` +
              broken.map((r) => `- [${r.status}] ${r.url}`).join("\n"),
      }],
    };
  }
);

flowchart LR
    A[createServer 工厂] --> B[npx inspector 手测]
    B -->|工具清单/报文正常| C[vitest 契约测试]
    B -->|报错| A
    C -->|全绿| D[.mcp.json 项目分发]
    C -->|失败| A
    D --> E[/mcp 验证连接]
    E --> F[CI 冒烟+发布清单]
    F --> G[团队复用]