建客 MCP 服

造客 MCP 服以露域專工於 AI 輔。

用

• 當露客能於 Claude Code 或 Claude Desktop
• 建 mcptools 之外專工
• 造域專 AI 輔整
• 包現 API 或服為 MCP 工

入

• 必：當露工列（名、述、參、行）
• 必：施語（Node.js 或 R）
• 必：傳類（stdio 或 HTTP）
• 可：認需
• 可：Docker 包需

行

一：定工規

書碼前→每工定：

tools:
  - name: query_database
    description: Execute a read-only SQL query against the analysis database
    parameters:
      query:
        type: string
        description: SQL SELECT query to execute
        required: true
      limit:
        type: integer
        description: Maximum rows to return
        default: 100
    returns: JSON array of result rows

  - name: run_analysis
    description: Execute a predefined statistical analysis by name
    parameters:
      analysis_name:
        type: string
        description: Name of the analysis to run
        enum: [descriptive, regression, survival]
      dataset:
        type: string
        description: Dataset identifier
        required: true

得： 每工以 YAML 或 markdown 規附名、述、參（含類、默、必旗）、返類已錄於書碼前。

敗： 工規不清→訪域專家或察現 API 文以定參類與返格。

二：施於 Node.js（用 MCP SDK）

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

const server = new McpServer({
  name: "my-analysis-server",
  version: "1.0.0",
});

// Define tools
server.tool(
  "query_database",
  "Execute a read-only SQL query against the analysis database",
  {
    query: z.string().describe("SQL SELECT query"),
    limit: z.number().default(100).describe("Max rows to return"),
  },
  async ({ query, limit }) => {
    // Validate read-only
    if (!/^\s*SELECT/i.test(query)) {
      return {
        content: [{ type: "text", text: "Error: Only SELECT queries allowed" }],
        isError: true,
      };
    }

    const results = await executeQuery(query, limit);
    return {
      content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
    };
  }
);

server.tool(
  "run_analysis",
  "Execute a predefined statistical analysis",
  {
    analysis_name: z.enum(["descriptive", "regression", "survival"]),
    dataset: z.string().describe("Dataset identifier"),
  },
  async ({ analysis_name, dataset }) => {
    const result = await runAnalysis(analysis_name, dataset);
    return {
      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
    };
  }
);

// Start server with stdio transport
const transport = new StdioServerTransport();
await server.connect(transport);

得： 可行 server.js 檔—引 MCP SDK、以 Zod 綱定工、以 stdio 傳連。node server.js 無誤始服。

敗： 驗 @modelcontextprotocol/sdk 與 zod 已裝（npm install）。察引徑合 SDK 版（SDK 於版間重排導出）。

三：施於 R（用 mcptools）

# server.R
library(mcptools)

# Register custom tools
mcp_tool(
  name = "query_database",
  description = "Execute a read-only SQL query",
  parameters = list(
    query = list(type = "string", description = "SQL SELECT query"),
    limit = list(type = "integer", description = "Max rows", default = 100)
  ),
  handler = function(query, limit = 100) {
    if (!grepl("^\\s*SELECT", query, ignore.case = TRUE)) {
      stop("Only SELECT queries allowed")
    }
    result <- DBI::dbGetQuery(con, paste(query, "LIMIT", limit))
    jsonlite::toJSON(result, auto_unbox = TRUE)
  }
)

# Start server
mcptools::mcp_server()

得： 可行 server.R 檔—以 mcp_tool() 註客工、以 mcp_server() 始服。Rscript server.R 始 MCP 服。

敗： 驗 mcptools 自 GitHub 裝（remotes::install_github("posit-dev/mcptools")）。察處函簽合參定。

四：設案構

my-mcp-server/
├── package.json          # Node.js dependencies
├── server.js             # Server implementation
├── tools/                # Tool implementations
│   ├── database.js
│   └── analysis.js
├── test/                 # Tests
│   └── tools.test.js
├── Dockerfile            # Container packaging
└── README.md             # Setup instructions

得： 案目造附 server.js（或 server.R）、package.json、tools/ 目以分模工、test/ 目以試。

敗： 目構不合施語→調。R 服或用 R/ 代 tools/ 與 tests/testthat/ 代 test/。

五：試服

stdio 手試：

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node server.js

註於 Claude Code：

claude mcp add my-server stdio "node" "/path/to/server.js"

驗工現：

起 Claude Code 會而察客工列且可行。

得： tools/list JSON-RPC 呼返諸定工附正名與綱。claude mcp list 示服已註。工於 Claude Code 會可呼。

敗： tools/list 返空陣→工未註於 server.connect() 前。Claude Code 不得服→驗 claude mcp add 命徑絕而二進可行。

六：加誤處

server.tool("risky_operation", "...", schema, async (params) => {
  try {
    const result = await performOperation(params);
    return {
      content: [{ type: "text", text: JSON.stringify(result) }],
    };
  } catch (error) {
    return {
      content: [{ type: "text", text: `Error: ${error.message}` }],
      isError: true,
    };
  }
});

得： 每工處以 try/catch 包。誤入返 isError: true 附述訊非崩服程。

敗： 服仍崩於劣入→察 try/catch 包全處體含諸 async 操。確保 promise 於 try 區內 await。

七：包發

造 package.json 附 bin 條：

{
  "name": "my-mcp-server",
  "version": "1.0.0",
  "bin": {
    "my-mcp-server": "./server.js"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0",
    "zod": "^3.22.0"
  }
}

用者可裝與配：

npm install -g my-mcp-server
claude mcp add my-server stdio "my-mcp-server"

得： package.json 附 bin 條指服入。用者以 npm install -g 全裝與 claude mcp add 註。

敗： bin 全裝後不行→確 server.js 首行有 shebang（#!/usr/bin/env node）且可行。驗包名不撞現 npm 包。

驗

• 服無誤始
• tools/list 返諸定工附正綱
• 每工以有效入正行
• 工於誤入返宜誤
• 服以 stdio 傳合 Claude Code
• 工於 Claude 會可發現且可用

忌

• 阻操：MCP 服當異處請。久操阻他工呼。
• 缺誤處：未處異崩服。必以 try/catch 包工處。
• 綱不合：工參綱當全合處所候
• stdio 緩：用 stdio 傳→確出已沖。Node.js 默緩 stdout。
• 安：MCP 服與程同權。精驗入，尤於殼命或庫查。

參

• configure-mcp-server — 連已建服與客
• troubleshoot-mcp-connection — 除連題
• containerize-mcp-server — 以 Docker 包服