mcp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

mcp - MCP Server 作成

mcp - MCP Server 创建

Model Context Protocol (MCP) サーバーの作成・管理。

Model Context Protocol (MCP) 服务器的创建与管理。

概要

MCP は Claude Code にカスタムツールを追加するためのプロトコル。

用途:

プロジェクト固有のツール提供
外部サービス連携
自動化タスク

MCP 是用于为Claude Code添加自定义工具的协议。

用途:

提供项目专属工具
外部服务集成
自动化任务

基本構造

基本结构

javascript

// scripts/mcp/my-tool.js
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server(
  { name: "my-tool", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// ツール一覧
server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "my_custom_tool",
      description: "カスタムツールの説明",
      inputSchema: {
        type: "object",
        properties: {
          param1: { type: "string", description: "パラメータ1" },
        },
        required: ["param1"],
      },
    },
  ],
}));

// ツール実行
server.setRequestHandler("tools/call", async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "my_custom_tool") {
    const result = await doSomething(args.param1);
    return { content: [{ type: "text", text: JSON.stringify(result) }] };
  }

  throw new Error(`Unknown tool: ${name}`);
});

// サーバー起動
const transport = new StdioServerTransport();
await server.connect(transport);

javascript

// scripts/mcp/my-tool.js
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server(
  { name: "my-tool", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// 工具列表
server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "my_custom_tool",
      description: "自定义工具的说明",
      inputSchema: {
        type: "object",
        properties: {
          param1: { type: "string", description: "参数1" },
        },
        required: ["param1"],
      },
    },
  ],
}));

// 工具执行
server.setRequestHandler("tools/call", async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "my_custom_tool") {
    const result = await doSomething(args.param1);
    return { content: [{ type: "text", text: JSON.stringify(result) }] };
  }

  throw new Error(`Unknown tool: ${name}`);
});

// 服务器启动
const transport = new StdioServerTransport();
await server.connect(transport);

設定

配置

プロジェクトレベル (.mcp.json)

项目级别 (.mcp.json)

json

{
  "mcpServers": {
    "my-tool": {
      "command": "node",
      "args": ["scripts/mcp/my-tool.js"]
    }
  }
}

json

{
  "mcpServers": {
    "my-tool": {
      "command": "node",
      "args": ["scripts/mcp/my-tool.js"]
    }
  }
}

ユーザーレベル (~/.claude/settings.json)

用户级别 (~/.claude/settings.json)

json

{
  "mcpServers": {
    "my-global-tool": {
      "command": "node",
      "args": ["/path/to/tool.js"]
    }
  }
}

json

{
  "mcpServers": {
    "my-global-tool": {
      "command": "node",
      "args": ["/path/to/tool.js"]
    }
  }
}

実用例

实用示例

テストランナー

测试运行器

javascript

server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "run_tests",
      description: "ユニットテストを実行",
      inputSchema: {
        type: "object",
        properties: {
          pattern: { type: "string", description: "テストパターン" },
        },
      },
    },
  ],
}));

server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "run_tests") {
    const pattern = request.params.arguments?.pattern || "";
    const result = await runTests(pattern);
    return { content: [{ type: "text", text: result }] };
  }
});

async function runTests(pattern) {
  const { execSync } = await import("child_process");
  try {
    const output = execSync(`npm test -- ${pattern}`, { encoding: "utf-8" });
    return output;
  } catch (error) {
    return error.stdout + error.stderr;
  }
}

javascript

server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "run_tests",
      description: "执行单元测试",
      inputSchema: {
        type: "object",
        properties: {
          pattern: { type: "string", description: "测试模式" },
        },
      },
    },
  ],
}));

server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "run_tests") {
    const pattern = request.params.arguments?.pattern || "";
    const result = await runTests(pattern);
    return { content: [{ type: "text", text: result }] };
  }
});

async function runTests(pattern) {
  const { execSync } = await import("child_process");
  try {
    const output = execSync(`npm test -- ${pattern}`, { encoding: "utf-8" });
    return output;
  } catch (error) {
    return error.stdout + error.stderr;
  }
}

DB クエリ

数据库查询

javascript

{
  name: "query_database",
  description: "データベースにクエリを実行",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string", description: "SQL クエリ" },
    },
    required: ["query"],
  },
}

javascript

{
  name: "query_database",
  description: "在数据库中执行查询",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string", description: "SQL 查询" },
    },
    required: ["query"],
  },
}

コンテキスト節約

上下文节约

使わないMCPサーバーを無効化してコンテキストを節約:

json

// .mcp.json
{
  "mcpServers": {
    "frequently-used": { "command": "node", "args": ["tool1.js"] }
  },
  "disabledMcpServers": [
    "rarely-used-tool",
    "heavy-context-tool"
  ]
}

禁用不使用的MCP服务器以节约上下文：

json

// .mcp.json
{
  "mcpServers": {
    "frequently-used": { "command": "node", "args": ["tool1.js"] }
  },
  "disabledMcpServers": [
    "rarely-used-tool",
    "heavy-context-tool"
  ]
}

デバッグ

调试

bash

undefined

bash

undefined

直接実行

直接执行

node scripts/mcp/my-tool.js

ログ確認

查看日志

DEBUG=mcp* node scripts/mcp/my-tool.js

Claude Code で確認

在Claude Code中查看

/mcp コマンドで接続状態を確認

使用/mcp命令确认连接状态

---

---

ベストプラクティス

最佳实践

エラーハンドリング: 常に try-catch で囲む
タイムアウト: 長時間処理は避ける（30秒以内）
説明を明確に: description はツール選択の判断材料
inputSchema 必須: パラメータの型を明示
10個以下: プロジェクトあたりのMCP数を制限

错误处理: 始终用try-catch包裹
超时控制: 避免长时间处理（30秒以内）
明确说明: description是工具选择的判断依据
必填inputSchema: 明确参数类型
数量限制: 每个项目的MCP数量控制在10个以内