# spec-server
An MCP (Model Context Protocol) server that provides structured feature development capabilities through a systematic three-phase workflow: **Requirements → Design → Implementation Tasks**.
## Overview
spec-server helps AI assistants and developers transform rough feature ideas into executable implementation plans through a structured approach:
1. **Requirements Phase**: Define user stories and acceptance criteria in EARS format
2. **Design Phase**: Create comprehensive technical design documents
3. **Tasks Phase**: Generate actionable implementation tasks with test-driven development focus
## Features
- **Systematic Workflow**: Enforced progression through Requirements → Design → Tasks phases
- **MCP Integration**: Works with any MCP-compatible AI assistant
- **File References**: Support for `#[[file:path]]` syntax to include external specifications
- **Task Management**: Hierarchical task tracking with status updates
- **Multiple Transports**: Support for both stdio and SSE (Server-Sent Events) transport methods
- **Validation**: Built-in validation for document formats and workflow transitions
## 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
Add to your MCP client configuration:
```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
The server exposes the following MCP tools:
### `create_spec`
Create a new feature specification with initial requirements document.
**Parameters:**
- `feature_name` (string): Kebab-case feature identifier
- `initial_idea` (string): User's rough feature description
### `update_spec_document`
Update requirements, design, or tasks documents with workflow validation.
**Parameters:**
- `feature_name` (string): Target spec identifier
- `document_type` (enum): "requirements" | "design" | "tasks"
- `content` (string): Updated document content
- `phase_approval` (boolean): Whether user approves current phase
### `list_specs`
List all existing specifications with their current status and progress.
### `read_spec_document`
Retrieve content of spec documents with file reference resolution.
**Parameters:**
- `feature_name` (string): Target spec identifier
- `document_type` (enum): "requirements" | "design" | "tasks"
### `execute_task`
Execute a specific implementation task from the tasks document.
**Parameters:**
- `feature_name` (string): Target spec identifier
- `task_identifier` (string): Task number/identifier
### `delete_spec`
Remove a specification entirely including all documents.
**Parameters:**
- `feature_name` (string): Target spec identifier
## Workflow
### 1. Requirements Phase
- Create user stories in "As a [role], I want [feature], so that [benefit]" format
- Define acceptance criteria using EARS (Easy Approach to Requirements Syntax)
- Must receive explicit approval before advancing to design phase
### 2. Design Phase
- Generate comprehensive technical design based on approved requirements
- Include sections: Overview, Architecture, Components, Data Models, Error Handling, Testing
- Conduct research and incorporate findings into design decisions
- Must receive explicit approval before advancing to tasks phase
### 3. Tasks Phase
- Create actionable implementation tasks focused on code development
- Format as numbered checkboxes with hierarchical structure
- Reference specific requirements and ensure test-driven development
- Tasks ready for execution by coding agents
## File Structure
```
specs/
├── feature-name-1/
│ ├── requirements.md
│ ├── design.md
│ └── tasks.md
├── feature-name-2/
│ ├── requirements.md
│ └── design.md
└── .spec-metadata.json
```
## File References
Spec documents support file references using the syntax `#[[file:relative/path/to/file.md]]`. These references are automatically resolved and their content is included when documents are read.
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 features intelligent workspace detection that automatically organizes your specifications with your project files when running in an IDE or project directory.
**How It Works:**
- **Automatic Detection**: Scans upward from current directory looking for workspace indicators
- **Smart Placement**: Creates `.specs/` directory at the detected workspace root
- **Fallback Behavior**: Uses `specs/` directory in current location if no workspace detected
- **IDE Friendly**: Works seamlessly with VS Code, IntelliJ, Sublime Text, and other editors
**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**: Specs can be committed alongside your code
- **Team Collaboration**: Shared specifications across team members
- **Context Awareness**: Specs are logically grouped with related projects
- **IDE Integration**: Specifications appear in your project file tree
- **Automatic Organization**: No manual directory management required
**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`: Base directory for specs (default: "specs")
- `SPEC_SERVER_AUTO_DETECT_WORKSPACE`: Enable workspace detection (default: "true")
- `SPEC_SERVER_WORKSPACE_SPECS_DIR`: Specs directory name in workspace (default: ".specs")
- `SPEC_SERVER_PORT`: Default SSE server port (default: 8000)
- `SPEC_SERVER_LOG_LEVEL`: Logging level (default: "INFO")
### Configuration File
Optional `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 the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- GitHub Issues: [https://github.com/teknologika/spec-server/issues](https://github.com/teknologika/spec-server/issues)
- Documentation: [Coming Soon]
## Roadmap
Raw data
{
"_id": null,
"home_page": null,
"name": "spec-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "design, feature-development, mcp, requirements, specification, tasks, workflow",
"author": null,
"author_email": "Teknologika <hello@teknologika.com>",
"download_url": "https://files.pythonhosted.org/packages/bb/9d/2bf3052d802a6d30373134fff7674641a7da927daa11757de87bfb639b33/spec_server-0.3.0.tar.gz",
"platform": null,
"description": "# spec-server\n\nAn MCP (Model Context Protocol) server that provides structured feature development capabilities through a systematic three-phase workflow: **Requirements \u2192 Design \u2192 Implementation Tasks**.\n\n## Overview\n\nspec-server helps AI assistants and developers transform rough feature ideas into executable implementation plans through a structured approach:\n\n1. **Requirements Phase**: Define user stories and acceptance criteria in EARS format\n2. **Design Phase**: Create comprehensive technical design documents \n3. **Tasks Phase**: Generate actionable implementation tasks with test-driven development focus\n\n## Features\n\n- **Systematic Workflow**: Enforced progression through Requirements \u2192 Design \u2192 Tasks phases\n- **MCP Integration**: Works with any MCP-compatible AI assistant\n- **File References**: Support for `#[[file:path]]` syntax to include external specifications\n- **Task Management**: Hierarchical task tracking with status updates\n- **Multiple Transports**: Support for both stdio and SSE (Server-Sent Events) transport methods\n- **Validation**: Built-in validation for document formats and workflow transitions\n\n## Installation\n\n### From PyPI\n\n```bash\npip install spec-server\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/teknologika/spec-server.git\ncd spec-server\npip install -e .\n```\n\n## Usage\n\n### As MCP Server\n\nAdd to your MCP client configuration:\n\n```json\n{\n \"mcpServers\": {\n \"spec-server\": {\n \"command\": \"spec-server\",\n \"args\": [\"stdio\"],\n \"disabled\": false\n }\n }\n}\n```\n\n### Command Line\n\n```bash\n# Run with stdio transport (default)\nspec-server\n\n# Run with SSE transport on port 8000\nspec-server sse 8000\n\n# Run with SSE transport on custom port\nspec-server sse 3000\n```\n\n## MCP Tools\n\nThe server exposes the following MCP tools:\n\n### `create_spec`\nCreate a new feature specification with initial requirements document.\n\n**Parameters:**\n- `feature_name` (string): Kebab-case feature identifier\n- `initial_idea` (string): User's rough feature description\n\n### `update_spec_document`\nUpdate requirements, design, or tasks documents with workflow validation.\n\n**Parameters:**\n- `feature_name` (string): Target spec identifier\n- `document_type` (enum): \"requirements\" | \"design\" | \"tasks\"\n- `content` (string): Updated document content\n- `phase_approval` (boolean): Whether user approves current phase\n\n### `list_specs`\nList all existing specifications with their current status and progress.\n\n### `read_spec_document`\nRetrieve content of spec documents with file reference resolution.\n\n**Parameters:**\n- `feature_name` (string): Target spec identifier\n- `document_type` (enum): \"requirements\" | \"design\" | \"tasks\"\n\n### `execute_task`\nExecute a specific implementation task from the tasks document.\n\n**Parameters:**\n- `feature_name` (string): Target spec identifier\n- `task_identifier` (string): Task number/identifier\n\n### `delete_spec`\nRemove a specification entirely including all documents.\n\n**Parameters:**\n- `feature_name` (string): Target spec identifier\n\n## Workflow\n\n### 1. Requirements Phase\n- Create user stories in \"As a [role], I want [feature], so that [benefit]\" format\n- Define acceptance criteria using EARS (Easy Approach to Requirements Syntax)\n- Must receive explicit approval before advancing to design phase\n\n### 2. Design Phase\n- Generate comprehensive technical design based on approved requirements\n- Include sections: Overview, Architecture, Components, Data Models, Error Handling, Testing\n- Conduct research and incorporate findings into design decisions\n- Must receive explicit approval before advancing to tasks phase\n\n### 3. Tasks Phase\n- Create actionable implementation tasks focused on code development\n- Format as numbered checkboxes with hierarchical structure\n- Reference specific requirements and ensure test-driven development\n- Tasks ready for execution by coding agents\n\n## File Structure\n\n```\nspecs/\n\u251c\u2500\u2500 feature-name-1/\n\u2502 \u251c\u2500\u2500 requirements.md\n\u2502 \u251c\u2500\u2500 design.md\n\u2502 \u2514\u2500\u2500 tasks.md\n\u251c\u2500\u2500 feature-name-2/\n\u2502 \u251c\u2500\u2500 requirements.md\n\u2502 \u2514\u2500\u2500 design.md\n\u2514\u2500\u2500 .spec-metadata.json\n```\n\n## File References\n\nSpec documents support file references using the syntax `#[[file:relative/path/to/file.md]]`. These references are automatically resolved and their content is included when documents are read.\n\nExample:\n```markdown\n# API Design\n\nThe API follows the OpenAPI specification defined in:\n#[[file:api/openapi.yaml]]\n```\n\n## Development\n\n### Setup Development Environment\n\n```bash\ngit clone https://github.com/teknologika/spec-server.git\ncd spec-server\npip install -e \".[dev]\"\n```\n\n### Run Tests\n\n```bash\npytest\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack src tests\n\n# Sort imports\nisort src tests\n\n# Lint code\nflake8 src tests\n\n# Type checking\nmypy src\n```\n\n## Configuration\n\n### Workspace Integration\n\nspec-server features intelligent workspace detection that automatically organizes your specifications with your project files when running in an IDE or project directory.\n\n**How It Works:**\n- **Automatic Detection**: Scans upward from current directory looking for workspace indicators\n- **Smart Placement**: Creates `.specs/` directory at the detected workspace root\n- **Fallback Behavior**: Uses `specs/` directory in current location if no workspace detected\n- **IDE Friendly**: Works seamlessly with VS Code, IntelliJ, Sublime Text, and other editors\n\n**Workspace Indicators:**\n- `.git` (Git repository)\n- `package.json` (Node.js project)\n- `pyproject.toml` (Python project)\n- `Cargo.toml` (Rust project)\n- `go.mod` (Go project)\n- `pom.xml` (Maven project)\n- `.vscode`, `.idea` (IDE configurations)\n- `README.md`, `LICENSE`, `Makefile` (common project files)\n\n**Example Structure:**\n```\nmy-project/ \u2190 Detected workspace root\n\u251c\u2500\u2500 .git/\n\u251c\u2500\u2500 src/\n\u251c\u2500\u2500 package.json\n\u251c\u2500\u2500 README.md\n\u2514\u2500\u2500 .specs/ \u2190 Specs automatically placed here\n \u251c\u2500\u2500 user-auth/\n \u2502 \u251c\u2500\u2500 requirements.md\n \u2502 \u251c\u2500\u2500 design.md\n \u2502 \u2514\u2500\u2500 tasks.md\n \u251c\u2500\u2500 data-export/\n \u2502 \u2514\u2500\u2500 requirements.md\n \u2514\u2500\u2500 .spec-metadata.json\n```\n\n**Benefits:**\n- **Version Control**: Specs can be committed alongside your code\n- **Team Collaboration**: Shared specifications across team members\n- **Context Awareness**: Specs are logically grouped with related projects\n- **IDE Integration**: Specifications appear in your project file tree\n- **Automatic Organization**: No manual directory management required\n\n**Configuration:**\n```bash\n# Enable/disable workspace detection (default: true)\nexport SPEC_SERVER_AUTO_DETECT_WORKSPACE=true\n\n# Customize specs directory name in workspace (default: \".specs\")\nexport SPEC_SERVER_WORKSPACE_SPECS_DIR=\".my-specs\"\n\n# Customize fallback directory name (default: \"specs\")\nexport SPEC_SERVER_SPECS_DIR=\"my-specs\"\n```\n\n### Environment Variables\n\n- `SPEC_SERVER_SPECS_DIR`: Base directory for specs (default: \"specs\")\n- `SPEC_SERVER_AUTO_DETECT_WORKSPACE`: Enable workspace detection (default: \"true\")\n- `SPEC_SERVER_WORKSPACE_SPECS_DIR`: Specs directory name in workspace (default: \".specs\")\n- `SPEC_SERVER_PORT`: Default SSE server port (default: 8000)\n- `SPEC_SERVER_LOG_LEVEL`: Logging level (default: \"INFO\")\n\n### Configuration File\n\nOptional `spec-server.json`:\n\n```json\n{\n \"specs_dir\": \"specs\",\n \"auto_detect_workspace\": true,\n \"workspace_specs_dir\": \".specs\",\n \"host\": \"127.0.0.1\",\n \"port\": 8000,\n \"transport\": \"stdio\",\n \"log_level\": \"INFO\",\n \"auto_backup\": true,\n \"cache_enabled\": true\n}\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- GitHub Issues: [https://github.com/teknologika/spec-server/issues](https://github.com/teknologika/spec-server/issues)\n- Documentation: [Coming Soon]\n\n## Roadmap\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for structured feature development through Requirements \u2192 Design \u2192 Tasks workflow",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/teknologika/spec-server",
"Issues": "https://github.com/teknologika/spec-server/issues",
"Repository": "https://github.com/teknologika/spec-server"
},
"split_keywords": [
"design",
" feature-development",
" mcp",
" requirements",
" specification",
" tasks",
" workflow"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "03d8d11ed07d77d5e020aa21a15ef032c3b9a321a74dee0c860a195bdb780326",
"md5": "015c1df689f8e046be9da951f5d8af57",
"sha256": "3f6f16e0d277c2079da1907c123d563a6a7a8787f87ea055462bb8fd1d963e15"
},
"downloads": -1,
"filename": "spec_server-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "015c1df689f8e046be9da951f5d8af57",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 47228,
"upload_time": "2025-07-17T22:57:57",
"upload_time_iso_8601": "2025-07-17T22:57:57.161501Z",
"url": "https://files.pythonhosted.org/packages/03/d8/d11ed07d77d5e020aa21a15ef032c3b9a321a74dee0c860a195bdb780326/spec_server-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bb9d2bf3052d802a6d30373134fff7674641a7da927daa11757de87bfb639b33",
"md5": "0ed07541170a243cecabd3f907e4907b",
"sha256": "d6029e7d9336129bbad62ec69d3bc066d1827c7e2d814cee9049bd5b04744c53"
},
"downloads": -1,
"filename": "spec_server-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "0ed07541170a243cecabd3f907e4907b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 82849,
"upload_time": "2025-07-17T22:57:58",
"upload_time_iso_8601": "2025-07-17T22:57:58.327355Z",
"url": "https://files.pythonhosted.org/packages/bb/9d/2bf3052d802a6d30373134fff7674641a7da927daa11757de87bfb639b33/spec_server-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-17 22:57:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "teknologika",
"github_project": "spec-server",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "spec-server"
}
JSON
