# kobra-api-mcp

**MCP server** para que cualquier IA (Grok, Cursor, Claude Desktop, etc.) use la **API Kobra de verdad**:

1. Lee el **OpenAPI live** (no un PDF viejo)
2. Sabe **cómo autenticarse** (partner key, bearer, session)
3. **Ejecuta** requests HTTP y devuelve status + body

Default: **`https://stage.api.trykobra.com`**. Prod solo con `KOBRA_ALLOW_PROD=1`.

## Install

```bash
cd kobra-api-mcp
uv sync
# o: pip install -e .
```

## Run (stdio MCP)

```bash
export KOBRA_ENV=stage
export KOBRA_PARTNER_KEY='kbr_…'   # para /api/partner/v1/*
uv run python -m kobra_api_mcp
```

## Config para Grok / Cursor / Claude

Ver `config/grok-mcp.example.json` y `config/cursor-mcp.example.json`.

Ejemplo Cursor (`~/.cursor/mcp.json` o settings MCP):

```json
{
  "mcpServers": {
    "kobra-api": {
      "command": "uv",
      "args": ["run", "--directory", "/ABS/PATH/kobra-api-mcp", "python", "-m", "kobra_api_mcp"],
      "env": {
        "KOBRA_ENV": "stage",
        "KOBRA_ALLOW_PROD": "0",
        "KOBRA_PARTNER_KEY": "kbr_…"
      }
    }
  }
}
```

**Grok (sesiones con MCP):** mismo bloque `mcpServers` en la config de MCP del host que use Grok Build / TUI. La key **nunca** va en el chat: solo en `env` del server.

## Auth (lo que la IA debe saber)

| Perfil | Env | Header | Rutas |
|--------|-----|--------|--------|
| `none` | — | — | `/health`, `/docs`, `/openapi.json`, `/sdk`, `/api/catalog*`, `/partner/docs` |
| `partner` | `KOBRA_PARTNER_KEY` | `X-Kobra-Partner-Key` (o `Authorization: Partner <key>`) | `/api/partner/v1/*` |
| `bearer` | `KOBRA_BEARER_TOKEN` | `Authorization: Bearer …` | si aplica |
| `session` | `KOBRA_SESSION_COOKIE` | `Cookie: …` | team/portal |
| `auto` | (elige) | según path | **default en `call_route`** |

Tools:

- `auth_profiles` — qué está configurado
- `call_route(..., auth_profile="auto"|"partner"|…)` — prueba real

## Tools

| Tool | Uso |
|------|-----|
| `api_info` | base URL, auth flags, links a docs humanas |
| `auth_profiles` | cómo autenticar cada perfil |
| `refresh_openapi` | re-baja OpenAPI full + partner |
| `list_routes` | filtrar method/tag/q |
| `get_route` | detalle + schema + auth_hint |
| `call_route` | **HTTP real** |
| `smoke_public` | health + docs sin auth |
| `smoke_partner` | `/me` + `/summary` con key |
| `suggest_probe_plan` | plan de pruebas ordenado |
| `docs_urls` | atajos Scalar/SDK |

## Flujo recomendado para la IA

```
1. api_info()
2. auth_profiles()
3. refresh_openapi()
4. list_routes(q="partner") o suggest_probe_plan(focus="partner")
5. get_route("GET", "/api/partner/v1/me")
6. call_route("GET", "/api/partner/v1/me", auth_profile="partner")
7. call_route writes solo en stage, con body del schema
```

## Docs humanas (mismo backend)

| URL | Qué |
|-----|-----|
| `{base}/docs` | Scalar API completa |
| `{base}/partner/docs` | Scalar Partner |
| `{base}/sdk` | SDK Python |
| `{base}/openapi.json` | Schema full |
| `{base}/api/partner/v1/openapi.json` | Schema partner |

Defaults:

- stage: `https://stage.api.trykobra.com`
- prod: `https://api.trykobra.com` (+ `KOBRA_ALLOW_PROD=1`)

## Tests

```bash
uv run pytest -q
KOBRA_MCP_LIVE=1 uv run pytest -q tests/test_client_live_optional.py
```

## Seguridad

- Secretos solo en env del proceso MCP
- Headers sensibles se devuelven **redactados** al modelo
- Prod bloqueado por default
- No hay tool para “guardar” keys desde el chat

## Licencia

MIT