Metadata-Version: 2.4
Name: specmap
Version: 0.3.9
Summary: Spec-to-code mapping: core library, MCP server, and CLI
Project-URL: Homepage, https://github.com/jdraines/specmap
Project-URL: Repository, https://github.com/jdraines/specmap
Project-URL: Issues, https://github.com/jdraines/specmap/issues
Author-email: John Raines <johndanielraines@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: code-review,llm,mcp,spec-mapping
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: cryptography>=46.0.7
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: litellm<1.82.7,>=1.30.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: mistune>=3.0.0
Requires-Dist: pydantic-ai>=0.2
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyjwt>=2.8.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: typer>=0.12.0
Requires-Dist: unidiff>=0.7.0
Requires-Dist: uvicorn[standard]>=0.29.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# Specmap

**Map AI-generated code changes back to spec intent.**

Specmap generates LLM-powered annotations that link code changes to specification documents. When an AI agent writes code, reviewers can see *which spec requirements* each code region implements, with inline `[N]` citations pointing to the exact spec sections.

## How It Works

1. **MCP server** integrates with your coding agent (e.g., Claude Code) to annotate code changes with spec references as you work
2. **CLI** validates annotations in CI (`specmap validate`)
3. **Web UI** lets reviewers browse PRs with spec annotations overlaid on diffs

```
Coding Agent ──MCP──► Specmap Server ──LLM──► .specmap/{branch}.json
                          │                          │
                     reads specs                committed to git
                     reads diffs                     │
                                                     ▼
                                              specmap validate (CI)
                                              specmap serve (Web UI)
```

## Use Specmap on Your Projects

No need to clone this repo. Install as a tool and use it in any project:

```bash
# Install
uv tool install git+https://github.com/jdraines/specmap.git

# Verify
specmap --version
```

Add the MCP server to your coding agent (`.mcp.json` in your project):

```json
{
  "mcpServers": {
    "specmap": {
      "command": "specmap-mcp",
      "env": {
        "SPECMAP_API_KEY": "sk-..."
      }
    }
  }
}
```

See the [full documentation](https://specmap.dev) for configuration, CLI commands, and CI integration.

## Develop Specmap

Clone and run locally:

```bash
git clone https://github.com/jdraines/specmap.git
cd specmap

# Install dependencies
just mcp-install     # Python (core library, MCP server, CLI, API server)
just web-install     # Node (React frontend)

# Run full dev stack (API + Vite dev server)
just dev

# Run tests
just test-all        # Unit + functional tests
just lint            # ruff + tsc

# Build wheel with bundled frontend
just build
```

To run the web UI locally, you'll need a forge token (PAT or OAuth). See [Development](docs/development.md) for the complete setup.

### Prerequisites

| Tool | Install |
|------|---------|
| Python 3.11+ | System package manager |
| [uv](https://docs.astral.sh/uv/) | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
| Node.js 20+ | System package manager |
| [just](https://github.com/casey/just) | `cargo install just` or [system packages](https://github.com/casey/just#installation) |
| git | System package manager |

## Project Structure

```
specmap/
├── core/          Python: core library, MCP server, CLI, API server
├── web/           React frontend (Vite + Tailwind)
├── tests/         Functional test suite
├── docs/          MkDocs documentation
└── justfile       Task runner (run `just` to see all commands)
```

## License

See [LICENSE](LICENSE).
