{
  "markdown": "# biz.dfch.SpecMgr\n\n<!-- mcp-name: io.github.dfch/biz-dfch-specmgr -->\n\n[![License: AGPL v3](https://img.shields.io/badge/License-AGPLv3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)\n![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue.svg)\n[![Lint and Test](https://github.com/dfch/biz.dfch.SpecMgr/actions/workflows/ci.yml/badge.svg)](https://github.com/dfch/biz.dfch.SpecMgr/actions/workflows/ci.yml)\n![Coverage](docs/coverage.svg)\n[![TestPyPI version](https://img.shields.io/badge/dynamic/json?url=https://test.pypi.org/pypi/biz-dfch-specmgr/json&label=TestPyPI&query=$.info.version&color=orange)](https://test.pypi.org/project/biz-dfch-specmgr/)\n[![PyPI version](https://img.shields.io/badge/dynamic/json?url=https://pypi.org/pypi/biz-dfch-specmgr/json&label=PyPI&query=$.info.version&color=blue)](https://pypi.org/project/biz-dfch-specmgr/)\n[![PyPI downloads](https://img.shields.io/pypi/dm/biz-dfch-specmgr.svg)](https://pypistats.org/packages/biz-dfch-specmgr)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.dfch%2Fbiz--dfch--specmgr-8A2BE2.svg)](https://registry.modelcontextprotocol.io/?q=io.github.dfch/biz-dfch-specmgr)\n\nAn artifact manager for system specifications.\n\nThis project is an **MCP server** that you can use to manage different\nspecification artifacts.\n\nAt this time, we have these artifact types:\n\n- Architecture Decision Record (ADR) (deprecated, will be phased out, use DEC instead)\n- Decision (DEC)\n- Feature (FEAT)\n- Goal (GOL)\n- Problem Statement (PRB)\n- Question and Answer (QA)\n- Requirement (REQ)\n- Risk (RSK)\n- Standard Operating Procedure (SOP)\n- System Requirements Specification (SYSRS)\n- Task List (TSK)\n- Use Case (UC)\n- Verification Case Record (VCR)\n\nSee [MCP Server](#mcp-server) and [docs/MCP.md](docs/MCP.md) for details.\n\nThe **MCP server** (and the management **CLI**) are optional. You install\nthem as \"extras\" (see [Installation](#installation)).\n\n## Table of Contents\n\n- [Installation](#installation)\n- [CLI Usage](#cli-usage)\n- [MCP Server](#mcp-server)\n- [Development](#development)\n- [Testing](#testing)\n- [Make a Release](#make-a-release)\n- [License](#license)\n\n## Installation\n\nAs a library only (no CLI, no MCP server):\n\n```bash\npip install biz-dfch-specmgr\n```\n\nWith the CLI:\n\n```bash\npip install \"biz-dfch-specmgr[cli]\"\n```\n\nWith the MCP server:\n\n```bash\npip install \"biz-dfch-specmgr[mcp]\"\n```\n\nOr with [uv](https://docs.astral.sh/uv/):\n\n```bash\nuv add \"biz-dfch-specmgr[cli,mcp]\"\n```\n\n## CLI Usage\n\nWith the CLI you can generate schema and documentation. We use these commands\nin pre-commit hooks and `ci.yml`.\n\n_No domain document-management commands (create/update/status/etc.) exist\nin the CLI yet — those are currently MCP-only, see\n[MCP Server](#mcp-server). The CLI covers `version`, `mcp` (below), and a\nhandful of cross-cutting/doc-generation commands (`specmgr --help` for the\nfull list)._\n\n```bash\nspecmgr version\n```\n\n## MCP Server\n\nRequires the `mcp` extra. The server exposes resources, tools, and prompts\nfor document management, plus cross-cutting utilities (e.g. markdown\nformatting).\n\n**The full, up-to-date list of every resource, resource template, tool, and\nprompt — with parameters, MIME types, and descriptions — lives in\n[docs/MCP.md](docs/MCP.md).** That document generated from the live server\nregistration by `specmgr mcp-docs` and kept in sync by a pre-commit hook and\na CI check.\n\n### Environment Variables\n\nEvery document type stores its `.md` files in a base directory on disk —\nthe file is always the source of truth, re-read and re-parsed on every\ntool call, so hand-editing a file between calls is safe.\n\n- ADRs: base directory defaults to `docs/adr`, configurable via the\n  `SPECMGR_ADR_DIR` environment variable. This is ADR-specific and not\n  shared with other document types.\n- Requirements (REQ) and future document types: share one root directory,\n  configurable via the `SPECMGR_DOCS_DIR` environment variable (default\n  `docs`), with each type's own subdirectory appended automatically (e.g.\n  `docs/req` for requirements).\n- Features (FEAT): base directory defaults to `.specmgr/feat`, configurable\n  via the `SPECMGR_FEAT_DIR` environment variable. This is FEAT-specific,\n  like ADRs above, and not shared via `SPECMGR_DOCS_DIR`.\n- The `confluence_fetch` tool (renamed from `webfetch`; bearer-authenticated,\n  URL-filtered HTTP GET, intended primarily for Confluence instances using\n  PAT authentication) requires two environment variables:\n  `SPECMGR_CONFLUENCE_BASE_URL` (the base URL requested URLs must\n  case-insensitively start with) and `SPECMGR_CONFLUENCE_BEARER` (the\n  bearer token sent as the `Authorization` header). Both must be set or the\n  tool raises an error; there are no defaults.\n\nAll of the base directories above are resolved relative to the MCP server\nprocess's own current working directory unless overridden by their env var\n(or, for the shared `SPECMGR_DOCS_DIR` root, unless the server was started\nwith `--directory`/`uv run --directory` targeting your project). If that\nCWD is not what you expect — e.g. after adding `specmgr` to an MCP host\nper [Add to OpenCode](#add-to-opencode) below — read the `specmgr://config`\nresource to see every domain's actually-resolved absolute base directory\nand whether its env var is explicitly set, without needing shell access to\nthe server's host.\n\n### Start the MCP Server\n\nStart the server with the `mcp` command:\n\n```bash\nspecmgr mcp\n```\n\nBy default it runs over `stdio`, for MCP hosts that launch it as a\nsubprocess (see [Add to OpenCode](#add-to-opencode) below). It can also\nrun over SSE/network:\n\n```bash\nspecmgr mcp --transport sse --host localhost --port 8000\n```\n\nOr over the spec-current `streamable-http` transport, which replaces the\nlegacy/deprecated `sse` transport for HTTP deployments:\n\n```bash\nspecmgr mcp --transport streamable-http --host localhost --port 8000\n```\n\n| Option | Env var | Default | Description |\n| -------------------- | ------------------------ | ----------- | -------------------------------- |\n| `--transport` / `-t` | `SPECMGR_MCP_TRANSPORT` | `stdio` | Transport mode: `stdio`, `sse`, or `streamable-http` |\n| `--host` / `-h` | `SPECMGR_MCP_HOST` | `localhost` | Bind address (SSE/streamable-http mode only) |\n| `--port` / `-p` | `SPECMGR_MCP_PORT` | `8000` | TCP port (SSE/streamable-http mode only) |\n\n### Add to OpenCode\n\nTo add the `specmgr` MCP server to your OpenCode configuration:\n\n1. Open your OpenCode config file (typically `~/.config/opencode/opencode.json` or `~/.config/opencode/opencode.jsonc`)\n\n2. Add a configuration to the `mcp` section (and use it via `stdio`).\n\n   **A bare `uvx --from biz-dfch-specmgr[mcp] specmgr mcp` command with no\n   `--directory` and no `SPECMGR_*_DIR` env vars is unsafe**: the server\n   resolves every base directory (`docs`, `docs/adr`, `.specmgr/feat`, ...)\n   relative to its own process's current working directory, which an MCP\n   host is free to launch from anywhere — not necessarily your project\n   root. Pick one of the two options below instead of the plain form:\n\n   **Option A — pin the working directory with `--directory`** (a global\n   `uv`/`uvx` flag, so it must come *before* `--from`):\n\n   ```json\n   \"specmgr\": {\n     \"type\": \"local\",\n     \"enabled\": true,\n     \"command\": [\n       \"uvx\",\n       \"--directory\",\n       \"<path-to-your-project>\",\n       \"--from\",\n       \"biz-dfch-specmgr[mcp]\",\n       \"specmgr\",\n       \"mcp\"\n     ]\n   }\n   ```\n\n   **Option B — set the directory env vars explicitly** instead of (or in\n   addition to) `--directory`:\n\n   ```json\n   \"specmgr\": {\n     \"type\": \"local\",\n     \"enabled\": true,\n     \"command\": [\n       \"uvx\",\n       \"--from\",\n       \"biz-dfch-specmgr[mcp]\",\n       \"specmgr\",\n       \"mcp\"\n     ],\n     \"environment\": {\n       \"SPECMGR_DOCS_DIR\": \"<path-to-your-project>/docs\",\n       \"SPECMGR_ADR_DIR\": \"<path-to-your-project>/docs/adr\",\n       \"SPECMGR_FEAT_DIR\": \"<path-to-your-project>/.specmgr/feat\"\n     }\n   }\n   ```\n\n   Either option (or both together) makes the resolved base directories\n   independent of wherever the MCP host happens to launch the server\n   from. Whichever you choose, you can confirm it worked by reading the\n   `specmgr://config` resource, which reports the actually-resolved\n   absolute base directory for every domain and whether its env var is\n   explicitly set.\n\n3. Save the file and restart OpenCode\n\n## Development\n\n### Install dev dependencies\n\n```bash\nuv sync --all-extras\n```\n\n### Install pre-commit hooks (one-time)\n\n```bash\nuv run --frozen pre-commit install\n```\n\n`uv sync` only installs Python dependencies into the venv — it never\nregisters the hooks from `.pre-commit-config.yaml` with git, so run\nthis once per clone before your first commit.\n\n### Run linters\n\n```bash\nuv run --frozen ruff format --check\nuv run --frozen ruff check\nuv run --frozen pylint $(git ls-files '*.py')\n```\n\n### Run tests\n\n```bash\nuv run --frozen pytest -n auto --cov=src --cov-report=\n```\n\n## Testing\n\nYou can exercise the MCP server directly with the\n[MCP Inspector](https://modelcontextprotocol.io/docs/latest/tools/inspector),\nin either its CLI (scriptable) or TUI (interactive terminal) client.\n\n### Prerequisites\n\n- The `mcp` extra installed (see [Installation](#installation)), so\n  `.venv/bin/specmgr` exists.\n- [`npx`](https://docs.npmjs.com/cli/v10/commands/npx) (ships with Node.js,\n  version 22.19.0 or newer) — no separate Inspector install is required, it\n  runs on demand via `npx @modelcontextprotocol/inspector`.\n\nPoint the Inspector at the venv's `specmgr` binary directly (rather than at\n`uv run specmgr mcp`) so none of `uv run`'s own flags (e.g. `--frozen`) are\nmistaken for Inspector flags:\n\n```bash\nnpx @modelcontextprotocol/inspector --tui .venv/bin/specmgr mcp\nnpx @modelcontextprotocol/inspector --cli .venv/bin/specmgr mcp --method tools/list\n```\n\n### CLI examples\n\nEach CLI invocation connects, runs one request, prints the result, and\nexits — useful for scripting or a quick smoke test.\n\nGet the `specmgr://version` resource:\n\n```bash\nnpx @modelcontextprotocol/inspector --cli .venv/bin/specmgr mcp \\\n  --method resources/read --uri specmgr://version\n```\n\nList task lists via the `list_tsk` tool:\n\n```bash\nnpx @modelcontextprotocol/inspector --cli .venv/bin/specmgr mcp \\\n  --method tools/call --tool-name list_tsk\n```\n\nGet one task list via the `get_tsk` tool (replace `<id>` with a real task\nlist id from the `list_tsk` output above):\n\n```bash\nnpx @modelcontextprotocol/inspector --cli .venv/bin/specmgr mcp \\\n  --method tools/call --tool-name get_tsk --tool-arg id=<id>\n```\n\nAdd `--format json` to any of the above to get machine-readable output,\ne.g. piped into `jq`.\n\n### Connecting with the TUI\n\n```bash\nnpx @modelcontextprotocol/inspector --tui .venv/bin/specmgr mcp\n```\n\nThis launches the server as an ad-hoc stdio target and opens the terminal\nUI with it preselected (unlike the CLI, the TUI has no `--server <name>`\nflag — it lists whichever servers are available and you pick one, though\nwith a single ad-hoc target there is nothing else to pick). **Press `c` to\nconnect**, then use the tabs to explore:\n\n- `t` — **Tools** tab: browse and call tools (e.g. `get_tsk`) with a\n  form-based input.\n- `r` — **Resources** tab: browse and read resources (e.g.\n  `specmgr://version`, `specmgr://iso25010`).\n- `m` — **Prompts** tab: list and render prompts.\n- `p` — **Protocol** tab: raw JSON-RPC request/response history, useful\n  for debugging.\n- `o` — **Console** tab: `stderr` from the connected `specmgr mcp`\n  process (tracebacks land here).\n- `c` / `d` — connect / disconnect; `Esc` or `Ctrl+C` — exit.\n\nThe TUI requires a real TTY (raw-mode support) and does not run in a\nheadless CI job — use the CLI client there instead.\n\n## Make a Release\n\nThe normative release procedure is the SOP\n[Perform a release of biz.dfch.SpecMgr](docs/sop/sop-98537416-0e6e-4a02-925f-974a17bfa10a-perform-a-release-of-biz-dfch-specmgr.md)\n(SOP `98537416`). Where this section, the script, or the command ever\ndisagree with the SOP, the SOP wins.\n\n### Using the OpenCode command (recommended)\n\n```\n/release [X.Y.Z | patch | minor | major] [--dry-run]\n```\n\nThe command drives the staged script and performs the SOP's agent-judgment\nsteps: it confirms the resolved version with you, curates the changelog's\n`[Unreleased]` section, pauses at the merge gate before `dev` is merged\ninto `main`, and triages failures without ever auto-retrying.\n\n### Using the script directly\n\nEach SOP step maps to a deterministic, idempotent stage (the SOP carries\na manual fallback command for every step):\n\n```bash\nscripts/release.sh resolve minor         # print the target version (e.g. 0.15.0); no mutation\nscripts/release.sh precheck 0.15.0       # fail-fast pre-release checks\nscripts/release.sh bump 0.15.0           # pyproject.toml + uv.lock\nscripts/release.sh changelog 0.15.0      # [Unreleased] -> dated section\nscripts/release.sh commit-push 0.15.0    # 3-file release commit, push dev, wait for CI\nscripts/release.sh pr-create 0.15.0      # dev->main release PR, wait for checks (no merge)\nscripts/release.sh pr-merge 0.15.0       # ff-only merge (after maintainer go-ahead)\nscripts/release.sh tag-push 0.15.0       # tag on main, push the tag, back to dev\nscripts/release.sh publish-wait 0.15.0   # the four publish.yml jobs\nscripts/release.sh release-notes 0.15.0  # verify the release + set the GH release notes\nscripts/release.sh status 0.15.0         # where does this release stand?\nscripts/release.sh all 0.15.0            # the whole chain, TTY only (interactive merge gate)\n```\n\nChangelog *curation* (SOP step 3) is an agent or manual step: the\n`changelog` stage only moves the already-curated `[Unreleased]` section\ninto its dated form.\n\n### Manual fallback\n\nFollow the SOP step by step — each step carries a *Manual fallback*\nparagraph. The essentials: bump the `version` in `pyproject.toml` and\nmove the `[Unreleased]` section of `CHANGELOG.md` into a new dated\n`## [x.y.z] - YYYY-MM-DD` section; `uv lock`; commit exactly\n`pyproject.toml` + `uv.lock` + `CHANGELOG.md` as\n`chore(release): bump version to vX.Y.Z` and push to `dev`; once CI is\ngreen, open the `dev` → `main` pull request and merge it\n**fast-forward-only** (`git merge --ff-only dev` — never a merge commit or\nsquash: `main` must stay a strict ancestor of `dev`); then create\n`git tag vX.Y.Z` on `main`, push the tag, and wait for the publish\nworkflow.\n\n_Note: `.github/workflows/publish.yml` handles the rest of the release\nautomatically once the tag above is pushed — it builds and publishes the\n`sdist`/wheel to TestPyPI then PyPI via Trusted Publishing (OIDC, no\nstored token), creates the matching GitHub Release with the built\nartifacts attached, and publishes `server.json` (repo root, the MCP\nRegistry publisher manifest — see the\n[server.json format spec](https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/server-json/generic-server-json.md))\nto the [MCP Registry](https://registry.modelcontextprotocol.io/?q=io.github.dfch%2Fbiz-dfch-specmgr)\nvia `mcp-publisher`/GitHub OIDC. `biz-dfch-specmgr` is live on\n[PyPI](https://pypi.org/project/biz-dfch-specmgr/) and in the\n[MCP Registry](https://registry.modelcontextprotocol.io/?q=io.github.dfch%2Fbiz-dfch-specmgr)\nas of `v0.1.0`._\n\n## License\n\n[AGPL-3.0-or-later](LICENSE)\n",
  "bytes": 15334,
  "sha": "a2d062b78752ecc436a412c588593f4fc0ffb0f84a6b3833dd65579a9b0d8d3a",
  "repo_slug": "dfch/biz.dfch.specmgr",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dfch_biz_dfch_specmgr_c1f9ea41/readme"
}