MCP Server TypeScript全实战：三原语到发布

┌──────────────┐    JSON-RPC     ┌──────────────┐
│  MCP Client  │◄──────────────►│  MCP Server  │
│  (Claude Code│    stdio/HTTP   │  (你开发的    │
│   / Desktop) │                 │   工具服务)   │
└──────────────┘                 └──────────────┘
       │                                │
       │ LLM 调用工具                    │ 访问外部系统
       ▼                                ▼
┌──────────────┐                 ┌──────────────┐
│   AI Model   │                 │  数据库/API/  │
│  (Claude等)  │                 │  文件系统等   │
└──────────────┘                 └──────────────┘

flowchart TB
    subgraph Local["本地模式 (stdio)"]
        CC1["Claude Code"] -->|stdin/stdout| MS1["MCP Server 进程"]
    end

    subgraph Remote["远程模式 (Streamable HTTP)"]
        CC2["Claude Code"] -->|HTTP POST| PROXY["HTTP Server"]
        PROXY -->|JSON-RPC| MS2["MCP Server"]
    end

    subgraph Dev["开发调试"]
        MI["MCP Inspector"] -->|stdio/HTTP| MS3["MCP Server"]
    end

# 确认 Node.js >= 18
node --version   # v18+ 或 v20+ 推荐

# 确认 Claude Code 已安装
claude --version

# 创建项目目录
mkdir mcp-weather-server && cd mcp-weather-server

# 初始化 TypeScript 项目
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node

# 创建 TypeScript 配置
cat > tsconfig.json << 'EOF'
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "declaration": true
  },
  "include": ["src/**/*"]
}
EOF

# 创建源码目录
mkdir src

{
  "name": "mcp-weather-server",
  "version": "1.0.0",
  "description": "MCP Server for weather data queries",
  "type": "module",
  "main": "dist/index.js",
  "bin": {
    "mcp-weather-server": "dist/index.js"
  },
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch",
    "start": "node dist/index.js",
    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js"
  },
  "files": ["dist"]
}

#!/usr/bin/env node

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

// 创建 MCP Server 实例
const server = new McpServer({
  name: "weather-server",
  version: "1.0.0",
});

// ========== Tool 1: 获取当前天气 ==========
server.tool(
  "get_current_weather",          // 工具名称
  "获取指定城市的当前天气信息",      // 工具描述（LLM 靠这个决定是否调用）
  {
    city: z.string().describe("城市名称，如'北京'、'Shanghai'"),
    unit: z.enum(["celsius", "fahrenheit"]).optional()
      .describe("温度单位，默认摄氏度"),
  },
  async ({ city, unit }) => {
    // 调用天气 API（这里用模拟数据演示）
    const weather = await fetchWeather(city, unit ?? "celsius");

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

// ========== Tool 2: 天气预报 ==========
server.tool(
  "get_weather_forecast",
  "获取指定城市未来几天的天气预报",
  {
    city: z.string().describe("城市名称"),
    days: z.number().min(1).max(7).optional()
      .describe("预报天数，1-7天，默认3天"),
  },
  async ({ city, days }) => {
    const forecast = await fetchForecast(city, days ?? 3);

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

// ========== 启动 Server ==========
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  // Server 启动后通过 stdin/stdout 与 Client 通信
  // 不需要 console.log — stdout 被用于协议通信
}

main().catch((error) => {
  // 错误输出到 stderr，避免干扰 MCP 协议
  process.stderr.write(`Fatal error: ${error}\n`);
  process.exit(1);
});

// ========== 模拟数据层（实际项目替换为真实 API）==========
async function fetchWeather(city: string, unit: string) {
  // 实际项目中调用 OpenWeatherMap / 和风天气 等 API
  return {
    city,
    temperature: unit === "fahrenheit" ? 82 : 28,
    unit: unit === "fahrenheit" ? "°F" : "°C",
    condition: "晴朗",
    humidity: 45,
    wind_speed: "12 km/h",
    updated_at: new Date().toISOString(),
  };
}

async function fetchForecast(city: string, days: number) {
  const conditions = ["晴", "多云", "小雨", "阴", "雷阵雨"];
  return Array.from({ length: days }, (_, i) => ({
    date: new Date(Date.now() + i * 86400000)
      .toISOString().split("T")[0],
    high: Math.round(25 + Math.random() * 10),
    low: Math.round(15 + Math.random() * 8),
    condition: conditions[Math.floor(Math.random() * conditions.length)],
  }));
}

function formatForecast(forecast: any[]): string {
  return forecast
    .map((d) => `${d.date}: ${d.condition}, ${d.low}°C ~ ${d.high}°C`)
    .join("\n");
}

server.tool(
  string,      // 工具名称 — 必须唯一，推荐 snake_case
  string,      // 描述 — LLM 根据描述决定是否调用，务必清晰准确
  ZodSchema,   // 参数 Schema — 用 Zod 定义，自动生成 JSON Schema
  Handler,     // 异步处理函数 — 接收解析后的参数，返回 content 数组
);

// Zod 定义                    → JSON Schema（自动生成）
z.string()                     → { type: "string" }
z.string().describe("城市")    → { type: "string", description: "城市" }
z.number().min(1).max(7)       → { type: "number", minimum: 1, maximum: 7 }
z.enum(["a", "b"])             → { enum: ["a", "b"] }
z.string().optional()          → 属性不加入 required 数组
z.array(z.string())            → { type: "array", items: { type: "string" } }

// 文本内容
return {
  content: [{ type: "text", text: "结果文本" }]
};

// 图片内容（Tool 特有）
return {
  content: [{
    type: "image",
    data: base64EncodedImage,
    mimeType: "image/png"
  }]
};

// 错误（不抛异常，而是返回 isError 标记）
return {
  content: [{ type: "text", text: "城市不存在: xxx" }],
  isError: true,
};

# 编译 TypeScript
npm run build

# 使用 MCP Inspector 可视化测试
npm run inspect

# 方式一：使用 claude mcp add 命令（推荐）
claude mcp add weather-server -- node /path/to/mcp-weather-server/dist/index.js

# 方式二：使用 JSON 配置
claude mcp add-json weather-server '{
  "type": "stdio",
  "command": "node",
  "args": ["/path/to/mcp-weather-server/dist/index.js"]
}'

# 验证配置
claude mcp list

# 在 Claude Code 中测试
claude
> 北京今天天气怎么样？
# Claude 会自动识别并调用 get_current_weather 工具

// ========== Resource: 支持的城市列表 ==========
server.resource(
  "supported-cities",              // 资源名称
  "weather://cities/supported",    // URI（MCP 使用自定义 URI Scheme）
  async (uri) => {
    const cities = [
      { name: "北京", code: "BJ", lat: 39.9, lon: 116.4 },
      { name: "上海", code: "SH", lat: 31.2, lon: 121.5 },
      { name: "广州", code: "GZ", lat: 23.1, lon: 113.3 },
      { name: "Shenzhen", code: "SZ", lat: 22.5, lon: 114.1 },
    ];

    return {
      contents: [
        {
          uri: uri.href,
          mimeType: "application/json",
          text: JSON.stringify(cities, null, 2),
        },
      ],
    };
  }
);

// ========== Resource Template: 城市天气历史 ==========
server.resource(
  "city-weather-history",
  new ResourceTemplate("weather://cities/{city}/history", { list: undefined }),
  async (uri, { city }) => {
    // {city} 从 URI 中自动提取
    const history = await getCityHistory(city);

    return {
      contents: [
        {
          uri: uri.href,
          mimeType: "application/json",
          text: JSON.stringify(history, null, 2),
        },
      ],
    };
  }
);

// 配合 list 回调，让 Client 能发现所有可用资源
server.resource(
  "city-detail",
  new ResourceTemplate("weather://cities/{city}/detail", {
    list: async () => {
      const cities = ["beijing", "shanghai", "guangzhou", "shenzhen"];
      return {
        resources: cities.map((city) => ({
          name: `${city} 详情`,
          uri: `weather://cities/${city}/detail`,
          mimeType: "application/json",
        })),
      };
    },
  }),
  async (uri, { city }) => {
    const detail = await getCityDetail(city);
    return {
      contents: [
        {
          uri: uri.href,
          mimeType: "application/json",
          text: JSON.stringify(detail, null, 2),
        },
      ],
    };
  }
);

// 声明支持订阅
const server = new McpServer({
  name: "weather-server",
  version: "1.0.0",
}, {
  capabilities: {
    resources: {
      subscribe: true,  // 启用订阅能力
      listChanged: true, // 启用资源列表变更通知
    },
  },
});

// 在数据变更时发送通知
async function onWeatherUpdate(city: string) {
  // 通知所有订阅了该资源的 Client
  await server.notification({
    method: "notifications/resources/updated",
    params: {
      uri: `weather://cities/${city}/current`,
    },
  });
}

// 资源列表变更时通知
async function onNewCityAdded() {
  await server.notification({
    method: "notifications/resources/list_changed",
  });
}

// ========== Prompt: 天气分析报告 ==========
server.prompt(
  "weather-analysis",              // Prompt 名称
  "生成城市天气分析报告，包含趋势预测和建议",  // 描述
  {
    city: z.string().describe("目标城市"),
    period: z.enum(["daily", "weekly", "monthly"])
      .describe("分析周期"),
    focus: z.string().optional()
      .describe("关注重点，如'出行'、'农业'、'能源'"),
  },
  async ({ city, period, focus }) => {
    const weatherData = await fetchWeather(city, "celsius");
    const forecast = await fetchForecast(city, 7);

    return {
      messages: [
        {
          role: "user",
          content: {
            type: "text",
            text: [
              `请为 ${city} 生成一份${period === "daily" ? "每日" : period === "weekly" ? "每周" : "每月"}天气分析报告。`,
              ``,
              `## 当前天气`,
              `- 温度: ${weatherData.temperature}°C`,
              `- 天气状况: ${weatherData.condition}`,
              `- 湿度: ${weatherData.humidity}%`,
              `- 风速: ${weatherData.wind_speed}`,
              ``,
              `## 未来预报`,
              forecast.map((f: any) => `- ${f.date}: ${f.condition}, ${f.low}°C ~ ${f.high}°C`).join("\n"),
              focus ? `\n## 特别关注\n请重点从"${focus}"角度分析影响。` : "",
              ``,
              `请包含以下内容：`,
              `1. 天气趋势总结`,
              `2. 对日常生活的影响和建议`,
              `3. ${focus ? `${focus}相关的具体建议` : "出行建议"}`,
            ].join("\n"),
          },
        },
      ],
    };
  }
);

// ========== Prompt: 对比分析 ==========
server.prompt(
  "city-comparison",
  "对比两个城市的天气状况",
  {
    city1: z.string().describe("第一个城市"),
    city2: z.string().describe("第二个城市"),
    aspect: z.enum(["temperature", "comfort", "travel"])
      .describe("对比维度"),
  },
  async ({ city1, city2, aspect }) => {
    const [w1, w2] = await Promise.all([
      fetchWeather(city1, "celsius"),
      fetchWeather(city2, "celsius"),
    ]);

    const aspectLabel = {
      temperature: "温度",
      comfort: "舒适度",
      travel: "出行适宜度",
    }[aspect];

    return {
      messages: [
        {
          role: "user",
          content: {
            type: "text",
            text: `对比 ${city1} 和 ${city2} 的${aspectLabel}：\n\n`
              + `${city1}: ${w1.temperature}°C, ${w1.condition}\n`
              + `${city2}: ${w2.temperature}°C, ${w2.condition}\n\n`
              + `请从${aspectLabel}角度进行详细对比分析。`,
          },
        },
      ],
    };
  }
);

                    由谁决定调用？
                         │
            ┌────────────┼────────────┐
            ▼            ▼            ▼
         LLM自主      用户选择      应用请求
         Tool         Prompt       Resource
            │            │            │
            ▼            ▼            ▼
     执行操作/计算    模板化交互    读取数据
     查询API         生成报告      获取配置
     修改状态        预设工作流    加载文件

server.tool(
  "weather_chart",
  "生成城市天气图表",
  {
    city: z.string().describe("城市名称"),
    chart_type: z.enum(["temperature", "humidity", "wind"])
      .describe("图表类型"),
  },
  async ({ city, chart_type }) => {
    // 生成图表（使用 chart.js + canvas 等库）
    const imageBuffer = await generateChart(city, chart_type);

    return {
      content: [
        {
          type: "image",
          data: imageBuffer.toString("base64"),
          mimeType: "image/png",
        },
      ],
    };
  }
);

server.tool(
  "batch_weather_report",
  "批量生成多个城市的天气报告",
  {
    cities: z.array(z.string()).describe("城市列表"),
  },
  async ({ cities }, { signal, meta }) => {
    const results: string[] = [];

    for (let i = 0; i < cities.length; i++) {
      // 检查是否被取消
      signal?.throwIfAborted();

      const report = await generateReport(cities[i]);
      results.push(report);

      // 发送进度通知
      await server.notification({
        method: "notifications/progress",
        params: {
          progress: i + 1,
          total: cities.length,
          progressToken: meta?.progressToken,
        },
      });
    }

    return {
      content: [{ type: "text", text: results.join("\n---\n") }],
    };
  }
);

#!/usr/bin/env node

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

const server = new McpServer(
  { name: "weather-server", version: "1.0.0" },
  {
    capabilities: {
      resources: { subscribe: true, listChanged: true },
    },
  }
);

// ━━━━━━━ Tools ━━━━━━━

server.tool("get_current_weather", "获取指定城市的当前天气信息", {
  city: z.string().describe("城市名称"),
  unit: z.enum(["celsius", "fahrenheit"]).optional().describe("温度单位"),
}, async ({ city, unit }) => {
  const u = unit ?? "celsius";
  const data = await fetchWeather(city, u);
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
});

server.tool("get_weather_forecast", "获取未来天气预报", {
  city: z.string().describe("城市名称"),
  days: z.number().min(1).max(7).optional().describe("预报天数"),
}, async ({ city, days }) => {
  const data = await fetchForecast(city, days ?? 3);
  const text = data
    .map((d: any) => `${d.date}: ${d.condition}, ${d.low}°C ~ ${d.high}°C`)
    .join("\n");
  return { content: [{ type: "text", text }] };
});

server.tool("compare_weather", "对比两个城市的天气", {
  city1: z.string().describe("城市1"),
  city2: z.string().describe("城市2"),
}, async ({ city1, city2 }) => {
  const [w1, w2] = await Promise.all([
    fetchWeather(city1, "celsius"),
    fetchWeather(city2, "celsius"),
  ]);
  const comparison = [
    `| 指标 | ${city1} | ${city2} |`,
    `|------|---------|---------|`,
    `| 温度 | ${w1.temperature}°C | ${w2.temperature}°C |`,
    `| 天气 | ${w1.condition} | ${w2.condition} |`,
    `| 湿度 | ${w1.humidity}% | ${w2.humidity}% |`,
    `| 风速 | ${w1.wind_speed} | ${w2.wind_speed} |`,
  ].join("\n");
  return { content: [{ type: "text", text: comparison }] };
});

// ━━━━━━━ Resources ━━━━━━━

server.resource("supported-cities", "weather://config/cities",
  async (uri) => ({
    contents: [{
      uri: uri.href,
      mimeType: "application/json",
      text: JSON.stringify([
        { name: "北京", code: "BJ" },
        { name: "上海", code: "SH" },
        { name: "广州", code: "GZ" },
      ], null, 2),
    }],
  })
);

server.resource("city-weather",
  new ResourceTemplate("weather://cities/{city}/current", {
    list: async () => ({
      resources: ["beijing", "shanghai", "guangzhou"].map((c) => ({
        name: `${c} 实时天气`,
        uri: `weather://cities/${c}/current`,
      })),
    }),
  }),
  async (uri, { city }) => {
    const data = await fetchWeather(city, "celsius");
    return {
      contents: [{
        uri: uri.href,
        mimeType: "application/json",
        text: JSON.stringify(data, null, 2),
      }],
    };
  }
);

// ━━━━━━━ Prompts ━━━━━━━

server.prompt("weather-analysis", "生成城市天气分析报告", {
  city: z.string().describe("目标城市"),
  period: z.enum(["daily", "weekly", "monthly"]).describe("分析周期"),
}, async ({ city, period }) => {
  const weather = await fetchWeather(city, "celsius");
  return {
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: `请为${city}生成${period === "daily" ? "每日" : period === "weekly" ? "每周" : "每月"}天气分析。\n`
          + `当前: ${weather.temperature}°C, ${weather.condition}, 湿度${weather.humidity}%`,
      },
    }],
  };
});

// ━━━━━━━ 启动 ━━━━━━━

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

main().catch((err) => {
  process.stderr.write(`Fatal: ${err}\n`);
  process.exit(1);
});

// ━━━━━━━ 数据层 ━━━━━━━

async function fetchWeather(city: string, unit: string) {
  return {
    city,
    temperature: unit === "fahrenheit" ? 82 : 28,
    unit: unit === "fahrenheit" ? "°F" : "°C",
    condition: "晴朗",
    humidity: 45,
    wind_speed: "12 km/h",
    updated_at: new Date().toISOString(),
  };
}

async function fetchForecast(city: string, days: number) {
  const conditions = ["晴", "多云", "小雨", "阴"];
  return Array.from({ length: days }, (_, i) => ({
    date: new Date(Date.now() + i * 86400000).toISOString().split("T")[0],
    high: Math.round(25 + Math.random() * 10),
    low: Math.round(15 + Math.random() * 8),
    condition: conditions[Math.floor(Math.random() * conditions.length)],
  }));
}

flowchart LR
    subgraph 开发阶段
        A["npm init + 安装依赖"] --> B["编写 MCP Server 代码"]
        B --> C["tsc 编译"]
        C --> D["MCP Inspector 调试"]
    end

    subgraph 集成阶段
        D --> E["claude mcp add"]
        E --> F["Claude Code 中测试"]
        F --> G{"功能正确?"}
        G -->|否| B
        G -->|是| H["项目级 .mcp.json"]
    end

    subgraph 发布阶段
        H --> I["npm publish"]
        I --> J["MCP Registry 注册"]
        J --> K["社区使用"]
    end

{
  "mcpServers": {
    "weather-server": {
      "type": "stdio",
      "command": "node",
      "args": ["./mcp-servers/weather/dist/index.js"]
    }
  }
}

# 全局配置（所有项目可用）
claude mcp add --scope user weather-server -- node ~/mcp-servers/weather/dist/index.js

项目级 .mcp.json > 用户级 ~/.claude.json > 系统级配置
     (高优先)                           (低优先)

# 方式一：通过 npm scripts（已在 package.json 中配置）
npm run inspect

# 方式二：直接使用 npx
npx @modelcontextprotocol/inspector node dist/index.js

# 方式三：带环境变量
npx @modelcontextprotocol/inspector \
  -e API_KEY=your_key \
  node dist/index.js

{
  "mcpServers": {
    "weather-server": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"]
    }
  }
}

# 确保入口文件有 shebang
head -1 dist/index.js
# 应输出: #!/usr/bin/env node

# 确保构建产物是最新的
npm run build

# 检查 package.json 字段
npm pack --dry-run

# 登录 npm（首次）
npm login

# 发布
npm publish --access public

# 发布后，用户可以这样使用：
# claude mcp add weather-server -- npx mcp-weather-server

# 安装 MCP CLI
npm install -g @modelcontextprotocol/cli

# 发布到 Registry
mcp publish

{
  "name": "weather-server",
  "description": "天气查询 MCP Server，支持全球城市天气、预报和对比",
  "repository": "https://github.com/yourname/mcp-weather-server",
  "npmPackage": "mcp-weather-server",
  "categories": ["weather", "utilities"],
  "tools": [
    {
      "name": "get_current_weather",
      "description": "获取当前天气"
    },
    {
      "name": "get_weather_forecast",
      "description": "获取天气预报"
    },
    {
      "name": "compare_weather",
      "description": "对比城市天气"
    }
  ]
}

// 使用 Zod 进行严格验证
server.tool("search_weather", "搜索天气记录", {
  query: z.string().min(1).max(200)
    .regex(/^[\w\s\u4e00-\u9fff,.-]+$/)  // 只允许安全字符
    .describe("搜索关键词"),
}, async ({ query }) => {
  // ...
});

server.tool("risky_operation", "需要安全处理的操作", {
  param: z.string(),
}, async ({ param }) => {
  try {
    const result = await callExternalAPI(param);
    return { content: [{ type: "text", text: JSON.stringify(result) }] };
  } catch (error) {
    // 返回错误信息，而非抛出异常
    return {
      content: [{
        type: "text",
        text: `操作失败: ${error instanceof Error ? error.message : "未知错误"}`,
      }],
      isError: true,
    };
  }
});

// 差：暴露了 API 端点
server.tool("get_user", "调用 /api/v2/users/{id} 获取用户", ...);

// 好：描述功能而非实现
server.tool("get_user", "获取指定用户的基本信息", ...);

flowchart TD
    START["Server 无法工作"] --> Q1{"能启动吗?"}
    Q1 -->|否| Q2{"Node版本?"}
    Q2 -->|< 18| A1["升级 Node.js"]
    Q2 -->|>= 18| Q3{"模块错误?"}
    Q3 -->|是| A2["检查 type:module 和 .js 后缀"]
    Q3 -->|否| A3["检查 import 路径"]

    Q1 -->|能启动| Q4{"Inspector 能调通?"}
    Q4 -->|否| Q5{"Schema 正确?"}
    Q5 -->|否| A4["用 Zod 验证参数"]
    Q5 -->|是| A5["检查 Handler 逻辑"]

    Q4 -->|能| Q6{"Claude Code 可见?"}
    Q6 -->|否| A6["检查 claude mcp list"]
    Q6 -->|是| A7["✅ 正常工作"]