把现有 API 封装为 MCP 工具：从端点映射到 Claude Code 接入全流程

// mock-api/server.js — 零依赖的网元告警 REST API
const http = require('http');

const alarms = [
  { id: 'A-1001', ne: 'gNB-North-07', severity: 'critical', text: 'S1 链路中断', raisedAt: '2026-06-18T08:12:00Z', acked: false },
  { id: 'A-1002', ne: 'AMF-East-02',  severity: 'major',    text: 'CPU 使用率 > 90%', raisedAt: '2026-06-18T08:30:00Z', acked: false },
  { id: 'A-1003', ne: 'UPF-Core-01',  severity: 'minor',    text: '会话数接近阈值', raisedAt: '2026-06-18T09:01:00Z', acked: true },
  { id: 'A-1004', ne: 'SMF-West-03',  severity: 'critical', text: 'PFCP 心跳超时', raisedAt: '2026-06-18T09:15:00Z', acked: false },
  { id: 'A-1005', ne: 'gNB-South-11', severity: 'major',    text: '光功率异常',     raisedAt: '2026-06-18T09:22:00Z', acked: false },
];

function send(res, status, body) {
  res.writeHead(status, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify(body));
}

const server = http.createServer((req, res) => {
  const url = new URL(req.url, 'http://localhost');
  // GET /alarms?severity=&limit=&cursor=
  if (req.method === 'GET' && url.pathname === '/alarms') {
    const sev = url.searchParams.get('severity');
    const limit = Math.min(parseInt(url.searchParams.get('limit') || '20', 10), 100);
    const cursor = parseInt(url.searchParams.get('cursor') || '0', 10);
    let filtered = alarms.filter(a => !sev || a.severity === sev);
    const slice = filtered.slice(cursor, cursor + limit);
    const nextCursor = cursor + limit < filtered.length ? String(cursor + limit) : null;
    return send(res, 200, { items: slice, nextCursor, total: filtered.length });
  }
  // GET /alarms/:id
  const m = url.pathname.match(/^\/alarms\/([^/]+)$/);
  if (req.method === 'GET' && m) {
    const a = alarms.find(x => x.id === m[1]);
    return a ? send(res, 200, a) : send(res, 404, { error: 'alarm not found' });
  }
  // POST /alarms/:id/acknowledge  body { note }
  const am = url.pathname.match(/^\/alarms\/([^/]+)\/acknowledge$/);
  if (req.method === 'POST' && am) {
    const a = alarms.find(x => x.id === am[1]);
    if (!a) return send(res, 404, { error: 'alarm not found' });
    let body = '';
    req.on('data', c => body += c);
    req.on('end', () => {
      const { note = '' } = body ? JSON.parse(body) : {};
      a.acked = true; a.ackNote = note; a.ackedAt = new Date().toISOString();
      return send(res, 200, a);
    });
    return;
  }
  send(res, 404, { error: 'no route' });
});

server.listen(3001, () => console.log('alarm API on http://localhost:3001'));

node mock-api/server.js
# 另开终端：
curl -s 'http://localhost:3001/alarms?severity=critical&limit=1'
# 预期: {"items":[{...A-1001...}],"nextCursor":"1","total":2}

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

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "Bundler",
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

"build": "tsc",
"start": "node dist/server.js"

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

const BASE = process.env.API_BASE_URL || 'http://localhost:3001';

async function httpGet(path: string) {
  const res = await fetch(`${BASE}${path}`);
  const body = await res.json().catch(() => ({}));
  return { ok: res.ok, status: res.status, body };
}

const server = new McpServer({ name: 'alarm-mcp', version: '1.0.0' });

server.registerTool(
  'list-alarms',
  {
    description:
      '列出网元告警。可按 severity 过滤，分页获取。' +
      '若返回的 nextCursor 不为 null，表示还有更多，可用该值作为下一次的 cursor 继续翻页。',
    inputSchema: {
      severity: z.enum(['critical', 'major', 'minor']).optional()
        .describe('按严重等级过滤；不传则返回全部'),
      limit: z.number().int().min(1).max(100).optional()
        .describe('单页数量，默认 20，最大 100'),
      cursor: z.string().optional().describe('上一页返回的 nextCursor'),
    },
    outputSchema: {
      alarms: z.array(z.object({
        id: z.string(), ne: z.string(), severity: z.string(),
        text: z.string(), acked: z.boolean(),
      })),
      nextCursor: z.string().nullable(),
      total: z.number(),
    },
  },
  async ({ severity, limit = 20, cursor }) => {
    const params = new URLSearchParams();
    if (severity) params.set('severity', severity);
    params.set('limit', String(limit));
    if (cursor) params.set('cursor', cursor);

    const { ok, status, body } = await httpGet(`/alarms?${params}`);
    if (!ok) {
      return {
        content: [{ type: 'text', text: `查询失败 (HTTP ${status})：${JSON.stringify(body)}` }],
        isError: true,
      };
    }
    // 给 LLM 的简短摘要 + 给程序的完整结构化数据
    const summary = body.items.map((a: any) =>
      `[${a.id}] ${a.severity} ${a.ne} — ${a.text}${a.acked ? ' (已确认)' : ''}`).join('\n');
    const hint = body.nextCursor
      ? `\n\n还有更多，可用 cursor="${body.nextCursor}" 翻下一页。`
      : '\n\n已是最后一页。';
    return {
      content: [{ type: 'text', text: `共 ${body.total} 条，本页 ${body.items.length} 条：\n${summary}${hint}` }],
      structuredContent: { alarms: body.items, nextCursor: body.nextCursor, total: body.total },
    };
  }
);

server.registerTool(
  'get-alarm',
  {
    description: '按 id 获取单个网元告警的完整详情。',
    inputSchema: { id: z.string().describe('告警 ID，如 A-1001') },
    outputSchema: {
      id: z.string(), ne: z.string(), severity: z.string(),
      text: z.string(), raisedAt: z.string(), acked: z.boolean(),
    },
  },
  async ({ id }) => {
    const { ok, status, body } = await httpGet(`/alarms/${encodeURIComponent(id)}`);
    if (!ok) {
      // 404 映射成 isError，并告诉 LLM 怎么办
      return {
        content: [{ type: 'text',
          text: status === 404
            ? `告警 ${id} 不存在。请先用 list-alarms 核对正确的 id。`
            : `获取失败 (HTTP ${status})：${JSON.stringify(body)}` }],
        isError: true,
      };
    }
    return {
      content: [{ type: 'text', text: JSON.stringify(body, null, 2) }],
      structuredContent: body,
    };
  }
);

async function httpPost(path: string, payload: any) {
  const res = await fetch(`${BASE}${path}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload),
  });
  const body = await res.json().catch(() => ({}));
  return { ok: res.ok, status: res.status, body };
}

server.registerTool(
  'acknowledge-alarm',
  {
    description: '确认（派单/消警）一条告警。这是写操作，会改变告警状态。',
    inputSchema: {
      id: z.string().describe('要确认的告警 ID'),
      note: z.string().optional().describe('可选的处理备注'),
    },
    outputSchema: {
      id: z.string(), acked: z.boolean(), ackedAt: z.string().nullable(),
    },
  },
  async ({ id, note }) => {
    const { ok, status, body } = await httpPost(
      `/alarms/${encodeURIComponent(id)}/acknowledge`, { note });
    if (!ok) {
      return {
        content: [{ type: 'text',
          text: status === 404
            ? `告警 ${id} 不存在，无法确认。`
            : `确认失败 (HTTP ${status})：${JSON.stringify(body)}` }],
        isError: true,
      };
    }
    return {
      content: [{ type: 'text',
        text: `已确认告警 ${body.id}（${body.ne}）。${note ? '备注：' + note : ''}` }],
      structuredContent: { id: body.id, acked: body.acked, ackedAt: body.ackedAt ?? null },
    };
  }
);

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

npm run build

npx @modelcontextprotocol/inspector node dist/server.js

# 1) local（默认）：只对当前项目当前机器的你可见
claude mcp add alarm-mcp -- node /绝对路径/mcp-wrap/dist/server.js

# 2) user：你在这台机器上所有项目都能用
claude mcp add alarm-mcp -s user -- node /绝对路径/mcp-wrap/dist/server.js

# 3) project：随仓库走，团队共享 —— 写进 .mcp.json 并提交

{
  "mcpServers": {
    "alarm-mcp": {
      "command": "node",
      "args": ["./mcp-wrap/dist/server.js"],
      "env": { "API_BASE_URL": "http://localhost:3001" }
    }
  }
}

claude mcp list          # 应看到 alarm-mcp 及其工具数
claude mcp get alarm-mcp # 查看命令、参数、env、状态

flowchart TD
    A[REST API 端点] --> B{端点→工具映射}
    B --> |GET /alarms| T1[list-alarms 工具<br/>分页入参 + structuredContent]
    B --> |GET /alarms/:id| T2[get-alarm 工具<br/>404→isError+恢复提示]
    B --> |POST acknowledge| T3[acknowledge-alarm 工具<br/>写操作+错误映射]
    T1 & T2 & T3 --> S[McpServer<br/>@modelcontextprotocol/sdk v1.x]
    S --> TR[StdioServerTransport]
    TR --> I[Inspector 全链路调试<br/>单工具验证绿]
    I --> CC[Claude Code 三作用域<br/>local/user/project .mcp.json]
    CC --> ENV[env: API_BASE_URL<br/>切后端不改代码]
    ENV --> U[团队共享 / 测试生产切换]

mcp-wrap/
├── mock-api/server.js        # 被封装的零依赖 REST API
├── src/server.ts             # MCP 服务器（三个工具）
├── dist/                     # tsc 产物
├── .mcp.json                 # project 作用域团队共享配置
└── package.json

# 终端1：起后端
node mock-api/server.js
# 终端2：构建 MCP 服务器
cd mcp-wrap && npm run build
# 终端3：在项目里用 Claude 值守
claude
> 列出所有未确认的 critical 告警，逐条确认并备注"已派单"