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!

说明

根据 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 的响应。

说明

如果觉得每次都输入构建命令很麻烦，可以运行 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

说明

执行 npm publish 时，将 package.json 的 name 设置为 @username/my-mcp-server 这样的形式，更容易识别出这是自己创建的软件包。

警告

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"
  ]
}