komainu-mcp 1.1.17

MCP stdio adapter for KomAInu: exposes tools via your hosted KomAInu API.

komainu-mcp

Thin stdio MCP server for KomAInu: it speaks MCP to your editor and calls your hosted KomAInu HTTP API only. It does not connect to any database.

Prerequisites

• uv installed (recommended), or another Python 3.11+ environment.
• A running KomAInu API with /tools/* routes and (after migration) the mcp_access_token table.

Authentication

GET /tools/* requires Authorization: Bearer <token> where <token> is either:

1. KomAInu MCP token — prefix kmcp_…, created from the web app (MCP page → Add to Cursor, or POST /mcp/tokens / POST /mcp/tokens/cursor-install with your normal Supabase session JWT). Only a hash is stored server-side; you cannot impersonate another user by editing a UUID in config.
2. Supabase access JWT — same token the web app uses for API calls (short-lived; refresh as your session renews).

Environment variables

Variable	Required	Description
KOMAINU_API_BASE_URL	Yes	Base URL of the KomAInu API, e.g. https://your-service.up.railway.app (no trailing slash).
KOMAINU_ACCESS_TOKEN	Yes	MCP token (kmcp_…) or Supabase access JWT, sent as Authorization: Bearer ….
KOMAINU_TESTS_ROOT	For pipeline tools	Local root directory containing test files. Pipeline tools upload this entire folder to KomAInu before traceability/coverage jobs. The web app may show <YOUR-TEST-FOLDER-LOCAL-PATH> until you set a real path.

Local development against a machine-run API:

export KOMAINU_API_BASE_URL=http://127.0.0.1:8000
export KOMAINU_ACCESS_TOKEN=kmcp_your_secret_from_web_or_curl
export KOMAINU_TESTS_ROOT='<YOUR-TEST-FOLDER-LOCAL-PATH>'

Cursor

Cursor Settings → MCP (or your MCP JSON). Example:

{
  "mcpServers": {
    "komainu": {
      "command": "uvx",
      "args": ["komainu-mcp@1.1.17"],
      "env": {
        "KOMAINU_API_BASE_URL": "https://YOUR-RAILWAY-URL",
        "KOMAINU_ACCESS_TOKEN": "kmcp_…",
        "KOMAINU_TESTS_ROOT": "<YOUR-TEST-FOLDER-LOCAL-PATH>"
      }
    }
  }
}

Pin with @version or use ["komainu-mcp"] for latest. The KomAInu web MCP page uses the same pin as KOMAINU_MCP_UVX_PACKAGE_ARG in web/src/lib/cursorMcpDeeplink.ts (currently komainu-mcp@1.1.17). If uvx is missing, install uv.

Claude Code

Claude Code MCP: prefer claude mcp add over hand-editing config.

From the KomAInu repo:

export KOMAINU_API_BASE_URL=https://YOUR-RAILWAY-URL
export KOMAINU_ACCESS_TOKEN=kmcp_…
export KOMAINU_TESTS_ROOT='<YOUR-TEST-FOLDER-LOCAL-PATH>'
bash scripts/add-komainu-mcp-claude.sh

Override the PyPI pin if needed: export KOMAINU_MCP_SPEC=komainu-mcp@… (default matches KOMAINU_MCP_UVX_PACKAGE_ARG in web/src/lib/cursorMcpDeeplink.ts).

All projects: CLAUDE_MCP_SCOPE=user bash scripts/add-komainu-mcp-claude.sh. Direct equivalent (same shape as Generate manual config on the web MCP page):

claude mcp add komainu --transport stdio \
  -e KOMAINU_API_BASE_URL='https://YOUR-RAILWAY-URL' \
  -e KOMAINU_ACCESS_TOKEN='kmcp_…' \
  -e KOMAINU_TESTS_ROOT='<YOUR-TEST-FOLDER-LOCAL-PATH>' \
  -- uvx komainu-mcp@1.1.17

For user scope (all projects): add --scope user on the line after --transport stdio.

claude mcp list / claude mcp remove komainu to verify or replace.

Manual

• Other MCP clients: same as Cursor — uvx, komainu-mcp@… (or komainu-mcp), same env.
• uvx cache: not the project venv; refresh with uv cache clean komainu-mcp. See CLI below for uv tool / uv pip differences.

Workflows (skills and prompts)

KomAInu exposes orchestration guides as MCP resources (and one prompt for Claude Code). The agent reads the skill, runs git locally, and calls KomAInu tools for requirement data and pipeline actions.

Entry	URI / name	Purpose
Resource	komainu://skill/requirement-coverage-from-changes	After code changes: scope git diff, pick affected requirements, approve pipeline work, write/fix tests from correction briefs
Resource	komainu://skill/honest-test-authoring	Write case-focused tests, run locally, triage red outcomes (product bug vs bad test)
Prompt	cover_changes (optional base_ref)	Same as the coverage-from-changes skill; slash command in Claude Code

Typical user request: “I changed a lot of code — help me cover the spec.” The agent should load komainu://skill/requirement-coverage-from-changes, ask which commit/branch to diff against, call list_all_requirements, propose affected requirement IDs, get approval before run_requirement_analysis / rerun_requirement_coverage, then use get_requirement_coverage_for_correction and honest-test-authoring while editing tests under KOMAINU_TESTS_ROOT.

Tools

Read-only: list_all_requirements, get_requirement_coverage, get_requirement_coverage_for_correction, get_coverage_summary.

Pipeline (require explicit user approval; each uploads KOMAINU_TESTS_ROOT first): run_requirement_analysis, run_requirement_mapping, rerun_requirement_coverage.

Local test folder sync

There are no separate sync_push_* MCP tools. Uploading the local test tree happens inside the pipeline tools above via POST /workspace/tests/sync (same behaviour as uploading the test folder on the KomAInu setup page). Configure KOMAINU_TESTS_ROOT to your local tests root.

CLI

komainu-mcp --help
komainu-mcp --version

Running komainu-mcp without arguments starts the stdio MCP server: it waits on stdin for your editor’s MCP client. In a bare terminal it looks “stuck” with no output — that is normal. Use --help to print usage without blocking.

If --help also appears to hang, you likely have an old komainu-mcp (no CLI flags). Upgrade: uv pip install -U 'komainu-mcp>=1.1.10' then try again.

Equivalent:

python -m komainu_mcp

uvx and uninstall: uvx does not install into your project venv; it uses uv’s cache. There is no uvx uninstall. To clear downloads for this package: uv cache clean komainu-mcp. Use uv tool uninstall komainu-mcp only if you installed via uv tool install.

Publishing a new version (maintainers, manual)

PyPI project name: komainu-mcp. One-time setup: create that project on pypi.org and generate an API token scoped to it (Account settings → API tokens).

For each release:

1. Bump the version in komainu-mcp/pyproject.toml ([project].version). PyPI does not allow re-uploading the same version number.

2. Build from the repository root (mono-repo):

   uv build --package komainu-mcp --out-dir komainu-mcp/dist --clear
   

   This writes the sdist and wheel under komainu-mcp/dist/.

3. Upload to PyPI with your token (do not commit the token):

   UV_PUBLISH_TOKEN=pypi-xxxxxxxx uv publish komainu-mcp/dist/*
   

   Alternatively: uv publish -t pypi-xxxxxxxx komainu-mcp/dist/*.

4. Verify on https://pypi.org/project/komainu-mcp/ and, if needed, test with uvx komainu-mcp@<new-version>.

If the upload fails because the version already exists, bump version again and repeat from step 2.