Metadata-Version: 2.5
Name: kervo-mcp
Version: 0.1.0
Summary: MCP server for the Kervo public API (stdio).
Project-URL: Homepage, https://kervo.app
Keywords: kervo,mcp,model-context-protocol,project-management
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.28
Requires-Dist: jsonschema>=4
Requires-Dist: mcp<3,>=2.2
Description-Content-Type: text/markdown

# kervo-mcp

MCP server for the [Kervo](https://kervo.app) public API. It runs locally over stdio, so any MCP
client (Claude Desktop, Cursor, VS Code…) can read and change your Kervo organization with the
permissions of a **service account API key**.

At startup it downloads the OpenAPI schema from your Kervo instance and creates one tool per
operation, so new API endpoints show up without upgrading this package. Only the tools allowed by
the key's scopes are listed.

## Requirements

- [uv](https://docs.astral.sh/uv/) (for `uvx`) or Python 3.10+.
- A Kervo organization whose plan includes the public API.
- A service account API key (`kvo_…`), created in **Organization › Integrations**.

## Configuration

| Variable | Required | Default | Description |
|---|---|---|---|
| `KERVO_API_KEY` | yes | — | Service account key (`kvo_<prefix>_<secret>`). |
| `KERVO_API_URL` | no | `https://api.kervo.app/public/v1` | Public API base URL (self-hosted instances). Must be `https://` (plain `http://` only for `localhost`). |
| `KERVO_MCP_LOG` | no | `info` | `info` or `debug`. Logs go to stderr only (stdout is the MCP channel). |

Replace `<paste your kvo_ key here>` with your key in the examples below.

### Claude Desktop

Settings › Developer › Edit Config opens `claude_desktop_config.json`
(`~/Library/Application Support/Claude/` on macOS, `%APPDATA%\Claude\` on Windows). Restart Claude
Desktop after saving.

```json
{
  "mcpServers": {
    "kervo": {
      "command": "uvx",
      "args": ["kervo-mcp"],
      "env": {
        "KERVO_API_URL": "https://api.kervo.app/public/v1",
        "KERVO_API_KEY": "<paste your kvo_ key here>"
      }
    }
  }
}
```

The same `mcpServers` block works in:

- **Antigravity** — `~/.gemini/config/mcp_config.json` (agent panel › MCP Servers › View raw config) or
  `.agents/mcp_config.json` in the workspace.
- **Gemini CLI** — `~/.gemini/settings.json` or `.gemini/settings.json` in the project.
- **Windsurf / Devin Desktop** — `~/.config/devin/mcp_config.json` (`%APPDATA%\devin\` on Windows).
- **Cursor** — `~/.cursor/mcp.json` or `.cursor/mcp.json` in the project; add `"type": "stdio"` to the
  `kervo` entry.

### Claude Code

```sh
claude mcp add --env "KERVO_API_URL=https://api.kervo.app/public/v1" --env "KERVO_API_KEY=<paste your kvo_ key here>" --transport stdio --scope user kervo -- uvx kervo-mcp
```

### VS Code

`.vscode/mcp.json`. VS Code asks for the key when the server starts and stores it encrypted, so it
never goes into the file:

```json
{
  "inputs": [
    { "type": "promptString", "id": "kervo-api-key", "description": "Kervo API key (kvo_…)", "password": true }
  ],
  "servers": {
    "kervo": {
      "type": "stdio",
      "command": "uvx",
      "args": ["kervo-mcp"],
      "env": {
        "KERVO_API_URL": "https://api.kervo.app/public/v1",
        "KERVO_API_KEY": "${input:kervo-api-key}"
      }
    }
  }
}
```

### Codex

`~/.codex/config.toml` (or `codex mcp add kervo --env KERVO_API_KEY=… -- uvx kervo-mcp`):

```toml
[mcp_servers.kervo]
command = "uvx"
args = ["kervo-mcp"]

[mcp_servers.kervo.env]
KERVO_API_URL = "https://api.kervo.app/public/v1"
KERVO_API_KEY = "<paste your kvo_ key here>"
```

### Zed

Run `zed: open settings file` and add under `context_servers`:

```json
{
  "context_servers": {
    "kervo": {
      "command": "uvx",
      "args": ["kervo-mcp"],
      "env": {
        "KERVO_API_URL": "https://api.kervo.app/public/v1",
        "KERVO_API_KEY": "<paste your kvo_ key here>"
      }
    }
  }
}
```

### Troubleshooting

If the client cannot start `uvx` (`spawn uvx ENOENT`, common in desktop apps on macOS), use the full
path printed by `which uvx` as `command`.

## Security

- The agent acts as the service account and only sees what it sees. Use a **dedicated key** with
  the **smallest scopes** that do the job (read-only when possible) and an expiration date.
- The key lives in your MCP client's config file; keep that file private and never commit it.
- This package never writes the key to disk or logs, and never logs tool arguments.
- Task contents are data written by people: the server tells the model never to follow
  instructions found in them, but review destructive actions your agent proposes.

## Exit codes

- `2` — invalid configuration (missing or malformed key, bad URL).
- `1` — startup failed (schema unreachable, invalid or revoked key, plan without the public API).

## Development

The code lives in `backend/kervo_mcp/` of the Kervo repository (shared with the remote connector).
Build the wheel with `python -m build --wheel packaging/kervo-mcp` from `backend/`; only the wheel is
published (the build pulls the modules from `../../kervo_mcp`). Releases are tagged
`kervo-mcp-v<version>`, matching `kervo_mcp.__version__`.
