Metadata-Version: 2.4
Name: komainu-mcp
Version: 1.1.2
Summary: MCP stdio adapter for KomAInu: exposes tools via your hosted KomAInu API.
Author: KomAInu
License-Expression: MIT
Project-URL: Repository, https://github.com/your-org/KomAInu
Keywords: mcp,komainu,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0

# komainu-mcp

Thin **stdio MCP server** for [KomAInu](https://github.com/your-org/KomAInu): it speaks MCP to your editor and calls your **hosted KomAInu HTTP API** only. It does **not** connect to any database.

## Prerequisites

- [uv](https://docs.astral.sh/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 …`. |

Local development against a machine-run API:

```bash
export KOMAINU_API_BASE_URL=http://127.0.0.1:8000
export KOMAINU_ACCESS_TOKEN=kmcp_your_secret_from_web_or_curl
```

## Cursor

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

```json
{
  "mcpServers": {
    "komainu": {
      "command": "uvx",
      "args": ["komainu-mcp@1.1.0"],
      "env": {
        "KOMAINU_API_BASE_URL": "https://YOUR-RAILWAY-URL",
        "KOMAINU_ACCESS_TOKEN": "kmcp_…"
      }
    }
  }
}
```

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](https://docs.astral.sh/uv/getting-started/installation/).

## Claude Code / other clients

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

## CLI

```bash
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:

```bash
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](https://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):

   ```bash
   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):

   ```bash
   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.
