npm package: @spec-r/mcp-server
Description: MCP server for spec-r — give AI agents direct access to your specifications
Latest version: 0.3.1

# @spec-r/mcp-server

MCP server — give Claude Code and other AI agents direct access to your specifications.

## Setup

**1. Get your API key**

Go to Settings → API Keys → Create.

**2. Add to your MCP config**

Per-project (`.mcp.json` at repo root):

```json
{
  "mcpServers": {
    "spec-r": {
      "command": "npx",
      "args": ["-y", "@spec-r/mcp-server"],
      "env": {
        "SPECR_API_KEY": "specr_xxxxx",
        "SPECR_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}
```

Global (`~/.claude/settings.json` or Claude Desktop config) — omit `SPECR_PROJECT_ID`, the agent will discover projects automatically:

```json
{
  "mcpServers": {
    "spec-r": {
      "command": "npx",
      "args": ["-y", "@spec-r/mcp-server"],
      "env": {
        "SPECR_API_KEY": "specr_xxxxx"
      }
    }
  }
}
```

## Environment variables

| Variable           | Required | Description                                           |
| ------------------ | -------- | ----------------------------------------------------- |
| `SPECR_API_KEY`    | Yes      | API key from Settings → API Keys                      |
| `SPECR_BASE_URL`   | No       | Override API base URL (default: `https://spec-r.app`) |
| `SPECR_PROJECT_ID` | No       | Default project UUID — skip to let the agent discover it |

## Tools

### Discovery

| Tool                  | Description                                                    |
| --------------------- | -------------------------------------------------------------- |
| `list_projects`       | List all projects and their UUIDs                              |
| `list_specs`          | List all specs in a project                                    |
| `get_spec`            | Get a spec with all blocks (`agent`, `markdown`, or `json`)    |
| `search_specs`        | Search specs and blocks by keyword                             |
| `get_project_context` | Get project tech stack, industry, and conventions              |
| `get_data_models`     | Get all data models defined across specs in a project          |

### Write

| Tool             | Description                                                       |
| ---------------- | ----------------------------------------------------------------- |
| `create_project` | Create a new project with name, tech stack, and conventions       |
| `update_project` | Update project metadata, tech stack, or conventions               |
| `publish_spec`   | Create or update a spec by title (upsert with blocks)             |
| `create_spec`    | Create an empty spec                                              |
| `add_block`      | Add a typed block to a spec                                       |
| `update_block`   | Update a block's content                                          |
| `delete_block`   | Delete a block                                                    |
| `update_spec`    | Update spec title, type, or status                                |

### Shared resources

Shared resources are reusable entities (`data_model`, `persona`, `enum_definition`, `external_dependency`) defined once at the project level and referenced from any spec block via `linkedResourceId`.

| Tool              | Description                                         |
| ----------------- | --------------------------------------------------- |
| `list_resources`  | List shared resources, optionally filtered by type  |
| `get_resource`    | Get a resource and see which specs reference it     |
| `create_resource` | Create a shared resource                            |
| `update_resource` | Update a shared resource                            |
| `delete_resource` | Delete a shared resource                            |

### Implementation tracking

| Tool                           | Description                                                         |
| ------------------------------ | ------------------------------------------------------------------- |
| `get_implementation_status`    | Get progress and per-step status for a spec                         |
| `update_implementation_status` | Mark a step as `pending`, `in_progress`, `done`, or `blocked`       |

### AI analysis

| Tool                 | Description                                                     |
| -------------------- | --------------------------------------------------------------- |
| `analyze_screenshot` | Analyze a wireframe/mockup and extract structured specs         |
| `analyze_feedback`   | Analyze client feedback and extract prioritized feature requests |

## Resources

The server exposes MCP resources for passive reading without tool calls:

| URI                                          | Description                              |
| -------------------------------------------- | ---------------------------------------- |
| `spec-r://block-types`                       | Schema reference for all 25 block types  |
| `spec-r://projects/{projectId}/specs`        | Spec list for a project                  |
| `spec-r://projects/{projectId}/resources`    | Shared resources for a project           |
| `spec-r://specs/{specId}`                    | Full spec content                        |

Before calling `publish_spec` or `add_block`, read `spec-r://block-types` to get the exact content schema for each block type.

## Tips

- No project yet? Use `create_project` to set one up — the agent will return a project ID to use in subsequent calls
- Omit `SPECR_PROJECT_ID` in global configs — the agent uses `list_projects` to discover IDs
- Use `get_spec` with `format: "agent"` for the most implementation-ready output
- Define cross-cutting entities (User, enums, external APIs) as shared resources with `create_resource` — avoids repeating the same data model in every spec
- Use `update_implementation_status` to track progress as you code — attach commit SHAs and PR URLs

## License

MIT