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

• Architecture Decision Record (ADR) (deprecated, will be phased out, use DEC instead)
• Decision (DEC)
• Feature (FEAT)
• Goal (GOL)
• Problem Statement (PRB)
• Question and Answer (QA)
• Requirement (REQ)
• Risk (RSK)
• Standard Operating Procedure (SOP)
• System Requirements Specification (SYSRS)
• Task List (TSK)
• Use Case (UC)
• Verification Case Record (VCR)

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).
• Features (FEAT): base directory defaults to .specmgr/feat, configurable via the SPECMGR_FEAT_DIR environment variable. This is FEAT-specific, like ADRs above, and not shared via SPECMGR_DOCS_DIR.
• The confluence_fetch tool (renamed from webfetch; bearer-authenticated, URL-filtered HTTP GET, intended primarily for Confluence instances using PAT authentication) requires two environment variables: SPECMGR_CONFLUENCE_BASE_URL (the base URL requested URLs must case-insensitively start with) and SPECMGR_CONFLUENCE_BEARER (the bearer token sent as the Authorization header). Both must be set or the tool raises an error; there are no defaults.

All of the base directories above are resolved relative to the MCP server process's own current working directory unless overridden by their env var (or, for the shared SPECMGR_DOCS_DIR root, unless the server was started with --directory/uv run --directory targeting your project). If that CWD is not what you expect — e.g. after adding specmgr to an MCP host per Add to OpenCode below — read the specmgr://config resource to see every domain's actually-resolved absolute base directory and whether its env var is explicitly set, without needing shell access to the server's host.

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 a configuration to the mcp section (and use it via stdio).

   A bare uvx --from biz-dfch-specmgr[mcp] specmgr mcp command with no --directory and no SPECMGR_*_DIR env vars is unsafe: the server resolves every base directory (docs, docs/adr, .specmgr/feat, ...) relative to its own process's current working directory, which an MCP host is free to launch from anywhere — not necessarily your project root. Pick one of the two options below instead of the plain form:

   Option A — pin the working directory with --directory (a global uv/uvx flag, so it must come before --from):

   json

   Copy

   "specmgr": {
     "type": "local",
     "enabled": true,
     "command": [
       "uvx",
       "--directory",
       "<path-to-your-project>",
       "--from",
       "biz-dfch-specmgr[mcp]",
       "specmgr",
       "mcp"
     ]
   }
   

   Option B — set the directory env vars explicitly instead of (or in addition to) --directory:

   json

   Copy

   "specmgr": {
     "type": "local",
     "enabled": true,
     "command": [
       "uvx",
       "--from",
       "biz-dfch-specmgr[mcp]",
       "specmgr",
       "mcp"
     ],
     "environment": {
       "SPECMGR_DOCS_DIR": "<path-to-your-project>/docs",
       "SPECMGR_ADR_DIR": "<path-to-your-project>/docs/adr",
       "SPECMGR_FEAT_DIR": "<path-to-your-project>/.specmgr/feat"
     }
   }
   

   Either option (or both together) makes the resolved base directories independent of wherever the MCP host happens to launch the server from. Whichever you choose, you can confirm it worked by reading the specmgr://config resource, which reports the actually-resolved absolute base directory for every domain and whether its env var is explicitly set.

3. Save the file and restart OpenCode

Development

Install dev dependencies

uv sync --all-extras

Install pre-commit hooks (one-time)

uv run --frozen pre-commit install

uv sync only installs Python dependencies into the venv — it never registers the hooks from .pre-commit-config.yaml with git, so run this once per clone before your first commit.

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 pytest -n auto --cov=src --cov-report=

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