komainu-mcp 1.1.4

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.

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=/absolute/path/to/your/tests

Cursor

Paste into your MCP config (e.g. Cursor Settings → MCP):

{
  "mcpServers": {
    "komainu": {
      "command": "uvx",
      "args": ["komainu-mcp@1.1.0"],
      "env": {
        "KOMAINU_API_BASE_URL": "https://YOUR-RAILWAY-URL",
        "KOMAINU_ACCESS_TOKEN": "kmcp_…",
        "KOMAINU_TESTS_ROOT": "/absolute/path/to/tests"
      }
    }
  }
}

Use ["komainu-mcp@1.1.0"] to pin a release; omit @… to track the latest published version.

If uvx is not on PATH, use the full path to uv’s binary or install uv per Astral’s docs.

Claude Code / other clients

Same idea: command uvx, args ["komainu-mcp@<version>"] (or ["komainu-mcp"]), same env block.

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.0' 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.