biz.dfch.SpecMgr

An artifact manager for system specifications.

This project is an MCP server that you can use to manage different specification artifacts — see Concepts for the full list of artifact types and how they relate, and MCP Server / docs/MCP.md for the tool/resource/prompt reference.

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

Table of Contents

• Concepts
• Installation
• CLI Usage
• MCP Server
• Usage
• Referencing Artifacts
• Development
• Testing
• Make a Release
• License

Concepts

Every artifact is a plain markdown file with a YAML frontmatter block on disk — git-friendly, diffable, and readable/editable by hand. The filesystem is always the source of truth; the MCP server wraps it with structured, validated read/write/list/status tools (see Usage).

A typical spec effort starts with a QA elicitation interview, which surfaces GOLs (goals) and PRBs (problems). Those inform REQs and UCs, which get risk-assessed (RSK) and backed by DECisions, verified via one VCR per REQ/UC (each collecting its acceptance criteria), and tracked via TSK task lists. A SYSRS ties all of it together into one ISO/IEC/IEEE 29148-structured specification. SOP and FEAT support the process itself rather than sitting in this chain.

QA -> GOL / PRB -> REQ / UC -> RSK / DEC -> TSK, VCR -> SYSRS (aggregates all)

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]"

With semantic-similarity search (find_related/find_similar_text, see Semantic Similarity Search below), add the similarity extra on top of mcp:

pip install "biz-dfch-specmgr[mcp,similarity]"

Or with uv:

uv add "biz-dfch-specmgr[cli,mcp,similarity]"

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 find_related/find_similar_text tools (semantic-similarity search, requires the similarity extra) are turned off by setting the SPECMGR_SIMILARITY_DISABLED environment variable (any value; presence-based) — see Semantic Similarity Search below for the full behavior (install, the non-blocking background warmup at server startup, the model cache location, and the structured unavailable result both tools return when the feature is disabled or the backend/model fails to load).

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.

Semantic Similarity Search

The find_related and find_similar_text tools rank documents by semantic similarity using local sentence embeddings (no API keys, no network at inference time). find_related(type, id) finds the documents most related to an existing document; find_similar_text(query) finds the documents most similar to a free-form query — e.g. a draft you have not saved yet, for pre-creation dedup/discovery. Both tools always appear in the tool list, regardless of whether the feature is installed or enabled: when it is unavailable, each call returns a structured {available: false, reason, message} result instead of raising.

Install. The tools need the optional similarity extra on top of mcp — the exact commands are in Installation (pip install "biz-dfch-specmgr[mcp,similarity]" or uv add "biz-dfch-specmgr[cli,mcp,similarity]"). The backend is fastembed running BAAI/bge-small-en-v1.5 (CPU-only, ONNX Runtime, 384-dim).

Model download and cache. The model is downloaded once from the Hugging Face Hub the first time it is loaded (network required at that point only; after that, inference is fully offline). It is cached in $FASTEMBED_CACHE_PATH if that environment variable is set, otherwise in <tempdir>/fastembed_cache (e.g. /tmp/fastembed_cache on Linux).

Background warmup at server startup. Whenever SPECMGR_SIMILARITY_DISABLED is not set, the server starts a background daemon thread at startup that embeds the full document corpus into the in-memory cache — the gate is the opt-out flag only, regardless of whether the similarity extra is installed. With the extra missing, or with the model failing to load, the thread runs the availability probe inside itself and exits immediately without cache writes (still never raising). The thread is non-blocking — server startup never waits for it (the model load/download, if needed, happens inside the thread, not on the startup path) — and a mid-warmup failure is logged and swallowed, leaving the cache partially warm. Its purpose is to keep the first tool call fast: against a cold cache the tools embed the corpus on demand, which can cost minutes of CPU.

Opt-out. Set SPECMGR_SIMILARITY_DISABLED (any value; presence-based) to disable the feature without uninstalling the extra — e.g. to skip the model download entirely, on a host where the model was never downloaded, or to free the memory the model and cache use. Both tools stay registered either way.

Introspection. Read the specmgr://config resource for the feature's static configuration — its similarity section reports whether the similarity extra is installed, whether the opt-out flag is set, the model name, and the resolved cache directory (static facts only; reading the resource never loads the model or creates the cache directory) — and the specmgr://version resource for the installed fastembed version (null when the extra is not installed).

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

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

   To also enable the Semantic Similarity Search feature (find_related/ find_similar_text), change [mcp] to [mcp,similarity] in the --from value above — see that section for install/runtime-activation details.

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

   json

   "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"
     }
   }
   

   The same [mcp] -> [mcp,similarity] change in the --from value applies here too, to enable Semantic Similarity Search.

   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.

   Option C — run from a local source checkout (development). Options A and B both use uvx (uv tool run), which resolves biz-dfch-specmgr[...] as a named package from the configured index (PyPI by default) into an ephemeral tool environment — they always run the published release, never local/unreleased changes. To instead run the project at a specific directory on disk — using its own pyproject.toml, lockfile, and source tree directly, including unreleased/dev-branch commits — use uv run --directory <path-to-your-checkout> (no --from, not uvx):

   json

   "specmgr": {
     "type": "local",
     "enabled": true,
     "command": [
       "uv",
       "run",
       "--directory",
       "<path-to-your-checkout>",
       "--extra",
       "mcp",
       "--extra",
       "similarity",
       "specmgr",
       "mcp"
     ]
   }
   

   This is the mechanism for contributors/developers pointing OpenCode at their own git checkout instead of the published package. Repeatable --extra flags (or --all-extras for everything) control which optional dependencies get synced into that local run, independent of what's published on PyPI — drop --extra similarity if you don't need Semantic Similarity Search.

3. Save the file and restart OpenCode

Usage

Once connected, your AI assistant sees two kinds of tools per document domain: per-domain tools (create_<d>, get_<d>, list_<d>, parse_<d>, plus get_<d>_example/get_<d>_template), and generic dispatch tools that take a type= parameter and behave the same way across every domain: update (whole-body or line-range edits), set_status, set_classification, delete, and validate (ADR is the one exception, predating this pattern, with its own dedicated tools instead). See docs/MCP.md for the full list.

The server also ships prompts (e.g. create_req, update_req, implement_task) — guided, multi-turn interview flows that are the intended way to author documents conversationally, rather than calling tools one by one. Most MCP hosts surface these as slash commands or a prompt picker.

Day to day, you don't need to know any tool names at all — just ask your connected AI assistant in plain language, e.g.:

• "Create a new goal for reducing customer onboarding time."
• "List all open risks and show me the high-severity ones."
• "Draft a task list for requirement <id>."

To resolve the cross-references an artifact already carries, see Referencing Artifacts.

Referencing Artifacts

specmgr documents cross-reference each other via <TYPE> <uuid> lines (VCR's ## Verifies, SYSRS's per-section bullet lists, DEC's ## Related Artifacts). The list_references MCP tool resolves those references: point your assistant at any artifact (<type> <id>) and it lists every <TYPE> <uuid> cross-reference in the artifact's body, each resolved to the referenced document's type, id, title (its H1), and on-disk path. Results are paged like every list_* tool; references that do not resolve on disk come back as rows carrying an error (not a failure), and free-form or non-uuid references are ignored.

In opencode, the /refs <type> <id> slash command (.opencode/command/refs.md) wraps the same tool: it delegates to the read-only ref-finder subagent (.opencode/agent/ref-finder.md), which calls list_references and reports the rows, flagging any NOT FOUND references. /refs requires opencode — the tool itself is plain MCP, callable directly from any MCP client.

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

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

The normative release procedure is the SOP Perform a release of biz.dfch.SpecMgr (SOP 98537416). Where this section, the script, or the command ever disagree with the SOP, the SOP wins.

Using the OpenCode command (recommended)

/release [X.Y.Z | patch | minor | major] [--dry-run]

The command drives the staged script and performs the SOP's agent-judgment steps: it confirms the resolved version with you, curates the changelog's [Unreleased] section, pauses at the merge gate before dev is merged into main, and triages failures without ever auto-retrying.

Using the script directly

Each SOP step maps to a deterministic, idempotent stage (the SOP carries a manual fallback command for every step):

scripts/release.sh resolve minor         # print the target version (e.g. 0.15.0); no mutation
scripts/release.sh precheck 0.15.0       # fail-fast pre-release checks
scripts/release.sh bump 0.15.0           # pyproject.toml + uv.lock
scripts/release.sh changelog 0.15.0      # [Unreleased] -> dated section
scripts/release.sh commit-push 0.15.0    # 3-file release commit, push dev, wait for CI
scripts/release.sh pr-create 0.15.0      # dev->main release PR, wait for checks (no merge)
scripts/release.sh pr-merge 0.15.0       # ff-only merge (after maintainer go-ahead)
scripts/release.sh tag-push 0.15.0       # tag on main, push the tag, back to dev
scripts/release.sh publish-wait 0.15.0   # the four publish.yml jobs
scripts/release.sh release-notes 0.15.0  # verify the release + set the GH release notes
scripts/release.sh status 0.15.0         # where does this release stand?
scripts/release.sh all 0.15.0            # the whole chain, TTY only (interactive merge gate)

Changelog curation (SOP step 3) is an agent or manual step: the changelog stage only moves the already-curated [Unreleased] section into its dated form.

Manual fallback

Follow the SOP step by step — each step carries a Manual fallback paragraph. The essentials: bump the version in pyproject.toml and move the [Unreleased] section of CHANGELOG.md into a new dated ## [x.y.z] - YYYY-MM-DD section; uv lock; commit exactly pyproject.toml + uv.lock + CHANGELOG.md as chore(release): bump version to vX.Y.Z and push to dev; once CI is green, open the dev → main pull request and merge it fast-forward-only (git merge --ff-only dev — never a merge commit or squash: main must stay a strict ancestor of dev); then create git tag vX.Y.Z on main, push the tag, and wait for the publish workflow.

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