feat(zh): add Chinese translations in zh/ directory
Add Chinese (Simplified) translations for all documentation, organized under a dedicated zh/ directory that mirrors the English folder structure. Co-authored-by: tanqingkuang <tanqingkuang@users.noreply.github.com> Translations originally contributed by @tanqingkuang in #45. Restructured from *-CN.md suffix pattern into zh/ directory to prevent the EPUB builder (scripts/build_epub.py collect_folder_files) from picking up Chinese files via glob("*.md") inside module folders.
This commit is contained in:
Luong NGUYEN
342
zh/05-mcp/README.md
Normal file
342
zh/05-mcp/README.md
Normal file
@@ -0,0 +1,342 @@
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">
|
||||
<img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">
|
||||
</picture>
|
||||
|
||||
# MCP（Model Context Protocol）
|
||||
|
||||
## 概览
|
||||
|
||||
MCP 是 Claude Code 访问外部工具、服务和 API 的标准协议。你可以把 GitHub、数据库、文件系统、聊天系统等都接到 Claude 里。
|
||||
|
||||
## MCP 架构
|
||||
|
||||
MCP 通常由三部分构成：
|
||||
|
||||
1. Claude Code
|
||||
2. MCP server
|
||||
3. 外部工具或数据源
|
||||
|
||||
Claude 会通过 MCP 协议向 server 发起工具调用，并把结果带回当前会话。
|
||||
|
||||
## MCP 生态
|
||||
|
||||
- GitHub 集成
|
||||
- 数据库集成
|
||||
- 文件系统集成
|
||||
- 组织内部工具
|
||||
- 第三方服务
|
||||
|
||||
## 安装方式
|
||||
|
||||
### HTTP 传输（推荐）
|
||||
|
||||
```bash
|
||||
# Basic HTTP connection
|
||||
|
||||
# HTTP with authentication header
|
||||
```
|
||||
|
||||
### Stdio 传输（本地）
|
||||
|
||||
```bash
|
||||
# Local Node.js server
|
||||
|
||||
# With environment variables
|
||||
```
|
||||
|
||||
### SSE 传输（已弃用）
|
||||
|
||||
旧版本中可能仍能见到 SSE 方式，但新配置一般优先考虑 HTTP 或 stdio。
|
||||
|
||||
### WebSocket 传输
|
||||
|
||||
适用于需要实时双向通信的场景。
|
||||
|
||||
### Windows 说明
|
||||
|
||||
在 Windows 上配置本地 server 时，要注意 shell、环境变量和路径写法。
|
||||
|
||||
### OAuth 2.0 认证
|
||||
|
||||
对于支持 OAuth 的 MCP server，Claude 可以通过交互式流程或预配置凭据完成认证。
|
||||
|
||||
## MCP 设置流程
|
||||
|
||||
1. 确认你要接入的服务
|
||||
2. 选择 transport
|
||||
3. 配置环境变量或认证
|
||||
4. 在 Claude Code 中添加 server
|
||||
5. 验证工具是否可用
|
||||
|
||||
## MCP 工具搜索
|
||||
|
||||
Claude 会根据当前上下文自动查找可用工具。
|
||||
|
||||
## 动态工具更新
|
||||
|
||||
当 MCP server 增加或移除工具时，Claude 可以在运行时感知变化。
|
||||
|
||||
## MCP 提示补充（Elicitation）
|
||||
|
||||
有些 MCP server 会在需要用户补充信息时触发 elicitation，Claude 再把问题转给用户。
|
||||
|
||||
## 工具描述与指令上限
|
||||
|
||||
每个 MCP 工具都应该有清晰的描述，帮助 Claude 选择正确的工具。
|
||||
|
||||
## 把 MCP Prompts 暴露成 Slash Commands
|
||||
|
||||
```text
|
||||
/mcp__<server-name>__<prompt-name> [arguments]
|
||||
```
|
||||
|
||||
例如：
|
||||
|
||||
```bash
|
||||
/mcp__github__list_prs
|
||||
/mcp__github__pr_review 456
|
||||
/mcp__jira__create_issue "Bug title" high
|
||||
```
|
||||
|
||||
## Server 去重
|
||||
|
||||
如果多个配置都指向同一个 server，Claude 会尽量避免重复加载。
|
||||
|
||||
## 通过 `@` 提及使用 MCP 资源
|
||||
|
||||
你可以把某些资源当作引用对象，在 prompt 中直接提及。
|
||||
|
||||
## MCP 作用域
|
||||
|
||||
MCP 配置通常有不同作用域，例如项目级和用户级。
|
||||
|
||||
### 使用项目作用域
|
||||
|
||||
适合把团队共享的 server 配置写进项目内。
|
||||
|
||||
## MCP 配置管理
|
||||
|
||||
### 添加 MCP server
|
||||
|
||||
```bash
|
||||
# Add HTTP-based server
|
||||
|
||||
# Add local stdio server
|
||||
|
||||
# List all MCP servers
|
||||
|
||||
# Get details on specific server
|
||||
|
||||
# Remove an MCP server
|
||||
|
||||
# Reset project-specific approval choices
|
||||
|
||||
# Import from Claude Desktop
|
||||
```
|
||||
|
||||
## 可用 MCP Server 表
|
||||
|
||||
你可以在配置中维护一张 server 清单，记录用途、认证方式和安装命令。
|
||||
|
||||
## 实战示例
|
||||
|
||||
### 示例 1：GitHub MCP 配置
|
||||
|
||||
你可以用 GitHub MCP 做这些事：
|
||||
|
||||
- PR 管理
|
||||
- Issue 管理
|
||||
- 仓库信息查询
|
||||
- commit 操作
|
||||
|
||||
### 环境变量展开
|
||||
|
||||
在配置中可以使用环境变量，让同一份配置适配不同环境。
|
||||
|
||||
### 示例 2：数据库 MCP
|
||||
|
||||
```bash
|
||||
# Using MCP database tool:
|
||||
|
||||
# Results:
|
||||
```
|
||||
|
||||
### 示例 3：多 MCP 工作流
|
||||
|
||||
适合日常报告、跨系统同步和自动化文档生成。
|
||||
|
||||
### 示例 4：文件系统 MCP 操作
|
||||
|
||||
可用于读写文件、批量整理、生成报告或导出结果。
|
||||
|
||||
## MCP vs Memory：决策矩阵
|
||||
|
||||
- **Memory**：适合长期规则、偏好和上下文
|
||||
- **MCP**：适合实时工具访问和外部数据
|
||||
|
||||
## 请求 / 响应模式
|
||||
|
||||
MCP 一般遵循：
|
||||
|
||||
1. Claude 发起请求
|
||||
2. Server 处理
|
||||
3. 返回结构化结果
|
||||
|
||||
## 环境变量
|
||||
|
||||
常见环境变量包括：
|
||||
|
||||
- API token
|
||||
- 数据库地址
|
||||
- 服务端口
|
||||
- 认证信息
|
||||
|
||||
## Claude 作为 MCP Server（`claude mcp serve`）
|
||||
|
||||
```bash
|
||||
# Start Claude Code as an MCP server on stdio
|
||||
```
|
||||
|
||||
## 受管 MCP 配置（企业）
|
||||
|
||||
企业可通过受管设置统一分发 MCP 配置。
|
||||
|
||||
## 插件提供的 MCP Servers
|
||||
|
||||
插件可以把自己的 MCP server 一起打包分发。
|
||||
|
||||
## Subagent 作用域 MCP
|
||||
|
||||
某些 MCP 只允许特定 subagent 使用。
|
||||
|
||||
## MCP 输出限制
|
||||
|
||||
如果输出过大，可以限制 token 数或分页获取。
|
||||
|
||||
### 增大最大输出
|
||||
|
||||
```bash
|
||||
# Increase the max output to 50,000 tokens
|
||||
```
|
||||
|
||||
## 用代码执行解决上下文膨胀
|
||||
|
||||
当重复把大量数据回传给 Claude 会浪费 token 时，可以把 MCP 当作代码 API 来用，减少来回传输。
|
||||
|
||||
### 问题
|
||||
|
||||
- 两个信息源都在耗 token
|
||||
- 大数据集不适合全量塞进上下文
|
||||
|
||||
### 方案
|
||||
|
||||
- 用 MCP 工具做实时查询
|
||||
- 只把必要结果传给 Claude
|
||||
|
||||
#### 工作方式
|
||||
|
||||
Claude 通过工具调用从外部系统取回需要的数据，而不是把所有数据先写进上下文。
|
||||
|
||||
### 好处
|
||||
|
||||
- 更少 token 浪费
|
||||
- 更清晰的数据边界
|
||||
- 更适合大规模查询
|
||||
|
||||
#### 示例：过滤大数据集
|
||||
|
||||
#### 示例：循环而不做 round-trip
|
||||
|
||||
### 取舍
|
||||
|
||||
- 实现复杂度更高
|
||||
- 需要维护 server
|
||||
- 但扩展性更好
|
||||
|
||||
### MCPorter：MCP 工具组合运行时
|
||||
|
||||
这是更高级的工具编排思路，可以把多个 MCP 工具串成一个流程。
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 安全注意事项
|
||||
|
||||
#### 应该做的
|
||||
|
||||
- 只授权必要的工具
|
||||
- 优先使用最小权限
|
||||
- 检查输出是否可信
|
||||
|
||||
#### 不要做的
|
||||
|
||||
- 不要把高风险 token 写死在仓库里
|
||||
- 不要默认开放所有工具
|
||||
- 不要忽视网络和认证风险
|
||||
|
||||
### 配置建议
|
||||
|
||||
- 给每个 server 写清楚用途
|
||||
- 用环境变量存认证信息
|
||||
- 把项目级配置版本化
|
||||
|
||||
### 性能建议
|
||||
|
||||
- 避免一次性拉回过多数据
|
||||
- 优先做过滤和分页
|
||||
- 只返回 Claude 真正需要的结果
|
||||
|
||||
## 安装说明
|
||||
|
||||
### 前置条件
|
||||
|
||||
- Claude Code
|
||||
- 对应的 MCP server
|
||||
- 必要的认证信息
|
||||
|
||||
### 分步设置
|
||||
|
||||
1. 安装 server
|
||||
2. 设置环境变量
|
||||
3. 添加到 Claude
|
||||
4. 测试工具
|
||||
|
||||
### 特定服务的安装
|
||||
|
||||
不同服务会有不同的安装命令和认证方式。
|
||||
|
||||
## 故障排查
|
||||
|
||||
### 找不到 MCP Server
|
||||
|
||||
- 检查是否安装
|
||||
- 检查路径
|
||||
- 检查配置是否正确
|
||||
|
||||
### 认证失败
|
||||
|
||||
- 检查环境变量是否设置
|
||||
- 确认 token 权限正确
|
||||
- 重新导出变量后再试
|
||||
|
||||
### 连接超时
|
||||
|
||||
- 检查网络
|
||||
- 检查 server 是否可用
|
||||
|
||||
### MCP Server 崩溃
|
||||
|
||||
- 查看 server 日志
|
||||
- 降低并发
|
||||
- 简化请求
|
||||
|
||||
## 相关概念
|
||||
|
||||
- [Memory 中文指南](../02-memory/README.md)
|
||||
- [Subagents 中文参考](../04-subagents/README.md)
|
||||
- [Plugins 中文指南](../07-plugins/README.md)
|
||||
|
||||
## 更多资源
|
||||
|
||||
- [根目录中文指南](../README.md)
|
||||
- [MCP 规范](https://modelcontextprotocol.io)
|
||||
Reference in New Issue
Block a user