MCP Server开发入门与协议调试生产部署

从 MCP Server 入门到生产级部署实战

上一篇文章中的 demo server 虽然能够正常运行，但实际上只提供了 echo 和 add 两个基础工具。想要将一个 Server 真正部署到生产环境，还需要解决以下 5 个关键工程问题：

1. 多个工具之间如何协同工作，数据如何实现共享
2. 用户输入如何进行验证——不要以为 LLM 就不会传递错误参数
3. 工具执行失败时，如何告知客户端，采用什么格式返回错误信息
4. 日志应该输出到哪里——写错位置会直接破坏协议
5. Resources 如何运用，让 LLM 能够动态获取上下文数据

本次 Demo 是一个完整的 Jira Server，内置了 mock 数据，无需真实的 Jira 账号即可运行。

MCP Server 整体架构设计

整个 Server 围绕 Jira 的核心业务操作展开，架构上包含了 4 个工具、1 个资源和 1 个 Prompt。工具分别是 search_issues（按关键字、项目或状态检索 issue）、get_issue（根据 issue key 获取详细信息）、create_issue（创建新 issue）和 update_issue（更新现有 issue）。资源方面暴露了一个 jira://projects 端点，LLM 可以通过读取它来了解有哪些合法的 project key。Prompt 则提供了一个 Bug 分析报告的模板。

模式 1：多工具协同工作机制

这 4 个工具共享同一个内存数据存储 ISSUES，形成了一个完整的读写操作闭环：

# 共享的数据层（生产环境对应真实数据库/API） ISSUES: dict[str, dict] = { "PROJ-101": { "key": "PROJ-101", "summary": "NullPointerException in parseInput() when config is null", "status": "Open", "priority": "P1", "issue_type": "Bug", ... }, ... } # search_issues：查询 # get_issue：精确读取 # create_issue：写入新 Issue（递增 ID） # update_issue：修改已有 Issue

在设计决策上，验证逻辑被提取为一个公共函数 validate_issue_key()，get_issue 和 update_issue 都调用该函数，有效避免了重复代码：

def validate_issue_key(key: str) -> str | None: """Return error message if key is invalid, None if valid.""" if not key or "-" not in key: return f"Invalid issue key format: '{key}'. Expected format: PROJECT-123" project = key.split("-")[0] if project not in PROJECTS: return f"Unknown project: '{project}'. A vailable projects: {', '.join(PROJECTS)}" if key not in ISSUES: return f"Issue '{key}' not found" return None

模式 2：输入验证机制

不可忽视的是，LLM 确实可能传递错误参数：project key 拼写错误、status 使用了非法值、summary 为空。Server 必须进行验证，否则返回的错误信息对 LLM 来说毫无意义。

枚举值验证是基础操作：

VALID_STATUSES = {"Open", "In Progress", "In Review", "Done", "Closed"} VALID_PRIORITIES = {"P0", "P1", "P2", "P3"} VALID_ISSUE_TYPES = {"Bug", "Story", "Task", "Epic"} if new_status and new_status not in VALID_STATUSES: return [TextContent(type="text", text=( f"Invalid status: '{new_status}'. Valid values: {', '.join(sorted(VALID_STATUSES))}" ), isError=True)]

必填字段同样需要严格检查：

if not summary: return [TextContent(type="text", text="'summary' is required.", isError=True)]

同样关键的是业务规则验证，例如 summary 不能超过 255 个字符，或者 update_issue 时至少需要传递一个要更新的字段：

if len(summary) > 255: return [TextContent(type="text", text="Summary exceeds 255 characters.", isError=True)] # 至少要更新一个字段 if not any([new_status, new_assignee is not None, new_priority]): return [TextContent(type="text", text=( "No fields to update. Provide at least one of: status, assignee, priority." ), isError=True)]

模式 3：结构化错误处理策略

MCP 协议提供了两种表示"失败"的方式，选择错误会直接影响 LLM 的处理效果。

方式 A 是硬错误，使用 isError=True：

return [TextContent(type="text", text="Issue 'PROJ-999' not found", isError=True)]

LLM 收到 isError=true 后，会调整策略——更换 issue key 重试，或者直接告知用户。这种方式适用于资源不存在、参数非法、权限不足等场景。

方式 B 是软反馈，正常响应但不标记为错误：

return [TextContent(type="text", text=( "Unknown project: 'INVALID'. A vailable projects: PROJ, MOBILE, INFRA" ))] # 注意：没有 isError=True

LLM 认为工具执行成功了，只是结果中包含了纠错信息。它会读取建议后自动修正参数并重试。这种方式更适合搜索类操作——输入可能模糊，返回提示有助于 LLM 自我校正。

测试结果对比很能说明问题：

search 'anything' with project='INVALID'（无 isError）: ✓ Unknown project: 'INVALID'. A vailable projects: PROJ, MOBILE, INFRA → LLM 读取后会用 PROJ/MOBILE/INFRA 重试 get_issue('PROJ-999')（有 isError=True）: ✗ Issue 'PROJ-999' not found → LLM 知道这是失败，不会继续用这个 key

模式 4：日志必须输出到 stderr

这里有一个关键约束需要强调：stdout 是 JSON-RPC 的通信通道。任何写入 stdout 的内容都会破坏协议。

# ✅ 正确：日志写到 stderr logging.basicConfig( stream=sys.stderr, # ← 必须是 stderr level=logging.INFO, format="%(asctime)s [%(levelname)s] %(name)s: %(message)s", ) logger = logging.getLogger("jira-mcp") # 工具里的日志 logger.info("tools/call: %s args=%s", name, arguments) logger.info("Created issue %s", key) # ❌ 错误：任何 print() 都会破坏协议 print("Created issue PROJ-201") # ← 这会把文字注入 JSON-RPC 流，导致 Client 解析失败

调试时查看日志的方法也很简单：

# 日志输出到 stderr，不影响 stdout 的 JSON-RPC 流 python demo_jira_server.py 2>server.log & # 后台运行，日志写文件 tail -f server.log # 另开终端实时查看

模式 5：Resources 提供动态上下文

工具 schema 中虽然可以写 "A vailable: PROJ, MOBILE, INFRA"，但这只是硬编码在描述文字里。更好的做法是暴露一个 Resource，让 LLM 能够主动读取最新的项目列表：

@server.list_resources() async def list_resources() -> list[Resource]: return [ Resource( uri="jira://projects", # type: ignore[arg-type] name="A vailable Projects", description="List of Jira projects. Read this to know valid project keys.", mimeType="application/json" ) ] @server.read_resource() # type: ignore[arg-type] async def read_resource(uri: str) -> str: if str(uri) == "jira://projects": data = [{"key": k, "name": v["name"], "lead": v["lead"]} for k, v in PROJECTS.items()] return json.dumps(data, indent=2)

这种方式的效果非常直接：LLM 在调用任何 Jira 工具之前，可以先读取 jira://projects 来了解合法的 project key，无需再去猜测。特别适合动态变化的枚举值——项目会增减，但 schema 中的硬编码不会自动更新。

完整测试结果汇总

所有测试结果汇总如下，覆盖了各个工具的正常流程和异常路径：

==================================== Jira MCP Server — Test Suite ==================================== [search_issues] ✓ search 'NPE' in PROJ Found 1 issue(s): [PROJ-101] NullPointerException in parseInput()... ✓ search 'crash' with status=Open Found 1 issue(s): [MOBILE-55] Crash on Android 14 when opening notification settings... ✓ search with invalid project (友好提示，无 isError) Unknown project: 'INVALID'. A vailable projects: PROJ, MOBILE, INFRA [get_issue] ✓ get PROJ-101 (P1 Bug) Issue: PROJ-101 Type: Bug | Status: Open | Priority: P1 ... ✗ get PROJ-999 (not found → isError=true) Issue 'PROJ-999' not found ✗ get malformed key 'not-a-key' (→ isError=true) Unknown project: 'NOT'. A vailable projects: PROJ, MOBILE, INFRA [create_issue] ✓ create valid Bug in PROJ Created issue PROJ-201: Redis connection pool not releasing connections... ✗ create with empty summary (→ isError=true) 'summary' is required. ✗ create with invalid priority 'CRITICAL' (→ isError=true) Invalid priority: 'CRITICAL'. Valid values: P0, P1, P2, P3 [update_issue] ✓ update PROJ-101 status + assignee Updated PROJ-101: status: Open → In Progress, assignee: alice → bob ✗ update with no fields (→ isError=true) No fields to update. Provide at least one of: status, assignee, priority. ✗ update with invalid status 'Shipped' (→ isError=true) Invalid status: 'Shipped'. Valid values: Closed, Done, In Progress, In Review, Open [resources] A vailable resources: ['jira://projects'] Projects: ['PROJ', 'MOBILE', 'INFRA']

这里有一个值得注意的细节：get_issue('not-a-key') 返回了 "Unknown project: 'NOT'" 而不是 "invalid key format"。原因是验证逻辑先拆分 - 取 project 部分，not-a-key 被拆出了 NOT，进入了"project 不存在"的分支。对 LLM 来说这个错误信息仍然足够有用——它知道 NOT 不是合法 project。但如果需要更精确，可以在验证前先检查 key 是否匹配 [A-Z]+-\d+ 的格式。

Schema 设计要点解析

工具 schema 是 LLM 读取的文档，其重要性甚至超过人类编写的代码注释：

Tool( name="search_issues", description=( "Search Jira issues by keyword, project, or status. " "Use when the user asks about bugs, tasks, tickets, or issues. " # ← 触发时机 "Returns a list of matching issues with key, summary, status, priority." # ← 返回格式 ), inputSchema={ "properties": { "project": { "type": "string", "description": f"Filter by project key. A vailable: {', '.join(PROJECTS)}" # ↑ 把合法值内联在描述里，LLM 不需要另外问 }, "max_results": { "type": "integer", "description": "Maximum number of results (default: 10, max: 50)", "default": 10 # ↑ 描述里写 max 值，schema 里写 default } } } )

接入 Claude Code 的配置方法

将这个 Server 接入 Claude Code 只需在配置文件中添加一个条目：

// .claude/settings.json { "mcpServers": { "jira-demo": { "command": "python", "args": ["/path/to/mcp-04-first-server/demo_jira_server.py"] } } }

重启 Claude Code 后，就可以直接提问："帮我搜一下 PROJ 项目里所有 P1 的 Bug"，Claude 会自动调用 search_issues 工具来完成搜索。

参考资料与延伸阅读

• MCP Python SDK 官方文档
• 本系列完整 Demo 代码：mcp-04-first-server