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:

• Architecture Decision Record (ADR)
• Use Case (UC)
• Question and Answer (QA)
• Requirement (REQ)
• Task List (TSK)
• Problem Statement (PRB)

See MCP Server and docs/MCP.md for details.

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

Table of Contents

• Installation
• CLI Usage
• MCP Server
• Development
• Testing
• 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

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. The CLI covers version, mcp (below), and a handful of cross-cutting/doc-generation commands (specmgr --help for the full list).

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. 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).
• The webfetch tool (bearer-authenticated, URL-filtered HTTP GET, intended primarily for Web Server instances using PAT authentication) requires two environment variables: SPECMGR_WEBFETCH_BASE_URL (the base URL requested URLs must case-insensitively start with) and SPECMGR_WEBFETCH_BEARER (the bearer token sent as the Authorization header). Both must be set or the tool raises an error; there are no defaults.

Start the MCP Server

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

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

specmgr mcp --transport streamable-http --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]",
    "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"

Testing

You can exercise the MCP server directly with the MCP Inspector, in either its CLI (scriptable) or TUI (interactive terminal) client.

Prerequisites

• The mcp extra installed (see Installation), so .venv/bin/specmgr exists.
• 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:

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:

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

List task lists via the list_tsk tool:

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):

npx @modelcontextprotocol/inspector --cli .venv/bin/specmgr mcp \
  --method tools/call --tool-name get_tsk --tool-arg id=<id>

Add --format json to any of the above to get machine-readable output, e.g. piped into jq.

Connecting with the TUI

npx @modelcontextprotocol/inspector --tui .venv/bin/specmgr mcp

This launches the server as an ad-hoc stdio target and opens the terminal UI with it preselected (unlike the CLI, the TUI has no --server <name> flag — it lists whichever servers are available and you pick one, though with a single ad-hoc target there is nothing else to pick). Press c to connect, then use the tabs to explore:

• t — Tools tab: browse and call tools (e.g. get_tsk) with a form-based input.
• r — Resources tab: browse and read resources (e.g. specmgr://version, specmgr://iso25010).
• m — Prompts tab: list and render prompts.
• p — Protocol tab: raw JSON-RPC request/response history, useful for debugging.
• o — Console tab: stderr from the connected specmgr mcp process (tracebacks land here).
• c / d — connect / disconnect; Esc or Ctrl+C — exit.

The TUI requires a real TTY (raw-mode support) and does not run in a headless CI job — use the CLI client there instead.

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.

3. Commit and push to dev

git add pyproject.toml CHANGELOG.md
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}
git checkout dev

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.

License

AGPL-3.0-or-later