biz.dfch.SpecMgr

<!-- mcp-name: io.github.dfch/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
• 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) 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:

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

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:

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