Skip to main content

MCP Server

The LeanSpec MCP (Model Context Protocol) server enables AI assistants like Claude Desktop, GitHub Copilot, and other MCP-compatible clients to interact with your LeanSpec projects directly.

Overview​

The MCP server provides AI assistants with:

  • Tools - Actions to list, search, create, update specs
  • Resources - Browseable content (specs, board, stats)
  • Prompts - Quick action templates for common workflows

Features​

Tools​

The MCP server exposes these tools to AI assistants:

  • list - List all specifications with optional filtering
  • search - Full-text search across specifications
  • view - View specification content (formatted, raw markdown, or JSON)
  • create - Create new specifications
  • update - Update specification metadata (status, priority, tags, etc.)
  • archive - Move specifications to archived/ directory
  • stats - Get project statistics
  • board - Get Kanban board view
  • deps - Show specification dependencies
  • files - List files in a spec (for exploring sub-specs and assets)
  • check - Check for sequence number conflicts
  • validate - Validate specs for quality issues (line count, complexity)
  • backfill - Backfill timestamps and metadata from git history

Resources​

Browseable content accessible to AI assistants:

  • spec://<spec-name> - Individual specification content
  • board://kanban - Current Kanban board state
  • stats://overview - Project statistics overview

Prompts​

Quick action templates for common workflows:

  • Create feature spec - Guided specification creation
  • Update spec status - Quick status changes
  • Find related specs - Dependency discovery

Installation​

The MCP server is included with LeanSpec. No additional installation is required.

npm install -g lean-spec

Configuration​

VS Code (GitHub Copilot)​

  1. Open VS Code settings (JSON):

    • Press Cmd/Ctrl + Shift + P
    • Type "Preferences: Open User Settings (JSON)"
    • Or directly edit ~/.vscode/settings.json

  2. Add the LeanSpec MCP server configuration:

{
  "github.copilot.chat.mcp.servers": {
    "lean-spec": {
      "command": "npx",
      "args": ["-y", "lean-spec", "mcp"],
      "cwd": "${workspaceFolder}"
    }
  }
}

The ${workspaceFolder} variable automatically uses your current workspace root. For a specific project path, replace it with the absolute path.

Using npx

Using npx ensures you're always using the latest version and works without global installation. The -y flag automatically confirms the installation prompt.

Claude Desktop​

  1. Open your Claude Desktop configuration file:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • Linux: ~/.config/Claude/claude_desktop_config.json

  2. Add the LeanSpec MCP server configuration:

{
  "mcpServers": {
    "lean-spec": {
      "command": "npx",
      "args": ["-y", "lean-spec", "mcp"],
      "cwd": "/path/to/your/lean-spec/project"
    }
  }
}

Replace /path/to/your/lean-spec/project with the absolute path to your LeanSpec project directory.

Multiple Projects​

You can configure multiple LeanSpec projects:

{
  "mcpServers": {
    "lean-spec-projectA": {
      "command": "npx",
      "args": ["-y", "lean-spec", "mcp"],
      "cwd": "/path/to/projectA"
    },
    "lean-spec-projectB": {
      "command": "npx",
      "args": ["-y", "lean-spec", "mcp"],
      "cwd": "/path/to/projectB"
    }
  }
}

Alternative: Using Global Installation​

If you have LeanSpec installed globally (npm install -g lean-spec), you can use:

{
  "mcpServers": {
    "lean-spec": {
      "command": "lean-spec",
      "args": ["mcp"],
      "cwd": "/path/to/your/lean-spec/project"
    }
  }
}

Other MCP Clients​

For other MCP-compatible clients, configure them to run:

  • Command: npx -y lean-spec mcp (recommended) or lean-spec mcp (if globally installed)
  • Working Directory: Your LeanSpec project root
  • Transport: stdio

Usage Examples​

Once configured, you can interact with your LeanSpec project through your AI assistant:

List specifications​

List all specifications in my project

Search for specifications​

Search for all specs related to "authentication"

Read a specification​

View the spec for "001-user-authentication"

Or for raw markdown:

View the spec for "001-user-authentication" in raw format

Create a new specification​

Create a new spec called "api-redesign" with high priority and tags "api, backend"

Get project statistics​

Show me the project statistics

View Kanban board​

Show me the current Kanban board

Archive a specification​

Archive the spec "024-flat-structure-migration"

List files in a spec​

Show me all files in spec 045

Check for conflicts​

Check for sequence number conflicts

Validate specs​

Validate all specs for quality issues

Or for specific specs:

Validate specs 018 and 045 with a max line limit of 500

Backfill timestamps​

Backfill missing timestamps from git history

Or with a dry run:

Show me what would be backfilled without making changes

Troubleshooting​

Server won't start​

  • Verify the cwd path in your configuration points to a valid LeanSpec project (has .lean-spec/config.json)
  • If using npx, ensure you have internet access for the first run
  • If using global installation, check that lean-spec is in your PATH
  • Try running npx -y lean-spec mcp or lean-spec mcp directly from your project directory

Tools not appearing​

  • Restart your MCP client after configuration changes
  • Check client logs for connection errors
  • Verify the LeanSpec project is properly initialized (lean-spec init)

Permission errors​

  • Ensure the working directory is readable/writable
  • Check file permissions on the specs directory

Development​

Testing the MCP Server​

You can test the MCP server using the MCP Inspector:

npx @modelcontextprotocol/inspector npx -y lean-spec mcp

Or test directly from your project:

cd /path/to/your/lean-spec/project
npx -y lean-spec mcp
# or if installed globally:
lean-spec mcp

Security Considerations​

Security
  • The MCP server runs with the same permissions as your user account
  • It can read and modify files in your LeanSpec project
  • Only expose the server to trusted MCP clients
  • Review changes made by AI assistants before committing

Learn More​