claudetools/mcp-servers/feature-management/README.md

# Feature Management MCP Server

**Source:** AutoCoder project
**Type:** Model Context Protocol (MCP) Server
**Purpose:** Manage autonomous coding features with priority-based workflow

---

## Overview

The Feature Management MCP Server provides tools for managing a feature queue in an autonomous coding workflow. It replaces the previous FastAPI-based REST API with a native MCP implementation that integrates directly with Claude Code.

**Key Capabilities:**
- Track feature implementation progress
- Priority-based feature queue management
- Mark features as passing/in-progress/skipped
- Regression testing support
- Bulk feature creation from app specifications

---

## Architecture

### Database
- **Backend:** SQLite (via SQLAlchemy)
- **Migration:** Auto-migrates legacy JSON to SQLite
- **Storage:** `{PROJECT_DIR}/features.db`

### Feature Model
```python
{
    "id": int,              # Auto-increment primary key
    "priority": int,        # Lower = higher priority
    "category": str,        # Feature category (e.g., "authentication", "ui")
    "name": str,            # Short feature name
    "description": str,     # Detailed description
    "steps": list[str],     # Implementation/test steps
    "passes": bool,         # True if feature is implemented and working
    "in_progress": bool     # True if currently being worked on
}
```

---

## Available Tools

### 1. feature_get_stats
**Purpose:** Get overall progress statistics

**Usage:**
```python
feature_get_stats()
```

**Returns:**
```json
{
  "passing": 42,
  "in_progress": 1,
  "total": 100,
  "percentage": 42.0
}
```

**When to use:** At the start/end of coding sessions to track progress

---

### 2. feature_get_next
**Purpose:** Get the next feature to implement

**Usage:**
```python
feature_get_next()
```

**Returns:**
```json
{
  "id": 15,
  "priority": 15,
  "category": "authentication",
  "name": "User login endpoint",
  "description": "Create POST /api/auth/login endpoint...",
  "steps": [
    "Create SQLAlchemy User model",
    "Implement login route",
    "Add JWT token generation",
    "Write tests"
  ],
  "passes": false,
  "in_progress": false
}
```

**When to use:** At the start of each implementation cycle

---

### 3. feature_mark_passing
**Purpose:** Mark a feature as successfully implemented

**Usage:**
```python
feature_mark_passing(feature_id=15)
```

**Returns:** Updated feature object with `passes=true`, `in_progress=false`

**When to use:** After implementing and verifying a feature works

---

### 4. feature_mark_in_progress
**Purpose:** Mark a feature as being worked on

**Usage:**
```python
feature_mark_in_progress(feature_id=15)
```

**Returns:** Updated feature object with `in_progress=true`

**When to use:** Immediately after `feature_get_next()` to claim the feature

**Important:** Prevents other parallel agent sessions from working on the same feature

---

### 5. feature_skip
**Purpose:** Move a feature to the end of the queue

**Usage:**
```python
feature_skip(feature_id=15)
```

**Returns:**
```json
{
  "id": 15,
  "name": "User login endpoint",
  "old_priority": 15,
  "new_priority": 101,
  "message": "Feature 'User login endpoint' moved to end of queue"
}
```

**When to use:**
- Feature has unmet dependencies
- External blockers (missing assets, unclear requirements)
- Technical prerequisites needed

---

### 6. feature_clear_in_progress
**Purpose:** Reset in-progress status

**Usage:**
```python
feature_clear_in_progress(feature_id=15)
```

**Returns:** Updated feature object with `in_progress=false`

**When to use:**
- Abandoning a feature midway
- Manually unsticking a stuck feature
- Resetting state after errors

---

### 7. feature_get_for_regression
**Purpose:** Get random passing features for regression testing

**Usage:**
```python
feature_get_for_regression(limit=3)  # 1-10, default 3
```

**Returns:**
```json
{
  "features": [
    {"id": 3, "name": "User registration", "passes": true, ...},
    {"id": 7, "name": "Login validation", "passes": true, ...},
    {"id": 12, "name": "Password reset", "passes": true, ...}
  ],
  "count": 3
}
```

**When to use:** After implementing new features to verify no regressions

---

### 8. feature_create_bulk
**Purpose:** Create multiple features at once

**Usage:**
```python
feature_create_bulk(features=[
    {
        "category": "authentication",
        "name": "User registration",
        "description": "Allow users to create accounts...",
        "steps": ["Create User model", "Create POST /register", "Add validation"]
    },
    {
        "category": "authentication",
        "name": "User login",
        "description": "Allow users to log in...",
        "steps": ["Create POST /login", "Add JWT tokens", "Write tests"]
    }
])
```

**Returns:**
```json
{
  "created": 2
}
```

**When to use:** Initializing a new project from an app specification

---

## Installation & Configuration

### 1. Install Dependencies

The MCP server requires SQLAlchemy and FastMCP. In the AutoCoder project these are already included, but for standalone use:

```bash
pip install sqlalchemy fastmcp pydantic
```

### 2. Configure Claude Desktop

Add to `~/.config/claude/claude_desktop_config.json` (macOS/Linux) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "features": {
      "command": "python",
      "args": ["D:\\ClaudeTools\\mcp-servers\\feature-management\\feature_mcp.py"],
      "env": {
        "PROJECT_DIR": "D:\\ClaudeTools\\projects\\your-project"
      }
    }
  }
}
```

### 3. Set PROJECT_DIR

The `PROJECT_DIR` environment variable determines where the SQLite database is stored:

```bash
# Windows (PowerShell)
$env:PROJECT_DIR="D:\ClaudeTools\projects\your-project"

# Linux/macOS
export PROJECT_DIR="/path/to/your/project"
```

The database will be created at `{PROJECT_DIR}/features.db`

---

## Typical Workflow

### Autonomous Coding Agent Session

```python
# 1. Check progress at start of session
stats = feature_get_stats()
# Output: 42/100 features passing (42.0%)

# 2. Get next feature to work on
next_feature = feature_get_next()
# Output: Feature #15 - "User login endpoint"

# 3. Mark it in-progress (claim it)
feature_mark_in_progress(feature_id=15)

# 4. Implement the feature
#    ... write code, run tests, verify ...

# 5. Mark as passing when done
feature_mark_passing(feature_id=15)

# 6. Optional: Run regression tests
regression = feature_get_for_regression(limit=5)
# Output: 5 random passing features to re-test
```

### Handling Blockers

```python
# Get next feature
next_feature = feature_get_next()
# Feature #20 - "OAuth integration"

# Realize it depends on feature #25 which isn't done yet
feature_skip(feature_id=20)
# Feature moved to end of queue (priority 101)

# Get actual next feature
next_feature = feature_get_next()
# Feature #21 - "Email validation"
```

---

## Database Schema

```sql
CREATE TABLE features (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    priority INTEGER NOT NULL,
    category VARCHAR(100) NOT NULL,
    name VARCHAR(255) NOT NULL,
    description TEXT NOT NULL,
    steps TEXT NOT NULL,           -- JSON array of strings
    passes BOOLEAN DEFAULT 0,
    in_progress BOOLEAN DEFAULT 0
);

CREATE INDEX idx_priority ON features(priority);
CREATE INDEX idx_passes ON features(passes);
```

---

## Integration with ClaudeTools

This MCP server can be integrated with the ClaudeTools context recall system:

1. Store feature completion decisions in `decision_logs` table
2. Save feature implementation context in `conversation_contexts`
3. Track feature work sessions in `sessions` table
4. Log feature-related errors in `problem_solutions`

**Example:**
```python
# After marking feature passing, log the decision
POST /api/decision-logs
{
  "project_id": "uuid",
  "decision_type": "technical",
  "decision_text": "Implemented user login endpoint",
  "rationale": "Feature #15 completed with JWT authentication",
  "tags": ["authentication", "feature-15", "jwt"]
}
```

---

## Troubleshooting

### Database not found
**Error:** `Database not initialized`

**Solution:** Ensure `PROJECT_DIR` environment variable is set and writable

### Migration issues
**Error:** `Migration failed`

**Solution:** The server auto-migrates legacy JSON (`features.json`) to SQLite. If you have custom JSON structure, you may need to adjust the migration in `api/migration.py`

### All features showing in-progress
**Problem:** Features stuck in `in_progress=true` state

**Solution:**
```python
# Clear all stuck features
for feature_id in [1, 2, 3, ...]:
    feature_clear_in_progress(feature_id=feature_id)
```

Or directly in SQLite:
```sql
UPDATE features SET in_progress = 0 WHERE in_progress = 1;
```

---

## Differences from REST API

The original AutoCoder project used a FastAPI REST server. This MCP server provides the same functionality with these improvements:

| Feature | REST API | MCP Server |
|---------|----------|------------|
| Integration | HTTP requests | Native Claude MCP tools |
| Authentication | API keys | Built into MCP protocol |
| Type safety | Manual validation | Pydantic models |
| Error handling | HTTP status codes | JSON error responses |
| Database | JSON files | SQLite (with JSON migration) |
| Startup time | ~1-2 seconds | ~100ms |

---

## File Structure

```
mcp-servers/feature-management/
├── feature_mcp.py      # Main MCP server implementation
├── __init__.py         # Python module marker
├── README.md           # This file
└── config.example.json # Example configuration
```

---

## Dependencies

**Required:**
- `fastmcp` - MCP protocol implementation
- `sqlalchemy` - Database ORM
- `pydantic` - Data validation

**Optional:**
- `api.database` - Feature model and database setup (from AutoCoder)
- `api.migration` - JSON to SQLite migration (from AutoCoder)

---

## License

Same license as the AutoCoder project (see LICENSE.txt in AutoCoder repository)

---

## See Also

- `.claude/commands/create-spec.md` - Create app specification
- `.claude/commands/checkpoint.md` - Create development checkpoint
- `.claude/skills/frontend-design/` - Frontend design skill
- `.claude/templates/` - Prompt templates for autonomous coding

---

**Last Updated:** 2026-01-17
**Status:** Production-ready (ported from AutoCoder)