biz.dfch.SpecMgr
An artifact manager for system specifications.
This project is a library, a CLI, and an MCP server, all in onerepository. The CLI and MCP server are optional — install only what youneed via extras (see Installation).
Status: first domain feature shipped. Architecture Decision Record (ADR)management — creating, reading, and editing MADR 4.0.0-derived ADRs — isimplemented end-to-end as MCP tools/resources (seeMCP Server below and doc/adr-tool-plan.md for the fulldesign). It is MCP-only so far: there is no specmgr adr ... CLI commandyet, 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. In addition to the specmgr://version resource,the server exposes a full set of Architecture Decision Record (ADR) toolsand resources, implementing the MADR 4.0.0-derived schema described indoc/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 ondisk is always the source of truth, re-read and re-parsed on every toolcall, 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 asubprocess (see Add to OpenCode below). It can alsorun 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.jsonor~/.config/opencode/opencode.jsonc)Add the following configuration to the
mcpsection (and use it viastdio):
"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
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 andthe one under packages[0]) to match — the MCP Registry manifest muststay 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 releaseautomatically once the tag above is pushed — it builds and publishes thesdist/wheel to TestPyPI then PyPI via Trusted Publishing (OIDC, nostored token), creates the matching GitHub Release with the builtartifacts attached, and publishes server.json (repo root, the MCPRegistry publisher manifest — see theserver.json format spec)to the MCP Registryvia mcp-publisher/GitHub OIDC. biz-dfch-specmgr is live onPyPI and in theMCP Registryas of v0.1.0.
Then switch back to dev to continue work:
git checkout dev
License
AGPL-3.0-or-later
