通用规范架构——MCP服务器
一个通用的、规范驱动的工程MCP服务器，可与任何兼容MCP的AI编码助手配合使用。它在编写单行实现代码之前，强制执行结构化的三阶段工作流——需求、设计和任务。
______________________________________________________________________
支持的助理
| 助手 | 配置文件 | 状态 |
|---|---|---|
| IBM 鲍勃 | .bob/mcp.json | 支持 |
| 光标 | .cursor/mcp.json | 支持 |
| VS代码（GitHub副本） | .vscode/mcp.json | 支持 |
| 帆板运动 | ~/.codeium/windsurf/mcp_config.json | 支持 |
| 克劳德桌面版 | claude_desktop_config.json | 支持 |
| Cline（VS代码扩展） | cline_mcp_settings.json | 支持 |
______________________________________________________________________
三阶段工作流程
| 阶段 | 文件 | 内容 |
|---|---|---|
| 1.要求 | requirements.md | EARS符号中的用户故事(WHEN... THE SYSTEM SHALL...) |
| 2.设计 | design.md | 架构、序列图、数据模型、错误处理 |
| 3.任务 | tasks.md | 离散、可跟踪的实施任务 |
______________________________________________________________________
项目结构
universal-spec-mcp/
├── src/
│ └── universal_spec_mcp/
│ ├── __init__.py
│ └── server.py # The MCP server — all tools defined here
├── tests/
│ └── test_server.py # Full test suite (9 tests)
├── configs/
│ ├── cursor/
│ │ └── mcp.json # Copy to .cursor/mcp.json
│ ├── vscode/
│ │ └── mcp.json # Copy to .vscode/mcp.json
│ ├── windsurf/
│ │ └── mcp_config.json # Merge into ~/.codeium/windsurf/mcp_config.json
│ ├── claude/
│ │ └── claude_desktop_config.json # Merge into Claude Desktop config
│ └── cline/
│ └── cline_mcp_settings.json # Merge into Cline MCP settings
├── .bob/
│ ├── mcp.json # IBM Bob MCP configuration
│ ├── modes/
│ │ └── spec-architect.json # IBM Bob custom mode
│ ├── rules/
│ │ └── spec-workflow.md # IBM Bob workflow rules
│ └── steering/
│ ├── product.md # Fill in: product context
│ ├── tech.md # Fill in: technology stack
│ └── structure.md # Fill in: project structure
├── .specs/ # Generated spec artifacts
├── SETUP_GUIDE.md # Per-assistant setup instructions
├── pyproject.toml
└── README.md______________________________________________________________________
安装
先决条件： Python 3.11+， uv 安装。
pip install fastmcp pydantic
# Or install as a package
pip install -e .______________________________________________________________________
快速设置（任何助手）
步骤1 --为您的助手复制正确的配置文件（见上表和 SETUP_GUIDE.md).
步骤2 --填写转向文件 .bob/steering/ 了解项目的产品、技术栈和结构细节。
步骤3 --启动你的助手，让它构建一个功能。MCP服务器将执行要求→ 设计→ 编写任何代码之前的任务。
______________________________________________________________________
MCP工具参考
| 工具 | 说明 |
|---|---|
initialize_spec(feature_name, workflow_variant) | 创建 .specs/{feature}/ 目录和元数据。 |
write_requirements(feature_name, requirements_data) | 写作 requirements.md.验证EARS符号；拒绝违规行为。 |
write_design(feature_name, design_data) | 写作 design.md 具有结构化的部分。 |
write_tasks(feature_name, tasks_data) | 写作 tasks.md 具有可跟踪的任务。 |
update_task_status(feature_name, task_id, new_status) | 实时更新任务的状态。 |
run_hook(hook_name, context) | 执行一个命名钩子(pre_task, post_task, post_save). |
______________________________________________________________________
内置安全：隐私过滤器
服务器包括一个内置 隐私过滤器 自动清除所有人工智能生成内容中的敏感数据 *之前* 它是写给 .specs/ 目录。这可以防止助手意外地将凭据泄漏到项目的git存储库中。
它会自动检测和编辑：
- AWS访问和密钥
- GitHub代币
- OpenAI和Anthropic API密钥
- 通用API密钥和承载令牌
- 密码和SSH私钥
- 数据库连接字符串
- 内部IP地址
______________________________________________________________________
运行测试
python3 tests/test_server.py______________________________________________________________________
EARS符号参考
每个需求都必须遵循需求语法简易方法（EARS）：
[WHEN ] [WHILE
] THE SHALL 有效期： WHEN a user submits valid credentials THE SYSTEM SHALL grant access
无效（被拒绝）： Users should be able to log in --失踪应
______________________________________________________________________
根据助理设置
看 SETUP_GUIDE.md 有关每个支持的助手的详细分步说明。
______________________________________________________________________
致谢
上下文注入和合规门模式的灵感来自 大象AI/大象 --用于AI代理的本地第一持久内存引擎。Elefante在存储前进行秘密清理的方法也为隐私过滤器的设计提供了信息。