内容
# 📘 MCP Server 开发全流程指导手册 (Master SOP)
**版本**: 1.0
**适用对象**: MCP 开发者 (Python/Node.js)
**目标**: 规范 Model Context Protocol 工具的从开发到发布的完整生命周期，避免常见错误。
---
## 目录
1. [🟢 Python 版本开发流程 (推荐)](#1-python-版本开发流程-推荐)
2. [🟡 Node.js 版本开发流程](#2-nodejs-版本开发流程)
3. [🔵 客户端配置指南 (Cursor/Claude)](#3-客户端配置指南-cursorclaude)
4. [🔴 避坑指南与最佳实践 (必读)](#4-避坑指南与最佳实践-必读)
5. [📄 附录：项目 README.md 模板](#5-附录项目-readmemd-模板)
---
## 1. Python 版本开发流程 (推荐)
Python 配合 `fastmcp` 库是目前开发效率最高的方式，也是本 SOP 的重点。
### 1.1 目录结构规范 (核心)
⚠️ **警告**：严禁将代码散落在根目录！必须建立包文件夹，否则 `uvx` 安装后无法正确导入模块。
**标准结构示例：**
```plaintext
my-project-root/ # 项目根目录
├── pyproject.toml # 核心配置文件 (必须存在)
├── README.md # 项目说明文档 (发布后显示在 PyPI)
└── my_tool_pkg/ # 源码包文件夹 (建议用下划线命名)
├── __init__.py # 标识文件 (必须有，内容可为空)
├── main.py # 入口文件 (定义 MCP 服务)
└── utils.py # 业务逻辑文件
1.2 代码编写规范
入口文件 (main.py) 导入规则：
Python
from fastmcp import FastMCP
# ⚠️ 关键点：包内引用必须使用相对导入 (.)
# ❌ 错误写法: import utils
# ✅ 正确写法: from . import utils
from . import utils
# 初始化服务
mcp = FastMCP("My Tool Name")
@mcp.tool()
def my_feature(arg: str) -> str:
"""
这里写详细的功能描述。
AI 会完全依赖这段注释来理解工具的作用，请务必详细。
"""
return utils.process(arg)
日志打印规范：
❌ 绝对禁止使用 print()：这会破坏 MCP 的 JSON 通讯协议，导致连接断开。
✅ 必须使用 sys.stderr.write("Log info...\n") 来打印调试信息。
1.3 配置文件详解 (pyproject.toml)
请直接复制以下模板，并根据注释修改相应字段：
Ini, TOML
# ================= 构建系统配置 (保持默认) =================
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
# ================= 项目基本信息 =================
[project]
# 1. 包名：PyPI 唯一标识，必须全网唯一。建议格式: id-toolname
name = "jd-excel-mcp"
# 2. 版本号：每次发布必须递增 (如 0.1.0 -> 0.1.1)，否则上传失败
version = "0.1.0"
# 3. 描述与作者
description = "一个强大的 Excel MCP 工具"
authors = [
{ name = "Your Name", email = "your@email.com" },
]
# 4. 依赖列表：列出代码中用到的所有第三方库
dependencies = [
"fastmcp",
"pandas",
"openpyxl"
]
# ================= 命令行入口配置 (关键) =================
[project.scripts]
# 格式：命令名 = "包文件夹名.文件名:实例名.run"
# 左边：uvx 运行时调用的命令
# 右边：Python 解释器寻找对象的路径
your-tool-command = "my_tool_pkg.main:mcp.run"
# ================= 打包目标配置 (关键) =================
[tool.hatch.build.targets.wheel]
# 告诉打包工具源码在哪，必须与你的包文件夹名一致
packages = ["my_tool_pkg"]
1.4 本地调试 (Debug)
在发布到 PyPI 之前，先在本地 Cursor 中测试，节省时间。
Cursor 配置 (指向本地文件)：
JSON
{
"mcpServers": {
"LocalTest": {
"command": "python3",
"args": ["/你的项目绝对路径/my_tool_pkg/main.py"],
"env": { "PYTHONUTF8": "1" },
"type": "stdio"
}
}
}
1.5 打包与发布 (Publish)
确保本地测试通过后，执行标准的 "改版本-清理-构建-发布" 四部曲。
修改版本号：打开 pyproject.toml，将 version 改为新版本（如 0.1.1）。
清理旧构建（防止上传残留文件，极为重要）：
Bash
rm -rf dist
构建新包：
Bash
python3 -m hatch build
(成功后会在 dist/ 目录下生成 .whl 文件)
发布到 PyPI：
Bash
python3 -m hatch publish
Username: __token__
Password: pypi-xxxxxxxx... (你的 API Token)
2. Node.js 版本开发流程
适用于 Web 集成或前端开发者。
2.1 初始化
Bash
mkdir my-node-mcp && cd my-node-mcp
npm init -y
npm install @modelcontextprotocol/sdk zod
2.2 package.json 关键配置
确保添加 bin 字段和 type: module。
JSON
{
"name": "my-node-tool",
"version": "1.0.0",
"type": "module",
"bin": {
"my-tool": "./build/index.js"
},
"dependencies": {
"@modelcontextprotocol/sdk": "...",
"zod": "..."
}
}
2.3 发布
Bash
npm login
npm publish --access public
3. 客户端配置指南 (Cursor/Claude)
无论 Python 还是 Node.js，发布后在 Cursor/Claude 中的配置逻辑一致。使用 uvx (Python) 或 npx (Node) 运行。
推荐配置 (JSON)：
JSON
{
"mcpServers": {
"MyCloudTool": {
"command": "uvx",
"args": [
"--refresh", // 1. 强制刷新缓存 (开发调试期必备)
"your-package-name" // 2. PyPI 包名
// 或者锁定版本: "your-package-name==0.1.5"
],
"env": {
"PYTHONUTF8": "1" // 3. 解决中文乱码问题
},
"type": "stdio",
"timeout": 120 // 4. 防止首次下载依赖超时
}
}
}
4. 避坑指南与最佳实践 (必读)
🛑 常见报错与解决方案
ModuleNotFoundError: No module named 'utils'
原因：在 main.py 中使用了 import utils。
解决：改为相对导入 from . import utils。
400 File already exists
原因：试图发布一个已经存在的版本号。
解决：修改 pyproject.toml 中的 version 字段。
发布时包含旧文件 / Upload Failed
原因：发布前没有删除 dist/ 文件夹，导致混入了旧版本的包。
解决：每次发布前务必运行 rm -rf dist。
Cursor 找不到工具 / 显示旧工具
原因：uvx 使用了本地缓存，没有去下载你刚发布的版本。
解决：在配置 args 中添加 --refresh，或直接指定版本号 name==0.1.x。
✅ 最佳实践
Docstring 是灵魂: 给每个 @mcp.tool 函数写清楚注释，这是 AI 识别工具能力的唯一依据。
Type Hint: 严格标注参数类型（如 arg: str, limit: int），AI 会根据这个生成 JSON Schema。
Environment: 始终加上 PYTHONUTF8: 1，避免处理中文数据时崩溃。
5. 附录：项目 README.md 模板
复制以下内容到项目的 README.md，发布后 PyPI 主页会自动展示，让你的项目看起来非常专业。
Markdown
# 📊 [Project Name] - MCP Server
[](https://pypi.org/project/your-package-name/)
[](https://opensource.org/licenses/MIT)
这是一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的工具集，允许大模型（Cursor, Claude）直接调用本地功能，实现[描述主要功能，如：自动化 Excel 操作]。
## ✨ 功能列表
* **功能A**: [描述功能A的作用]
* **功能B**: [描述功能B的作用]
## 🚀 快速开始
### 1. Cursor / Claude Desktop 配置
无需手动下载代码，将以下内容添加到 MCP `settings.json`：
```json
{
"mcpServers": {
"MyTool": {
"command": "uvx",
"args": [
"--refresh",
"your-package-name"
],
"env": {
"PYTHONUTF8": "1"
},
"type": "stdio",
"timeout": 120
}
}
}
```
### 2. 终端手动测试
在配置前，建议先在终端运行一次以缓存环境：
```bash
uvx your-package-name
```
## 🛠 开发与贡献
1. 克隆仓库
2. 安装依赖: `pip install -r requirements.txt`
3. 本地调试: `python3 my_pkg/main.py`
## 📄 License
MIT License
