@specforge/mcp

MCP (Model Context Protocol) server for SpecForge - enables AI agents to interact with your projects, specifications, epics, and tickets.

Installation

npm install -g @specforge/mcp

Or install locally:

npm install @specforge/mcp

Getting Your API Key

1. Log in to the SpecForge webapp
2. Navigate to Settings > API Keys
3. Click Create New API Key
4. Select the permissions you need (read, write, or both)
5. Copy the key immediately - it's only shown once!

API keys have the format: sf_live_xxxxxxxxxxxxxxxxxxxxxx

Environment Variables

AI Client Configuration

Claude Desktop

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

{
  "mcpServers": {
    "specforge": {
      "command": "specforge-mcp",
      "env": {
        "SPECFORGE_API_KEY": "sf_live_your_api_key_here",
        "SPECFORGE_API_URL": "https://your-api-gateway-url.amazonaws.com/prod"
      }
    }
  }
}

Claude Code (CLI)

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "specforge": {
      "command": "specforge-mcp",
      "env": {
        "SPECFORGE_API_KEY": "sf_live_your_api_key_here",
        "SPECFORGE_API_URL": "https://your-api-gateway-url.amazonaws.com/prod"
      }
    }
  }
}

Or set environment variables in your shell and run:

export SPECFORGE_API_KEY="sf_live_your_api_key_here"
export SPECFORGE_API_URL="https://your-api-gateway-url.amazonaws.com/prod"
specforge-mcp

Cursor

Add to your Cursor MCP configuration:

{
  "mcpServers": {
    "specforge": {
      "command": "npx",
      "args": ["-y", "@specforge/mcp"],
      "env": {
        "SPECFORGE_API_KEY": "sf_live_your_api_key_here",
        "SPECFORGE_API_URL": "https://your-api-gateway-url.amazonaws.com/prod"
      }
    }
  }
}

GitHub Copilot VS Code Extension

Add to your VS Code settings.json:

{
  "github.copilot.advanced": {
    "mcp": {
      "servers": {
        "specforge": {
          "command": "specforge-mcp",
          "env": {
            "SPECFORGE_API_KEY": "sf_live_your_api_key_here",
            "SPECFORGE_API_URL": "https://your-api-gateway-url.amazonaws.com/prod"
          }
        }
      }
    }
  }
}

GitHub Copilot CLI

Create a config file at ~/.config/gh-copilot/mcp.json:

{
  "servers": {
    "specforge": {
      "command": "specforge-mcp",
      "env": {
        "SPECFORGE_API_KEY": "sf_live_your_api_key_here",
        "SPECFORGE_API_URL": "https://your-api-gateway-url.amazonaws.com/prod"
      }
    }
  }
}

OpenAI Codex CLI

Configure using environment variables:

export SPECFORGE_API_KEY="sf_live_your_api_key_here"
export SPECFORGE_API_URL="https://your-api-gateway-url.amazonaws.com/prod"

# Then configure your Codex CLI to use the MCP server
codex --mcp-server specforge-mcp

ChatGPT Desktop

Add to ChatGPT Desktop's MCP configuration:

{
  "mcpServers": {
    "specforge": {
      "command": "specforge-mcp",
      "env": {
        "SPECFORGE_API_KEY": "sf_live_your_api_key_here",
        "SPECFORGE_API_URL": "https://your-api-gateway-url.amazonaws.com/prod"
      }
    }
  }
}

Windsurf

Add to Windsurf's settings:

{
  "mcp": {
    "servers": {
      "specforge": {
        "command": "specforge-mcp",
        "env": {
          "SPECFORGE_API_KEY": "sf_live_your_api_key_here",
          "SPECFORGE_API_URL": "https://your-api-gateway-url.amazonaws.com/prod"
        }
      }
    }
  }
}

Generic MCP Client

For any MCP-compatible client, the server uses stdio transport:

# Start the server with environment variables
SPECFORGE_API_KEY="sf_live_xxx" SPECFORGE_API_URL="https://xxx" specforge-mcp

The server communicates via JSON-RPC over stdin/stdout.

Available Tools

The SpecForge MCP server provides the following tool categories:

Core Operations

• list_projects - List all accessible projects
• get_project - Get project details
• list_specifications - List specifications in a project
• get_specification - Get specification details
• list_epics - List epics in a specification
• get_epic - Get epic details
• list_tickets - List tickets in an epic
• get_ticket - Get ticket details with implementation steps

Context & AI Tools

• get_implementation_context - Get full context for implementing a ticket
• get_next_actionable_tickets - Get tickets ready to work on
• get_blocked_tickets - Get blocked tickets with reasons
• get_critical_path - Get the critical implementation path

Workflow & Tracking

• start_work_session - Start working on a ticket
• complete_work_session - Mark work complete with summary
• report_progress - Report progress on a ticket

Testing Tools

• report_test_results - Report test results for a ticket
• get_ticket_test_status - Get test status
• validate_ticket_completion - Validate completion criteria

Discovery Tools

• report_discovery - Report bugs, tech debt, or new requirements
• get_pending_discoveries - Get unresolved discoveries
• resolve_discovery - Mark a discovery as resolved

Status & Analytics

• get_specification_status - Get specification progress
• get_epic_status - Get epic progress
• get_implementation_summary - Get overall project summary
• get_blockers_report - Get blocking dependencies

Search Tools

• search_tickets - Search tickets by text
• find_tickets_by_file - Find tickets affecting a file
• find_tickets_by_tag - Find tickets with specific tags
• find_related_tickets - Find related tickets

Git Integration

• link_commit - Link a commit to a ticket
• link_pull_request - Link a PR to a ticket
• get_ticket_commits - Get commits for a ticket
• get_ticket_prs - Get PRs for a ticket

Troubleshooting

"SPECFORGE_API_KEY environment variable is required"

Make sure you've set the SPECFORGE_API_KEY environment variable with your API key from the SpecForge webapp.

# Check if it's set
echo $SPECFORGE_API_KEY

# Set it
export SPECFORGE_API_KEY="sf_live_your_key_here"

"Invalid API key format"

API keys must start with sf_live_. If your key doesn't match this format, regenerate it in the webapp.

"SPECFORGE_API_URL environment variable is required"

You need to provide the API Gateway URL from your SpecForge deployment. This is output when you deploy the backend.

Connection Timeouts

If you're experiencing connection issues:

1. Verify your API URL is correct
2. Check your network connection
3. Enable debug mode to see detailed logs:

export SPECFORGE_DEBUG=true
specforge-mcp

Debug Mode

Enable debug logging to troubleshoot issues:

export SPECFORGE_DEBUG=true

This will output detailed logs to stderr, including:

• Configuration loaded
• Tool calls received
• API requests made
• Response data

Server Not Starting

1. Ensure Node.js 18+ is installed
2. Check that the package is installed globally: npm list -g @specforge/mcp
3. Try reinstalling: npm install -g @specforge/mcp

Permission Denied

If you get "permission denied" when running specforge-mcp:

# On macOS/Linux
chmod +x $(which specforge-mcp)

# Or run with node directly
node $(npm root -g)/@specforge/mcp/dist/index.js

Development

To contribute to the MCP server:

# Clone the repo
git clone https://github.com/your-org/specforge.git
cd specforge/mcp

# Install dependencies
npm install

# Build
npm run build

# Link for local testing
npm link

# Run in development mode
npm run dev

License

MIT