MCP 完整研究指南

1
~/.config/opencode/
2
├── opencode.json          # OpenCode 主配置（AI Provider 设置）
3
├── oh-my-opencode.json    # 插件配置（Agent 模型映射）
4
├── skills/
5
│   └── mcp-builder/       # MCP 构建技能
6
│       ├── SKILL.md       # 开发指南
7
│       └── reference/     # 参考文档
8
│           ├── python_mcp_server.md
9
│           ├── node_mcp_server.md
10
│           └── mcp_best_practices.md
11
└── node_modules/oh-my-opencode/
12
    └── dist/
13
        ├── mcp/           # 内置 MCP 客户端
14
        ├── features/
15
        │   ├── skill-mcp-manager/   # MCP 连接管理器
16
        │   └── claude-code-mcp-loader/  # Claude MCP 加载器
17
        └── tools/skill-mcp/  # skill_mcp 工具

1
{
2
  "mcpServers": {
3
    "server-name": {
4
      "type": "stdio",
5
      "command": "npx",
6
      "args": ["-y", "@your/mcp-server"],
7
      "env": {
8
        "API_KEY": "your-api-key"
9
      }
10
    }
11
  }
12
}

1
┌─────────────────┐     JSON-RPC      ┌──────────────────┐
2
│   AI Client     │ ◄───────────────► │   MCP Server     │
3
│  (OpenCode/     │                   │  (Python/Node)   │
4
│   Claude)       │                   │                  │
5
└─────────────────┘                   └──────────────────┘
6
        │                                       │
7
        │            Transport Layer            │
8
        ├─ stdio    ◄────────────────────────►  │
9
        │   stdin /stdout                       │
10
        │                                       │
11
        └─ Streamable HTTP   ◄───────────────►  │
12
            POST / mcp

1
// stdio 传输（本地）
2
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
3

4
const transport = new StdioServerTransport();
5
await server.connect(transport);
6

7
// HTTP 传输（远程）
8
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
9

10
const transport = new StreamableHTTPServerTransport({
11
  sessionIdGenerator: undefined,
12
  enableJsonResponse: true
13
});
14
await server.connect(transport);

1
my-service-mcp-server/
2
├── package.json
3
├── tsconfig.json
4
├── src/
5
│   ├── index.ts          # 主入口
6
│   ├── types.ts          # 类型定义
7
│   ├── tools/            # 工具实现
8
│   │   └── search.ts
9
│   └── services/         # API 客户端
10
│       └── api.ts
11
└── dist/                 # 编译输出

1
{
2
  "name": "my-service-mcp-server",
3
  "version": "1.0.0",
4
  "type": "module",
5
  "main": "dist/index.js",
6
  "scripts": {
7
    "build": "tsc",
8
    "start": "node dist/index.js",
9
    "dev": "tsx watch src/index.ts"
10
  },
11
  "dependencies": {
12
    "@modelcontextprotocol/sdk": "^1.6.1",
13
    "axios": "^1.7.9",
14
    "zod": "^3.23.8"
15
  },
16
  "devDependencies": {
17
    "@types/node": "^22.10.0",
18
    "tsx": "^4.19.2",
19
    "typescript": "^5.7.2"
20
  }
21
}

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
  },
12
  "include": ["src/**/*"],
13
  "exclude": ["node_modules", "dist"]
14
}

1
#!/usr/bin/env node
2
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
3
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
4
import { z } from "zod";
5
import axios from "axios";
6

7
// 常量配置
8
const API_BASE_URL = "https://api.example.com/v1";
9

10
// 创建 MCP 服务器
11
const server = new McpServer({
12
  name: "my-service-mcp-server",
13
  version: "1.0.0"
14
});
15

16
// Zod 输入验证 Schema
17
const SearchSchema = z.object({
18
  query: z.string()
19
    .min(2, "关键词至少 2 个字符")
20
    .max(200, "关键词最多 200 个字符")
21
    .describe("搜索关键词"),
22
  limit: z.number()
23
    .int()
24
    .min(1)
25
    .max(100)
26
    .default(20)
27
    .describe("返回结果数量限制")
28
}).strict();
29

30
// 工具注册
31
server.registerTool(
32
  "my_search",
33
  {
34
    title: "搜索工具",
35
    description: `执行搜索操作，返回匹配的结果。
36

37
Args:
38
  - query: 搜索关键词
39
  - limit: 返回结果数量 (默认 20)
40

41
Returns:
42
  JSON 格式的搜索结果`,
43
    inputSchema: SearchSchema,
44
    annotations: {
45
      readOnlyHint: true,
46
      destructiveHint: false,
47
      idempotentHint: true,
48
      openWorldHint: true
49
    }
50
  },
51
  async (params) => {
52
    try {
53
      const response = await axios.get(`${API_BASE_URL}/search`, {
54
        params: { q: params.query, limit: params.limit },
55
        timeout: 30000
56
      });
57

58
      return {
59
        content: [{
60
          type: "text",
61
          text: JSON.stringify(response.data, null, 2)
62
        }],
63
        structuredContent: response.data
64
      };
65
    } catch (error) {
66
      const message = error instanceof Error ? error.message : String(error);
67
      return {
68
        content: [{
69
          type: "text",
70
          text: `Error: ${message}`
71
        }]
72
      };
73
    }
74
  }
75
);
76

77
// 启动服务器
78
async function main() {
79
  const transport = new StdioServerTransport();
80
  await server.connect(transport);
81
  console.error("MCP server running via stdio");
82
}
83

84
main().catch(console.error);

1
~/.config/opencode/skills/my-mcp/
2
├── SKILL.md           # 技能描述
3
├── mcp.json           # MCP 服务器配置
4
└── scripts/
5
    └── run.sh         # 启动脚本

1
---
2
name: my-mcp
3
description: 我的自定义 MCP 服务
4
---
5

6
# My MCP Service
7

8
提供 XXX 功能的 MCP 服务器。

1
{
2
  "my_service": {
3
    "type": "stdio",
4
    "command": "python",
5
    "args": ["/home/fenlyin/my_mcp_server.py"],
6
    "env": {
7
      "API_KEY": "your-api-key"
8
    }
9
  }
10
}

1
{
2
  "projects": {
3
    "/home/fenlyin/your-project": {
4
      "mcpServers": {
5
        "my-custom-mcp": {
6
          "type": "stdio",
7
          "command": "node",
8
          "args": ["/path/to/dist/index.js"],
9
          "env": {
10
            "MY_API_KEY": "xxx"
11
          }
12
        }
13
      }
14
    }
15
  }
16
}

1
{
2
  "mcpServers": {
3
    "my-remote-mcp": {
4
      "type": "http",
5
      "url": "https://your-server.com/mcp",
6
      "headers": {
7
        "Authorization": "Bearer your-token"
8
      }
9
    }
10
  }
11
}

1
import logging
2
logging.basicConfig(level=logging.DEBUG)

1
// 使用 console.error 而不是 console.log（stdout 用于通信）
2
console.error("Debug message:", data);