komainu-mcp 1.1.18

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 sync tools	Local root directory containing test files. Sync tool paths can be absolute or relative to this folder. 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.10"],
      "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.10). 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.10

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 skill (MCP resource)

komainu-mcp ships a test-authoring skill embedded in the package — no extra download. It is exposed as an MCP resource:

• URI: komainu://skill/write-tests
• MIME: text/markdown

MCP clients can list and read it like any resource. It guides the model to turn a KomAInu test case into a real, non-false-positive test, run it, and honestly report OK / NOK (a documented red is a valid outcome). The content is framework- and project-agnostic.

Local test sync tools

komainu-mcp includes built-in sync tools:

• sync_push_file(path)
• sync_push_files(paths)
• sync_delete_file(path)

No separate komainu-sync installation is required for end users.
These tools read local files directly from the machine running MCP and call POST /workspace/tests/sync on the backend.

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.