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 Firebase ID token). Only a hash is stored server-side; you cannot impersonate another user by editing a UUID in config.
2. Firebase ID token — same token the web app uses for API calls (short-lived; refresh as your session renews).

Environment variables

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"],
      "env": {
        "KOMAINU_API_BASE_URL": "https://YOUR-API-URL",
        "KOMAINU_ACCESS_TOKEN": "kmcp_…",
        "KOMAINU_TESTS_ROOT": "<YOUR-TEST-FOLDER-LOCAL-PATH>"
      }
    }
  }
}

This runs the latest PyPI release, like the KomAInu web MCP page. Pin with komainu-mcp@<version> if you need a fixed one. 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-API-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: latest release).

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-API-URL' \
  -e KOMAINU_ACCESS_TOKEN='kmcp_…' \
  -e KOMAINU_TESTS_ROOT='<YOUR-TEST-FOLDER-LOCAL-PATH>' \
  -- uvx komainu-mcp

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.

Bundled skills (MCP resources)

komainu-mcp ships orchestration guides as MCP resources — no extra download. Full documentation:

• Skills overview — when to use which skill
• Cover changes workflow — git diff → requirements → tests
• Write tests skill — honest test authoring for one case
• Skills comparison — side-by-side differences

Typical user request: “I changed a lot of code — help me cover the spec.” See cover-changes workflow.

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, start_requirement_coverage_rerun (background variant of rerun — returns a job_id immediately, track progress in the web app).

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.