用 Node.js 开发一个 MCP 服务：从协议本质到最佳实践用 Node.js 开发一个 MCP 服务：从协议本质到最佳实践

1{
2  name: "get_weather",             // 唯一标识
3  title: "天气查询",                // UI 展示名称（可选）
4  description: "获取指定城市的天气", // 给 LLM 看的描述（很重要！）
5  inputSchema: {                   // JSON Schema，定义入参
6    type: "object",
7    properties: {
8      city: { type: "string", description: "城市名称" }
9    },
10    required: ["city"]
11  }
12}

1{
2  "compilerOptions": {
3    "target": "ES2022",
4    "module": "Node16",
5    "moduleResolution": "Node16",
6    "outDir": "./dist",
7    "rootDir": "./src",
8    "strict": true,
9    "esModuleInterop": true,
10    "skipLibCheck": true,
11    "forceConsistentCasingInFileNames": true
12  },
13  "include": ["src/**/*"],
14  "exclude": ["node_modules"]
15}

1import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
3import { z } from "zod";
4
5// 1. 创建 Server 实例（声明名称和版本）
6const server = new McpServer({
7  name: "my-mcp-server",
8  version: "1.0.0",
9});
10
11// 2. 注册一个 Tool
12server.registerTool(
13  "add",
14  {
15    title: "加法",
16    description: "计算两个数字的和",
17    inputSchema: {
18      a: z.number().describe("第一个数字"),
19      b: z.number().describe("第二个数字"),
20    },
21  },
22  async ({ a, b }) => ({
23    content: [{ type: "text", text: `${a + b}` }],
24  })
25);
26
27// 3. 连接传输层并启动
28const transport = new StdioServerTransport();
29await server.connect(transport);
30
31// 注意：使用 console.error 而不是 console.log！
32console.error("MCP Server is running on stdio");

1server.registerTool(
2  "get_github_user",
3  {
4    title: "GitHub 用户信息",
5    description: "根据用户名查询 GitHub 用户的公开信息",
6    inputSchema: {
7      username: z.string().min(1).describe("GitHub 用户名"),
8    },
9  },
10  async ({ username }) => {
11    try {
12      const response = await fetch(
13        `https://api.github.com/users/${username}`,
14        {
15          headers: { "User-Agent": "my-mcp-server/1.0.0" },
16        }
17      );
18
19      if (!response.ok) {
20        return {
21          content: [
22            {
23              type: "text",
24              text: `查询失败：${response.status} ${response.statusText}`,
25            },
26          ],
27          isError: true,
28        };
29      }
30
31      const user = await response.json();
32      return {
33        content: [
34          {
35            type: "text",
36            text: [
37              `用户名: ${user.login}`,
38              `昵称: ${user.name || "未设置"}`,
39              `Bio: ${user.bio || "无"}`,
40              `公开仓库数: ${user.public_repos}`,
41              `关注者: ${user.followers}`,
42              `主页: ${user.html_url}`,
43            ].join("\n"),
44          },
45        ],
46      };
47    } catch (error) {
48      return {
49        content: [
50          { type: "text", text: `请求异常：${(error as Error).message}` },
51        ],
52        isError: true,
53      };
54    }
55  }
56);

1import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
2
3// 静态资源
4server.registerResource(
5  "project-readme",            // 资源标识
6  "file:///project/README.md", // URI
7  {
8    title: "Project README",
9    description: "项目说明文件",
10    mimeType: "text/markdown",
11  },
12  async (uri) => ({
13    contents: [
14      {
15        uri: uri.href,
16        mimeType: "text/markdown",
17        text: "# My Project\n\nThis is the README.",
18      },
19    ],
20  })
21);
22
23// 动态资源模板
24const userProfileTemplate = new ResourceTemplate("users://{userId}/profile");
25
26server.registerResource(
27  "user-profile",
28  userProfileTemplate,
29  {
30    title: "用户资料",
31    description: "用户资料 JSON",
32    mimeType: "application/json",
33  },
34  async (uri, { userId }) => {
35    const profile = await fetchUserProfile(userId);
36    return {
37      contents: [
38        {
39          uri: uri.href,
40          mimeType: "application/json",
41          text: JSON.stringify(profile),
42        },
43      ],
44    };
45  }
46);

1server.registerPrompt(
2  "code_review",
3  {
4    title: "代码审查",
5    description: "审查代码并给出改进建议",
6    argsSchema: {
7      code: z.string().describe("待审查的代码"),
8      language: z.string().optional().describe("编程语言"),
9    },
10  },
11  async ({ code, language }) => ({
12    messages: [
13      {
14        role: "user",
15        content: {
16          type: "text",
17          text: [
18            `请审查以下${language ? language + " " : ""}代码：`,
19            "",
20            "```" + (language || ""),
21            code,
22            "```",
23            "",
24            "请从以下几个方面给出建议：",
25            "1. 代码质量和可读性",
26            "2. 潜在的 bug 或边界情况",
27            "3. 性能优化空间",
28            "4. 最佳实践合规性",
29          ].join("\n"),
30        },
31      },
32    ],
33  })
34);

1#!/usr/bin/env node
2
3import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
4import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
5import { z } from "zod";
6
7const GITHUB_API = "https://api.github.com";
8const USER_AGENT = "github-mcp-server/1.0.0";
9
10// ---------- 辅助函数 ----------
11
12async function githubRequest<T>(path: string): Promise<T> {
13  const response = await fetch(`${GITHUB_API}${path}`, {
14    headers: {
15      "User-Agent": USER_AGENT,
16      Accept: "application/vnd.github.v3+json",
17      // 如果有 token：
18      // "Authorization": `Bearer ${process.env.GITHUB_TOKEN}`,
19    },
20  });
21
22  if (!response.ok) {
23    throw new Error(`GitHub API error: ${response.status} ${response.statusText}`);
24  }
25
26  return response.json() as Promise<T>;
27}
28
29function formatError(error: unknown): string {
30  return error instanceof Error ? error.message : String(error);
31}
32
33// ---------- 创建 Server ----------
34
35const server = new McpServer({
36  name: "github-mcp-server",
37  version: "1.0.0",
38});
39
40// ---------- Tools ----------
41
42// 查询用户信息
43server.registerTool(
44  "get_user",
45  {
46    title: "GitHub 用户信息",
47    description: "查询 GitHub 用户的公开信息",
48    inputSchema: {
49      username: z.string().min(1).describe("GitHub 用户名"),
50    },
51  },
52  async ({ username }) => {
53    try {
54      const user = await githubRequest<Record<string, unknown>>(
55        `/users/${username}`
56      );
57      return {
58        content: [
59          {
60            type: "text" as const,
61            text: JSON.stringify(user, null, 2),
62          },
63        ],
64      };
65    } catch (error) {
66      return {
67        content: [{ type: "text" as const, text: formatError(error) }],
68        isError: true,
69      };
70    }
71  }
72);
73
74// 搜索仓库
75server.registerTool(
76  "search_repos",
77  {
78    title: "GitHub 仓库搜索",
79    description: "根据关键词搜索 GitHub 仓库",
80    inputSchema: {
81      query: z.string().min(1).describe("搜索关键词"),
82      sort: z
83        .enum(["stars", "forks", "updated"])
84        .optional()
85        .describe("排序方式"),
86      limit: z
87        .number()
88        .min(1)
89        .max(30)
90        .optional()
91        .default(5)
92        .describe("返回数量，默认 5"),
93    },
94  },
95  async ({ query, sort, limit }) => {
96    try {
97      const params = new URLSearchParams({
98        q: query,
99        per_page: String(limit),
100      });
101      if (sort) params.set("sort", sort);
102
103      const result = await githubRequest<{
104        total_count: number;
105        items: Array<{
106          full_name: string;
107          description: string | null;
108          stargazers_count: number;
109          language: string | null;
110          html_url: string;
111        }>;
112      }>(`/search/repositories?${params}`);
113
114      const formatted = result.items
115        .map(
116          (repo, i) =>
117            `${i + 1}. **${repo.full_name}** ⭐${repo.stargazers_count}\n` +
118            `   ${repo.description || "无描述"}\n` +
119            `   语言: ${repo.language || "未知"} | ${repo.html_url}`
120        )
121        .join("\n\n");
122
123      return {
124        content: [
125          {
126            type: "text" as const,
127            text: `共找到 ${result.total_count} 个仓库，展示前 ${limit} 个：\n\n${formatted}`,
128          },
129        ],
130      };
131    } catch (error) {
132      return {
133        content: [{ type: "text" as const, text: formatError(error) }],
134        isError: true,
135      };
136    }
137  }
138);
139
140// 获取仓库的 README
141server.registerTool(
142  "get_repo_readme",
143  {
144    title: "仓库 README",
145    description: "获取指定 GitHub 仓库的 README 内容",
146    inputSchema: {
147      owner: z.string().describe("仓库所有者"),
148      repo: z.string().describe("仓库名称"),
149    },
150  },
151  async ({ owner, repo }) => {
152    try {
153      const response = await fetch(
154        `${GITHUB_API}/repos/${owner}/${repo}/readme`,
155        {
156          headers: {
157            "User-Agent": USER_AGENT,
158            Accept: "application/vnd.github.raw+json",
159          },
160        }
161      );
162
163      if (!response.ok) {
164        throw new Error(`${response.status} ${response.statusText}`);
165      }
166
167      const readme = await response.text();
168      return {
169        content: [{ type: "text" as const, text: readme }],
170      };
171    } catch (error) {
172      return {
173        content: [{ type: "text" as const, text: formatError(error) }],
174        isError: true,
175      };
176    }
177  }
178);
179
180// ---------- Resources ----------
181
182server.registerResource(
183  "github-rate-limit",
184  "github://rate-limit",
185  {
186    title: "GitHub Rate Limit",
187    description: "GitHub API 速率限制信息",
188    mimeType: "application/json",
189  },
190  async (uri) => {
191    const data = await githubRequest<Record<string, unknown>>("/rate_limit");
192    return {
193      contents: [
194        {
195          uri: uri.href,
196          mimeType: "application/json",
197          text: JSON.stringify(data, null, 2),
198        },
199      ],
200    };
201  }
202);
203
204// ---------- Prompts ----------
205
206server.registerPrompt(
207  "analyze_repo",
208  {
209    title: "仓库分析",
210    description: "分析一个 GitHub 仓库的技术栈和架构",
211    argsSchema: {
212      owner: z.string().describe("仓库所有者"),
213      repo: z.string().describe("仓库名称"),
214    },
215  },
216  async ({ owner, repo }) => ({
217    messages: [
218      {
219        role: "user" as const,
220        content: {
221          type: "text" as const,
222          text: [
223            `请帮我分析 GitHub 仓库 ${owner}/${repo}，包括：`,
224            "",
225            "1. 项目概述和用途",
226            "2. 技术栈分析（语言、框架、工具链）",
227            "3. 项目架构和代码组织方式",
228            "4. 代码质量评估",
229            "5. 值得学习的设计模式或最佳实践",
230            "",
231            "请先使用 get_user 和 search_repos 等工具获取相关信息。",
232          ].join("\n"),
233        },
234      },
235    ],
236  })
237);
238
239// ---------- 启动 ----------
240
241async function main() {
242  const transport = new StdioServerTransport();
243  await server.connect(transport);
244  console.error("GitHub MCP Server running on stdio");
245}
246
247main().catch((error) => {
248  console.error("Fatal error:", error);
249  process.exit(1);
250});

1// ❌ 差的描述
2server.registerTool("query", { description: "查询数据" }, ...);
3
4// ✅ 好的描述
5server.registerTool(
6  "search_products",
7  {
8    description: "根据关键词搜索商品列表，返回商品名称、价格和库存信息。支持按价格排序。",
9    inputSchema: { ... },
10  },
11  ...
12);

1import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
3import express from "express";
4
5const app = express();
6const server = new McpServer({
7  name: "my-remote-server",
8  version: "1.0.0",
9});
10
11// 注册 Tools / Resources / Prompts（同上）...
12
13// 设置 HTTP transport
14app.post("/mcp", async (req, res) => {
15  const transport = new StreamableHTTPServerTransport("/mcp");
16  await server.connect(transport);
17  await transport.handleRequest(req, res);
18});
19
20app.listen(3000, () => {
21  console.log("MCP Server listening on http://localhost:3000/mcp");
22});