biz.dfch.SpecMgr

An artifact manager for system specifications.

This project is a library, a CLI, and an MCP server, all in one repository. The CLI and MCP server are optional — install only what you need via extras (see Installation).

Status: first domain feature shipped. Architecture Decision Record (ADR) management — creating, reading, and editing MADR 4.0.0-derived ADRs — is implemented end-to-end as MCP tools/resources (see MCP Server below and .specmgr/feat/feat-0-doc-in-specmgr/adr-tool-plan.md for the full design). It is MCP-only so far: there is no specmgr adr ... CLI command yet, and no second document type beyond ADRs.

Table of Contents

• Installation
• CLI Usage
• MCP Server
• Development
• Make a Release
• License

Installation

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

pip install biz-dfch-specmgr

With the CLI:

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

With the MCP server:

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

Or with uv:

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

CLI Usage

No ADR (or other domain) commands exist yet — only version and mcp (below). ADR management is currently MCP-only, see MCP Server.

specmgr version

MCP Server

Requires the mcp extra. The server exposes resources, tools, and prompts for Architecture Decision Record (ADR), requirement (REQ), and use-case (UC) 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. Unlike this README, it is not hand-maintained: it is regenerated from the live server registration by specmgr mcp-docs and kept in sync by a pre-commit hook, so it can never silently drift as tools/resources/prompts are added, renamed, or removed.

ADRs live as .md files in a base directory (default docs/adr, configurable via the SPECMGR_ADR_DIR environment variable) — the file on disk is always the source of truth, re-read and re-parsed on every tool call, so hand-editing a file between calls is safe.

Start the server with the mcp command:

specmgr mcp

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

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

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 the following configuration to the mcp section (and use it via stdio):

"specmgr": {
  "type": "local",
  "enabled": true,
  "command": ["uvx", "--from", "biz-dfch-specmgr[mcp]", "python", "-m", "biz.dfch.specmgr", "mcp"]
}

3. Save the file and restart OpenCode

Development

Install dev dependencies

uv sync --all-extras

Run linters

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

Run tests

uv run --frozen python -m unittest discover -v -s tests -t . -p "test_*.py"

Make a Release

1. Make sure all tests pass

Before releasing, make sure the CI pipeline is green on the dev branch:

uv run --frozen ruff format --check
uv run --frozen ruff check
uv run --frozen pylint $(git ls-files '*.py')
uv run --frozen python -m unittest discover -v -s tests -t . -p "test_*.py"

2. Increase the version

Update the version in pyproject.toml:

version = "x.y.z"

Move the [Unreleased] section in CHANGELOG.md into a new dated ## [x.y.z] - YYYY-MM-DD section.

Also update both version fields in server.json (the top-level one and the one under packages[0]) to match — the MCP Registry manifest must stay in lockstep with pyproject.toml.

3. Commit and push to dev

git add pyproject.toml CHANGELOG.md server.json
git commit -m "chore: bump version to vx.y.z"
git push origin dev

4. Merge dev into main

git checkout main
git merge dev
git push origin main

5. Create and push a version tag

export VERSION=x.y.z
git tag v${VERSION}
git push origin v${VERSION}

Note: .github/workflows/publish.yml handles the rest of the release automatically once the tag above is pushed — it builds and publishes the sdist/wheel to TestPyPI then PyPI via Trusted Publishing (OIDC, no stored token), creates the matching GitHub Release with the built artifacts attached, and publishes server.json (repo root, the MCP Registry publisher manifest — see the server.json format spec) to the MCP Registry via mcp-publisher/GitHub OIDC. biz-dfch-specmgr is live on PyPI and in the MCP Registry as of v0.1.0.

Then switch back to dev to continue work:

git checkout dev

License

AGPL-3.0-or-later