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 Records (ADR)
• Use Case (UC)
• Requirement (REQ)
• Task List (TSK)

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
• 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

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"

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