用 TypeScript 构建 MCP Server：从零到发布完整教程

┌─────────────────────────────────────────────┐
│           MCP 客户端 (Host)                  │
│   Claude Code / Cursor / VS Code Copilot    │
├─────────────────────────────────────────────┤
│           MCP 协议层                         │
│         JSON-RPC 2.0 + STDIO/HTTP           │
├─────────────────────────────────────────────┤
│           MCP Server (你的代码)              │
│   工具 / 资源 / 提示模板                      │
└─────────────────────────────────────────────┘

mkdir weather-mcp-server
cd weather-mcp-server
npm init -y

npm install @modelcontextprotocol/server zod
npm install -D typescript @types/node

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

{
  "name": "weather-mcp-server",
  "version": "1.0.0",
  "type": "module",
  "bin": {
    "weather-mcp-server": "./dist/index.js"
  },
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

#!/usr/bin/env node

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

// 1. 创建服务器实例
const server = new McpServer({
  name: "weather-server",
  version: "1.0.0",
});

// 2. 模拟天气数据（生产环境请替换为真实 API）
function getWeatherData(city: string) {
  const weatherMap: Record<
    string,
    { temperature: number; condition: string; humidity: number }
  > = {
    "New York": { temperature: 2, condition: "Cloudy", humidity: 65 },
    "San Francisco": { temperature: 14, condition: "Sunny", humidity: 70 },
    London: { temperature: 8, condition: "Rainy", humidity: 85 },
    Tokyo: { temperature: 10, condition: "Clear", humidity: 55 },
    Sydney: { temperature: 25, condition: "Sunny", humidity: 60 },
  };

  const data = weatherMap[city];
  if (!data) {
    return { city, temperature: 15, condition: "Unknown", humidity: 50 };
  }
  return { city, ...data };
}

// 3. 注册工具：获取天气
server.registerTool(
  "get_weather",
  {
    title: "Get Weather",
    description:
      "Get current weather for a city including temperature, condition, and humidity",
    inputSchema: z.object({
      city: z
        .string()
        .describe("City name, e.g. New York, London, Tokyo"),
    }),
  },
  async ({ city }) => {
    const weather = getWeatherData(city);
    const text = `Weather in ${weather.city}: ${weather.condition}, ${weather.temperature}°C, humidity ${weather.humidity}%`;
    return {
      content: [{ type: "text", text }],
    };
  }
);

// 4. 注册工具：对比两个城市的天气
server.registerTool(
  "compare_weather",
  {
    title: "Compare Weather",
    description: "Compare weather between two cities",
    inputSchema: z.object({
      city1: z.string().describe("First city"),
      city2: z.string().describe("Second city"),
    }),
  },
  async ({ city1, city2 }) => {
    const w1 = getWeatherData(city1);
    const w2 = getWeatherData(city2);
    const diff = w1.temperature - w2.temperature;

    const text = [
      `Weather Comparison: ${w1.city} vs ${w2.city}`,
      `---`,
      `${w1.city}: ${w1.condition}, ${w1.temperature}°C, humidity ${w1.humidity}%`,
      `${w2.city}: ${w2.condition}, ${w2.temperature}°C, humidity ${w2.humidity}%`,
      `---`,
      `Temperature difference: ${Math.abs(diff)}°C (${diff > 0 ? w1.city + " is warmer" : w2.city + " is warmer"})`,
    ].join("\n");

    return {
      content: [{ type: "text", text }],
    };
  }
);

// 5. 启动 STDIO 传输
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Weather MCP Server started"); // 用 stderr 而不是 stdout！
}

main().catch(console.error);

npx tsc
chmod +x dist/index.js

claude mcp add weather-server node /absolute/path/to/dist/index.js

> What's the weather in Tokyo?

> Compare the weather in New York and London

claude mcp list

server.registerResource(
  "supported-cities",
  "weather://cities",
  {
    title: "Supported Cities",
    description: "Returns all cities with weather data available",
    mimeType: "application/json",
  },
  async (uri) => ({
    contents: [
      {
        uri: uri.href,
        text: JSON.stringify([
          "New York",
          "San Francisco",
          "London",
          "Tokyo",
          "Sydney",
        ]),
      },
    ],
  })
);

server.registerPrompt(
  "travel-advice",
  {
    title: "Travel Advice",
    description: "Get outfit and travel tips based on destination weather",
    argsSchema: z.object({
      destination: z.string().describe("Destination city"),
    }),
  },
  ({ destination }) => ({
    messages: [
      {
        role: "user" as const,
        content: {
          type: "text" as const,
          text: `Based on the current weather in ${destination}, suggest appropriate clothing and travel tips.`,
        },
      },
    ],
  })
);

#!/usr/bin/env node

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

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

// 工具：列出最近的 Issues
server.registerTool(
  "list_issues",
  {
    title: "List GitHub Issues",
    description: "List recent issues from a GitHub repository",
    inputSchema: z.object({
      owner: z.string().describe("Repository owner (e.g. 'anthropics')"),
      repo: z.string().describe("Repository name (e.g. 'claude-code')"),
      state: z
        .enum(["open", "closed", "all"])
        .default("open")
        .describe("Issue state filter"),
      limit: z
        .number()
        .min(1)
        .max(30)
        .default(10)
        .describe("Number of issues to return"),
    }),
  },
  async ({ owner, repo, state, limit }) => {
    const url = `https://api.github.com/repos/${owner}/${repo}/issues?state=${state}&per_page=${limit}`;

    const response = await fetch(url, {
      headers: {
        Accept: "application/vnd.github.v3+json",
        "User-Agent": "mcp-github-issues",
      },
    });

    if (!response.ok) {
      return {
        content: [
          {
            type: "text",
            text: `Error fetching issues: ${response.status} ${response.statusText}`,
          },
        ],
        isError: true,
      };
    }

    const issues = await response.json();
    const formatted = issues
      .map(
        (issue: any) =>
          `#${issue.number} [${issue.state}] ${issue.title}\n  Labels: ${issue.labels.map((l: any) => l.name).join(", ") || "none"}\n  Created: ${issue.created_at}\n  URL: ${issue.html_url}`
      )
      .join("\n\n");

    return {
      content: [
        {
          type: "text",
          text: `Issues for ${owner}/${repo} (${state}):\n\n${formatted}`,
        },
      ],
    };
  }
);

// 工具：获取 Issue 详情
server.registerTool(
  "get_issue",
  {
    title: "Get Issue Details",
    description: "Get detailed information about a specific GitHub issue",
    inputSchema: z.object({
      owner: z.string().describe("Repository owner"),
      repo: z.string().describe("Repository name"),
      issue_number: z.number().describe("Issue number"),
    }),
  },
  async ({ owner, repo, issue_number }) => {
    const url = `https://api.github.com/repos/${owner}/${repo}/issues/${issue_number}`;

    const response = await fetch(url, {
      headers: {
        Accept: "application/vnd.github.v3+json",
        "User-Agent": "mcp-github-issues",
      },
    });

    if (!response.ok) {
      return {
        content: [
          {
            type: "text",
            text: `Error: ${response.status} ${response.statusText}`,
          },
        ],
        isError: true,
      };
    }

    const issue = await response.json();
    const text = [
      `# #${issue.number}: ${issue.title}`,
      `State: ${issue.state}`,
      `Author: ${issue.user.login}`,
      `Created: ${issue.created_at}`,
      `Labels: ${issue.labels.map((l: any) => l.name).join(", ") || "none"}`,
      `Comments: ${issue.comments}`,
      `---`,
      issue.body || "(no description)",
    ].join("\n");

    return {
      content: [{ type: "text", text }],
    };
  }
);

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("GitHub Issues MCP Server started");
}

main().catch(console.error);

> List open issues in anthropics/claude-code
> Show me the details of issue #42 in that repo

// 错误——会破坏 STDIO 协议
console.log("Debug info");

// 正确——使用 stderr，不会干扰
console.error("Debug info");

server.registerTool(
  "fetch-data",
  {
    description: "Fetch data from URL",
    inputSchema: z.object({ url: z.string() }),
  },
  async ({ url }, ctx) => {
    await ctx.mcpReq.log("info", `Fetching ${url}`);
    const res = await fetch(url);
    await ctx.mcpReq.log("debug", `Response status: ${res.status}`);
    const text = await res.text();
    return { content: [{ type: "text", text }] };
  }
);

const server = new McpServer(
  { name: "my-server", version: "1.0.0" },
  { capabilities: { logging: {} } }
);

# 检查已注册的服务器
claude mcp list

# 移除并重新添加（重启服务器）
claude mcp remove weather-server
claude mcp add weather-server node /path/to/dist/index.js

{
  "name": "@your-scope/weather-mcp-server",
  "version": "1.0.0",
  "description": "MCP server for weather data queries",
  "type": "module",
  "bin": {
    "weather-mcp-server": "./dist/index.js"
  },
  "files": ["dist"],
  "keywords": ["mcp", "mcp-server", "weather"],
  "license": "MIT"
}

npm run build
npm publish --access public

claude mcp add weather-server npx @your-scope/weather-mcp-server

my-mcp-server/
├── src/
│   ├── index.ts          # 入口文件，服务器配置
│   ├── tools/            # 工具处理函数
│   │   ├── query.ts
│   │   └── mutate.ts
│   ├── resources/        # 资源处理函数
│   │   └── config.ts
│   └── utils/            # 共享工具函数
│       └── api-client.ts
├── dist/                 # 编译输出
├── package.json
├── tsconfig.json
└── README.md