spec-server 0.6.3
MCP server for structured feature development through Requirements → Design → Tasks workflow
License: MIT
Requires Python: >=3.12
Keywords: design, feature-development, mcp, requirements, specification, tasks, workflow

# 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
- **Enhanced Design Format**: Intent/Goals/Logic structure for all technical elements
- **Auto-Format Task Lists**: Automatic formatting and requirements linking for tasks
- **LLM Guidance**: Built-in guidance system for AI assistants with conversation templates
- **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 and completion validation
- **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

### `get_full_guidance`
Get the complete LLM guidance document for effective spec-server usage.

**Returns:** Complete guidance on conversational approach, enhanced design format, and auto-format task lists.

### `get_guidance`
Get phase-specific guidance for requirements, design, or tasks phases.

**Parameters:**
- `phase` (string): "requirements" | "design" | "tasks" | "general"

**Returns:** Phase-specific conversation starters, templates, and best practices.

## LLM Guidance System

spec-server includes a comprehensive guidance system designed to help AI assistants use the tool effectively through conversational interactions with users.

### Accessing Guidance

**For AI Assistants:**
- Use `get_full_guidance()` to access the complete guidance document
- Use `get_guidance(phase="requirements|design|tasks")` for phase-specific guidance
- Guidance includes conversation starters, templates, and best practices

**For Developers:**
- Guidance is available at [`docs/llm-guidance.md`](docs/llm-guidance.md)
- Automatically accessible through MCP tools when using spec-server
- Always up-to-date with the installed version

### Enhanced Features

**Enhanced Design Format:**
- All technical elements use Intent/Goals/Logic structure
- Intent: Brief description of purpose
- Goals: Specific, measurable objectives
- Logic: Detailed implementation approach

**Auto-Format Task Lists:**
- Tasks are automatically formatted into consistent structure
- Requirements references are automatically added
- Non-task content is moved to appropriate documents
- Task completion is validated against requirements and design

## 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
- Use Intent/Goals/Logic structure for all technical elements
- 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
- System automatically formats tasks and links to requirements
- Tasks are validated against requirements and design upon completion
- Tasks ready for execution by coding agents

## 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 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)
- LLM Guidance: [docs/llm-guidance.md](docs/llm-guidance.md)
- Documentation: [Coming Soon]

## Roadmap