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

{
    "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:

feature_get_stats()

Returns:

{
  "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:

feature_get_next()

Returns:

{
  "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:

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:

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:

feature_skip(feature_id=15)

Returns:

{
  "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:

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:

feature_get_for_regression(limit=3)  # 1-10, default 3

Returns:

{
  "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:

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:

{
  "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:

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):

{
  "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:

# 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

# 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

# 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

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:

# 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:

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

Or directly in SQLite:

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)