MCP服务器构建指南 - 模型上下文协议开发教程与最佳实践

mcp-builder by vudovn/antigravity-kit

93 周安装量

6,700 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/vudovn/antigravity-kit --skill mcp-builder

AI/机器学习开发 API

🇨🇳中文介绍

MCP 构建指南

构建 MCP 服务器的原则。

1. MCP 概述

什么是 MCP？

模型上下文协议 - 用于连接 AI 系统与外部工具和数据源的标准。

核心概念

概念	用途
工具	AI 可以调用的函数
资源	AI 可以读取的数据
提示	预定义的提示模板

2. 服务器架构

项目结构

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

传输类型

类型	用途

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

3. 工具设计原则

良好的工具设计

原则	描述
名称清晰	面向操作（get_weather, create_user）
目的单一	做好一件事
输入验证	包含类型和描述的架构
结构化输出	可预测的响应格式

字段	是否必需？
类型	是 - 对象
属性	定义每个参数
必需项	列出必填参数
描述	人类可读

类型	用途
静态	固定数据（配置、文档）
动态	按请求生成
模板	带参数的 URI

模式	示例
固定	`docs://readme`
参数化	`users://{userId}`
集合	`files://project/*`

情况	响应
参数无效	验证错误信息
未找到	清晰的“未找到”信息
服务器错误	通用错误，记录详细信息

返回结构化错误
不要暴露内部细节
记录日志以便调试
提供可操作的错误信息

类型	编码
文本	纯文本
图像	Base64 + MIME 类型
文件	Base64 + MIME 类型

验证所有工具输入
清理用户提供的数据
限制资源访问

使用环境变量
不要记录密钥
验证权限

Claude Desktop 配置

字段	用途
命令	要运行的可执行文件
参数	命令参数
环境变量	环境变量

类型	重点
单元测试	工具逻辑
集成测试	完整服务器
契约测试	架构验证

10. 最佳实践清单

清晰、面向操作的工具名称
包含描述的完整输入架构
结构化 JSON 输出
所有情况下的错误处理
输入验证
基于环境的配置
用于调试的日志记录

请记住： MCP 工具应该简单、专注且文档齐全。AI 依赖描述来正确使用它们。

🇺🇸English

MCP Builder

Principles for building MCP servers.

1. MCP Overview

What is MCP?

Model Context Protocol - standard for connecting AI systems with external tools and data sources.

Core Concepts

Concept	Purpose
Tools	Functions AI can call
Resources	Data AI can read
Prompts	Pre-defined prompt templates

2. Server Architecture

Project Structure

my-mcp-server/
├── src/
│   └── index.ts      # Main entry
├── package.json
└── tsconfig.json

Transport Types

Type	Use
Stdio	Local, CLI-based
SSE	Web-based, streaming
WebSocket	Real-time, bidirectional

3. Tool Design Principles

Good Tool Design

Principle	Description
Clear name	Action-oriented (get_weather, create_user)
Single purpose	One thing well
Validated input	Schema with types and descriptions
Structured output	Predictable response format

Input Schema Design

Field	Required?
Type	Yes - object
Properties	Define each param
Required	List mandatory params
Description	Human-readable

4. Resource Patterns

Resource Types

Type	Use
Static	Fixed data (config, docs)
Dynamic	Generated on request
Template	URI with parameters

URI Patterns

Pattern	Example
Fixed	`docs://readme`
Parameterized	`users://{userId}`
Collection	`files://project/*`

5. Error Handling

Error Types

Situation	Response
Invalid params	Validation error message
Not found	Clear "not found"
Server error	Generic error, log details

Best Practices

Return structured errors
Don't expose internal details
Log for debugging
Provide actionable messages

6. Multimodal Handling

Supported Types

Type	Encoding
Text	Plain text
Images	Base64 + MIME type
Files	Base64 + MIME type

7. Security Principles

Input Validation

Validate all tool inputs
Sanitize user-provided data
Limit resource access

API Keys

Use environment variables
Don't log secrets
Validate permissions

8. Configuration

Claude Desktop Config

Field	Purpose
command	Executable to run
args	Command arguments
env	Environment variables

9. Testing

Test Categories

Type	Focus
Unit	Tool logic
Integration	Full server
Contract	Schema validation

10. Best Practices Checklist

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.

Weekly Installs

Repository

vudovn/antigravity-kit

GitHub Stars

6.7K

First Seen

Jan 21, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

gemini-cli81

codex78

opencode75

cursor71

github-copilot69

antigravity65

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

157,400 周安装