# MCP Builder

> MCP（Model Context Protocol）服务器构建原则。工具设计、资源模式与最佳实践。

- Skill: `misonl/mcp-builder` (Agent Skill)
- Install (CLI): `npx skillmds@latest add misonl/mcp-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/misonl/mcp-builder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: misonl (https://skillmd.com/u/misonl)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/misonl/mcp-builder

---


# MCP 构建器

> MCP 服务器构建原则。

---

## 1. MCP 概览

### 什么是 MCP？

Model Context Protocol：用于连接 AI 系统与外部工具、数据源的标准协议。

### 核心概念

| 概念 | 目的 |
| --- | --- |
| **Tools** | AI 可调用的函数能力 |
| **Resources** | AI 可读取的数据资源 |
| **Prompts** | 预定义提示词模板 |

---

## 2. 服务架构

### 项目结构

```
my-mcp-server/
+-- src/
|   +-- index.ts      # 主入口
+-- package.json
+-- tsconfig.json
```

### 传输类型

| 类型 | 用途 |
| --- | --- |
| **Stdio** | 本地、CLI 场景 |
| **SSE** | Web 场景、流式输出 |
| **WebSocket** | 实时、双向通信 |

---

## 3. 工具设计原则

### 优秀工具设计

| 原则 | 描述 |
| --- | --- |
| 名称清晰 | 动作导向（get_weather, create_user） |
| 单一职责 | 一次只做好一件事 |
| 输入可校验 | 使用含类型与描述的 schema |
| 输出结构化 | 响应格式可预测 |

### 输入 Schema 设计

| 字段 | 必填？ |
| --- | --- |
| Type | 是（object） |
| Properties | 定义每个参数 |
| Required | 列出必填参数 |
| Description | 人类可读说明 |

---

## 4. 资源模式

### 资源类型

| 类型 | 用途 |
| --- | --- |
| Static | 固定数据（配置、文档） |
| Dynamic | 按请求动态生成 |
| Template | 含参数的 URI 模板 |

### URI 模式

| 模式 | 示例 |
| --- | --- |
| Fixed | `docs://readme` |
| Parameterized | `users://{userId}` |
| Collection | `files://project/*` |

---

## 5. 错误处理

### 错误类型

| 情况 | 响应 |
| --- | --- |
| 参数无效 | 返回明确的校验错误 |
| 资源不存在 | 返回清晰的 “not found” |
| 服务器错误 | 返回通用错误并记录日志 |

### 最佳实践

- 返回结构化错误对象
- 不暴露内部实现细节
- 记录可追踪日志用于调试
- 提供可执行的错误提示

---

## 6. 多模态处理

### 支持类型

| 类型 | 编码 |
| --- | --- |
| Text | Plain text |
| Images | Base64 + MIME type |
| Files | Base64 + MIME type |

---

## 7. 安全原则

### 输入校验

- 校验所有工具输入
- 清洗用户提供的数据
- 限制资源访问范围

### API 密钥

- 使用环境变量存储
- 禁止日志输出密钥
- 校验调用权限

---

## 8. 配置

### Claude Desktop 配置

| 字段 | 目的 |
| --- | --- |
| command | 要执行的命令 |
| args | 命令参数 |
| env | 环境变量 |

---

## 9. 测试

### 测试类别

| 类型 | 关注点 |
| --- | --- |
| Unit | 工具逻辑 |
| Integration | 服务整体 |
| Contract | Schema 校验 |

---

## 10. 最佳实践检查清单

- [ ] 工具名称清晰且动作导向
- [ ] 输入 schema 完整且含说明
- [ ] 输出为结构化 JSON
- [ ] 覆盖各类错误处理场景
- [ ] 输入校验到位
- [ ] 使用环境变量进行配置
- [ ] 日志可用于排障与调试

---

> **记住：** MCP 工具应保持简单、聚焦且文档完善。AI 依赖描述来正确调用它们。