Metadata-Version: 2.4
Name: komainu-mcp
Version: 1.0.0
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 (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:

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

```json
{
  "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](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

After install:

```bash
komainu-mcp
```

Equivalent:

```bash
python -m komainu_mcp
```

## 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.
