ct-bigpanda-mcp-server 0.1.0__tar.gz

ct_bigpanda_mcp_server-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/

ct_bigpanda_mcp_server-0.1.0/HANDOFF.md

@@ -0,0 +1,65 @@
+# Handoff: `ct-bigpanda-mcp-server` (parallel workstream — separate repo)
+
+> **STATUS (built):** the server has been implemented at `/home/user/ct-bigpanda-mcp-server` (v0.1.0, read-only scope) — from-scratch wrapper over the BigPanda Incidents V2 / Environments REST API. Pure helpers are unit-tested offline; the FastMCP `listTools` surface is asserted without network. **NOT yet verified against a live BigPanda tenant**, and **NOT yet published to PyPI**. Remaining: (1) live-tenant verification of the four assumptions in README → "Live-tenant verification required"; (2) `twine upload` to PyPI (needs a PyPI token + a real User API Key for the live check).
+
+**For:** the team owning the MCP-server / sandbox-package repo.
+**Goal:** publish a PyPI package `ct-bigpanda-mcp-server` that CloudThinker's BigPanda connection launches via `uvx` inside the sandbox.
+
+**NOT in scope:** No change to the OpenSandbox runtime, the `cloudthinker-sandbox` image, k8s manifests, or egress policy (prod runs allow-all egress; BigPanda is a public API; `uvx`/`uv` already baked into the sandbox image). This package is the only external dependency.
+
+## What CloudThinker will run
+
+The backend catalog (`migrate_builtin_connection.py`, prefix `bigpanda`) launches it exactly like Prometheus:
+```python
+config = {
+  "command": "uvx",
+  "args": ["--from", "ct-bigpanda-mcp-server@0.1.0", "ct-bigpanda-mcp-server"],
+}
+```
+`uvx` resolves the package from PyPI at connect time. So: **the package MUST be published to PyPI** before the connection can connect. (cco-2 already pins `@0.1.0` in the seed — keep the published version in sync, or bump both together.)
+
+## Why from-scratch (not a wrapper over upstream)
+
+Unlike RabbitMQ (wraps `amq-mcp-server-rabbitmq`), **BigPanda has no upstream MCP server** (web search, June 2026). So this implements the three read tools directly against the REST API. Same CloudThinker connection model as the others: auto-connect from env vars, no runtime connect/login tool, stdio transport.
+
+## Required behavior (the CONTRACT — must match the backend catalog seed exactly)
+
+1. On startup, read these env vars:
+
+   | Env var | Required | Default | Purpose |
+   |---|---|---|---|
+   | `BIGPANDA_API_TOKEN` | yes | — | User API Key, sent `Authorization: Bearer <key>` |
+   | `BIGPANDA_REGION` | no | `us` | `us` → `api.bigpanda.io`, `eu` → `eu-api.bigpanda.io` |
+   | `BIGPANDA_ENVIRONMENT_ID` | no | — | default environment for the incident tools |
+   | `LOG_LEVEL` | no | `info` | logging level (also → `FASTMCP_LOG_LEVEL`) |
+
+2. Auto-connect from those env vars; the first tool call works with no bootstrap tool call. Probe `GET /environments` once at startup so a bad key / wrong region fails fast (the connection test then reports a real error).
+3. Expose exactly these three **read-only** tools (snake_case — they ARE the contract the executor skill imports). CloudThinker leaves the catalog `tools` list **empty**; runtime discovery owns the inventory.
+   - `list_environments()` → `GET /resources/v2.0/environments`
+   - `search_incidents({environment_id, query?, status?, limit})` → `GET .../environments/{id}/incidents` — `limit` is a STRING, capped at 100.
+   - `get_incident({environment_id, incident_id})` → `GET .../environments/{id}/incidents/{incident_id}`
+4. **Read-only.** No write path (no snooze/resolve/comment). That is a deliberate v1 scope boundary.
+5. stdio transport (default).
+6. Dependencies are pure-Python (`fastmcp`, `httpx`) — no native libs, sandbox image needs nothing extra.
+
+## Acceptance criteria
+
+- `uvx --from ct-bigpanda-mcp-server@<VERSION> ct-bigpanda-mcp-server` starts over stdio with only the env vars above set, and `listTools` returns exactly `list_environments`, `search_incidents`, `get_incident`.
+- Against a live tenant: `list_environments` returns real environments; `search_incidents` honors `limit` (bounded ≤100); `get_incident` returns an incident with its correlated alerts.
+- `eu` region routes to `eu-api.bigpanda.io`; a region/key mismatch surfaces the 404→region hint, not a bare 401.
+- Published to PyPI as `ct-bigpanda-mcp-server` with a pinned semver; report the version so the backend catalog `args` stays in sync.
+
+## Live-tenant verification checklist (do before publishing — see README)
+
+1. Per-endpoint response wrapping (`items` vs `incidents` vs bare array) — record the real shape; the client accepts all three but the docs should state the truth.
+2. The real `search_incidents` pagination param name (`page_size` assumed) + true max page size.
+3. `listTools` shows exactly the three tools, nothing else (`mcp-surface-phantom-tools`).
+4. Correlated-alerts field name inside an incident (`alerts` vs `entities`) — align `executor/.../incident-detail.ts` extraction.
+
+## Local checks already run
+
+```bash
+cd /home/user/ct-bigpanda-mcp-server
+uv run pytest -q          # pure-helper unit tests (offline)
+uv run python -m ... # listTools smoke (asserts the 3 tool names, no network)
+```

ct_bigpanda_mcp_server-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

ct_bigpanda_mcp_server-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+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.

ct_bigpanda_mcp_server-0.1.0/README.md

@@ -0,0 +1,49 @@
+# 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.

ct_bigpanda_mcp_server-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "ct-bigpanda-mcp-server"
+version = "0.1.0"
+description = "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."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "CloudThinker" }]
+keywords = ["bigpanda", "aiops", "incidents", "mcp", "llm", "cloudthinker"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+# BigPanda has no upstream MCP server, so this is a from-scratch wrapper over the
+# REST API (Incidents V2). Only two runtime deps: the MCP framework + an HTTP client.
+dependencies = [
+    "fastmcp>=2.0,<3",
+    "httpx>=0.27",
+]
+
+[project.scripts]
+ct-bigpanda-mcp-server = "ct_bigpanda_mcp_server.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/cloudthinker/ct-bigpanda-mcp-server"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ct_bigpanda_mcp_server"]

ct_bigpanda_mcp_server-0.1.0/src/ct_bigpanda_mcp_server/__init__.py

@@ -0,0 +1,3 @@
+"""CloudThinker BigPanda MCP server (read-only)."""
+
+__version__ = "0.1.0"

ct_bigpanda_mcp_server-0.1.0/src/ct_bigpanda_mcp_server/__main__.py

@@ -0,0 +1,61 @@
+"""Entry point — read env, construct the client, fail fast, serve over stdio.
+
+Env contract (must match the CloudThinker backend catalog seed for `bigpanda`):
+
+  | Env var                 | Required | Default | Purpose                          |
+  |-------------------------|----------|---------|----------------------------------|
+  | BIGPANDA_API_TOKEN      | yes      | —       | User API Key (Bearer)            |
+  | BIGPANDA_REGION         | no       | us      | us | eu  -> REST base host       |
+  | BIGPANDA_ENVIRONMENT_ID | no       | —       | default environment for tools    |
+  | LOG_LEVEL               | no       | info    | logging level                    |
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+
+from .client import BigPandaClient, BigPandaError
+from .server import build_server
+
+log = logging.getLogger("ct-bigpanda-mcp-server")
+
+
+def _require(name: str) -> str:
+    value = os.getenv(name, "").strip()
+    if not value:
+        sys.stderr.write(f"ct-bigpanda-mcp-server: required env var {name} is not set\n")
+        raise SystemExit(2)
+    return value
+
+
+def main() -> None:
+    token = _require("BIGPANDA_API_TOKEN")
+    region = os.getenv("BIGPANDA_REGION", "us").strip() or "us"
+    default_env = os.getenv("BIGPANDA_ENVIRONMENT_ID", "").strip()
+
+    level = os.getenv("LOG_LEVEL", "info").strip().upper()
+    logging.basicConfig(level=getattr(logging, level, logging.INFO), stream=sys.stderr)
+    # FastMCP's own logger reads FASTMCP_LOG_LEVEL; mirror LOG_LEVEL into it.
+    os.environ.setdefault("FASTMCP_LOG_LEVEL", level)
+
+    try:
+        client = BigPandaClient(token, region=region, default_environment_id=default_env)
+    except ValueError as exc:  # unknown region
+        sys.stderr.write(f"ct-bigpanda-mcp-server: {exc}\n")
+        raise SystemExit(2) from exc
+
+    # Fail fast: probe a cheap read so the connection test reports a real error
+    # (bad key / wrong region) instead of deferring it to the first tool call.
+    try:
+        client.list_environments()
+    except BigPandaError as exc:
+        sys.stderr.write(f"ct-bigpanda-mcp-server: startup connection check failed: {exc}\n")
+        raise SystemExit(1) from exc
+
+    build_server(client).run()
+
+
+if __name__ == "__main__":
+    main()

ct_bigpanda_mcp_server-0.1.0/src/ct_bigpanda_mcp_server/_util.py

@@ -0,0 +1,95 @@
+"""Pure helpers — stdlib only.
+
+Kept free of ``httpx``/``fastmcp`` imports so the response-shape and argument
+coercion logic can be unit-tested without the network stack installed. Every
+function here is deterministic and side-effect free.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# region -> REST base URL. BigPanda's API is region-scoped; a User API Key minted
+# in one region returns 404 (not 401) against the other region's host.
+_REGION_BASE = {
+    "us": "https://api.bigpanda.io",
+    "eu": "https://eu-api.bigpanda.io",
+}
+API_PREFIX = "/resources/v2.0"
+
+# Hard server-side cap on how many incidents a single search returns, regardless
+# of what the caller asks for. discovery-bounded-output / tool-args-pagination-cap:
+# the output must stay bounded even if the upstream API ignores our page_size hint.
+MAX_LIMIT = 100
+DEFAULT_LIMIT = 20
+
+
+def region_base_url(region: str) -> str:
+    """Map a region code to its REST base URL. Raises on an unknown region."""
+    base = _REGION_BASE.get((region or "").strip().lower())
+    if base is None:
+        valid = ", ".join(sorted(_REGION_BASE))
+        raise ValueError(f"unknown BIGPANDA_REGION {region!r}; expected one of: {valid}")
+    return base + API_PREFIX
+
+
+def clamp_limit(raw: Any) -> int:
+    """Coerce a string/number limit to an int in [1, MAX_LIMIT].
+
+    Numeric tool args arrive as STRINGS (tool-args-string-not-int) because this
+    proxies an HTTP API. A missing/garbage value falls back to DEFAULT_LIMIT.
+    """
+    try:
+        value = int(str(raw).strip())
+    except (TypeError, ValueError):
+        return DEFAULT_LIMIT
+    if value < 1:
+        return DEFAULT_LIMIT
+    return min(value, MAX_LIMIT)
+
+
+def as_list(data: Any, keys: tuple[str, ...]) -> list:
+    """Normalize a BigPanda list response to a plain list.
+
+    return-shapes-wrap-vs-raw: BigPanda is inconsistent about wrapping — some
+    endpoints return a bare JSON array, others wrap it under ``items`` /
+    ``incidents`` / ``environments``. Accept either rather than hard-coding one
+    shape that breaks on the other. The exact per-endpoint shape must still be
+    confirmed against a live tenant before the documented contract is trusted.
+    """
+    if isinstance(data, list):
+        return data
+    if isinstance(data, dict):
+        for key in keys:
+            value = data.get(key)
+            if isinstance(value, list):
+                return value
+    return []
+
+
+def total_count(data: Any, fallback: int) -> int | None:
+    """Pull a total/count from a wrapped response; None if not advertised."""
+    if isinstance(data, dict):
+        for key in ("total", "count", "total_count"):
+            value = data.get(key)
+            if isinstance(value, int):
+                return value
+    return None
+
+
+def build_query(query: str | None, status: str | None) -> str | None:
+    """Compose a BPQL query string from a raw query and/or a status filter.
+
+    If the caller passes an explicit ``query`` it wins as-is. Otherwise a bare
+    ``status`` is lifted into BPQL (``status = "<status>"``). Returns None when
+    neither is supplied (search all).
+    """
+    query = (query or "").strip()
+    status = (status or "").strip()
+    if query:
+        return query
+    if status:
+        # BPQL string literals are double-quoted; escape embedded quotes.
+        escaped = status.replace('"', '\\"')
+        return f'status = "{escaped}"'
+    return None