Metadata-Version: 2.4
Name: okovia-mcp
Version: 0.2.1
Summary: OkOvia MCP server — query your AI cost, margin, and reliability from any MCP client (Claude Desktop, Claude Code, …) in natural language.
Project-URL: Homepage, https://okovia.com
Project-URL: Repository, https://github.com/geomichelon/okovia-mcp
Project-URL: Changelog, https://github.com/geomichelon/okovia-mcp/blob/main/CHANGELOG.md
Author-email: OkOvia <hello@okovia.com>
License: MIT
Keywords: ai,cost,llm,mcp,model-context-protocol,observability,okovia
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: mcp<2,>=1.2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# okovia-mcp

OkOvia MCP server — ask any MCP client (Claude Desktop, Claude Code, …) about the **cost, margin, reliability, and quality** of your AI usage, in natural language.

It talks to the OkOvia API with your key and exposes the read dashboards as MCP tools. It runs on your machine; no data beyond the API calls leaves it, and it never sends prompts or content.

## What you can ask

- "How much did my AI features cost, highest first?"
- "Which model or provider is driving the cost?"
- "Show the most recent operations and their cost. Detail `op_7K9x`."
- "What's my reliability — which model has the most errors or timeouts?"
- "Compare the models I use."

## Requirements

- Python 3.10+ (run via [`uvx`](https://docs.astral.sh/uv/) or `pipx`)
- An OkOvia **secret** API key (`vik_sec_…`) from the console → Settings → Service accounts

## Configure your MCP client

Claude Desktop / Claude Code (`mcpServers` block):

```json
{
  "mcpServers": {
    "okovia": {
      "command": "uvx",
      "args": ["okovia-mcp"],
      "env": {
        "OKOVIA_API_KEY": "vik_sec_your_key",
        "OKOVIA_ENDPOINT": "https://api.okovia.com"
      }
    }
  }
}
```

`OKOVIA_ENDPOINT` defaults to `https://api.okovia.com` — set it only for self-hosted deployments.

## Tools

| Tool | What it returns |
|---|---|
| `check_connection` | API reachable + endpoint |
| `cost_by_feature` | cost (USD) + op count per feature |
| `cost_by_model` / `cost_by_provider` / `cost_by_channel` | cost grouped by that dimension |
| `list_operations` | recent operations with total cost (`limit`, default 20) |
| `get_operation` | full detail for one operation id |
| `reliability` | success/error/timeout rates, daily timeline, top error codes |
| `quality` | client-side eval scores (0..1): totals, timeline, per-evaluator/feature/model with cost per operation |
| `model_comparison` | models side by side (incl. avg eval score when available) |

Everything is scoped to the workspace/project the API key belongs to — the server passes no ids of its own.

## Security

Use a **read-only key** (`vik_read_...`, create one on the console's API Keys page): it can query dashboards and reports but can never submit events or manage anything — if it leaks, your data can be read but not touched. Secret keys still work for backwards compatibility, but carry admin scope; prefer rotating to a read key.

## Development

```bash
pip install -e ".[dev]"
pytest            # client tests — stdlib only, no MCP runtime or network needed
```

`client.py` is stdlib-only and independently tested; `server.py` wires those methods as MCP tools via the official `mcp` SDK.

MIT licensed. Part of [OkOvia](https://okovia.com).
