内容
# spec-server
一个 MCP (Model Context Protocol) 服务器，通过系统的三阶段工作流程提供结构化的功能开发能力：**Requirements → Design → Implementation Tasks**。
## Overview
spec-server 帮助 AI 助手和开发者通过结构化的方法将粗略的功能想法转化为可执行的实施计划：
1. **Requirements Phase**：以 EARS 格式定义用户故事和验收标准
2. **Design Phase**：创建全面的技术设计文档
3. **Tasks Phase**：生成具有测试驱动开发重点的可操作实施任务
## Features
- **Systematic Workflow**：强制执行 Requirements → Design → Tasks 阶段的进展
- **Enhanced Design Format**：所有技术元素的意图/目标/逻辑结构
- **Auto-Format Task Lists**：任务的自动格式化和需求链接
- **LLM Guidance**：具有对话模板的 AI 助手的内置指导系统
- **MCP Integration**：与任何 MCP 兼容的 AI 助手一起使用
- **File References**：支持 `#[[file:path]]` 语法以包含外部规范
- **Task Management**：具有状态更新和完成验证的分层任务跟踪
- **Multiple Transports**：支持 stdio 和 SSE (Server-Sent Events) 传输方法
- **Validation**：内置的文档格式和工作流程转换验证
## Installation
### From PyPI
```bash
pip install spec-server
```
### From Source
```bash
git clone https://github.com/teknologika/spec-server.git
cd spec-server
pip install -e .
```
## Usage
### As MCP Server
添加到您的 MCP 客户端配置：
```json
{
"mcpServers": {
"spec-server": {
"command": "spec-server",
"args": ["stdio"],
"disabled": false
}
}
}
```
### Command Line
```bash
# Run with stdio transport (default)
spec-server
# Run with SSE transport on port 8000
spec-server sse 8000
# Run with SSE transport on custom port
spec-server sse 3000
```
## MCP Tools
该服务器公开了以下 MCP 工具：
### `create_spec`
创建一个新的功能规范，其中包含初始需求文档。
**Parameters:**
- `feature_name` (string): Kebab-case 功能标识符
- `initial_idea` (string): 用户的粗略功能描述
### `update_spec_document`
使用工作流程验证更新需求、设计或任务文档。
**Parameters:**
- `feature_name` (string): 目标规范标识符
- `document_type` (enum): "requirements" | "design" | "tasks"
- `content` (string): 更新的文档内容
- `phase_approval` (boolean): 用户是否批准当前阶段
### `list_specs`
列出所有现有规范及其当前状态和进度。
### `read_spec_document`
检索具有文件引用解析的规范文档的内容。
**Parameters:**
- `feature_name` (string): 目标规范标识符
- `document_type` (enum): "requirements" | "design" | "tasks"
### `execute_task`
从任务文档中执行特定的实施任务。
**Parameters:**
- `feature_name` (string): 目标规范标识符
- `task_identifier` (string): 任务编号/标识符
### `delete_spec`
完全删除规范，包括所有文档。
**Parameters:**
- `feature_name` (string): 目标规范标识符
### `get_full_guidance`
获取有效的 spec-server 使用的完整 LLM 指导文档。
**Returns:** 关于对话方法、增强的设计格式和自动格式化任务列表的完整指导。
### `get_guidance`
获取需求、设计或任务阶段的特定于阶段的指导。
**Parameters:**
- `phase` (string): "requirements" | "design" | "tasks" | "general"
**Returns:** 特定于阶段的对话启动器、模板和最佳实践。
## LLM Guidance System
spec-server 包括一个全面的指导系统，旨在帮助 AI 助手通过与用户的对话互动有效地使用该工具。
### Accessing Guidance
**For AI Assistants:**
- 使用 `get_full_guidance()` 访问完整的指导文档
- 使用 `get_guidance(phase="requirements|design|tasks")` 获取特定于阶段的指导
- 指导包括对话启动器、模板和最佳实践
**For Developers:**
- 指导位于 [`docs/llm-guidance.md`](docs/llm-guidance.md)
- 在使用 spec-server 时，可以通过 MCP 工具自动访问
- 始终与已安装的版本保持同步
### Enhanced Features
**Enhanced Design Format:**
- 所有技术元素都使用意图/目标/逻辑结构
- Intent：目的的简要描述
- Goals：具体、可衡量的目标
- Logic：详细的实施方法
**Auto-Format Task Lists:**
- 任务会自动格式化为一致的结构
- 自动添加需求参考
- 非任务内容将移动到相应的文档
- 任务完成情况根据需求和设计进行验证
## Workflow
### 1. Requirements Phase
- 以“As a [role], I want [feature], so that [benefit]”格式创建用户故事
- 使用 EARS（Easy Approach to Requirements Syntax）定义验收标准
- 必须在进入设计阶段之前获得明确批准
### 2. Design Phase
- 根据批准的需求生成全面的技术设计
- 对所有技术元素使用意图/目标/逻辑结构
- 包括以下部分：概述、架构、组件、数据模型、错误处理、测试
- 进行研究并将发现纳入设计决策
- 必须在进入任务阶段之前获得明确批准
### 3. Tasks Phase
- 创建专注于代码开发的可操作实施任务
- 系统自动格式化任务并链接到需求
- 任务在完成后根据需求和设计进行验证
- 任务已准备好由编码代理执行
## File Structure
```
specs/
├── feature-name-1/
│ ├── requirements.md # EARS format requirements
│ ├── design.md # Intent/Goals/Logic format design
│ └── tasks.md # Auto-formatted tasks with requirements links
├── feature-name-2/
│ ├── requirements.md
│ └── design.md
├── completed/ # Automatically moved completed specs
│ └── old-feature/
│ ├── requirements.md
│ ├── design.md
│ └── tasks.md
└── .spec-metadata.json # Spec tracking and progress metadata
```
## File References
Spec 文档支持使用语法 `#[[file:relative/path/to/file.md]]` 的文件引用。这些引用会自动解析，并且在读取文档时会包含其内容。
Example:
```markdown
# API Design
The API follows the OpenAPI specification defined in:
#[[file:api/openapi.yaml]]
```
## Development
### Setup Development Environment
```bash
git clone https://github.com/teknologika/spec-server.git
cd spec-server
pip install -e ".[dev]"
```
### Run Tests
```bash
pytest
```
### Code Quality
```bash
# Format code
black src tests
# Sort imports
isort src tests
# Lint code
flake8 src tests
# Type checking
mypy src
```
## Configuration
### Workspace Integration
spec-server 具有智能工作区检测功能，可在 IDE 或项目目录中运行时自动使用您的项目文件组织您的规范。
**How It Works:**
- **Automatic Detection**：从当前目录向上扫描，寻找工作区指示器
- **Smart Placement**：在检测到的工作区根目录中创建 `.specs/` 目录
- **Fallback Behavior**：如果未检测到工作区，则在当前位置使用 `specs/` 目录
- **IDE Friendly**：与 VS Code、IntelliJ、Sublime Text 和其他编辑器无缝协作
**Workspace Indicators:**
- `.git` (Git repository)
- `package.json` (Node.js project)
- `pyproject.toml` (Python project)
- `Cargo.toml` (Rust project)
- `go.mod` (Go project)
- `pom.xml` (Maven project)
- `.vscode`, `.idea` (IDE configurations)
- `README.md`, `LICENSE`, `Makefile` (common project files)
**Example Structure:**
```
my-project/ ← Detected workspace root
├── .git/
├── src/
├── package.json
├── README.md
└── .specs/ ← Specs automatically placed here
├── user-auth/
│ ├── requirements.md
│ ├── design.md
│ └── tasks.md
├── data-export/
│ └── requirements.md
└── .spec-metadata.json
```
**Benefits:**
- **Version Control**：规范可以与您的代码一起提交
- **Team Collaboration**：跨团队成员共享规范
- **Context Awareness**：规范在逻辑上与相关项目分组
- **IDE Integration**：规范显示在您的项目文件树中
- **Automatic Organization**：无需手动目录管理
**Configuration:**
```bash
# Enable/disable workspace detection (default: true)
export SPEC_SERVER_AUTO_DETECT_WORKSPACE=true
# Customize specs directory name in workspace (default: ".specs")
export SPEC_SERVER_WORKSPACE_SPECS_DIR=".my-specs"
# Customize fallback directory name (default: "specs")
export SPEC_SERVER_SPECS_DIR="my-specs"
```
### Environment Variables
- `SPEC_SERVER_SPECS_DIR`：规范的基本目录（默认值：“specs”）
- `SPEC_SERVER_AUTO_DETECT_WORKSPACE`：启用工作区检测（默认值：“true”）
- `SPEC_SERVER_WORKSPACE_SPECS_DIR`：工作区中的规范目录名称（默认值：“.specs”）
- `SPEC_SERVER_PORT`：默认 SSE 服务器端口（默认值：8000）
- `SPEC_SERVER_LOG_LEVEL`：日志记录级别（默认值：“INFO”）
### Configuration File
可选 `spec-server.json`：
```json
{
"specs_dir": "specs",
"auto_detect_workspace": true,
"workspace_specs_dir": ".specs",
"host": "127.0.0.1",
"port": 8000,
"transport": "stdio",
"log_level": "INFO",
"auto_backup": true,
"cache_enabled": true
}
```
## Contributing
1. Fork 存储库
2. 创建一个功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交您的更改 (`git commit -m 'Add amazing feature'`)
4. 将其推送到分支 (`git push origin feature/amazing-feature`)
5. 打开一个 Pull Request
## License
该项目已获得 MIT 许可 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
## Support
- GitHub Issues: [https://github.com/teknologika/spec-server/issues](https://github.com/teknologika/spec-server/issues)
- LLM Guidance: [docs/llm-guidance.md](docs/llm-guidance.md)
- Documentation: [Coming Soon]
## Roadmap
连接信息
猜你喜欢
暂无推荐服务器