@clampd/mcp-proxy 0.2.0

package/Dockerfile

@@ -0,0 +1,32 @@
+FROM node:22-alpine AS builder
+
+WORKDIR /app
+
+COPY package.json package-lock.json* ./
+RUN npm ci --ignore-scripts
+
+COPY tsconfig.json ./
+COPY src/ ./src/
+RUN npm run build
+
+# ── Runtime ────────────────────────────────────────────────────────────
+FROM node:22-alpine
+
+RUN addgroup -g 1001 clampd && adduser -D -u 1001 -G clampd clampd
+
+WORKDIR /app
+
+COPY --from=builder /app/package.json /app/package-lock.json* ./
+RUN npm ci --omit=dev --ignore-scripts
+
+COPY --from=builder /app/dist/ ./dist/
+
+# Copy fleet config if present (for fleet mode)
+COPY fleet*.json ./
+
+USER clampd
+EXPOSE 3003
+
+# Single mode: reads config from env vars
+# Fleet mode: set CMD to ["node", "dist/index.js", "--fleet-config", "fleet.json"]
+CMD ["node", "dist/index.js"]

package/README.md

@@ -0,0 +1,103 @@
+# @clampd/mcp-proxy
+
+Standalone MCP proxy that wraps **any** MCP server with Clampd's 9-stage security pipeline. Connect Claude Desktop, Cursor, or any MCP client to this proxy instead of directly to an MCP server. Every tool call is classified through ag-gateway — dangerous calls are blocked before they reach the tool.
+
+## Quick Start
+
+```bash
+# Install
+cd sdk/typescript/mcp-proxy && npm install
+
+# Run (wraps the filesystem MCP server)
+npx tsx src/index.ts \
+  --upstream "npx -y @modelcontextprotocol/server-filesystem /tmp" \
+  --gateway http://localhost:8080 \
+  --agent-id b0000001-0000-0000-0000-000000000001 \
+  --api-key ag_test_acme_demo_2026
+
+# Open the dashboard
+open http://localhost:3003
+```
+
+## Claude Desktop Configuration
+
+Add to your Claude Desktop `mcpServers` config:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "url": "http://localhost:3003/sse"
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `JWT_SECRET` | JWT signing secret for agent auth | (none) |
+
+## CLI Options
+
+```
+--upstream, -u    Command to spawn the upstream MCP server (required)
+--agent-id, -a    Clampd agent UUID (required)
+--gateway, -g     Clampd gateway URL (default: http://localhost:8080)
+--api-key, -k     Clampd API key (default: clmpd_demo_key)
+--port, -p        Port to listen on (default: 3003)
+--secret, -s      JWT signing secret
+--dry-run         Classify but never forward to upstream
+--verbose, -v     Enable debug logging
+```
+
+## Architecture
+
+```
+Claude Desktop / Cursor / Any MCP Client
+    |
+    | MCP protocol (SSE transport)
+    v
+Clampd MCP Proxy (:3003)
+    |
+    +---> GET /sse      -- MCP SSE endpoint (client connects here)
+    +---> GET /          -- Live dashboard (blocked/allowed in real-time)
+    +---> GET /health    -- Health check JSON
+    +---> GET /events    -- Dashboard SSE stream (live updates)
+    |
+    | For each tool call:
+    |   1. Extract tool_name + params from MCP call_tool request
+    |   2. POST to ag-gateway /v1/proxy { tool, params, target_url }
+    |   3. If gateway says BLOCK -> return MCP error to client
+    |   4. If gateway says ALLOW -> forward to upstream MCP server
+    |
+    v
+Upstream MCP Server (filesystem, database, github, shell, etc.)
+    (spawned as child process, communicates via stdio)
+```
+
+## Deployment
+
+### Docker
+
+```bash
+docker build -t clampd-mcp-proxy .
+docker run -p 3003:3003 clampd-mcp-proxy \
+  --upstream "npx -y @modelcontextprotocol/server-filesystem /tmp" \
+  --gateway http://host.docker.internal:8080 \
+  --agent-id b0000001-0000-0000-0000-000000000001
+```
+
+### npm global install
+
+```bash
+npm install -g @clampd/mcp-proxy
+clampd-mcp-proxy --upstream "..." --agent-id "..."
+```
+
+### npx (no install)
+
+```bash
+npx @clampd/mcp-proxy --upstream "..." --agent-id "..."
+```

package/dist/dashboard.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Live dashboard — serves an HTML page at GET / with a real-time event log
+ * of all tool calls flowing through the proxy.
+ *
+ * Features:
+ *   - Enriched event data (classification, session flags, intent labels, encodings)
+ *   - Expandable detail rows with full gateway response data
+ *   - Real-time risk trend SVG sparkline chart
+ *   - Session summary panel with aggregated stats
+ *   - Export (Copy Report / Download JSON)
+ *   - Attack Demo panel with pre-built payloads
+ *   - Status filter tabs (All / Allowed / Blocked / Flagged / Errors)
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { ProxyOptions } from "./proxy.js";
+export interface ProxyEvent {
+    timestamp: string;
+    tool: string;
+    params: string;
+    status: "allowed" | "blocked" | "flagged" | "error";
+    risk_score: number;
+    latency_ms: number;
+    reason?: string;
+    matched_rules?: string[];
+    classification?: string;
+    session_flags?: string[];
+    intent_labels?: string[];
+    encodings_detected?: string[];
+    scope_granted?: string;
+    action?: string;
+    reasoning?: string;
+    degraded_stages?: string[];
+    scan_details?: {
+        pii_found?: Array<{
+            pii_type: string;
+            count: number;
+        }>;
+        secrets_found?: Array<{
+            secret_type: string;
+            count: number;
+        }>;
+        input_risk?: number;
+        output_risk?: number;
+    };
+    descriptor_hash?: string;
+    scope_token?: string;
+}
+export interface SessionStats {
+    toolCallCount: number;
+    uniqueTools: string[];
+    blockedCount: number;
+    flaggedCount: number;
+    totalRisk: number;
+    firstCallAt: string;
+    lastCallAt: string;
+    rulesTriggered: Record<string, number>;
+    piiDetected: boolean;
+    secretsDetected: boolean;
+}
+export declare function serveDashboard(_req: IncomingMessage, res: ServerResponse, events: ProxyEvent[], opts: ProxyOptions & {
+    demoPanel?: boolean;
+    sessionStats?: SessionStats;
+}): void;
+//# sourceMappingURL=dashboard.d.ts.map

package/dist/dashboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard.d.ts","sourceRoot":"","sources":["../src/dashboard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAI/C,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,YAAY,CAAC,EAAE;QACb,SAAS,CAAC,EAAE,KAAK,CAAC;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACvD,aAAa,CAAC,EAAE,KAAK,CAAC;YAAE,WAAW,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,WAAW,EAAE,OAAO,CAAC;IACrB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAmhBD,wBAAgB,cAAc,CAC5B,IAAI,EAAE,eAAe,EACrB,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,UAAU,EAAE,EACpB,IAAI,EAAE,YAAY,GAAG;IAAE,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,YAAY,CAAA;CAAE,GACxE,IAAI,CAON"}