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 doc/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
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.
MCP Server
Requires the mcp extra. In addition to the specmgr://version resource,
the server exposes a full set of Architecture Decision Record (ADR) tools
and resources, implementing the MADR 4.0.0-derived schema described in
doc/adr-tool-plan.md:
| Kind | Name(s) | Description |
|---|
| Resource | specmgr://version | Installed biz-dfch-specmgr package version |
| Resource | specmgr://adr/list | Id/title/status/filename of every ADR |
| Resource | specmgr://adr/{id} | Full ADR document (frontmatter + body) by id |
| Tool | get_adr, create_adr, update_frontmatter, update_section, set_status, option_list, option_create, option_read, option_update, option_delete, validate_adr | Structured create/read/update operations over one ADR, by id |
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:
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
| Option | Env var | Default | Description |
|---|
--transport / -t | SPECMGR_MCP_TRANSPORT | stdio | Transport mode: stdio or sse |
--host / -h | SPECMGR_MCP_HOST | localhost | Bind address (SSE mode only) |
--port / -p | SPECMGR_MCP_PORT | 8000 | TCP port (SSE mode only) |
Add to OpenCode
To add the specmgr MCP server to your OpenCode configuration:
-
Open your OpenCode config file (typically ~/.config/opencode/opencode.json or ~/.config/opencode/opencode.jsonc)
-
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"]
}
- Save the file and restart OpenCode
Development
Install dev dependencies
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:
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:
License
AGPL-3.0-or-later