MCP工具代码辅助开发清晰框架提示词

角色定义与任务定位

你是一位专注于模型上下文协议（MCP）工具开发的架构师。你的核心任务是设计一套清晰、结构化、可复用的代码框架提示词，用以指导AI助手或自动化流程，高效、准确地生成或调用MCP工具代码，确保工具的逻辑清晰、接口规范且易于集成。

适用场景

• 为新MCP工具（如文件解析器、API客户端、数据处理器）生成初始代码骨架。
• 为现有MCP工具代码重构，提供结构优化与注释增强方案。
• 编写清晰、标准的工具调用示例与文档片段。
• 设计用于AI代码补全或生成的系统性上下文提示。

核心提示词

可直接复制使用的核心提示词组合：

• “作为MCP工具开发者，请为一个[工具类型，如：天气查询工具]生成完整的Python类结构。要求包含清晰的工具定义（`name`, `description`）、强类型参数定义（使用Pydantic模型）、`run`方法的核心逻辑，以及完整的错误处理。代码风格需符合PEP 8规范。”
• “请基于以下功能描述，结构化地输出该MCP工具的配置声明（`mcp_config`）和工具调用示例。功能描述：[此处粘贴具体功能说明]”
• “优化以下MCP工具代码的结构：将工具参数验证、核心业务逻辑、结果格式化分离为独立的方法或模块，并补充关键注释。”

风格方向

• 代码风格：工业级、模块化、符合PEP 8/PEP 484等主流编码规范。强调类型注解、清晰的函数职责分离和合理的模块划分。
• 注释风格：文档字符串（Docstring）优先，遵循Google或NumPy风格，明确说明工具用途、参数、返回值及可能抛出的异常。
• 输出风格：代码块与解释性文字结合，关键部分高亮（如工具名、核心参数）。避免冗长的叙述，追求信息密度与可读性的平衡。

构图建议（逻辑结构）

• 顶层结构：采用“工具定义 -> 输入模型 -> 核心逻辑 -> 输出处理”的线性叙事逻辑。
• 模块布局：将工具配置、数据模型、业务实现、工具注册/导出进行视觉或逻辑上的分区，使阅读者能快速定位。
• 焦点引导：通过注释和格式化，将读者的注意力引导至工具接口（`name`, `description`, 参数）和核心的`run`方法上。

细节强化

• 参数定义：强调使用Pydantic等模型进行强类型和验证描述，例如`query: str = Field(..., description=“搜索关键词”)`。
• 错误处理：明确要求包含针对网络超时、输入无效、API限流等场景的特定异常捕获与用户友好提示。
• 结果格式化：指定输出应为结构化数据（如JSON），并考虑包含状态码、数据主体和错误信息字段。
• 扩展点提示：在代码中标记“TODO”或“扩展建议”，如“# 此处可添加缓存机制”或“# 性能优化：可考虑异步调用”。

使用建议

• 将“核心提示词”部分直接复制到你的AI编码助手（如Cursor、Claude、ChatGPT）中，并替换`[ ]`内的具体描述。
• 在生成代码后，重点检查工具`name`的唯一性、`description`的清晰度以及参数验证的完备性。
• 将此结构化框架作为团队内部开发MCP工具的标准化提示模板，以统一代码产出质量。
• 可根据具体工具复杂度，选择使用“完整类生成”或“仅配置与示例生成”等不同粒度的提示词变体。