把真实API封装成MCP工具：从设计到调试发布的完整闭环

flowchart LR
    U[用户: 帮我看看张三提的bug] --> CC[Claude Code]
    CC -->|tools/call search_issues| MCP[mcp-github-issues]
    MCP -->|GET /search/issues| GH[GitHub REST API]
    GH -->|JSON| MCP
    MCP -->|结构化文本| CC
    CC --> U

mkdir mcp-github-issues && cd mcp-github-issues
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx esbuild
npx tsc --init

{
  "name": "mcp-github-issues",
  "version": "0.1.0",
  "type": "module",
  "bin": { "mcp-github-issues": "./dist/index.js" },
  "files": ["dist"],
  "scripts": {
    "build": "tsc",
    "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js",
    "dev": "tsx src/index.ts",
    "inspector": "npx @modelcontextprotocol/inspector node dist/index.js"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0",
    "zod": "^3.23.0"
  }
}

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const TOKEN = process.env.GITHUB_TOKEN;
if (!TOKEN) {
  console.error("[fatal] 缺少 GITHUB_TOKEN 环境变量");
  process.exit(1);
}

const API = "https://api.github.com";

// 统一的请求封装：注入鉴权、处理速率限制、抛出结构化错误
async function gh(path: string, init: RequestInit = {}) {
  const res = await fetch(`${API}${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      Accept: "application/vnd.github+json",
      "X-GitHub-Api-Version": "2022-11-28",
      ...(init.body ? { "Content-Type": "application/json" } : {}),
      ...init.headers,
    },
  });

  if (res.status === 403 && res.headers.get("x-ratelimit-remaining") === "0") {
    const reset = res.headers.get("x-ratelimit-reset");
    throw new Error(`GitHub 速率限制已耗尽，将于 ${reset} (epoch) 重置`);
  }
  if (!res.ok) {
    const body = await res.text();
    throw new Error(`GitHub API ${res.status}: ${body.slice(0, 200)}`);
  }
  return res.json();
}

const server = new McpServer({
  name: "mcp-github-issues",
  version: "0.1.0",
});

// 工具 1：列出某仓库的开放 Issues
server.tool(
  "list_issues",
  "列出指定 GitHub 仓库最近开放的 Issues，按创建时间倒序。用于'看看最近有哪些 issue''某人提了什么'等浏览类任务。",
  {
    owner: z.string().describe("仓库所有者，如 vercel"),
    repo: z.string().describe("仓库名，如 next.js"),
    limit: z.number().int().min(1).max(50).default(10).describe("返回条数，1-50"),
  },
  async ({ owner, repo, limit }) => {
    const data = await gh(
      `/repos/${owner}/${repo}/issues?state=open&per_page=${limit}&sort=created&direction=desc`
    );
    const rows = (data as any[])
      .filter((i) => !("pull_request" in i)) // 排除 PR
      .map((i) => `#${i.number} [${(i.labels ?? []).map((l: any) => l.name).join(",")}] ${i.title} (@${i.user.login})`);
    return {
      content: [{ type: "text", text: rows.join("\n") || "无开放 Issue" }],
    };
  }
);

// 工具 2：创建 Issue（写操作，description 必须明示副作用）
server.tool(
  "create_issue",
  "在指定 GitHub 仓库创建一个新 Issue。属于写操作，会真实写入仓库，调用前应与用户确认。",
  {
    owner: z.string(),
    repo: z.string(),
    title: z.string().min(1).max(256).describe("Issue 标题，必填"),
    body: z.string().max(65536).optional().describe("Issue 正文 Markdown"),
    labels: z.array(z.string()).optional().describe("标签列表"),
  },
  async ({ owner, repo, title, body, labels }) => {
    const created = await gh(`/repos/${owner}/${repo}/issues`, {
      method: "POST",
      body: JSON.stringify({ title, body, labels }),
    });
    return {
      content: [{ type: "text", text: `已创建 #${(created as any).number}: ${(created as any).html_url}` }],
    };
  }
);

// search_issues / get_issue 同理，省略以节省篇幅

const transport = new StdioServerTransport();
await server.connect(transport);

flowchart TB
    C[tools/call 请求] --> Z{Zod 校验}
    Z -->|失败| ERR1[自动 isError 返回]
    Z -->|通过| B{业务前置校验}
    B -->|失败| ERR2[抛出带建议的 Error]
    B -->|通过| N[gh 网络层]
    N -->|限流/4xx/5xx| ERR3[归一化错误信息]
    N -->|2xx| OK[结构化文本返回]

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

npm run bundle

{
  "mcpServers": {
    "github-issues": {
      "command": "node",
      "args": ["/绝对路径/mcp-github-issues/dist/index.js"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

# 注册到当前项目作用域（写入 .mcp.json）
claude mcp add github-issues node ./dist/index.js \
  -e GITHUB_TOKEN=$GITHUB_TOKEN --scope project

# 或注册到用户作用域（全局可用）
claude mcp add github-issues node ./dist/index.js \
  -e GITHUB_TOKEN=$GITHUB_TOKEN --scope user

npm publish --access public

{
  "mcpServers": {
    "github-issues": {
      "command": "npx",
      "args": ["-y", "mcp-github-issues@latest"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

sequenceDiagram
    participant U as 用户
    participant M as Claude Code
    participant S as mcp-github-issues
    participant G as GitHub API

    U->>M: 生成本周 bug 周报
    M->>S: search_issues label:bug created:>=本周
    S->>G: GET /search/issues
    G-->>S: 30 条 JSON
    S-->>M: 结构化文本
    M->>M: 按负责人分组聚合
    M->>U: 写入 weekly.md（文件系统工具）