Back to Details

mcp-builder

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MCP Builder

MCP 服务器构建指南

Principles for building MCP servers.
MCP服务器构建原则。

1. MCP Overview

1. MCP 概述

What is MCP?

什么是MCP？

Model Context Protocol - standard for connecting AI systems with external tools and data sources.
Model Context Protocol - 用于连接AI系统与外部工具及数据源的标准协议。

Core Concepts

核心概念

ConceptPurpose
ToolsFunctions AI can call
ResourcesData AI can read
PromptsPre-defined prompt templates
概念用途
Tools（工具）AI可调用的功能
Resources（资源）AI可读取的数据
Prompts（提示词）预定义的提示词模板

2. Server Architecture

2. 服务器架构

Project Structure

项目结构

my-mcp-server/
├── src/
│   └── index.ts      # Main entry
├── package.json
└── tsconfig.json
my-mcp-server/
├── src/
│   └── index.ts      # 主入口文件
├── package.json
└── tsconfig.json

Transport Types

传输类型

TypeUse
StdioLocal, CLI-based
SSEWeb-based, streaming
WebSocketReal-time, bidirectional
类型用途
Stdio本地、基于CLI的传输
SSE基于Web的流式传输
WebSocket实时双向传输

3. Tool Design Principles

3. 工具设计原则

Good Tool Design

优秀工具设计准则

PrincipleDescription
Clear nameAction-oriented (get_weather, create_user)
Single purposeOne thing well
Validated inputSchema with types and descriptions
Structured outputPredictable response format
原则说明
清晰的命名面向动作（如get_weather、create_user）
单一职责专注完成一件事
输入验证带类型和描述的Schema
结构化输出可预测的响应格式

Input Schema Design

输入Schema设计

FieldRequired?
TypeYes - object
PropertiesDefine each param
RequiredList mandatory params
DescriptionHuman-readable
字段是否必填？
Type（类型）是 - 对象类型
Properties（属性）定义每个参数
Required（必填项）列出必填参数
Description（描述）便于人类阅读的说明

4. Resource Patterns

4. 资源模式

Resource Types

资源类型

TypeUse
StaticFixed data (config, docs)
DynamicGenerated on request
TemplateURI with parameters
类型用途
Static（静态资源）固定数据（如配置、文档）
Dynamic（动态资源）按需生成的数据
Template（模板资源）带参数的URI

URI Patterns

URI 模式

PatternExample
Fixed
docs://readme
Parameterized
users://{userId}
Collection
files://project/*
模式示例
固定URI
docs://readme
带参数URI
users://{userId}
集合URI
files://project/*

5. Error Handling

5. 错误处理

Error Types

错误类型

SituationResponse
Invalid paramsValidation error message
Not foundClear "not found"
Server errorGeneric error, log details
场景响应方式
参数无效返回验证错误信息
资源未找到返回清晰的“未找到”提示
服务器错误返回通用错误，详细信息记录到日志

Best Practices

最佳实践

  • Return structured errors
  • Don't expose internal details
  • Log for debugging
  • Provide actionable messages
  • 返回结构化错误信息
  • 不暴露内部细节
  • 记录日志用于调试
  • 提供可操作的提示信息

6. Multimodal Handling

6. 多模态处理

Supported Types

支持的类型

TypeEncoding
TextPlain text
ImagesBase64 + MIME type
FilesBase64 + MIME type
类型编码方式
文本纯文本
图片Base64 + MIME类型
文件Base64 + MIME类型

7. Security Principles

7. 安全原则

Input Validation

输入验证

  • Validate all tool inputs
  • Sanitize user-provided data
  • Limit resource access
  • 验证所有工具输入
  • 清理用户提供的数据
  • 限制资源访问权限

API Keys

API密钥管理

  • Use environment variables
  • Don't log secrets
  • Validate permissions
  • 使用环境变量存储
  • 不记录敏感信息
  • 验证权限

8. Configuration

8. 配置

Claude Desktop Config

Claude Desktop 配置

FieldPurpose
commandExecutable to run
argsCommand arguments
envEnvironment variables
字段用途
command要运行的可执行文件
args命令参数
env环境变量

9. Testing

9. 测试

Test Categories

测试分类

TypeFocus
UnitTool logic
IntegrationFull server
ContractSchema validation
类型测试重点
Unit（单元测试）工具逻辑
Integration（集成测试）完整服务器功能
Contract（契约测试）Schema验证

10. Best Practices Checklist

10. 最佳实践检查清单

  • Clear, action-oriented tool names
  • Complete input schemas with descriptions
  • Structured JSON output
  • Error handling for all cases
  • Input validation
  • Environment-based configuration
  • Logging for debugging
Remember: MCP tools should be simple, focused, and well-documented. The AI relies on descriptions to use them correctly.
  • 清晰、面向动作的工具命名
  • 带完整描述的输入Schema
  • 结构化JSON输出
  • 覆盖所有场景的错误处理
  • 输入验证
  • 基于环境的配置
  • 用于调试的日志记录
注意： MCP工具应保持简洁、专注且文档完善。AI依赖这些描述来正确使用工具。