Metadata-Version: 2.4
Name: komainu-mcp
Version: 1.1.26
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 …`. |
| `KOMAINU_TESTS_ROOT` | **For pipeline tools** | Local root directory containing test files. Pipeline tools upload this entire folder to KomAInu before traceability/coverage jobs. The web app may show **`<YOUR-TEST-FOLDER-LOCAL-PATH>`** until you set a real path. |

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
export KOMAINU_TESTS_ROOT='<YOUR-TEST-FOLDER-LOCAL-PATH>'
```

## Cursor

Cursor **Settings → MCP** (or your MCP JSON). Example:

```json
{
  "mcpServers": {
    "komainu": {
      "command": "uvx",
      "args": ["komainu-mcp@1.1.20"],
      "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.20`**). If `uvx` is missing, install [uv](https://docs.astral.sh/uv/getting-started/installation/).

## Claude Code

[Claude Code MCP](https://docs.claude.com/en/docs/claude-code/mcp): prefer `claude mcp add` over hand-editing config.

From the KomAInu repo:

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

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

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 skills (MCP resources)

`komainu-mcp` ships orchestration guides as MCP resources — no extra download. Full documentation:

- **[Skills overview](./docs/README.md)** — when to use which skill
- **[Cover changes workflow](./docs/cover-changes-workflow.md)** — git diff → requirements → tests
- **[Write tests skill](./docs/write-tests-skill.md)** — honest test authoring for one case
- **[Skills comparison](./docs/skills-comparison.md)** — side-by-side differences

| Entry | URI / name | Purpose |
|-------|------------|---------|
| Resource | `komainu://skill/requirement-coverage-from-changes` | After code changes: scope git diff, pick affected requirements, approve pipeline work, write/fix tests from correction briefs |
| Resource | `komainu://skill/write-tests` | Write case-focused tests, run locally, triage red outcomes (product bug vs bad test) |
| Prompt | `cover_changes` (optional `base_ref`) | Same as the coverage-from-changes skill; slash command in Claude Code |

**Typical user request:** “I changed a lot of code — help me cover the spec.” See [cover-changes workflow](./docs/cover-changes-workflow.md).

## Tools

Read-only: `list_all_requirements`, `get_requirement_coverage`, `get_requirement_coverage_for_correction`, `get_coverage_summary`.

Generation-only: `generate_requirement_test_cases` generates a fresh structured
test design for one requirement from the active SRS. It does not upload local
tests or run traceability/coverage.

Pipeline (require explicit user approval; each uploads `KOMAINU_TESTS_ROOT` first): `run_requirement_analysis`, `run_requirement_mapping`, `rerun_requirement_coverage`, `start_requirement_coverage_rerun` (background variant of rerun — returns a `job_id` immediately, track progress in the web app).

## Local test folder sync

There are no separate `sync_push_*` MCP tools. Uploading the local test tree happens **inside** the pipeline tools above via `POST /workspace/tests/sync` (same behaviour as uploading the test folder on the KomAInu setup page). Configure **`KOMAINU_TESTS_ROOT`** to your local tests root.

## 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.10'` 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.
