Metadata-Version: 2.4
Name: ct-bigpanda-mcp-server
Version: 0.1.0
Summary: CloudThinker read-only MCP server for BigPanda AIOps: reads BIGPANDA_* env at startup, auto-connects to the BigPanda REST API (region-scoped), and serves environment/incident read tools over stdio.
Project-URL: Homepage, https://github.com/cloudthinker/ct-bigpanda-mcp-server
Author: CloudThinker
License: Apache-2.0
License-File: LICENSE
Keywords: aiops,bigpanda,cloudthinker,incidents,llm,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: fastmcp<3,>=2.0
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# ct-bigpanda-mcp-server

A read-only CloudThinker MCP server for [BigPanda](https://www.bigpanda.io/) AIOps. BigPanda has no upstream MCP server, so this wraps the BigPanda **Incidents V2 / Environments REST API** directly and exposes it over **stdio**, auto-authenticated from environment variables — dropping into CloudThinker's env-injection connection model (same shape as `ct-prometheus-mcp-server` / `ct-rabbitmq-mcp-server`).

## What it does

- Reads `BIGPANDA_*` env vars at startup and pins the REST client to a region.
- Probes `GET /environments` once at startup to fail fast on a bad key / wrong region.
- Serves three **read-only** tools over stdio. No write path exists.

## Run

```bash
uvx --from ct-bigpanda-mcp-server@0.1.0 ct-bigpanda-mcp-server
```

## Environment

| Var | Required | Default | Purpose |
|---|---|---|---|
| `BIGPANDA_API_TOKEN` | yes | — | BigPanda **User API Key**, sent as `Authorization: Bearer <key>` |
| `BIGPANDA_REGION` | no | `us` | `us` → `api.bigpanda.io`, `eu` → `eu-api.bigpanda.io` |
| `BIGPANDA_ENVIRONMENT_ID` | no | — | default environment for `search_incidents` / `get_incident` |
| `LOG_LEVEL` | no | `info` | logging level (also mapped to `FASTMCP_LOG_LEVEL`) |

The token must be a **User API Key** (Incidents V2 auth), not a login password. Keys are **region-scoped**: a US key against the EU host (or vice-versa) returns **404, not 401** — check `BIGPANDA_REGION` first if you see 404s.

## Tools (read-only)

| Tool | Args (all strings) | REST call | Returns |
|---|---|---|---|
| `list_environments` | — | `GET /resources/v2.0/environments` | `{environments, total}` |
| `search_incidents` | `environment_id`, `query?`, `status?`, `limit?` | `GET .../environments/{id}/incidents?query=&page_size=` | `{incidents, returned, total, has_more, query}` |
| `get_incident` | `environment_id`, `incident_id` | `GET .../environments/{id}/incidents/{incident_id}` | the incident with correlated alerts inline |

`limit` is a **string** and is capped server-side at 100; results are also truncated client-side so output stays bounded even if the API ignores `page_size`. `status` is a convenience filter lifted into BPQL as `status = "<status>"`; pass a full `query` for richer BPQL.

## ⚠️ Live-tenant verification required before pinning the contract

Authored from the public API reference; the following could **not** be confirmed offline and MUST be checked against a live BigPanda tenant before the documented contract is trusted (connections-kit lessons `return-shapes-wrap-vs-raw`, `mcp-surface-phantom-tools`, `tool-args-pagination-cap`):

1. The exact response wrapping per endpoint (`items` vs `incidents` vs bare array). The client accepts all three defensively, but the real shape should be recorded.
2. The real `search_incidents` pagination parameter name (`page_size` assumed) and its true max page size.
3. That `listTools` shows exactly these three tool names and nothing else.
4. The correlated-alerts field name inside an incident (`alerts` vs `entities`).

## License

Apache-2.0.
