# SpecForged MCP Server
[](https://pypi.org/project/specforged/)
[](https://pypi.org/project/specforged/)
[](https://github.com/whit3rabbit/specforged/actions/workflows/test.yml)
A Model Context Protocol (MCP) server that implements specification-driven development with EARS notation, intelligent mode classification, and structured workflow management.
## ✨ TL;DR: How specforged Works
**SpecForged transforms your AI conversations into structured software development workflows.**
### The Planning Workflow (Guided by Wizard Mode)
**🧙♂️ Wizard Mode covers 3 planning phases only:**
1. **Requirements** → Define user stories with EARS notation (5 requirement types)
2. **Design** → Interactive architecture and component planning
3. **Planning** → Auto-generate numbered task hierarchies (1, 1.1, 1.2...)
**⚡ Execution Phase (Separate from Wizard):**
4. **Execution** → Context-aware task implementation with automatic test generation
**IMPORTANT**: The wizard creates specifications and plans, but does NOT implement code. Implementation happens in a separate execution phase with proper context loading and test generation.
### Natural Language Interface
Just talk naturally - specforged understands:
- *"Use specforged to create a new project"* → 🧙♂️ **Activates wizard mode**
- *"Create a spec for a user dashboard"* → Starts requirements phase
- *"Mark task 2.1 as done"* → Updates progress, suggests next tasks
- *"How's my progress?"* → Shows completion stats and milestones
- *"What should I work on next?"* → Lists available tasks with context
### 🎯 Key Features
**EARS Requirements** - All 5 patterns supported:
- **Ubiquitous**: THE SYSTEM SHALL always validate inputs
- **Event-Driven**: WHEN user clicks login THE SYSTEM SHALL authenticate
- **State-Driven**: WHILE processing THE SYSTEM SHALL show progress
- **Optional**: WHERE premium enabled THE SYSTEM SHALL unlock features
- **Error-Handling**: IF invalid data THEN THE SYSTEM SHALL show errors
**Smart Task Management**:
- ✅ Auto-complete parent tasks when all subtasks done
- 🔗 Requirement traceability (every task links to user needs)
- 📊 Real-time progress tracking with motivational feedback
- 🎯 Dependency-aware task ordering
**Conversational Workflow**:
- Interactive prompts guide each phase transition
- Natural language commands OR function calls
- Automatic progress updates and celebration
- Built-in coaching for requirement refinement
### 🏗️ Generated Structure
```
specifications/
└── my-dashboard/
├── spec.json # Metadata & status
├── requirements.md # User stories + EARS
├── design.md # Architecture decisions
└── tasks.md # Checkbox implementation plan
```
**Perfect for**: Feature specs, API design, project planning, requirement gathering, team alignment, and structured development workflows.
## Quick Start
🎉 **SpecForged is now available on [PyPI](https://pypi.org/project/specforged/)!**
### 🧙♂️ Interactive Project Wizard (Recommended)
The fastest way to get started with SpecForged is using the **interactive project wizard** - your guided companion for creating complete specifications:
```bash
# Install specforged
pipx install specforged
# Set up with your LLM (Claude Code, Cursor, etc.)
# Then simply say: "Start specforge wizard for my project"
```
The wizard will guide you through:
1. **Project Setup**: Name, description, and project type
2. **Requirements Gathering**: User stories with EARS notation
3. **Design Phase**: Architecture and component selection
4. **Task Generation**: Automatic implementation plan creation
Available project templates:
- `web-app`: Full-stack web application
- `rest-api`: RESTful API service
- `cli-tool`: Command-line tool
- `python-lib`: Python library
- `microservice`: Microservice architecture
### Quick Installation
```bash
# Install specforged globally with pipx
pipx install specforged
# Verify installation
specforged --version
```
**Choose your integration method:**
- 🔌 See combined setup: **[IDE & Host Integration](#ide--host-integration)**
#### Available Commands
- `specforged`: Run MCP server (default)
- `specforged-http`: Run HTTP server for web integration
- `specforged-cli`: Simplified CLI (same as `specforged`, kept for compatibility)
#### Management
```bash
# Upgrade to latest version
pipx upgrade specforged
# Uninstall
pipx uninstall specforged
```
## Installation for Development
⚠️ **Important**: For local development work, you need MCP servers that can write to your project files. HTTP-based deployments run on remote servers and cannot write to your local project directories.
## IDE & Host Integration
Below are collapsible, focused setup guides. Expand only what you need.
<details>
<summary><strong>Claude Code (recommended for coding)</strong></summary>
The best way to use specforged for active development.
```bash
# Install specforged globally with pipx
pipx install specforged
# Add to Claude Code with project scope (enables team sharing)
claude mcp add --scope=project specforged specforged
# Or for personal use only
claude mcp add specforged specforged
```
Why project scope? It creates a `.mcp.json` in your project root that teammates can reuse:
```json
{
"mcpServers": {
"specforged": {
"command": "specforged",
"args": [],
"env": {}
}
}
}
```
File access: Claude Code will prompt for permission to write to your project directory.
</details>
<details>
<summary><strong>Cursor IDE</strong></summary>
1) Install specforged: `pipx install specforged`
2) Configure MCP in Cursor settings (Advanced → MCP) or create `.cursor/mcp.json` in your project root.
- Important: There is no reliable auto-detection of the project folder. You must hardcode the absolute project path via `SPECFORGE_PROJECT_ROOT`.
```json
{
"mcpServers": {
"specforged": {
"command": "specforged",
"args": [],
"env": {
"SPECFORGE_PROJECT_ROOT": "/absolute/path/to/this/project",
"SPECFORGE_BASE_DIR": ".specifications"
}
}
}
}
```
3) Restart Cursor. 4) Grant local file access when prompted.
5) Because this file lives in the project (`.cursor/mcp.json`), the hardcoded path is per-project.
</details>
<details>
<summary><strong>Windsurf IDE</strong></summary>
1) Install: `pipx install specforged`
2) Configure via Settings → Cascade → Plugins, or edit `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"specforged": {
"command": "specforged",
"args": [],
"env": {
"SPECFORGE_PROJECT_ROOT": "/absolute/path/to/your/project",
"SPECFORGE_BASE_DIR": ".specifications"
}
}
}
}
```
3) Press refresh, then restart Windsurf.
4) Note: Windsurf does not reliably pass your workspace folder as the server CWD. There is no auto-detect. You must hardcode the absolute project path using `SPECFORGE_PROJECT_ROOT` as shown above.
- If you work across multiple projects, add separate entries (e.g., `specforged-foo`, `specforged-bar`) each with its own `SPECFORGE_PROJECT_ROOT`, or use a small wrapper script that `cd`s into the project before launching `specforged`.
</details>
<details>
<summary><strong>VS Code (Continue/Codeium/etc.)</strong></summary>
1) `pipx install specforged`
2) Add specforged MCP server in your AI extension settings
3) Ensure workspace file permissions are enabled
</details>
<details>
<summary><strong>Claude Desktop</strong></summary>
Note: Best for chat/spec work. For coding, prefer Claude Code.
Install:
```bash
pipx install specforged
```
**Basic Configuration** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"specforged": { "command": "specforged" }
}
}
```
**Advanced Configuration** (recommended for reliable project detection):
```json
{
"mcpServers": {
"specforged": {
"command": "specforged",
"args": [],
"env": {
"SPECFORGE_PROJECT_ROOT": "/absolute/path/to/your/project",
"SPECFORGE_BASE_DIR": ".specifications"
}
}
}
}
```
Use the advanced configuration when:
- Working with multiple projects
- Basic config fails to detect your project root correctly
- You need explicit control over where specifications are stored
Config file paths:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
</details>
## Permissions & Path Security
- **Project root = CWD**: specforged treats the server's current working directory as the project root. Run the server from your project folder.
- **Specs location**: Defaults to `./.specifications/` under the project root. You can override by initializing `SpecificationManager(base_dir=Path("./.my-specs"))`.
- **Strict path validation**: All tool paths (e.g., `read_file`, `write_file`, `create_directory`, `edit_block`) are resolved and must remain within the project root. Absolute and relative paths are allowed but are validated against the project root after resolution.
- **No escapes**: Attempts to access files outside the project (e.g., `..`, absolute paths elsewhere, or via symlinks) are rejected.
- **Symlinks**: Paths are fully resolved before validation. Symlinks that point outside the project root are denied.
- **Large files**: Operations on very large files may be warned against or rejected depending on host constraints.
- **IDE prompts**: IDEs/hosts (Claude Code, Windsurf, Cursor, etc.) may prompt for permission before allowing write access to your workspace—accept to enable file creation in `./.specifications/`.
Tip: Keep the server process scoped per-project to avoid writing specs into the wrong project directory.
## Advanced Installation Methods
### Docker with Bind Mounts
For Docker users who want to persist specifications locally:
```bash
# Build the Docker image
docker build -t specforged:latest .
```
Configure in Claude Desktop with bind mount:
```json
{
"mcpServers": {
"specforged": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"--mount", "type=bind,src=/absolute/path/to/host/specifications,dst=/app/specifications",
"specforged:latest",
"python", "main.py"
]
}
}
}
```
**Notes:**
- Container writes to `/app/specifications` which maps to your local directory
- Specifications persist on your local machine
- Restart Claude Desktop after configuration changes
### Manual Development Installation
For development or local testing without pipx:
```bash
# Clone the repository
git clone https://github.com/whit3rabbit/specforged.git
cd specforged
# Install dependencies
pip install -r requirements.txt
# Test locally
python main.py
```
Configure in Claude Desktop:
```json
{
"mcpServers": {
"specforged": {
"command": "python",
"args": ["/absolute/path/to/specforged/main.py"]
}
}
}
```
## Example
```bash
Use specforged to create a spec for a TODO list app that supports creating, editing, completing, and filtering tasks.
```
## Overview
specforged transforms ad-hoc development into a structured process by:
- **Classifying intent** - Routes requests to appropriate handlers (spec mode vs. action mode)
- **Enforcing workflow** - Guides through requirements → design → tasks → execution phases
- **Using EARS notation** - Creates unambiguous, testable requirements
- **Managing artifacts** - Maintains requirements.md, design.md, and tasks.md files
## Background
This server implements the EARS (Easy Approach to Requirements Syntax) notation, developed by Alistair Mavin et al. at Rolls-Royce (2009). EARS is an industry-standard methodology for writing clear, testable requirements, widely used in aerospace, automotive, and safety-critical systems.
## Features
### Intelligent Mode Classification
Automatically determines user intent and routes to appropriate handler:
- **Spec Mode**: Creating specifications, requirements, design documents
- **Do Mode**: Code modifications, commands, implementation tasks
- **Chat Mode**: Questions, explanations, general discussion
### Complete Specification Workflow
#### Requirements Phase
- User stories: "As a [user], I want [goal], so that [benefit]"
- EARS acceptance criteria: "WHEN [condition] THE SYSTEM SHALL [response]"
- Structured requirement tracking with unique IDs
#### Design Phase
- Technical architecture documentation
- Component specifications
- Data models and interfaces
- Sequence diagrams (Mermaid format)
- API contracts and schemas
#### Task Planning
- Discrete, trackable implementation tasks
- Dependency management
- Progress tracking (pending → in_progress → completed)
- Links to requirements for traceability
#### Execution Phase
- Individual task execution with validation
- Real-time status updates
- Progress reporting
### File Management
Automatically generates and maintains three key files per specification:
```
.specifications/
└── your-feature/
├── spec.json # Specification metadata
├── requirements.md # User stories & EARS criteria
├── design.md # Technical architecture
└── tasks.md # Implementation plan
```
## Usage
### Interactive Project Wizard (Recommended)
The quickest way to create comprehensive specifications is through conversation with your LLM:
```
User: "Start specforge wizard for my task management app"
LLM: 🎉 Project 'task-management-app' created! I'm ready to guide you through
the requirements phase. Let's start by understanding your users and their
needs. What kind of system are you building and who will use it?
User: "It's for team collaboration, users need to create and assign tasks"
LLM: Great! Let me help you create user stories. I'll use add_requirement() to
add this to your specification...
```
The wizard guides you conversationally through:
1. **Requirements**: Define user stories with EARS acceptance criteria
2. **Design**: Document system architecture and components
3. **Planning**: Generate implementation tasks automatically
4. **Execution**: Track progress as tasks are completed
**Wizard Features:**
- **Guided Requirements**: Step-by-step user story creation with EARS notation help
- **Architecture Templates**: Pre-built patterns for common project types
- **Smart Task Generation**: Automatic breakdown from requirements to implementable tasks
- **Progress Tracking**: Generated tasks in checkbox format for easy progress monitoring
- **Professional Output**: Creates complete specification with requirements.md, design.md, and tasks.md
### Wizard Mode via MCP (Planning Only - Automatic Activation)
specforged can automatically activate wizard mode through natural language when using MCP integration:
#### Auto-Activation Triggers
The wizard automatically starts when:
- **No .specifications folder exists** in your project
- **Using "specforged" keyword** in requests
- **First-time setup** is detected
```bash
# These phrases trigger wizard mode automatically (PLANNING ONLY):
"Use specforged to create a new project specification"
"Start specforge wizard for my application"
"Create a new spec with specforged for payment processing"
"I need specforged to help set up my project"
"Launch the specforged wizard for user management"
"Use specforged wizard mode to design my API"
```
**⚠️ Important**: The wizard creates specifications but does NOT implement tasks. It guides you through Requirements → Design → Planning phases only.
**Pro Tip**: Just say "specforged" in your request and the wizard will activate if no specifications exist in your project!
#### Three-Phase Planning Workflow (Wizard Mode)
When wizard mode activates, you'll be guided through **PLANNING ONLY**:
1. **📝 Phase 1: Requirements Gathering**
- Interactive user story creation
- EARS notation assistance and examples
- Creates `requirements.md` with structured stories
- Real-time validation and suggestions
2. **🎨 Phase 2: System Design**
- Architecture pattern selection
- Component definition wizard
- Data model creation help
- Creates `design.md` with technical specifications
3. **✅ Phase 3: Task Generation**
- Automatic breakdown from requirements to tasks
- Dependency analysis and ordering
- Creates `tasks.md` with checkbox format
- Progress tracking setup
#### ⚡ Execution Phase (After Wizard Completion)
**The wizard does NOT execute tasks.** Implementation happens separately with:
- **Context Loading**: Automatically reads requirements.md and design.md before each task
- **Architecture Compliance**: Ensures implementation follows the planned design
- **EARS Validation**: Verifies acceptance criteria are met
- **Test Generation**: Auto-generates test templates for each completed task
- **Quality Assurance**: Validates implementation against specifications
#### Example Wizard Session
```
User: Use specforged to create a specification for user authentication
Claude: I'll start the specforged wizard to create a comprehensive specification.
📝 Phase 1/3: Requirements Gathering
• Created user story: "As a user, I want secure login..."
• Added EARS requirements with validation patterns
• Generated requirements.md ✅
🎨 Phase 2/3: System Design
• Selected MVC architecture pattern
• Defined AuthService and UserController components
• Created data models for User and Session entities
• Generated design.md ✅
✅ Phase 3/3: Task Generation
• Analyzed requirements and created 12 implementation tasks
• Established dependency relationships
• Generated tasks.md with checkbox format ✅
🎉 Complete specification created at: ./.specifications/user-authentication/
```
### Manual Specification Creation (MCP)
For experienced users or specific workflows, you can create specifications manually:
```
User: Create a spec for user authentication system
Response: Creates new specification with requirements.md, design.md, and tasks.md files
```
### Mode Classification Examples
```python
# Spec mode - Wizard activation (high priority)
"Use specforged to create a new project specification"
"Start specforge wizard for user management"
"Create a spec with specforged for payment processing"
"I need specforged to set up my API specification"
# Spec mode - Standard specification creation
"Create a spec for payment processing"
"Generate a specification for the login system"
"Execute task 3.2 from user-auth spec"
"Add a requirement to the auth spec"
# Do mode (code/action requests)
"Fix the syntax error in app.js"
"Run the test suite"
"Deploy to production"
# Chat mode (questions/explanations)
"What is EARS notation?"
"How do promises work?"
"Explain the architecture"
```
## Triggering MCP Commands
specforged integrates with Claude Desktop and other MCP hosts through natural language interactions. The system automatically classifies your input and routes requests to appropriate tools based on context and intent.
### Command Patterns
**Specification Management:**
- "Create a spec for [feature name]"
- "List all specifications"
- "Show details for [spec-id]"
**Requirements and Design:**
- "Add a requirement to [spec-id] as a [user type]..."
- "Update the design for [spec-id] with [architecture details]"
**Task Management (Checkbox Style):**
- "Generate implementation plan for [spec-id]"
- "Check off task 1.2 in [spec-id]"
- "Mark tasks 1.1, 1.2, and 2.1 as complete"
- "What tasks are ready to work on?"
- "Show progress summary for [spec-id]"
**General Queries:**
- "What is EARS notation?"
- "Explain the workflow phases"
The system will automatically invoke the appropriate MCP tools based on your natural language input.
### Available Tools
| Tool | Description | Parameters |
|------|-------------|------------|
| `classify_mode` | Classify user input intent | `user_input` |
| `create_spec` | Create new specification | `name`, `description` |
| `add_requirement` | Add user story with EARS criteria | `spec_id`, `as_a`, `i_want`, `so_that`, `ears_requirements` |
| `update_design` | Update technical design | `spec_id`, `architecture`, `components`, `data_models`, `sequence_diagrams` |
| `generate_implementation_plan` | Create task hierarchy from requirements | `spec_id` |
| `update_implementation_plan` | Refresh plan preserving completion status | `spec_id` |
| `check_task` | Mark task as completed | `spec_id`, `task_number` |
| `uncheck_task` | Mark task as pending | `spec_id`, `task_number` |
| `bulk_check_tasks` | Check multiple tasks at once | `spec_id`, `task_numbers`, `all_tasks` |
| `get_task_details` | Get detailed task information | `spec_id`, `task_number` |
| `get_next_available_tasks` | Find tasks ready to work on | `spec_id` |
| `get_task_status_summary` | Complete progress overview | `spec_id` |
| `add_implementation_task` | Add individual task to plan | `spec_id`, `title`, `description`, `dependencies`, `subtasks` |
| `execute_task` | Execute a specific task | `spec_id`, `task_id` |
| `transition_workflow_phase` | Move to next phase | `spec_id`, `target_phase` |
| `list_specifications` | List all specs | - |
| `get_specification_details` | Get spec details | `spec_id`, `include_content` |
| `create_directory` | Create a directory within project root | `path`, `exist_ok` |
| `read_file` | Read a UTF-8 text file within project root | `path` |
| `write_file` | Write/append a UTF-8 text file within project root | `path`, `content`, `mode` |
| `edit_block` | Safely replace exact text in a file | `file_path`, `old_string`, `new_string`, `expected_replacements` |
### Filesystem Tools (Project-Scoped)
These tools operate only within your current project directory (the server's CWD). Any path outside the project root is rejected.
```bash
# Create specs directory (if you want to initialize manually)
create_directory(path=".specifications")
# Create files
write_file(path=".specifications/requirements.md", content="# Requirements")
write_file(path="README.md", content="\nExtra line\n", mode="append")
# Read a file
read_file(path="src/main.py")
# Safe in-place edit
edit_block(
file_path="src/main.py",
old_string="print('Hello')",
new_string="print('Hello, World!')",
expected_replacements=1
)
```
### EARS Notation Examples
EARS (Easy Approach to Requirements Syntax) provides clear, testable requirements:
```markdown
WHEN a user submits valid credentials
THE SYSTEM SHALL authenticate and create a session
WHILE processing a payment
THE SYSTEM SHALL display a progress indicator
WHERE two-factor authentication is enabled
THE SYSTEM SHALL require a verification code
IF the session expires
THEN THE SYSTEM SHALL redirect to login
```
### Complete Workflow Example
```python
# 1. Create specification
create_spec(name="Payment Processing", description="Handle customer payments")
# 2. Add requirements
add_requirement(
spec_id="payment-processing",
as_a="customer",
i_want="to pay with multiple methods",
so_that="I can choose my preferred payment option",
ears_requirements=[
{
"condition": "WHEN a customer selects credit card",
"system_response": "display secure card entry form"
},
{
"condition": "IF payment fails",
"system_response": "show error and suggest alternatives"
}
]
)
# 3. Design architecture
update_design(
spec_id="payment-processing",
architecture="Microservices with payment gateway integration",
components=[
{"name": "PaymentService", "description": "Handles payment processing"},
{"name": "GatewayAdapter", "description": "Integrates with payment providers"}
]
)
# 4. Generate implementation plan
generate_implementation_plan(spec_id="payment-processing")
# 5. Check task progress
get_task_status_summary(spec_id="payment-processing")
# 6. Complete tasks
check_task(spec_id="payment-processing", task_number="1")
check_task(spec_id="payment-processing", task_number="2.1")
# 7. Bulk complete multiple tasks
bulk_check_tasks(
spec_id="payment-processing",
task_numbers=["3.1", "3.2", "4.1"]
)
# 8. Or complete all remaining tasks
bulk_check_tasks(
spec_id="payment-processing",
all_tasks=True
)
```
## File Structure
### requirements.md
```markdown
# Requirements for Payment Processing
## User Story US-001
**As a** customer,
**I want** to pay with multiple methods,
**So that** I can choose my preferred payment option
### Acceptance Criteria (EARS Format)
- [US-001-R01] WHEN a customer selects credit card THE SYSTEM SHALL display secure card entry form
- [US-001-R02] IF payment fails THEN THE SYSTEM SHALL show error and suggest alternatives
```
### design.md
```markdown
# Technical Design for Payment Processing
## System Architecture
Microservices architecture with API gateway and payment provider integration...
## Components
### PaymentService
Core service handling payment orchestration...
### GatewayAdapter
Adapter pattern implementation for multiple payment providers...
## Data Models
```typescript
interface Payment {
id: string;
amount: number;
currency: string;
method: PaymentMethod;
status: PaymentStatus;
}
```
## Sequence Diagrams
```mermaid
sequenceDiagram
Customer->>API: Submit payment
API->>PaymentService: Process payment
PaymentService->>Gateway: Authorize
Gateway-->>PaymentService: Token
PaymentService-->>API: Success
API-->>Customer: Confirmation
```
```
### tasks.md
```markdown
# Implementation Plan
## Progress Summary
- **Total Tasks:** 8
- **Completed:** 2
- **In Progress:** 1
- **Pending:** 5
- **Progress:** 37.5%
- [x] 1. Set up project structure
- Initialize project with required dependencies
- _Requirements: US-001-R01_
- [ ] 2. Implement payment service API
- [ ] 2.1. Create API endpoints
- Build RESTful endpoints for payment processing
- _Requirements: US-001-R01, US-001-R02_
- [x] 2.2. Add authentication middleware
- Implement JWT-based authentication
- _Requirements: US-001-R03_
- [ ] 3. Build payment gateway integration
- Integrate with external payment providers
- _Requirements: US-002-R01_
```
## Resources
The server provides MCP resources for accessing specification files:
- `spec://{spec_id}/requirements` - Get requirements.md content
- `spec://{spec_id}/design` - Get design.md content
- `spec://{spec_id}/tasks` - Get tasks.md content
## Configuration Options
Customize the server by modifying these settings in the Python file:
```python
# By default, specforged uses ./.specifications under your project root.
# To override the specifications directory:
spec_manager = SpecificationManager(base_dir=Path("./.my-specs"))
# Adjust mode classification weights
classifier.spec_patterns = [
(r'your_pattern', weight),
# Add custom patterns
]
```
## Development
### Project Structure
```
specforged/
├── src/
│ ├── models/ # Data models and enums
│ ├── core/ # Core business logic
│ ├── tools/ # MCP tool implementations
│ ├── resources.py # MCP resource handlers
│ ├── prompts.py # MCP prompt definitions
│ └── server.py # Main server factory
├── tests/ # Comprehensive test suite
├── scripts/ # Development helper scripts
├── main.py # Local CLI entry point
└── requirements.txt # Dependencies
```
### Development Commands
```bash
# Run local MCP server
python main.py
# Install dependencies
pip install -r requirements.txt
# Run tests
python -m pytest tests/
# Run linting and formatting
python scripts/dev.py lint
python scripts/dev.py format
# Run all quality checks
python scripts/dev.py all
```
### Running Tests
```bash
python -m pytest tests/
```
### Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting: `python scripts/dev.py all`
5. Submit a pull request
### Adding Custom Patterns
Extend the mode classifier with domain-specific patterns:
```python
# Add to spec_patterns for specification detection
(r'\b(?:epic|feature)\s+definition', 0.8)
# Add to do_patterns for action detection
(r'\b(?:migrate|backup|restore)\s+database', 0.85)
```
## Troubleshooting
### Common Issues
**Server not appearing in Claude Desktop**
- Ensure absolute paths in configuration
- Check Python is in PATH
- Restart Claude Desktop after config changes
**Mode classification incorrect**
- Check classifier confidence scores with `classify_mode` tool
- Add custom patterns for your domain
- Default is "do mode" when confidence is low
**Files not generating**
- Check write permissions in .specifications directory
- Ensure all phases are properly transitioned
- Verify spec_id matches existing specification
- Ensure you start the server from your project directory (CWD becomes the project root)
## License
MIT License - See LICENSE file for details
## Acknowledgments
- EARS notation methodology by Alistair Mavin et al. (Rolls-Royce, 2009)
- FastMCP framework by Jonathan Lowin
- Inspired by specification-driven development practices
## References
- [EARS Paper - IEEE RE Conference](https://ieeexplore.ieee.org/document/5328509)
- [FastMCP Documentation](https://github.com/jlowin/fastmcp)
- [Model Context Protocol Specification](https://modelcontextprotocol.io)
Raw data
{
"_id": null,
"home_page": null,
"name": "specforged",
"maintainer": "SpecForge Team",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ears, mcp, requirements, specifications, workflow",
"author": "SpecForge Team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/8e/57/cfadaec7d753458ef6b7b6165f30f1e6fd3c0e3cd4598673778650c3dd44/specforged-0.3.0.tar.gz",
"platform": null,
"description": "# SpecForged MCP Server\n\n[](https://pypi.org/project/specforged/)\n[](https://pypi.org/project/specforged/)\n[](https://github.com/whit3rabbit/specforged/actions/workflows/test.yml)\n\nA Model Context Protocol (MCP) server that implements specification-driven development with EARS notation, intelligent mode classification, and structured workflow management.\n\n## \u2728 TL;DR: How specforged Works\n\n**SpecForged transforms your AI conversations into structured software development workflows.**\n\n### The Planning Workflow (Guided by Wizard Mode)\n\n**\ud83e\uddd9\u200d\u2642\ufe0f Wizard Mode covers 3 planning phases only:**\n\n1. **Requirements** \u2192 Define user stories with EARS notation (5 requirement types)\n2. **Design** \u2192 Interactive architecture and component planning\n3. **Planning** \u2192 Auto-generate numbered task hierarchies (1, 1.1, 1.2...)\n\n**\u26a1 Execution Phase (Separate from Wizard):**\n\n4. **Execution** \u2192 Context-aware task implementation with automatic test generation\n\n**IMPORTANT**: The wizard creates specifications and plans, but does NOT implement code. Implementation happens in a separate execution phase with proper context loading and test generation.\n\n### Natural Language Interface\n\nJust talk naturally - specforged understands:\n- *\"Use specforged to create a new project\"* \u2192 \ud83e\uddd9\u200d\u2642\ufe0f **Activates wizard mode**\n- *\"Create a spec for a user dashboard\"* \u2192 Starts requirements phase\n- *\"Mark task 2.1 as done\"* \u2192 Updates progress, suggests next tasks\n- *\"How's my progress?\"* \u2192 Shows completion stats and milestones\n- *\"What should I work on next?\"* \u2192 Lists available tasks with context\n\n### \ud83c\udfaf Key Features\n\n**EARS Requirements** - All 5 patterns supported:\n- **Ubiquitous**: THE SYSTEM SHALL always validate inputs\n- **Event-Driven**: WHEN user clicks login THE SYSTEM SHALL authenticate\n- **State-Driven**: WHILE processing THE SYSTEM SHALL show progress\n- **Optional**: WHERE premium enabled THE SYSTEM SHALL unlock features\n- **Error-Handling**: IF invalid data THEN THE SYSTEM SHALL show errors\n\n**Smart Task Management**:\n- \u2705 Auto-complete parent tasks when all subtasks done\n- \ud83d\udd17 Requirement traceability (every task links to user needs)\n- \ud83d\udcca Real-time progress tracking with motivational feedback\n- \ud83c\udfaf Dependency-aware task ordering\n\n**Conversational Workflow**:\n- Interactive prompts guide each phase transition\n- Natural language commands OR function calls\n- Automatic progress updates and celebration\n- Built-in coaching for requirement refinement\n\n### \ud83c\udfd7\ufe0f Generated Structure\n\n```\nspecifications/\n\u2514\u2500\u2500 my-dashboard/\n \u251c\u2500\u2500 spec.json # Metadata & status\n \u251c\u2500\u2500 requirements.md # User stories + EARS\n \u251c\u2500\u2500 design.md # Architecture decisions\n \u2514\u2500\u2500 tasks.md # Checkbox implementation plan\n```\n\n**Perfect for**: Feature specs, API design, project planning, requirement gathering, team alignment, and structured development workflows.\n\n## Quick Start\n\n\ud83c\udf89 **SpecForged is now available on [PyPI](https://pypi.org/project/specforged/)!**\n\n### \ud83e\uddd9\u200d\u2642\ufe0f Interactive Project Wizard (Recommended)\n\nThe fastest way to get started with SpecForged is using the **interactive project wizard** - your guided companion for creating complete specifications:\n\n```bash\n# Install specforged\npipx install specforged\n\n# Set up with your LLM (Claude Code, Cursor, etc.)\n# Then simply say: \"Start specforge wizard for my project\"\n```\n\nThe wizard will guide you through:\n1. **Project Setup**: Name, description, and project type\n2. **Requirements Gathering**: User stories with EARS notation\n3. **Design Phase**: Architecture and component selection\n4. **Task Generation**: Automatic implementation plan creation\n\nAvailable project templates:\n- `web-app`: Full-stack web application\n- `rest-api`: RESTful API service\n- `cli-tool`: Command-line tool\n- `python-lib`: Python library\n- `microservice`: Microservice architecture\n\n### Quick Installation\n\n```bash\n# Install specforged globally with pipx\npipx install specforged\n\n# Verify installation\nspecforged --version\n```\n\n**Choose your integration method:**\n\n- \ud83d\udd0c See combined setup: **[IDE & Host Integration](#ide--host-integration)**\n\n#### Available Commands\n\n- `specforged`: Run MCP server (default)\n- `specforged-http`: Run HTTP server for web integration\n- `specforged-cli`: Simplified CLI (same as `specforged`, kept for compatibility)\n\n#### Management\n\n```bash\n# Upgrade to latest version\npipx upgrade specforged\n\n# Uninstall\npipx uninstall specforged\n```\n\n## Installation for Development\n\n\u26a0\ufe0f **Important**: For local development work, you need MCP servers that can write to your project files. HTTP-based deployments run on remote servers and cannot write to your local project directories.\n\n## IDE & Host Integration\n\nBelow are collapsible, focused setup guides. Expand only what you need.\n\n<details>\n<summary><strong>Claude Code (recommended for coding)</strong></summary>\n\nThe best way to use specforged for active development.\n\n```bash\n# Install specforged globally with pipx\npipx install specforged\n\n# Add to Claude Code with project scope (enables team sharing)\nclaude mcp add --scope=project specforged specforged\n\n# Or for personal use only\nclaude mcp add specforged specforged\n```\n\nWhy project scope? It creates a `.mcp.json` in your project root that teammates can reuse:\n\n```json\n{\n \"mcpServers\": {\n \"specforged\": {\n \"command\": \"specforged\",\n \"args\": [],\n \"env\": {}\n }\n }\n}\n```\n\nFile access: Claude Code will prompt for permission to write to your project directory.\n\n</details>\n\n<details>\n<summary><strong>Cursor IDE</strong></summary>\n\n1) Install specforged: `pipx install specforged`\n2) Configure MCP in Cursor settings (Advanced \u2192 MCP) or create `.cursor/mcp.json` in your project root.\n\n - Important: There is no reliable auto-detection of the project folder. You must hardcode the absolute project path via `SPECFORGE_PROJECT_ROOT`.\n\n```json\n{\n \"mcpServers\": {\n \"specforged\": {\n \"command\": \"specforged\",\n \"args\": [],\n \"env\": {\n \"SPECFORGE_PROJECT_ROOT\": \"/absolute/path/to/this/project\",\n \"SPECFORGE_BASE_DIR\": \".specifications\"\n }\n }\n }\n}\n```\n\n3) Restart Cursor. 4) Grant local file access when prompted.\n5) Because this file lives in the project (`.cursor/mcp.json`), the hardcoded path is per-project.\n\n</details>\n\n<details>\n<summary><strong>Windsurf IDE</strong></summary>\n\n1) Install: `pipx install specforged`\n2) Configure via Settings \u2192 Cascade \u2192 Plugins, or edit `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"specforged\": {\n \"command\": \"specforged\",\n \"args\": [],\n \"env\": {\n \"SPECFORGE_PROJECT_ROOT\": \"/absolute/path/to/your/project\",\n \"SPECFORGE_BASE_DIR\": \".specifications\"\n }\n }\n }\n}\n```\n\n3) Press refresh, then restart Windsurf.\n4) Note: Windsurf does not reliably pass your workspace folder as the server CWD. There is no auto-detect. You must hardcode the absolute project path using `SPECFORGE_PROJECT_ROOT` as shown above.\n - If you work across multiple projects, add separate entries (e.g., `specforged-foo`, `specforged-bar`) each with its own `SPECFORGE_PROJECT_ROOT`, or use a small wrapper script that `cd`s into the project before launching `specforged`.\n\n</details>\n\n<details>\n<summary><strong>VS Code (Continue/Codeium/etc.)</strong></summary>\n\n1) `pipx install specforged`\n2) Add specforged MCP server in your AI extension settings\n3) Ensure workspace file permissions are enabled\n\n</details>\n\n<details>\n<summary><strong>Claude Desktop</strong></summary>\n\nNote: Best for chat/spec work. For coding, prefer Claude Code.\n\nInstall:\n\n```bash\npipx install specforged\n```\n\n**Basic Configuration** (`claude_desktop_config.json`):\n\n```json\n{\n \"mcpServers\": {\n \"specforged\": { \"command\": \"specforged\" }\n }\n}\n```\n\n**Advanced Configuration** (recommended for reliable project detection):\n\n```json\n{\n \"mcpServers\": {\n \"specforged\": {\n \"command\": \"specforged\",\n \"args\": [],\n \"env\": {\n \"SPECFORGE_PROJECT_ROOT\": \"/absolute/path/to/your/project\",\n \"SPECFORGE_BASE_DIR\": \".specifications\"\n }\n }\n }\n}\n```\n\nUse the advanced configuration when:\n- Working with multiple projects\n- Basic config fails to detect your project root correctly\n- You need explicit control over where specifications are stored\n\nConfig file paths:\n\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\\\Claude\\\\claude_desktop_config.json`\n- Linux: `~/.config/Claude/claude_desktop_config.json`\n\n</details>\n\n## Permissions & Path Security\n\n- **Project root = CWD**: specforged treats the server's current working directory as the project root. Run the server from your project folder.\n- **Specs location**: Defaults to `./.specifications/` under the project root. You can override by initializing `SpecificationManager(base_dir=Path(\"./.my-specs\"))`.\n- **Strict path validation**: All tool paths (e.g., `read_file`, `write_file`, `create_directory`, `edit_block`) are resolved and must remain within the project root. Absolute and relative paths are allowed but are validated against the project root after resolution.\n- **No escapes**: Attempts to access files outside the project (e.g., `..`, absolute paths elsewhere, or via symlinks) are rejected.\n- **Symlinks**: Paths are fully resolved before validation. Symlinks that point outside the project root are denied.\n- **Large files**: Operations on very large files may be warned against or rejected depending on host constraints.\n- **IDE prompts**: IDEs/hosts (Claude Code, Windsurf, Cursor, etc.) may prompt for permission before allowing write access to your workspace\u2014accept to enable file creation in `./.specifications/`.\n\nTip: Keep the server process scoped per-project to avoid writing specs into the wrong project directory.\n\n## Advanced Installation Methods\n\n### Docker with Bind Mounts\n\nFor Docker users who want to persist specifications locally:\n\n```bash\n# Build the Docker image\ndocker build -t specforged:latest .\n```\n\nConfigure in Claude Desktop with bind mount:\n\n```json\n{\n \"mcpServers\": {\n \"specforged\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"-i\", \"--rm\",\n \"--mount\", \"type=bind,src=/absolute/path/to/host/specifications,dst=/app/specifications\",\n \"specforged:latest\",\n \"python\", \"main.py\"\n ]\n }\n }\n}\n```\n\n**Notes:**\n- Container writes to `/app/specifications` which maps to your local directory\n- Specifications persist on your local machine\n- Restart Claude Desktop after configuration changes\n\n### Manual Development Installation\n\nFor development or local testing without pipx:\n\n```bash\n# Clone the repository\ngit clone https://github.com/whit3rabbit/specforged.git\ncd specforged\n\n# Install dependencies\npip install -r requirements.txt\n\n# Test locally\npython main.py\n```\n\nConfigure in Claude Desktop:\n\n```json\n{\n \"mcpServers\": {\n \"specforged\": {\n \"command\": \"python\",\n \"args\": [\"/absolute/path/to/specforged/main.py\"]\n }\n }\n}\n```\n\n## Example\n\n```bash\nUse specforged to create a spec for a TODO list app that supports creating, editing, completing, and filtering tasks.\n```\n\n## Overview\n\nspecforged transforms ad-hoc development into a structured process by:\n- **Classifying intent** - Routes requests to appropriate handlers (spec mode vs. action mode)\n- **Enforcing workflow** - Guides through requirements \u2192 design \u2192 tasks \u2192 execution phases\n- **Using EARS notation** - Creates unambiguous, testable requirements\n- **Managing artifacts** - Maintains requirements.md, design.md, and tasks.md files\n\n## Background\n\nThis server implements the EARS (Easy Approach to Requirements Syntax) notation, developed by Alistair Mavin et al. at Rolls-Royce (2009). EARS is an industry-standard methodology for writing clear, testable requirements, widely used in aerospace, automotive, and safety-critical systems.\n\n## Features\n\n### Intelligent Mode Classification\nAutomatically determines user intent and routes to appropriate handler:\n- **Spec Mode**: Creating specifications, requirements, design documents\n- **Do Mode**: Code modifications, commands, implementation tasks\n- **Chat Mode**: Questions, explanations, general discussion\n\n### Complete Specification Workflow\n\n#### Requirements Phase\n- User stories: \"As a [user], I want [goal], so that [benefit]\"\n- EARS acceptance criteria: \"WHEN [condition] THE SYSTEM SHALL [response]\"\n- Structured requirement tracking with unique IDs\n\n#### Design Phase\n- Technical architecture documentation\n- Component specifications\n- Data models and interfaces\n- Sequence diagrams (Mermaid format)\n- API contracts and schemas\n\n#### Task Planning\n- Discrete, trackable implementation tasks\n- Dependency management\n- Progress tracking (pending \u2192 in_progress \u2192 completed)\n- Links to requirements for traceability\n\n#### Execution Phase\n- Individual task execution with validation\n- Real-time status updates\n- Progress reporting\n\n### File Management\nAutomatically generates and maintains three key files per specification:\n```\n.specifications/\n\u2514\u2500\u2500 your-feature/\n \u251c\u2500\u2500 spec.json # Specification metadata\n \u251c\u2500\u2500 requirements.md # User stories & EARS criteria\n \u251c\u2500\u2500 design.md # Technical architecture\n \u2514\u2500\u2500 tasks.md # Implementation plan\n```\n\n## Usage\n\n### Interactive Project Wizard (Recommended)\n\nThe quickest way to create comprehensive specifications is through conversation with your LLM:\n\n```\nUser: \"Start specforge wizard for my task management app\"\n\nLLM: \ud83c\udf89 Project 'task-management-app' created! I'm ready to guide you through\n the requirements phase. Let's start by understanding your users and their\n needs. What kind of system are you building and who will use it?\n\nUser: \"It's for team collaboration, users need to create and assign tasks\"\n\nLLM: Great! Let me help you create user stories. I'll use add_requirement() to\n add this to your specification...\n```\n\nThe wizard guides you conversationally through:\n1. **Requirements**: Define user stories with EARS acceptance criteria\n2. **Design**: Document system architecture and components\n3. **Planning**: Generate implementation tasks automatically\n4. **Execution**: Track progress as tasks are completed\n\n**Wizard Features:**\n- **Guided Requirements**: Step-by-step user story creation with EARS notation help\n- **Architecture Templates**: Pre-built patterns for common project types\n- **Smart Task Generation**: Automatic breakdown from requirements to implementable tasks\n- **Progress Tracking**: Generated tasks in checkbox format for easy progress monitoring\n- **Professional Output**: Creates complete specification with requirements.md, design.md, and tasks.md\n\n### Wizard Mode via MCP (Planning Only - Automatic Activation)\n\nspecforged can automatically activate wizard mode through natural language when using MCP integration:\n\n#### Auto-Activation Triggers\n\nThe wizard automatically starts when:\n- **No .specifications folder exists** in your project\n- **Using \"specforged\" keyword** in requests\n- **First-time setup** is detected\n\n```bash\n# These phrases trigger wizard mode automatically (PLANNING ONLY):\n\"Use specforged to create a new project specification\"\n\"Start specforge wizard for my application\"\n\"Create a new spec with specforged for payment processing\"\n\"I need specforged to help set up my project\"\n\"Launch the specforged wizard for user management\"\n\"Use specforged wizard mode to design my API\"\n```\n\n**\u26a0\ufe0f Important**: The wizard creates specifications but does NOT implement tasks. It guides you through Requirements \u2192 Design \u2192 Planning phases only.\n\n**Pro Tip**: Just say \"specforged\" in your request and the wizard will activate if no specifications exist in your project!\n\n#### Three-Phase Planning Workflow (Wizard Mode)\n\nWhen wizard mode activates, you'll be guided through **PLANNING ONLY**:\n\n1. **\ud83d\udcdd Phase 1: Requirements Gathering**\n - Interactive user story creation\n - EARS notation assistance and examples\n - Creates `requirements.md` with structured stories\n - Real-time validation and suggestions\n\n2. **\ud83c\udfa8 Phase 2: System Design**\n - Architecture pattern selection\n - Component definition wizard\n - Data model creation help\n - Creates `design.md` with technical specifications\n\n3. **\u2705 Phase 3: Task Generation**\n - Automatic breakdown from requirements to tasks\n - Dependency analysis and ordering\n - Creates `tasks.md` with checkbox format\n - Progress tracking setup\n\n#### \u26a1 Execution Phase (After Wizard Completion)\n\n**The wizard does NOT execute tasks.** Implementation happens separately with:\n\n- **Context Loading**: Automatically reads requirements.md and design.md before each task\n- **Architecture Compliance**: Ensures implementation follows the planned design\n- **EARS Validation**: Verifies acceptance criteria are met\n- **Test Generation**: Auto-generates test templates for each completed task\n- **Quality Assurance**: Validates implementation against specifications\n\n#### Example Wizard Session\n\n```\nUser: Use specforged to create a specification for user authentication\n\nClaude: I'll start the specforged wizard to create a comprehensive specification.\n\n\ud83d\udcdd Phase 1/3: Requirements Gathering\n\u2022 Created user story: \"As a user, I want secure login...\"\n\u2022 Added EARS requirements with validation patterns\n\u2022 Generated requirements.md \u2705\n\n\ud83c\udfa8 Phase 2/3: System Design\n\u2022 Selected MVC architecture pattern\n\u2022 Defined AuthService and UserController components\n\u2022 Created data models for User and Session entities\n\u2022 Generated design.md \u2705\n\n\u2705 Phase 3/3: Task Generation\n\u2022 Analyzed requirements and created 12 implementation tasks\n\u2022 Established dependency relationships\n\u2022 Generated tasks.md with checkbox format \u2705\n\n\ud83c\udf89 Complete specification created at: ./.specifications/user-authentication/\n```\n\n### Manual Specification Creation (MCP)\n\nFor experienced users or specific workflows, you can create specifications manually:\n\n```\nUser: Create a spec for user authentication system\nResponse: Creates new specification with requirements.md, design.md, and tasks.md files\n```\n\n### Mode Classification Examples\n\n```python\n# Spec mode - Wizard activation (high priority)\n\"Use specforged to create a new project specification\"\n\"Start specforge wizard for user management\"\n\"Create a spec with specforged for payment processing\"\n\"I need specforged to set up my API specification\"\n\n# Spec mode - Standard specification creation\n\"Create a spec for payment processing\"\n\"Generate a specification for the login system\"\n\"Execute task 3.2 from user-auth spec\"\n\"Add a requirement to the auth spec\"\n\n# Do mode (code/action requests)\n\"Fix the syntax error in app.js\"\n\"Run the test suite\"\n\"Deploy to production\"\n\n# Chat mode (questions/explanations)\n\"What is EARS notation?\"\n\"How do promises work?\"\n\"Explain the architecture\"\n```\n\n## Triggering MCP Commands\n\nspecforged integrates with Claude Desktop and other MCP hosts through natural language interactions. The system automatically classifies your input and routes requests to appropriate tools based on context and intent.\n\n### Command Patterns\n\n**Specification Management:**\n- \"Create a spec for [feature name]\"\n- \"List all specifications\"\n- \"Show details for [spec-id]\"\n\n**Requirements and Design:**\n- \"Add a requirement to [spec-id] as a [user type]...\"\n- \"Update the design for [spec-id] with [architecture details]\"\n\n**Task Management (Checkbox Style):**\n- \"Generate implementation plan for [spec-id]\"\n- \"Check off task 1.2 in [spec-id]\"\n- \"Mark tasks 1.1, 1.2, and 2.1 as complete\"\n- \"What tasks are ready to work on?\"\n- \"Show progress summary for [spec-id]\"\n\n**General Queries:**\n- \"What is EARS notation?\"\n- \"Explain the workflow phases\"\n\nThe system will automatically invoke the appropriate MCP tools based on your natural language input.\n\n### Available Tools\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `classify_mode` | Classify user input intent | `user_input` |\n| `create_spec` | Create new specification | `name`, `description` |\n| `add_requirement` | Add user story with EARS criteria | `spec_id`, `as_a`, `i_want`, `so_that`, `ears_requirements` |\n| `update_design` | Update technical design | `spec_id`, `architecture`, `components`, `data_models`, `sequence_diagrams` |\n| `generate_implementation_plan` | Create task hierarchy from requirements | `spec_id` |\n| `update_implementation_plan` | Refresh plan preserving completion status | `spec_id` |\n| `check_task` | Mark task as completed | `spec_id`, `task_number` |\n| `uncheck_task` | Mark task as pending | `spec_id`, `task_number` |\n| `bulk_check_tasks` | Check multiple tasks at once | `spec_id`, `task_numbers`, `all_tasks` |\n| `get_task_details` | Get detailed task information | `spec_id`, `task_number` |\n| `get_next_available_tasks` | Find tasks ready to work on | `spec_id` |\n| `get_task_status_summary` | Complete progress overview | `spec_id` |\n| `add_implementation_task` | Add individual task to plan | `spec_id`, `title`, `description`, `dependencies`, `subtasks` |\n| `execute_task` | Execute a specific task | `spec_id`, `task_id` |\n| `transition_workflow_phase` | Move to next phase | `spec_id`, `target_phase` |\n| `list_specifications` | List all specs | - |\n| `get_specification_details` | Get spec details | `spec_id`, `include_content` |\n| `create_directory` | Create a directory within project root | `path`, `exist_ok` |\n| `read_file` | Read a UTF-8 text file within project root | `path` |\n| `write_file` | Write/append a UTF-8 text file within project root | `path`, `content`, `mode` |\n| `edit_block` | Safely replace exact text in a file | `file_path`, `old_string`, `new_string`, `expected_replacements` |\n\n### Filesystem Tools (Project-Scoped)\n\nThese tools operate only within your current project directory (the server's CWD). Any path outside the project root is rejected.\n\n```bash\n# Create specs directory (if you want to initialize manually)\ncreate_directory(path=\".specifications\")\n\n# Create files\nwrite_file(path=\".specifications/requirements.md\", content=\"# Requirements\")\nwrite_file(path=\"README.md\", content=\"\\nExtra line\\n\", mode=\"append\")\n\n# Read a file\nread_file(path=\"src/main.py\")\n\n# Safe in-place edit\nedit_block(\n file_path=\"src/main.py\",\n old_string=\"print('Hello')\",\n new_string=\"print('Hello, World!')\",\n expected_replacements=1\n)\n```\n\n### EARS Notation Examples\n\nEARS (Easy Approach to Requirements Syntax) provides clear, testable requirements:\n\n```markdown\nWHEN a user submits valid credentials\nTHE SYSTEM SHALL authenticate and create a session\n\nWHILE processing a payment\nTHE SYSTEM SHALL display a progress indicator\n\nWHERE two-factor authentication is enabled\nTHE SYSTEM SHALL require a verification code\n\nIF the session expires\nTHEN THE SYSTEM SHALL redirect to login\n```\n\n### Complete Workflow Example\n\n```python\n# 1. Create specification\ncreate_spec(name=\"Payment Processing\", description=\"Handle customer payments\")\n\n# 2. Add requirements\nadd_requirement(\n spec_id=\"payment-processing\",\n as_a=\"customer\",\n i_want=\"to pay with multiple methods\",\n so_that=\"I can choose my preferred payment option\",\n ears_requirements=[\n {\n \"condition\": \"WHEN a customer selects credit card\",\n \"system_response\": \"display secure card entry form\"\n },\n {\n \"condition\": \"IF payment fails\",\n \"system_response\": \"show error and suggest alternatives\"\n }\n ]\n)\n\n# 3. Design architecture\nupdate_design(\n spec_id=\"payment-processing\",\n architecture=\"Microservices with payment gateway integration\",\n components=[\n {\"name\": \"PaymentService\", \"description\": \"Handles payment processing\"},\n {\"name\": \"GatewayAdapter\", \"description\": \"Integrates with payment providers\"}\n ]\n)\n\n# 4. Generate implementation plan\ngenerate_implementation_plan(spec_id=\"payment-processing\")\n\n# 5. Check task progress\nget_task_status_summary(spec_id=\"payment-processing\")\n\n# 6. Complete tasks\ncheck_task(spec_id=\"payment-processing\", task_number=\"1\")\ncheck_task(spec_id=\"payment-processing\", task_number=\"2.1\")\n\n# 7. Bulk complete multiple tasks\nbulk_check_tasks(\n spec_id=\"payment-processing\",\n task_numbers=[\"3.1\", \"3.2\", \"4.1\"]\n)\n\n# 8. Or complete all remaining tasks\nbulk_check_tasks(\n spec_id=\"payment-processing\",\n all_tasks=True\n)\n```\n\n## File Structure\n\n### requirements.md\n```markdown\n# Requirements for Payment Processing\n\n## User Story US-001\n\n**As a** customer,\n**I want** to pay with multiple methods,\n**So that** I can choose my preferred payment option\n\n### Acceptance Criteria (EARS Format)\n\n- [US-001-R01] WHEN a customer selects credit card THE SYSTEM SHALL display secure card entry form\n- [US-001-R02] IF payment fails THEN THE SYSTEM SHALL show error and suggest alternatives\n```\n\n### design.md\n```markdown\n# Technical Design for Payment Processing\n\n## System Architecture\n\nMicroservices architecture with API gateway and payment provider integration...\n\n## Components\n\n### PaymentService\nCore service handling payment orchestration...\n\n### GatewayAdapter\nAdapter pattern implementation for multiple payment providers...\n\n## Data Models\n\n```typescript\ninterface Payment {\n id: string;\n amount: number;\n currency: string;\n method: PaymentMethod;\n status: PaymentStatus;\n}\n```\n\n## Sequence Diagrams\n\n```mermaid\nsequenceDiagram\n Customer->>API: Submit payment\n API->>PaymentService: Process payment\n PaymentService->>Gateway: Authorize\n Gateway-->>PaymentService: Token\n PaymentService-->>API: Success\n API-->>Customer: Confirmation\n```\n```\n\n### tasks.md\n```markdown\n# Implementation Plan\n\n## Progress Summary\n\n- **Total Tasks:** 8\n- **Completed:** 2\n- **In Progress:** 1\n- **Pending:** 5\n- **Progress:** 37.5%\n\n- [x] 1. Set up project structure\n - Initialize project with required dependencies\n - _Requirements: US-001-R01_\n\n- [ ] 2. Implement payment service API\n - [ ] 2.1. Create API endpoints\n - Build RESTful endpoints for payment processing\n - _Requirements: US-001-R01, US-001-R02_\n - [x] 2.2. Add authentication middleware\n - Implement JWT-based authentication\n - _Requirements: US-001-R03_\n\n- [ ] 3. Build payment gateway integration\n - Integrate with external payment providers\n - _Requirements: US-002-R01_\n```\n\n## Resources\n\nThe server provides MCP resources for accessing specification files:\n\n- `spec://{spec_id}/requirements` - Get requirements.md content\n- `spec://{spec_id}/design` - Get design.md content\n- `spec://{spec_id}/tasks` - Get tasks.md content\n\n## Configuration Options\n\nCustomize the server by modifying these settings in the Python file:\n\n```python\n# By default, specforged uses ./.specifications under your project root.\n# To override the specifications directory:\nspec_manager = SpecificationManager(base_dir=Path(\"./.my-specs\"))\n\n# Adjust mode classification weights\nclassifier.spec_patterns = [\n (r'your_pattern', weight),\n # Add custom patterns\n]\n```\n\n## Development\n\n### Project Structure\n```\nspecforged/\n\u251c\u2500\u2500 src/\n\u2502 \u251c\u2500\u2500 models/ # Data models and enums\n\u2502 \u251c\u2500\u2500 core/ # Core business logic\n\u2502 \u251c\u2500\u2500 tools/ # MCP tool implementations\n\u2502 \u251c\u2500\u2500 resources.py # MCP resource handlers\n\u2502 \u251c\u2500\u2500 prompts.py # MCP prompt definitions\n\u2502 \u2514\u2500\u2500 server.py # Main server factory\n\u251c\u2500\u2500 tests/ # Comprehensive test suite\n\u251c\u2500\u2500 scripts/ # Development helper scripts\n\u251c\u2500\u2500 main.py # Local CLI entry point\n\u2514\u2500\u2500 requirements.txt # Dependencies\n```\n\n### Development Commands\n```bash\n# Run local MCP server\npython main.py\n\n# Install dependencies\npip install -r requirements.txt\n\n# Run tests\npython -m pytest tests/\n\n# Run linting and formatting\npython scripts/dev.py lint\npython scripts/dev.py format\n\n# Run all quality checks\npython scripts/dev.py all\n```\n\n### Running Tests\n```bash\npython -m pytest tests/\n```\n\n### Contributing\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run tests and linting: `python scripts/dev.py all`\n5. Submit a pull request\n\n### Adding Custom Patterns\n\nExtend the mode classifier with domain-specific patterns:\n\n```python\n# Add to spec_patterns for specification detection\n(r'\\b(?:epic|feature)\\s+definition', 0.8)\n\n# Add to do_patterns for action detection\n(r'\\b(?:migrate|backup|restore)\\s+database', 0.85)\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**Server not appearing in Claude Desktop**\n- Ensure absolute paths in configuration\n- Check Python is in PATH\n- Restart Claude Desktop after config changes\n\n**Mode classification incorrect**\n- Check classifier confidence scores with `classify_mode` tool\n- Add custom patterns for your domain\n- Default is \"do mode\" when confidence is low\n\n**Files not generating**\n- Check write permissions in .specifications directory\n- Ensure all phases are properly transitioned\n- Verify spec_id matches existing specification\n- Ensure you start the server from your project directory (CWD becomes the project root)\n\n## License\n\nMIT License - See LICENSE file for details\n\n## Acknowledgments\n\n- EARS notation methodology by Alistair Mavin et al. (Rolls-Royce, 2009)\n- FastMCP framework by Jonathan Lowin\n- Inspired by specification-driven development practices\n\n## References\n\n- [EARS Paper - IEEE RE Conference](https://ieeexplore.ieee.org/document/5328509)\n- [FastMCP Documentation](https://github.com/jlowin/fastmcp)\n- [Model Context Protocol Specification](https://modelcontextprotocol.io)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Spec-driven development workflow with mode classification and EARS notation",
"version": "0.3.0",
"project_urls": {
"Documentation": "https://github.com/whit3rabbit/SpecForge#readme",
"Homepage": "https://github.com/whit3rabbit/SpecForge",
"Issues": "https://github.com/whit3rabbit/SpecForge/issues",
"PyPI": "https://pypi.org/project/specforged/",
"Repository": "https://github.com/whit3rabbit/SpecForge.git"
},
"split_keywords": [
"ears",
" mcp",
" requirements",
" specifications",
" workflow"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "153a16e17dddf5ff1ccd88da77f6ceb6540325edb5a3c18709c0d1a23aeec950",
"md5": "d99c9b5896bb5c2e49c0460603094d6d",
"sha256": "4bac5fc26619f3dee6fe6b88a67a7383d8b683fde55333894b8bac67a2a052cc"
},
"downloads": -1,
"filename": "specforged-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d99c9b5896bb5c2e49c0460603094d6d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 70768,
"upload_time": "2025-08-28T21:41:05",
"upload_time_iso_8601": "2025-08-28T21:41:05.210538Z",
"url": "https://files.pythonhosted.org/packages/15/3a/16e17dddf5ff1ccd88da77f6ceb6540325edb5a3c18709c0d1a23aeec950/specforged-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8e57cfadaec7d753458ef6b7b6165f30f1e6fd3c0e3cd4598673778650c3dd44",
"md5": "6d5a8a891c0e92024472e1b9becac6ad",
"sha256": "02267cf10f4f3b89f19fab16014b861564cc45a5b485485191a1a8b449520043"
},
"downloads": -1,
"filename": "specforged-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "6d5a8a891c0e92024472e1b9becac6ad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 98831,
"upload_time": "2025-08-28T21:41:06",
"upload_time_iso_8601": "2025-08-28T21:41:06.852861Z",
"url": "https://files.pythonhosted.org/packages/8e/57/cfadaec7d753458ef6b7b6165f30f1e6fd3c0e3cd4598673778650c3dd44/specforged-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-28 21:41:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "whit3rabbit",
"github_project": "SpecForge#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "mcp",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "fastmcp",
"specs": [
[
">=",
"0.3.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "aiofiles",
"specs": [
[
">=",
"23.0.0"
]
]
},
{
"name": "uvicorn",
"specs": [
[
">=",
"0.24.0"
]
]
},
{
"name": "starlette",
"specs": [
[
">=",
"0.32.0"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"7.0.0"
]
]
},
{
"name": "pytest-asyncio",
"specs": [
[
">=",
"0.21.0"
]
]
},
{
"name": "black",
"specs": [
[
">=",
"23.0.0"
]
]
},
{
"name": "flake8",
"specs": [
[
">=",
"6.0.0"
]
]
},
{
"name": "mypy",
"specs": [
[
">=",
"1.0.0"
]
]
}
],
"lcname": "specforged"
}
JSON
