biz.dfch.SpecMgr

# biz.dfch.SpecMgr

<!-- mcp-name: io.github.dfch/biz-dfch-specmgr -->

[![License: AGPL v3](https://img.shields.io/badge/License-AGPLv3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue.svg)
[![Lint and Test](https://github.com/dfch/biz.dfch.SpecMgr/actions/workflows/ci.yml/badge.svg)](https://github.com/dfch/biz.dfch.SpecMgr/actions/workflows/ci.yml)
![Coverage](docs/coverage.svg)
[![TestPyPI version](https://img.shields.io/badge/dynamic/json?url=https://test.pypi.org/pypi/biz-dfch-specmgr/json&label=TestPyPI&query=$.info.version&color=orange)](https://test.pypi.org/project/biz-dfch-specmgr/)
[![PyPI version](https://img.shields.io/badge/dynamic/json?url=https://pypi.org/pypi/biz-dfch-specmgr/json&label=PyPI&query=$.info.version&color=blue)](https://pypi.org/project/biz-dfch-specmgr/)
[![PyPI downloads](https://img.shields.io/pypi/dm/biz-dfch-specmgr.svg)](https://pypistats.org/packages/biz-dfch-specmgr)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.dfch%2Fbiz--dfch--specmgr-8A2BE2.svg)](https://registry.modelcontextprotocol.io/?q=io.github.dfch/biz-dfch-specmgr)

An artifact manager for system specifications.

This project is an **MCP server** that you can use to manage different
specification artifacts.

At this time, we have these artifact types:

- Architecture Decision Record (ADR) (deprecated, will be phased out, use DEC instead)
- Decision (DEC)
- Feature (FEAT)
- Goal (GOL)
- Problem Statement (PRB)
- Question and Answer (QA)
- Requirement (REQ)
- Risk (RSK)
- Standard Operating Procedure (SOP)
- System Requirements Specification (SYSRS)
- Task List (TSK)
- Use Case (UC)
- Verification Case Record (VCR)

See [MCP Server](#mcp-server) and [docs/MCP.md](docs/MCP.md) for details.

The **MCP server** (and the management **CLI**) are optional. You install
them as "extras" (see [Installation](#installation)).

## Table of Contents

- [Installation](#installation)
- [CLI Usage](#cli-usage)
- [MCP Server](#mcp-server)
- [Development](#development)
- [Testing](#testing)
- [Make a Release](#make-a-release)
- [License](#license)

## Installation

As a library only (no CLI, no MCP server):

```bash
pip install biz-dfch-specmgr
```

With the CLI:

```bash
pip install "biz-dfch-specmgr[cli]"
```

With the MCP server:

```bash
pip install "biz-dfch-specmgr[mcp]"
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv add "biz-dfch-specmgr[cli,mcp]"
```

## CLI Usage

With the CLI you can generate schema and documentation. We use these commands
in pre-commit hooks and `ci.yml`.

_No domain document-management commands (create/update/status/etc.) exist
in the CLI yet — those are currently MCP-only, see
[MCP Server](#mcp-server). The CLI covers `version`, `mcp` (below), and a
handful of cross-cutting/doc-generation commands (`specmgr --help` for the
full list)._

```bash
specmgr version
```

## MCP Server

Requires the `mcp` extra. The server exposes resources, tools, and prompts
for document management, plus cross-cutting utilities (e.g. markdown
formatting).

**The full, up-to-date list of every resource, resource template, tool, and
prompt — with parameters, MIME types, and descriptions — lives in
[docs/MCP.md](docs/MCP.md).** That document generated from the live server
registration by `specmgr mcp-docs` and kept in sync by a pre-commit hook and
a CI check.

### Environment Variables

Every document type stores its `.md` files in a base directory on disk —
the file is always the source of truth, re-read and re-parsed on every
tool call, so hand-editing a file between calls is safe.

- ADRs: base directory defaults to `docs/adr`, configurable via the
  `SPECMGR_ADR_DIR` environment variable. This is ADR-specific and not
  shared with other document types.
- Requirements (REQ) and future document types: share one root directory,
  configurable via the `SPECMGR_DOCS_DIR` environment variable (default
  `docs`), with each type's own subdirectory appended automatically (e.g.
  `docs/req` for requirements).
- Features (FEAT): base directory defaults to `.specmgr/feat`, configurable
  via the `SPECMGR_FEAT_DIR` environment variable. This is FEAT-specific,
  like ADRs above, and not shared via `SPECMGR_DOCS_DIR`.

All of the base directories above are resolved relative to the MCP server
process's own current working directory unless overridden by their env var
(or, for the shared `SPECMGR_DOCS_DIR` root, unless the server was started
with `--directory`/`uv run --directory` targeting your project). If that
CWD is not what you expect — e.g. after adding `specmgr` to an MCP host
per [Add to OpenCode](#add-to-opencode) below — read the `specmgr://config`
resource to see every domain's actually-resolved absolute base directory
and whether its env var is explicitly set, without needing shell access to
the server's host.

### Start the MCP Server

Start the server with the `mcp` command:

```bash
specmgr mcp
```

By default it runs over `stdio`, for MCP hosts that launch it as a
subprocess (see [Add to OpenCode](#add-to-opencode) below). It can also
run over SSE/network:

```bash
specmgr mcp --transport sse --host localhost --port 8000
```

Or over the spec-current `streamable-http` transport, which replaces the
legacy/deprecated `sse` transport for HTTP deployments:

```bash
specmgr mcp --transport streamable-http --host localhost --port 8000
```

| Option | Env var | Default | Description |
| -------------------- | ------------------------ | ----------- | -------------------------------- |
| `--transport` / `-t` | `SPECMGR_MCP_TRANSPORT` | `stdio` | Transport mode: `stdio`, `sse`, or `streamable-http` |
| `--host` / `-h` | `SPECMGR_MCP_HOST` | `localhost` | Bind address (SSE/streamable-http mode only) |
| `--port` / `-p` | `SPECMGR_MCP_PORT` | `8000` | TCP port (SSE/streamable-http mode only) |

### Add to OpenCode

To add the `specmgr` MCP server to your OpenCode configuration:

1. Open your OpenCode config file (typically `~/.config/opencode/opencode.json` or `~/.config/opencode/opencode.jsonc`)

2. Add a configuration to the `mcp` section (and use it via `stdio`).

   **A bare `uvx --from biz-dfch-specmgr[mcp] specmgr mcp` command with no
   `--directory` and no `SPECMGR_*_DIR` env vars is unsafe**: the server
   resolves every base directory (`docs`, `docs/adr`, `.specmgr/feat`, ...)
   relative to its own process's current working directory, which an MCP
   host is free to launch from anywhere — not necessarily your project
   root. Pick one of the two options below instead of the plain form:

   **Option A — pin the working directory with `--directory`** (a global
   `uv`/`uvx` flag, so it must come *before* `--from`):

   ```json
   "specmgr": {
     "type": "local",
     "enabled": true,
     "command": [
       "uvx",
       "--directory",
       "<path-to-your-project>",
       "--from",
       "biz-dfch-specmgr[mcp]",
       "specmgr",
       "mcp"
     ]
   }
   ```

   **Option B — set the directory env vars explicitly** instead of (or in
   addition to) `--directory`:

   ```json
   "specmgr": {
     "type": "local",
     "enabled": true,
     "command": [
       "uvx",
       "--from",
       "biz-dfch-specmgr[mcp]",
       "specmgr",
       "mcp"
     ],
     "environment": {
       "SPECMGR_DOCS_DIR": "<path-to-your-project>/docs",
       "SPECMGR_ADR_DIR": "<path-to-your-project>/docs/adr",
       "SPECMGR_FEAT_DIR": "<path-to-your-project>/.specmgr/feat"
     }
   }
   ```

   Either option (or both together) makes the resolved base directories
   independent of wherever the MCP host happens to launch the server
   from. Whichever you choose, you can confirm it worked by reading the
   `specmgr://config` resource, which reports the actually-resolved
   absolute base directory for every domain and whether its env var is
   explicitly set.

3. Save the file and restart OpenCode

## Development

### Install dev dependencies

```bash
uv sync --all-extras
```

### Install pre-commit hooks (one-time)

```bash
uv run --frozen pre-commit install
```

`uv sync` only installs Python dependencies into the venv — it never
registers the hooks from `.pre-commit-config.yaml` with git, so run
this once per clone before your first commit.

### Run linters

```bash
uv run --frozen ruff format --check
uv run --frozen ruff check
uv run --frozen pylint $(git ls-files '*.py')
```

### Run tests

```bash
uv run --frozen pytest -n auto --cov=src --cov-report=
```

## Testing

You can exercise the MCP server directly with the
[MCP Inspector](https://modelcontextprotocol.io/docs/latest/tools/inspector),
in either its CLI (scriptable) or TUI (interactive terminal) client.

### Prerequisites

- The `mcp` extra installed (see [Installation](#installation)), so
  `.venv/bin/specmgr` exists.
- [`npx`](https://docs.npmjs.com/cli/v10/commands/npx) (ships with Node.js,
  version 22.19.0 or newer) — no separate Inspector install is required, it
  runs on demand via `npx @modelcontextprotocol/inspector`.

Point the Inspector at the venv's `specmgr` binary directly (rather than at
`uv run specmgr mcp`) so none of `uv run`'s own flags (e.g. `--frozen`) are
mistaken for Inspector flags:

```bash
npx @modelcontextprotocol/inspector --tui .venv/bin/specmgr mcp
npx @modelcontextprotocol/inspector --cli .venv/bin/specmgr mcp --method tools/list
```

### CLI examples

Each CLI invocation connects, runs one request, prints the result, and
exits — useful for scripting or a quick smoke test.

Get the `specmgr://version` resource:

```bash
npx @modelcontextprotocol/inspector --cli .venv/bin/specmgr mcp \
  --method resources/read --uri specmgr://version
```

List task lists via the `list_tsk` tool:

```bash
npx @modelcontextprotocol/inspector --cli .venv/bin/specmgr mcp \
  --method tools/call --tool-name list_tsk
```

Get one task list via the `get_tsk` tool (replace `<id>` with a real task
list id from the `list_tsk` output above):

```bash
npx @