MCP Server

The betterspec MCP server exposes your project's specs, knowledge, and capabilities through the Model Context Protocol. It is the primary programmatic interface for AI coding platforms to interact with betterspec — giving them structured, typed access without raw filesystem scanning.

Installation

# Via npx (no global install needed)
npx @betterspec/mcp

# Via the CLI
betterspec serve

Both start a stdio-based MCP server in the current directory (or nearest parent with a betterspec/ directory).

Connecting to Your AI Tool

Claude Code

claude mcp add betterspec -- npx @betterspec/mcp

OpenCode

Add to your OpenCode MCP configuration:

{
  "betterspec": {
    "command": "npx",
    "args": ["@betterspec/mcp"]
  }
}

Gemini CLI

Add to your Gemini CLI settings:

{
  "mcpServers": {
    "betterspec": {
      "command": "npx",
      "args": ["@betterspec/mcp"]
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "betterspec": {
      "command": "npx",
      "args": ["@betterspec/mcp"]
    }
  }
}

Available Tools

The MCP server exposes 9 tools that AI platforms can call:

Read

Tool	Description
`betterspec_status`	Get project status — active changes, capabilities count, task completion
`betterspec_list`	List changes with optional status filter and archived flag
`betterspec_show`	Return all spec files for a change (proposal, requirements, scenarios, design, tasks)
`betterspec_search`	Keyword search across specs and capabilities
`betterspec_impact`	Show what specs and capabilities reference a file or path
`betterspec_digest`	Get a summary of project knowledge — capabilities, active changes, configuration

Write

Tool	Description
`betterspec_propose`	Create a new change proposal from a description
`betterspec_archive`	Archive a completed change with an optional outcome summary

Analysis

Tool	Description
`betterspec_verify`	Run structural completeness checks on a change's spec files
`betterspec_diff`	Run drift analysis and return the full drift report (score + items)

Available Resources

The MCP server exposes 6 resources that AI platforms can read:

Resource URI	Description
`betterspec://knowledge/architecture`	Project architecture documentation
`betterspec://knowledge/patterns`	Established code patterns and conventions
`betterspec://knowledge/glossary`	Domain-specific terminology
`betterspec://capabilities`	All registered project capabilities (JSON)
`betterspec://decisions`	Architecture decision records (JSON)
`betterspec://changes/active`	Currently active change specifications (JSON)

Typical AI workflow via MCP

1. betterspec_status       → understand current project state
2. betterspec_show         → read full spec for a change before implementing
3. betterspec_diff         → check for drift before starting work
4. betterspec_propose      → create a new change when planning
5. betterspec_verify       → confirm spec is complete before handing off to builder
6. betterspec_archive      → capture outcome and knowledge after implementation

MCP vs. Direct File Access

The MCP server is optional. AI tools can always read betterspec files directly from the filesystem. Use MCP when:

You want structured, typed access instead of raw markdown reads
Your tool supports MCP natively
You need to run actions (propose, archive) programmatically in sandboxed environments

MCP Server

On this page