Local Mcp Server Tutorial

本地 MCP 服务器教程

这是一个创建本地 MCP 服务器的教程。

准备工作

• Node.js（推荐 v22）
• Claude Desktop 或其他 MCP 客户端

教程

1. 创建项目

npx giget@latest gh:7nohe/local-mcp-server-tutorial my-mcp-server
cd my-mcp-server
npm install
git init
git branch -M main
git add .
git commit -m "Initial commit"

2. 构建并运行 TypeScript 代码

尝试构建并运行以下 src/index.ts 中的内容，使其成为可执行文件。

#!/usr/bin/env node
async function main() {
  console.error("Hello, world!");
}

main().catch((error) => {
  console.error("Fatal error in main():", error);
  process.exit(1);
});

npm run build
./dist/index.js
# Hello, world!

[!NOTE] 通过 package.json 的 bin 属性设置，将在 node_modules/.bin/ 下创建符号链接，从而可以执行 ./dist/index.js。

3. 安装必要的库

npm install @modelcontextprotocol/sdk zod

4. 实现 MCP 服务器

#!/usr/bin/env node
import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// 创建 MCP 服务器的实例。
const server = new McpServer({
  name: "my-mcp-server",
  version: "1.0.0",
  capabilities: {
    resources: {},
    tools: {},
  },
});

async function main() {
  const transport = new StdioServerTransport();
  // Resources

  // 定义一个返回 "Hello, world!" 的 Resource。
  server.resource(
    "Greeting",
    "greeting://hello",
    (uri, { }) => {
      console.log(uri)
      return {
        contents: [
          {
            uri: uri.href,
            text: "Hello, world!",
          }
        ]
      }
    })

  // 对于动态 Resource，使用 ResourceTemplate 类。
  // list 选项是用于列出与此模板匹配的所有 Resources 的回调。如果使用 ResourceTemplate，则必须指定为 undefined。
  server.resource(
    "Greeting with name",
    new ResourceTemplate("greeting://hello/{name}", {
      // list
      list: async () => {
        // 例如，您可以在此处调用 API 以获取用户列表。
        await setTimeout(() => { }, 1000);
        // 在这里返回虚拟数据。
        return {
          resources:
            [
              { name: "Alice", uri: "greeting://hello/Alice" },
              { name: "Bob", uri: "greeting://hello/Bob" },
              { name: "Charlie", uri: "greeting://hello/Charlie" },
            ]
        }
      },
    }),
    (uri, { name }) => {
      return {
        contents: [
          {
            uri: uri.href,
            text: `Hello, ${name}!`,
          }
        ]
      }
    })

    // Prompts
  server.prompt(
    "Japanese Translation",
    {
      englishText: z.string().describe("翻译する英語のテキスト"),
    },
    ({ englishText }) => ({
      messages: [{
        role: 'user',
        content: {
          type: 'text',
          text: `あなたはプロの翻訳者です。次のテキストを日本語に翻訳してください: ${englishText}`,
        }
      }]
    }));


  // Tools
  server.tool(
    "calculate-bmi",
    "BMIの計算を行います",
    {
      weightKg: z.number().describe("体重(kg)"),
      heightM: z.number().describe("身長(m)"),
    },
    ({ weightKg, heightM }) => {
      return {
        content: [
          {
            type: "text",
            text: String(weightKg / (heightM * heightM)),
          }
        ]
      }
    })

  server.connect(transport);
  console.error("my-mcp-server started");
}

main().catch((error) => {
  console.error("Fatal error in main():", error);
  process.exit(1);
});

5. 调试

使用 Inspector 进行调试。

npx @modelcontextprotocol/inspector ./dist/index.js

在浏览器中打开 http://127.0.0.1:6274，您可以检查定义的 Resources 和 Tools 的响应。

[!NOTE] 如果每次都输入构建命令很麻烦，可以运行 npm run watch，它会在每次更改时自动构建。

接下来，在 Claude Desktop 中进行操作确认。 从 Settings -> Developer -> Edit Config 在编辑器中打开 claude_desktop_config.json，并进行如下设置：

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "/<Projectまでの絶対パス>/my-mcp-server/dist/index.js"
    }
  }
}

保存后，重新启动 Claude Desktop。

如果可以从 Tools 按钮确认列表，并且可以从 Attach from MCP 按钮选择 Resource 和 Prompt，则表示成功。

6. 发布包

npm login
npm publish

[!NOTE] 在 npm publish 时，通过将 package.json 的 name 设置为 @username/my-mcp-server 之类的名称，可以更容易地识别您创建的包。

[!WARNING] npm 包一旦发布就很难删除，因此请谨慎发布。

要点：

• 在 package.json 的 scripts.prepublishOnly 中设置构建，以便在 npm publish 时自动构建。
• 在 package.json 的 bin 属性中进行如下设置，使其可以作为 CLI 执行。

"bin": "./dist/index.js"

• 在 package.json 的 files 属性中进行如下设置，以便仅发布 dist 文件夹。

"files": [
  "dist"
]

7. 运行已发布的 MCP 服务器

将 Claude Desktop 的设置更改如下：

"my-mcp-server": {
  "command": "npx",
  "args": [
    "@your-name/my-mcp-server@latest"
  ]
}