komainu-mcp 1.0.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 (e.g. on Railway) with /tools/* routes enabled.

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_TOOLS_API_KEY	If the API enforces auth	Same value as on the API server. Sent as Authorization: Bearer ….

Local development against a machine-run API:

export KOMAINU_API_BASE_URL=http://127.0.0.1:8000
export KOMAINU_TOOLS_API_KEY=...   # optional if tools routes are open

Cursor

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

{
  "mcpServers": {
    "komainu": {
      "command": "uvx",
      "args": ["komainu-mcp"],
      "env": {
        "KOMAINU_API_BASE_URL": "https://YOUR-RAILWAY-URL",
        "KOMAINU_TOOLS_API_KEY": "YOUR-API-KEY"
      }
    }
  }
}

Use ["komainu-mcp@1.0.0"] instead of ["komainu-mcp"] 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.

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 komainu-mcp==1.0.0 (no CLI flags). Upgrade: uv pip install -U 'komainu-mcp>=1.0.3' 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.