{"id":"ee381d68-502f-4c23-bd62-426f36eff488","slug":"ice-panel-mcp-server","kind":"mcp","name":"ice-panel-mcp-server","summary":"Official Model Context Protocol Server integrating the IcePanel SDK. Features 100% test coverage natively orchestrating L1, L2, L3 diagram generation and capability flows.","owner":"mihailt","repoUrl":"https://github.com/mihailt/ice-panel-mcp-server","license":"MIT","licenseTier":"permissive","trust":"community","stars":4,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-03-22T01:09:39.000Z","addedAt":"2026-10-21T17:04:09.043Z","logoUrl":"https://avatars.githubusercontent.com/u/70798?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","cloud-infra","design-media"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T23:34:42.819Z","sample":false,"url":"https://conduits.dev/tools/ice-panel-mcp-server","language":"TypeScript","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# IcePanel MCP Server\n\nMCP server for the [IcePanel](https://icepanel.io) API.\n\n## Architectural Documentation\n\nThe source codebase has been seamlessly mapped through the C4 architectural abstraction directly integrating via **IcePanel Cloud**. \n\n- **C4 Context (L1)**: Maps the physical boundaries separating the standard Developer environments, AI Agents, and the standard Host systems executing node instances bridging to the Remote API.\n- **C4 Containers (L2)**: Granular separation of the local REST Server interceptor versus the native TypeScript SDK layer passing boundaries explicitly.\n- **C4 Components (L3)**: Strict domain separation isolating the generic **Protocol Router Layer**, the strict **Zod Schema Validators**, the executing **Domain Capabilities**, and the outbound **Cloud Client**.\n\n### Execution Flows (L1-L3)\n\nEach structural map hosts autonomous, step-by-step chronological flows defining explicit component boundaries:\n1. **Developer Setup & Deployment Lifecycle** (`L1`): Traces physical environment instantiation variables mapping locally.\n2. **System Context Data Synchronization** (`L1`): Tracks the broad sequence of AI Agents requesting capability execution schemas mapping to remote mutations.\n3. **Schema Generation Deep-Dive** (`L2`): Outlines the local AST type-safe scanning extraction compiling models offline.\n4. **Internal API Capabilities Execution** (`L2`): Maps physical REST wrapper sequences passing secure payload arguments into the verified SDK logic endpoints.\n5. **Tool Execution Pipeline** (`L3`): Evaluates granular JSON-RPC strings hitting standard router edges, resolving against Zod schemas, into discrete structural domains.\n6. **Cloud Payload Transmission** (`L3`): Resolves strict capabilities mapping secure Bearer structures passing via physical HTTP interfaces terminating onto IcePanel graph clusters.\n\n> **Visual Demonstration**:\n>\n> ![IcePanel Sequence Execution Demo](./docs/assets/icepanel_flows_demo.webp)\n\n## Features\n\nThe formal architecture of this repository across all execution contexts is rigorously modeled according to the C4 methodology.\n\n- **[System Context (L1)](docs/c4-context.md)**: Defines the overarching ecosystem, actors, and remote endpoint boundaries.\n- **[Container Architecture (L2)](docs/c4-container.md)**: The 9 major independent execution pipelines and configuration blocks.\n- **[Component Graph (L3)](docs/c4-component.md)**: A physical 1-to-1 graph comprehensively mapping every single TypeScript logic file, JSON schema, and Vitest suite across the entire repository.\n\n> 📊 **[View Interactive Architecture Diagrams on IcePanel](https://s.icepanel.io/W4aTobhklkvDMF/Lc23)**\n\n### L1: Context Architecture\n![Context Architecture](docs/assets/l1.png)\n\n### L2: Container Architecture\n![Container Architecture](docs/assets/l2.png)\n\n### L3: Component Architecture\n![Component Architecture](docs/assets/l3.png)\n\n## Features\n\n- 🔍 **Zero-config discovery** — `find_tool` searches all tools by name, description, or module\n- ⚡ **Universal executor** — `run_tool` dynamically invokes any discovered tool\n- 🔄 **Batch pipelines** — `batch_run_tool` executes arrays of tools chronologically across domains\n- 🚀 **Parallel pipelines** — `batch_run_parallel_tool` executes arrays of tools concurrently across domains\n- 📦 **Modular loading** — `?modules=diagrams,model` loads only what you need\n\n## Deployment & Client Configuration\n\nThe server gracefully supports two explicit deployment strategies mapping strict execution environments dynamically natively utilizing blazing fast Server-Sent Events (SSE) securely natively across all MCP clients (`mcp_config.json`, Claude Desktop, Google Antigravity, etc):\n\n### Option A: Local Docker Proxy (Stdio JSON-RPC)\nRuns the server independently on your local machine using standard input/output (stdio) pipelines via Docker. This explicitly bypasses local network restrictions, corporate VPNs, and TLS interception organically natively.\n1. Configure your `.env` with `DOCKER_ICEPANEL_API_KEY=your_key`\n2. `docker compose up -d` (Boots the persistent STDIN local background proxy)\n\n**mcp_config.json Payload for Cursor/Claude Desktop:**\n```json\n\"ice-panel\": {\n  \"command\": \"docker\",\n  \"args\": [\n    \"exec\",\n    \"-i\",\n    \"ice-panel-mcp\",\n    \"npx\",\n    \"tsx\",\n    \"src/stdio.ts\"\n  ],\n  \"disabled\": false\n}\n```\n\n### Option B: Edge Serverless API (Cloudflare Workers SSE)\nInstantly binds the exact AST extraction architecture universally publicly onto your secure edge domain without requiring specific execution proxies gracefully deployed to zero-maintenance global endpoints.\n1. `pnpm run deploy` \n\n**mcp_config.json Payload:**\n```json\n\"ice-panel\": {\n  \"serverUrl\": \"https://ice-panel-mcp.<your-subdomain>.workers.dev/mcp\",\n  \"headers\": {\n    \"Authorization\": \"Bearer <YOUR_ICEPANEL_API_KEY>\"\n  }\n}\n```\n\nGenerate an API token from [IcePanel Settings](https://app.icepanel.io).\n\n## Available Scripts\n\nThis project includes the following `pnpm` scripts:\n\n| Command | Description |\n|---|---|\n| `pnpm run dev` (or `start`) | Starts the local `wrangler dev` server on `http://localhost:8787/mcp`. |\n| `pnpm run deploy` | Deploys the production build to Cloudflare Workers. |\n| `pnpm run codegen` | Automatically regenerates all SDK tool wrappers inside `src/`. |\n| `pnpm test` | Runs the offline unit test suite checking output serialization. |\n| `pnpm run test:coverage` | Runs unit tests and yields the Istanbul code coverage breakdown. |\n| `pnpm run test:e2e` | Runs the live integration suite testing upstream IcePanel API connectivity. |\n| `pnpm run cf-typegen` | Updates Cloudflare environment types. |\n| `pnpm run docker:build` | Compiles the standalone STDIN Docker proxy image locally. |\n| `pnpm run docker:run` | Executes the container interactively bridging the STDIN pipeline. |\n| `pnpm run docker:start` | Unpacks the native Node.js `stdio` interceptor (entrypoint inside Docker). |\n\n## Development\n\nTool wrappers are auto-generated from the [@icepanel/sdk](https://www.npmjs.com/package/@icepanel/sdk) NPM package types, managed directly from the official [IcePanel/icepanel-js](https://github.com/IcePanel/icepanel-js) repository.\n\n```bash\npnpm install\npnpm run codegen\npnpm run dev\n```\n\n## Testing\n\n### Unit Tests & Coverage\n\nWe maintain 100% test coverage across all generated wrappers and schemas locally.\n\n```bash\npnpm test\npnpm run test:coverage \n```\n\n```text\n-------------------|---------|----------|---------|---------|-------------------\nFile               | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s \n-------------------|---------|----------|---------|---------|-------------------\nAll files          |     100 |      100 |     100 |     100 |                   \n src               |     100 |      100 |     100 |     100 |                   \n  agent.ts         |     100 |      100 |     100 |     100 |                   \n  index.ts         |     100 |      100 |     100 |     100 |                   \n  schemas.ts       |     100 |      100 |     100 |     100 |                   \n  stdio.ts         |     100 |      100 |     100 |     100 |                   \n src/generated     |     100 |      100 |     100 |     100 |                   \n  ...og-schemas.ts |     100 |      100 |     100 |     100 |                   \n  catalog.ts       |     100 |      100 |     100 |     100 |                   \n  ...ts-schemas.ts |     100 |      100 |     100 |     100 |                   \n  comments.ts      |     100 |      100 |     100 |     100 |                   \n  ...ms-schemas.ts |     100 |      100 |     100 |     100 |                   \n  diagrams.ts      |     100 |      100 |     100 |     100 |                   \n  ...ns-schemas.ts |     100 |      100 |     100 |     100 |                   \n  domains.ts       |     100 |      100 |     100 |     100 |                   \n  ...ts-schemas.ts |     100 |      100 |     100 |     100 |                   \n  drafts.ts        |     100 |      100 |     100 |     100 |                   \n  ...ol-schemas.ts |     100 |      100 |     100 |     100 |                   \n  find_tool.ts     |     100 |      100 |     100 |     100 |                   \n  flows-schemas.ts |     100 |      100 |     100 |     100 |                   \n  flows.ts         |     100 |      100 |     100 |     100 |                   \n  index.ts         |     100 |      100 |     100 |     100 |                   \n  ...es-schemas.ts |     100 |      100 |     100 |     100 |                   \n  landscapes.ts    |     100 |      100 |     100 |     100 |                   \n  model-schemas.ts |     100 |      100 |     100 |     100 |                   \n  model.ts         |     100 |      100 |     100 |     100 |                   \n  ...ns-schemas.ts |     100 |      100 |     100 |     100 |                   \n  organizations.ts |     100 |      100 |     100 |     100 |                   \n  ...nk-schemas.ts |     100 |      100 |     100 |     100 |                   \n  shareLink.ts     |     100 |      100 |     100 |     100 |                   \n  tags-schemas.ts  |     100 |      100 |     100 |     100 |                   \n  tags.ts          |     100 |      100 |     100 |     100 |                   \n  teams-schemas.ts |     100 |      100 |     100 |     100 |                   \n  teams.ts         |     100 |      100 |     100 |     100 |                   \n  ...ns-schemas.ts |     100 |      100 |     100 |     100 |                   \n  versions.ts      |     100 |      100 |     100 |     100 |                   \n-------------------|---------|----------|---------|---------|-------------------\n```\n\n### End-to-End Testing\n\nTo run the live E2E test suite against the actual IcePanel API:\n\n1. Create a `.env` file in the root directory:\n   ```env\n   E2E_TEST_ICEPANEL_API_KEY=your_api_key_here\n   ```\n2. Start the local server in one terminal: `pnpm run dev`\n3. Run the E2E suite in another terminal: `pnpm run test:e2e`\n\n#### Known Limitations (Skipped Tests)\n\nThe E2E suite contains 48 exhaustive assertions. Two tests are formally tracked as conditionally skipped (`it.skip`) to account for proven upstream constraints in the IcePanel API when authenticating via API Keys:\n1. **`delete_comments_replies`**: Throws a `401 Unauthorized` (\"Comment reply was created by another user\") because the backend lacks identity tracking for API Keys exclusively on this nested route.\n2. **`create_versions_reverts`**: Throws a `422 Unprocessable Entity` (\"User not provided\") because restoring a version demands a user profile that API Keys do not inherently possess.\n\n## Support\n\nIf you found this tool helpful and want to sustainably support its development, you can send SOL to the author:\n`4er5rfqU5iQPswcmzorjUCnftu3BwfbgXohvgp8seLeu`\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE)."}