From 5d99645383ea6a0f02bf57c52b2141fec4a1bf0a Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 13 Feb 2026 16:55:50 +0000 Subject: [PATCH 1/2] Add feature proposals for Web UI enhancements and universal MCP proxy Comprehensive feature proposal covering 16 features across 5 categories: - Web UI UX improvements (detail inspector, session timeline, theme toggle, shortcuts) - Data collection enhancements (client identification, param analysis, error classification) - Analytics & intelligence (heatmap, workflow correlation, anomaly detection, digests) - Universal MCP proxy concept (generic proxy mode, multi-server hub, transform pipeline) - Prioritized roadmap with effort/impact assessment https://claude.ai/code/session_01WHGdcPbiap1HQddHkFd4wS --- SPECS/FEATURE_PROPOSALS.md | 416 +++++++++++++++++++++++++++++++++++++ 1 file changed, 416 insertions(+) create mode 100644 SPECS/FEATURE_PROPOSALS.md diff --git a/SPECS/FEATURE_PROPOSALS.md b/SPECS/FEATURE_PROPOSALS.md new file mode 100644 index 00000000..b76adaf6 --- /dev/null +++ b/SPECS/FEATURE_PROPOSALS.md @@ -0,0 +1,416 @@ +# Feature Proposals: Web UI & Universal MCP Proxy + +## Context + +Based on the current Workplan, FEATURE_REBUILD spec, and existing Web UI implementation +(dashboard.js, metrics.py, shared_metrics.py, server.py), this document proposes +concrete next features grouped by category. + +Current state: The Web UI has 6 KPI cards, 4 charts (tool bar, tool pie, request timeline, +latency), a per-tool latency table, and a paginated audit log with filter/export. +All real-time via WebSocket with HTTP polling fallback. + +--- + +## A. Web UI UX Improvements + +### A1. Tool Call Detail Inspector (Request/Response Viewer) + +**Problem:** The audit log shows metadata (timestamp, tool, direction, latency, error) +but not *what* was actually sent or returned. Debugging requires digging through JSONL +audit files manually. + +**Proposal:** Add a clickable row expansion or slide-out panel in the audit table that +shows the full JSON-RPC request and response payloads. The payloads would be syntax- +highlighted and collapsible. + +**Implementation sketch:** +- Backend: Add optional `capture_payload: bool` config flag (default off for privacy). + When enabled, store truncated request params and response content in audit entries. +- New API: `GET /api/audit/{request_id}/detail` returns `{request: {...}, response: {...}}`. +- Frontend: Click audit row -> expand inline or open side panel with pretty-printed JSON. +- Storage: Bounded ring buffer in SQLite (e.g. last 500 payloads, max 64KB each). + +**Value:** Developers can debug tool failures without leaving the dashboard. Answers +"what did I actually send to XcodeGrep?" and "what came back?". + +--- + +### A2. Session Timeline View + +**Problem:** The current audit log is a flat table. There's no visual sense of how tool +calls relate to each other within a coding session or conversation. + +**Proposal:** Add a vertical timeline view that groups tool calls into sessions +(detected by gaps > N minutes between calls). Each session shows a compact +sequence of tool calls with icons, durations, and error badges. + +**Implementation sketch:** +- Backend: Add session detection logic: gap-based (configurable, default 5 min silence + = new session) or explicit session ID from client if available. +- New API: `GET /api/sessions` returns `[{id, start, end, tool_count, error_count, tools: [...]}]`. +- Frontend: New tab/view with vertical timeline using CSS (no extra library needed). + Each node is a tool call; hover shows summary; click opens detail inspector (A1). + +**Value:** Gives a "conversation replay" feel. See what an agent did in sequence. +Useful for understanding multi-step workflows (e.g. ListWindows -> Grep -> Read -> Write). + +--- + +### A3. Dashboard Theme Toggle (Dark/Light) + +**Problem:** Current dashboard is dark-theme only. Some developers prefer light mode +or need it for accessibility/screen-sharing. + +**Proposal:** CSS-variable-based theme system with a toggle button in the header. +Store preference in `localStorage`. + +**Implementation sketch:** +- Define all colors as CSS custom properties on `:root` (already partially dark-themed). +- Add `[data-theme="light"]` overrides. +- Header button toggles `document.documentElement.dataset.theme`. +- Chart.js colors updated via `Chart.defaults` on toggle. + +**Value:** Low effort, high polish. Improves accessibility and professional appearance. + +--- + +### A4. Keyboard Shortcuts & Command Palette + +**Problem:** No keyboard navigation. Power users can't quickly switch between +charts/audit/export without mouse clicks. + +**Proposal:** Add lightweight keyboard shortcuts: +- `1-4` to focus chart sections +- `a` to jump to audit log +- `r` to reset metrics (with confirmation) +- `e` to export JSON +- `?` to show shortcut overlay + +**Implementation sketch:** +- Pure JS `keydown` listener with a shortcut map. +- Small modal overlay for `?` help. +- No library needed. + +**Value:** Developer-friendly UX. Feels like a real dev tool, not just a web page. + +--- + +## B. Data Collection Enhancements + +### B1. MCP Client Identification + +**Problem:** The wrapper currently doesn't know *which* client is making requests +(Cursor, Zed, Claude Code, Codex). All calls look identical in metrics. + +**Proposal:** Detect the calling client from the MCP `initialize` handshake. +The `clientInfo` field in the initialize request contains `{name, version}`. +Capture this and tag all subsequent metrics with the client identity. + +**Implementation sketch:** +- In `__main__.py` `on_request` callback, detect `initialize` method and extract + `params.clientInfo.name`. +- Store as `current_client` in metrics context. +- Add `client` column to shared_metrics SQLite schema. +- Dashboard: new KPI card "Active Client" showing the connected client name. +- Charts: optional client-based breakdown in tool usage. + +**Value:** Multi-client users (Cursor + Claude Code) can see which client uses +which tools most. Essential for the universal proxy vision (B4). + +--- + +### B2. Tool Parameter Frequency Analysis + +**Problem:** We know *which* tools are called and how often, but not *how* they're +used. For example: does the agent call `XcodeGrep` with regex patterns or plain strings? +Does `BuildProject` always target the same tab? + +**Proposal:** Optionally capture and aggregate tool call parameters (anonymized/hashed +where needed). Show top-N parameter patterns per tool. + +**Implementation sketch:** +- Config flag: `capture_params: bool` (default off). +- On request capture, extract `params.arguments` keys (not values by default). +- Store parameter key signatures: e.g. `XcodeGrep(pattern, path, tabIdentifier)`. +- New API: `GET /api/analytics/param-patterns?tool=XcodeGrep`. +- Dashboard: new expandable section in latency table showing common param combos. + +**Value:** Understand agent behavior patterns. "My agent always passes `tabIdentifier` +but never uses `caseSensitive`" - useful for optimizing agent prompts. + +--- + +### B3. Error Classification & Categorization + +**Problem:** Errors are currently tracked as a boolean (error: true/false). There's +no breakdown by error type (-32600 spec violation, -32601 method not found, timeout, etc.) + +**Proposal:** Parse JSON-RPC error codes and messages. Categorize into buckets: +- Protocol errors (-326xx) +- Tool execution errors (Xcode-side failures) +- Timeout errors +- Connection errors + +**Implementation sketch:** +- Extend `record_response` to accept `error_code: Optional[int]` and `error_message: Optional[str]`. +- New metrics: `error_counts_by_code: Dict[int, int]`. +- Dashboard: replace single "Total Errors" KPI with error breakdown doughnut chart. +- Audit table: color-code error column by severity. + +**Value:** "I have 50 errors" is less useful than "I have 48 spec-compliance errors +and 2 timeouts." Directly actionable for debugging. + +--- + +## C. Analytics & Intelligence + +### C1. Usage Heatmap + +**Problem:** No visibility into *when* tools are used. Is the agent most active +during code reviews? At night during batch operations? + +**Proposal:** Hour-of-day x day-of-week heatmap showing tool call density. +Similar to GitHub's contribution graph but for MCP usage. + +**Implementation sketch:** +- Backend: Aggregate audit entries by (hour, weekday) buckets. +- New API: `GET /api/analytics/heatmap?days=30`. +- Frontend: HTML table/CSS grid with color intensity mapping. No extra library. + +**Value:** Understand usage patterns. Identify peak hours. Plan maintenance windows. + +--- + +### C2. Tool Correlation Analysis (Workflow Patterns) + +**Problem:** We see individual tool calls but not the workflows they form. +Agents typically follow patterns: `ListWindows -> Read -> Update -> Build`. + +**Proposal:** Detect and display common tool call sequences (n-grams). +Show the top-10 most frequent 2-tool and 3-tool sequences. + +**Implementation sketch:** +- Backend: Sliding window over audit entries within a session. + Count bigrams (toolA -> toolB) and trigrams. +- New API: `GET /api/analytics/workflows?n=2&limit=10`. +- Frontend: Sankey diagram or simple ranked list with flow arrows. + +**Value:** Reveals agent behavior patterns. "70% of sessions start with +ListWindows -> Grep" - insights for optimizing agent instructions or MCP server config. + +--- + +### C3. Latency Anomaly Detection + +**Problem:** Latency spikes are visible in the chart but require manual watching. +A slow `BuildProject` at 3AM goes unnoticed. + +**Proposal:** Simple statistical anomaly detection: flag tool calls with latency +> mean + 2*stddev for that tool. Show alerts in the dashboard. + +**Implementation sketch:** +- Backend: On each `record_response`, compare latency against running stats. + If anomalous, set flag in audit entry. +- Dashboard: "Anomalies" badge on KPI bar. Click to see recent anomalous calls. +- Optional: WebSocket push for real-time anomaly notification (browser toast). + +**Value:** Passive monitoring. Catch performance regressions early without +constantly watching the dashboard. + +--- + +### C4. Daily/Weekly Summary Digest + +**Problem:** Dashboard is real-time only. No persistent summary for "what happened +this week." + +**Proposal:** Generate periodic summary snapshots stored in SQLite. Expose via +API and optional email/webhook notification. + +**Implementation sketch:** +- Backend scheduler (simple `threading.Timer` loop): every 24h, snapshot current + metrics into `daily_summaries` table. +- New API: `GET /api/analytics/summary?period=daily&days=7`. +- Frontend: new "History" tab showing daily cards with key stats and trends + (up/down arrows vs previous period). + +**Value:** Longitudinal view. "Tool usage increased 40% this week after I enabled +the new agent prompt." Compare periods without raw data exports. + +--- + +## D. Universal MCP Proxy (mcpproxy) + +### Vision + +The current wrapper is Xcode-specific: it wraps `xcrun mcpbridge` and fixes +`structuredContent` compliance. But the **architecture** is already a generic +stdin/stdout MCP proxy with metrics/audit/dashboard bolted on. + +The idea: extract and generalize this into a **universal MCP analytics proxy** +that works with *any* MCP server. Think of it as an "MCP Observatory" - +wrap any server, get full observability for free. + +``` +┌────────────┐ MCP ┌──────────────┐ MCP ┌──────────────┐ +│ MCP Client │ ◄────────► │ mcpproxy │ ◄────────► │ ANY MCP │ +│ (Cursor, │ stdin/ │ (universal │ stdin/ │ Server │ +│ Zed, etc) │ stdout │ proxy) │ stdout │ (filesystem, │ +│ │ │ │ │ github, db, │ +│ │ │ ┌─────────┐ │ │ custom...) │ +│ │ │ │ Web UI │ │ │ │ +│ │ │ │Dashboard│ │ │ │ +│ │ │ └─────────┘ │ │ │ +└────────────┘ └──────────────┘ └──────────────┘ +``` + +### D1. Core: Generic MCP Proxy Mode + +**Proposal:** Add a `--wrap` flag (or make it the default mode) that proxies +any MCP server command, not just `xcrun mcpbridge`. + +```bash +# Current (Xcode-specific): +mcpbridge-wrapper --web-ui + +# Proposed (universal): +mcpproxy --wrap "npx @modelcontextprotocol/server-filesystem /tmp" --web-ui +mcpproxy --wrap "python -m mcp_server_github" --web-ui +mcpproxy --wrap "docker run -i my-mcp-server" --web-ui +mcpproxy --wrap "xcrun mcpbridge" --web-ui --fix-structured-content +``` + +**Implementation sketch:** +- Refactor `bridge.py`: accept arbitrary command instead of hardcoded `xcrun mcpbridge`. +- Move `structuredContent` fix into an optional transform plugin (`--fix-structured-content`). +- Keep backward compatibility: bare `mcpbridge-wrapper` still wraps mcpbridge. +- New entrypoint: `mcpproxy` (or alias) with `--wrap `. + +**Value:** Every MCP server gets free analytics. The MCP ecosystem lacks +observability tooling - this fills that gap. + +--- + +### D2. Multi-Server Proxy Hub + +**Proposal:** Proxy multiple MCP servers simultaneously through one dashboard. +Each server gets its own metrics namespace but shares a single Web UI. + +```bash +mcpproxy \ + --server xcode="xcrun mcpbridge" \ + --server github="python -m mcp_server_github" \ + --server fs="npx @modelcontextprotocol/server-filesystem /tmp" \ + --web-ui --web-ui-port 8080 +``` + +**Implementation sketch:** +- Config file (`mcpproxy.yaml`) listing servers with names and commands. +- Each server runs as a separate bridge subprocess with its own stdin/stdout. +- Metrics tagged by server name. Dashboard shows per-server tabs or merged view. +- MCP client connects to the proxy which routes `tools/call` to the correct server + based on tool name prefixes or a registry built from `tools/list` responses. + +**Value:** Single pane of glass for all MCP servers. One dashboard to monitor +your entire MCP setup. + +--- + +### D3. Protocol-Level Analytics + +**Proposal:** Deep MCP protocol analysis beyond tool calls. Track: +- Initialize/shutdown lifecycle +- Capabilities negotiation +- `tools/list` frequency (some clients call this repeatedly) +- Notification patterns +- Protocol version compatibility + +**Implementation sketch:** +- Parse ALL JSON-RPC messages (not just `tools/call` responses). +- Categorize by method: `initialize`, `tools/list`, `tools/call`, notifications. +- New dashboard section: "Protocol Overview" showing message type distribution. +- Detect protocol anti-patterns (e.g. client calling `tools/list` every 5 seconds). + +**Value:** Understand MCP protocol behavior. Debug interop issues between clients +and servers. Essential for MCP server developers. + +--- + +### D4. Transform Pipeline (Plugin System) + +**Proposal:** Make response transformations pluggable. The `structuredContent` fix +is just one transform. Others could include: +- Response caching (repeat identical tool calls) +- Rate limiting (prevent runaway agents) +- Response filtering (redact sensitive data) +- Schema validation (verify MCP compliance before forwarding) +- Logging enrichment (add trace IDs) + +**Implementation sketch:** +- Define `Transform` protocol: `def transform(message: dict) -> dict`. +- Chain of transforms applied in order. +- Config-driven: list transforms in config file. +- Built-in transforms: `fix-structured-content`, `validate-schema`, `rate-limit`. +- User transforms: Python files loaded dynamically. + +**Value:** Extensible proxy. Users can add custom behavior without forking. +The `structuredContent` fix becomes just another plugin. + +--- + +### D5. Comparative Analytics Across Servers + +**Proposal:** When proxying multiple servers (D2), enable cross-server analytics: +- Which server has the highest error rate? +- Latency comparison across servers. +- Tool overlap detection (multiple servers offering similar tools). +- Usage balance: is one server handling 90% of traffic? + +**Implementation sketch:** +- Cross-server metrics aggregation in shared_metrics. +- Dashboard: comparison charts with server selector dropdowns. +- Alert: "Server X error rate > 10% while others are < 1%." + +**Value:** Operational intelligence for complex MCP setups. + +--- + +## E. Prioritized Roadmap Suggestion + +| Priority | Feature | Effort | Impact | Category | +|----------|---------|--------|--------|----------| +| **P0** | D1: Generic MCP Proxy Mode | Medium | Very High | Universal Proxy | +| **P0** | B1: Client Identification | Small | High | Data Collection | +| **P1** | A1: Tool Call Detail Inspector | Medium | High | UX | +| **P1** | B3: Error Classification | Small | High | Data Collection | +| **P1** | A2: Session Timeline View | Medium | High | UX | +| **P1** | D3: Protocol-Level Analytics | Medium | High | Universal Proxy | +| **P2** | C2: Tool Correlation (Workflows) | Medium | Medium | Analytics | +| **P2** | D4: Transform Pipeline | Large | High | Universal Proxy | +| **P2** | C1: Usage Heatmap | Small | Medium | Analytics | +| **P2** | A3: Theme Toggle | Small | Medium | UX | +| **P3** | D2: Multi-Server Hub | Large | Very High | Universal Proxy | +| **P3** | C3: Latency Anomaly Detection | Medium | Medium | Analytics | +| **P3** | C4: Daily/Weekly Digest | Medium | Medium | Analytics | +| **P3** | A4: Keyboard Shortcuts | Small | Low | UX | +| **P3** | B2: Param Frequency Analysis | Medium | Low | Data Collection | +| **P3** | D5: Cross-Server Analytics | Large | Medium | Universal Proxy | + +--- + +## F. Naming & Packaging Thoughts + +If going the universal proxy route, consider: + +- **Package name:** `mcpproxy` or `mcp-observatory` or `mcp-dashboard` +- **Relationship:** XcodeMCPWrapper becomes a *preset* of mcpproxy + (i.e. `mcpproxy --preset xcode` = current behavior) +- **Backward compat:** `mcpbridge-wrapper` / `xcodemcpwrapper` entrypoints + remain, calling `mcpproxy --preset xcode` internally. +- **Separate repo vs monorepo:** Could live in same repo with the Xcode + preset, or be extracted into its own package that XcodeMCPWrapper depends on. + +The cleanest path: keep XcodeMCPWrapper as-is, create `mcpproxy` as a new +package that reuses the webui/metrics/audit modules, and have XcodeMCPWrapper +depend on mcpproxy + add the structuredContent transform. From 3fd5e3b589900a5064149f728cf29b9ea31a10d5 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 13 Feb 2026 17:10:51 +0000 Subject: [PATCH 2/2] Add Phase 11/12 tasks to Workplan and create Universal_Proxy.md Workplan updates: - Phase 11 (Web UI UX): P11-T1 detail inspector, P11-T2 session timeline, P11-T3 theme toggle, P11-T4 keyboard shortcuts - Phase 12 (Data Collection): P12-T1 client identification, P12-T2 param frequency analysis, P12-T3 error classification New file SPECS/Universal_Proxy.md: - Analytics features (heatmap, workflow correlation, anomaly detection, digests) - Universal MCP proxy vision (generic proxy, multi-server hub, transform pipeline, protocol analytics, cross-server comparison) - Prioritized roadmap and packaging strategy https://claude.ai/code/session_01WHGdcPbiap1HQddHkFd4wS --- SPECS/Universal_Proxy.md | 264 +++++++++++++++++++++++++++++++++++++++ SPECS/Workplan.md | 174 ++++++++++++++++++++++++++ 2 files changed, 438 insertions(+) create mode 100644 SPECS/Universal_Proxy.md diff --git a/SPECS/Universal_Proxy.md b/SPECS/Universal_Proxy.md new file mode 100644 index 00000000..1041eb07 --- /dev/null +++ b/SPECS/Universal_Proxy.md @@ -0,0 +1,264 @@ +# Universal MCP Proxy — Vision & Roadmap + +## 1. Overview + +The current XcodeMCPWrapper is Xcode-specific: it wraps `xcrun mcpbridge` and fixes +`structuredContent` compliance. But the **architecture** — stdin/stdout bridge, +response transformation, metrics collection, audit logging, WebSocket dashboard — +is already a generic MCP proxy with one preset baked in. + +This document outlines the vision for extracting and generalizing the architecture +into a **universal MCP analytics proxy** (working name: `mcpproxy`) that works +with *any* MCP server. Think of it as an "MCP Observatory" — wrap any server, +get full observability for free. + +``` +┌────────────┐ MCP ┌──────────────┐ MCP ┌──────────────┐ +│ MCP Client │ ◄────────► │ mcpproxy │ ◄────────► │ ANY MCP │ +│ (Cursor, │ stdin/ │ (universal │ stdin/ │ Server │ +│ Zed, etc) │ stdout │ proxy) │ stdout │ (filesystem, │ +│ │ │ │ │ github, db, │ +│ │ │ ┌─────────┐ │ │ custom...) │ +│ │ │ │ Web UI │ │ │ │ +│ │ │ │Dashboard│ │ │ │ +│ │ │ └─────────┘ │ │ │ +└────────────┘ └──────────────┘ └──────────────┘ +``` + +--- + +## 2. Analytics & Intelligence Features + +These features enhance the dashboard with deeper analytical capabilities +that apply to any MCP server (not Xcode-specific). + +### 2.1 Usage Heatmap + +**Problem:** No visibility into *when* tools are used. Is the agent most active +during code reviews? At night during batch operations? + +**Proposal:** Hour-of-day × day-of-week heatmap showing tool call density. +Similar to GitHub's contribution graph but for MCP usage. + +**Implementation sketch:** +- Backend: Aggregate audit entries by (hour, weekday) buckets. +- New API: `GET /api/analytics/heatmap?days=30`. +- Frontend: HTML table/CSS grid with color intensity mapping. No extra library. + +**Value:** Understand usage patterns. Identify peak hours. Plan maintenance windows. + +--- + +### 2.2 Tool Correlation Analysis (Workflow Patterns) + +**Problem:** We see individual tool calls but not the workflows they form. +Agents typically follow patterns: `ListWindows -> Read -> Update -> Build`. + +**Proposal:** Detect and display common tool call sequences (n-grams). +Show the top-10 most frequent 2-tool and 3-tool sequences. + +**Implementation sketch:** +- Backend: Sliding window over audit entries within a session. + Count bigrams (toolA → toolB) and trigrams. +- New API: `GET /api/analytics/workflows?n=2&limit=10`. +- Frontend: Sankey diagram or simple ranked list with flow arrows. + +**Value:** Reveals agent behavior patterns. "70% of sessions start with +ListWindows → Grep" — insights for optimizing agent instructions or MCP server config. + +--- + +### 2.3 Latency Anomaly Detection + +**Problem:** Latency spikes are visible in the chart but require manual watching. +A slow `BuildProject` at 3AM goes unnoticed. + +**Proposal:** Simple statistical anomaly detection: flag tool calls with latency +> mean + 2×stddev for that tool. Show alerts in the dashboard. + +**Implementation sketch:** +- Backend: On each `record_response`, compare latency against running stats. + If anomalous, set flag in audit entry. +- Dashboard: "Anomalies" badge on KPI bar. Click to see recent anomalous calls. +- Optional: WebSocket push for real-time anomaly notification (browser toast). + +**Value:** Passive monitoring. Catch performance regressions early without +constantly watching the dashboard. + +--- + +### 2.4 Daily/Weekly Summary Digest + +**Problem:** Dashboard is real-time only. No persistent summary for "what happened +this week." + +**Proposal:** Generate periodic summary snapshots stored in SQLite. Expose via +API and optional email/webhook notification. + +**Implementation sketch:** +- Backend scheduler (simple `threading.Timer` loop): every 24h, snapshot current + metrics into `daily_summaries` table. +- New API: `GET /api/analytics/summary?period=daily&days=7`. +- Frontend: new "History" tab showing daily cards with key stats and trends + (up/down arrows vs previous period). + +**Value:** Longitudinal view. "Tool usage increased 40% this week after I enabled +the new agent prompt." Compare periods without raw data exports. + +--- + +## 3. Universal MCP Proxy (mcpproxy) + +### 3.1 Core: Generic MCP Proxy Mode + +**Proposal:** Add a `--wrap` flag (or make it the default mode) that proxies +any MCP server command, not just `xcrun mcpbridge`. + +```bash +# Current (Xcode-specific): +mcpbridge-wrapper --web-ui + +# Proposed (universal): +mcpproxy --wrap "npx @modelcontextprotocol/server-filesystem /tmp" --web-ui +mcpproxy --wrap "python -m mcp_server_github" --web-ui +mcpproxy --wrap "docker run -i my-mcp-server" --web-ui +mcpproxy --wrap "xcrun mcpbridge" --web-ui --fix-structured-content +``` + +**Implementation sketch:** +- Refactor `bridge.py`: accept arbitrary command instead of hardcoded `xcrun mcpbridge`. +- Move `structuredContent` fix into an optional transform plugin (`--fix-structured-content`). +- Keep backward compatibility: bare `mcpbridge-wrapper` still wraps mcpbridge. +- New entrypoint: `mcpproxy` (or alias) with `--wrap `. + +**Value:** Every MCP server gets free analytics. The MCP ecosystem lacks +observability tooling — this fills that gap. + +--- + +### 3.2 Multi-Server Proxy Hub + +**Proposal:** Proxy multiple MCP servers simultaneously through one dashboard. +Each server gets its own metrics namespace but shares a single Web UI. + +```bash +mcpproxy \ + --server xcode="xcrun mcpbridge" \ + --server github="python -m mcp_server_github" \ + --server fs="npx @modelcontextprotocol/server-filesystem /tmp" \ + --web-ui --web-ui-port 8080 +``` + +**Implementation sketch:** +- Config file (`mcpproxy.yaml`) listing servers with names and commands. +- Each server runs as a separate bridge subprocess with its own stdin/stdout. +- Metrics tagged by server name. Dashboard shows per-server tabs or merged view. +- MCP client connects to the proxy which routes `tools/call` to the correct server + based on tool name prefixes or a registry built from `tools/list` responses. + +**Value:** Single pane of glass for all MCP servers. One dashboard to monitor +your entire MCP setup. + +--- + +### 3.3 Protocol-Level Analytics + +**Proposal:** Deep MCP protocol analysis beyond tool calls. Track: +- Initialize/shutdown lifecycle +- Capabilities negotiation +- `tools/list` frequency (some clients call this repeatedly) +- Notification patterns +- Protocol version compatibility + +**Implementation sketch:** +- Parse ALL JSON-RPC messages (not just `tools/call` responses). +- Categorize by method: `initialize`, `tools/list`, `tools/call`, notifications. +- New dashboard section: "Protocol Overview" showing message type distribution. +- Detect protocol anti-patterns (e.g. client calling `tools/list` every 5 seconds). + +**Value:** Understand MCP protocol behavior. Debug interop issues between clients +and servers. Essential for MCP server developers. + +--- + +### 3.4 Transform Pipeline (Plugin System) + +**Proposal:** Make response transformations pluggable. The `structuredContent` fix +is just one transform. Others could include: +- Response caching (repeat identical tool calls) +- Rate limiting (prevent runaway agents) +- Response filtering (redact sensitive data) +- Schema validation (verify MCP compliance before forwarding) +- Logging enrichment (add trace IDs) + +**Implementation sketch:** +- Define `Transform` protocol: `def transform(message: dict) -> dict`. +- Chain of transforms applied in order. +- Config-driven: list transforms in config file. +- Built-in transforms: `fix-structured-content`, `validate-schema`, `rate-limit`. +- User transforms: Python files loaded dynamically. + +**Value:** Extensible proxy. Users can add custom behavior without forking. +The `structuredContent` fix becomes just another plugin. + +--- + +### 3.5 Comparative Analytics Across Servers + +**Proposal:** When proxying multiple servers (3.2), enable cross-server analytics: +- Which server has the highest error rate? +- Latency comparison across servers. +- Tool overlap detection (multiple servers offering similar tools). +- Usage balance: is one server handling 90% of traffic? + +**Implementation sketch:** +- Cross-server metrics aggregation in shared_metrics. +- Dashboard: comparison charts with server selector dropdowns. +- Alert: "Server X error rate > 10% while others are < 1%." + +**Value:** Operational intelligence for complex MCP setups. + +--- + +## 4. Prioritized Roadmap + +| Priority | Feature | Effort | Impact | Section | +|----------|---------|--------|--------|---------| +| **P0** | 3.1: Generic MCP Proxy Mode | Medium | Very High | Universal Proxy | +| **P1** | 3.3: Protocol-Level Analytics | Medium | High | Universal Proxy | +| **P2** | 2.2: Tool Correlation (Workflows) | Medium | Medium | Analytics | +| **P2** | 3.4: Transform Pipeline | Large | High | Universal Proxy | +| **P2** | 2.1: Usage Heatmap | Small | Medium | Analytics | +| **P3** | 3.2: Multi-Server Hub | Large | Very High | Universal Proxy | +| **P3** | 2.3: Latency Anomaly Detection | Medium | Medium | Analytics | +| **P3** | 2.4: Daily/Weekly Digest | Medium | Medium | Analytics | +| **P3** | 3.5: Cross-Server Analytics | Large | Medium | Universal Proxy | + +--- + +## 5. Naming & Packaging + +If going the universal proxy route, consider: + +- **Package name:** `mcpproxy` or `mcp-observatory` or `mcp-dashboard` +- **Relationship:** XcodeMCPWrapper becomes a *preset* of mcpproxy + (i.e. `mcpproxy --preset xcode` = current behavior) +- **Backward compat:** `mcpbridge-wrapper` / `xcodemcpwrapper` entrypoints + remain, calling `mcpproxy --preset xcode` internally. +- **Separate repo vs monorepo:** Could live in same repo with the Xcode + preset, or be extracted into its own package that XcodeMCPWrapper depends on. + +The cleanest path: keep XcodeMCPWrapper as-is, create `mcpproxy` as a new +package that reuses the webui/metrics/audit modules, and have XcodeMCPWrapper +depend on mcpproxy + add the structuredContent transform. + +--- + +## 6. Relationship to Existing Workplan + +- **Phase 11 (UX) and Phase 12 (Data Collection)** tasks are tracked in `SPECS/Workplan.md`. + They enhance the existing dashboard and are prerequisites for several proxy features. +- **This document** covers the broader proxy vision and analytics features that go beyond + the current Xcode-specific scope. +- **Key dependency:** P12-T1 (Client Identification) is a prerequisite for 3.1 (Generic Proxy) + since multi-server/multi-client tracking requires client tagging in the metrics schema. diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index 9f4f2b5e..3769624d 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -52,6 +52,12 @@ Create a Python-based protocol compatibility wrapper that intercepts MCP respons ### Phase 10: Web UI Control & Audit Dashboard **Intent:** Create a web-based dashboard for real-time monitoring, control, and audit logging of the XcodeMCPWrapper. +### Phase 11: Web UI UX Improvements +**Intent:** Enhance the dashboard with better debugging tools, session awareness, theming, and keyboard-driven workflows. + +### Phase 12: Data Collection Enhancements +**Intent:** Enrich collected telemetry with client identity, parameter patterns, and structured error classification for deeper operational insight. + --- ## 3. Tasks @@ -1212,6 +1218,174 @@ Phase 9 Follow-up Backlog --- +### Phase 11: Web UI UX Improvements + +**Intent:** Enhance the dashboard with better debugging tools, session awareness, theming, and keyboard-driven workflows. + +#### P11-T1: Add Tool Call Detail Inspector (Request/Response Viewer) +- **Description:** Add a clickable row expansion or slide-out panel in the audit table that displays the full JSON-RPC request and response payloads. Payloads are syntax-highlighted and collapsible. Backend stores truncated payloads in a bounded ring buffer (last 500, max 64KB each) behind an optional `capture_payload` config flag (default off for privacy). New API: `GET /api/audit/{request_id}/detail` returns `{request: {...}, response: {...}}`. Frontend: click audit row to expand inline or open side panel with pretty-printed JSON. +- **Priority:** P1 +- **Dependencies:** P10-T1 +- **Parallelizable:** yes +- **Outputs/Artifacts:** + - Updated `src/mcpbridge_wrapper/webui/audit.py` - payload capture and storage + - New SQLite table or column for request/response payloads + - New API endpoint in `src/mcpbridge_wrapper/webui/server.py` + - Updated `src/mcpbridge_wrapper/webui/static/dashboard.js` - row expansion UI + - Updated `src/mcpbridge_wrapper/webui/static/dashboard.css` - detail panel styling + - Updated `src/mcpbridge_wrapper/webui/config.py` - `capture_payload` flag + - Tests in `tests/unit/webui/test_audit.py` and `tests/unit/webui/test_server.py` +- **Acceptance Criteria:** + - [ ] `capture_payload: true` in config enables payload storage + - [ ] `GET /api/audit/{request_id}/detail` returns full request/response JSON + - [ ] Clicking an audit row in the dashboard expands to show payload detail + - [ ] Payloads are truncated at 64KB to bound storage + - [ ] Ring buffer retains last 500 payloads and evicts oldest + - [ ] Default behavior (flag off) is unchanged — no payload capture overhead + - [ ] Tests cover payload capture, retrieval, truncation, and ring buffer eviction + +--- + +#### P11-T2: Add Session Timeline View +- **Description:** Add a vertical timeline view that groups tool calls into sessions detected by configurable idle gaps (default 5 min). Each session shows a compact sequence of tool calls with icons, durations, and error badges. New API: `GET /api/sessions` returns `[{id, start, end, tool_count, error_count, tools: [...]}]`. Frontend: new tab/view with vertical timeline using CSS. Each node is a tool call; hover shows summary; click opens detail inspector (P11-T1). +- **Priority:** P1 +- **Dependencies:** P11-T1 +- **Parallelizable:** no +- **Outputs/Artifacts:** + - New module `src/mcpbridge_wrapper/webui/sessions.py` - session detection logic + - New API endpoint `GET /api/sessions` in `src/mcpbridge_wrapper/webui/server.py` + - Updated `src/mcpbridge_wrapper/webui/static/index.html` - timeline tab + - Updated `src/mcpbridge_wrapper/webui/static/dashboard.js` - timeline rendering + - Updated `src/mcpbridge_wrapper/webui/static/dashboard.css` - timeline styling + - Updated `src/mcpbridge_wrapper/webui/config.py` - `session_gap_seconds` setting + - Tests in `tests/unit/webui/test_sessions.py` +- **Acceptance Criteria:** + - [ ] Sessions are detected by idle gap (configurable, default 300s) + - [ ] `GET /api/sessions` returns session list with tool call summaries + - [ ] Dashboard displays vertical timeline with tool call nodes + - [ ] Hover on node shows tool name, latency, error status + - [ ] Click on node opens detail inspector (if P11-T1 payload capture enabled) + - [ ] Sessions update in real-time via existing WebSocket stream + - [ ] Tests cover session boundary detection, edge cases (single-call sessions, zero-gap) + +--- + +#### P11-T3: Add Dashboard Theme Toggle (Dark/Light) +- **Description:** Implement CSS-variable-based theme system with a toggle button in the header. Refactor all hardcoded colors in `dashboard.css` to CSS custom properties on `:root`. Add `[data-theme="light"]` overrides. Store user preference in `localStorage`. Update Chart.js color defaults on theme toggle. +- **Priority:** P2 +- **Dependencies:** P10-T1 +- **Parallelizable:** yes +- **Outputs/Artifacts:** + - Updated `src/mcpbridge_wrapper/webui/static/dashboard.css` - CSS variable refactor + light theme + - Updated `src/mcpbridge_wrapper/webui/static/dashboard.js` - theme toggle logic and Chart.js color sync + - Updated `src/mcpbridge_wrapper/webui/static/index.html` - theme toggle button in header +- **Acceptance Criteria:** + - [ ] All colors in CSS use custom properties (no hardcoded hex in selectors) + - [ ] Toggle button switches between dark and light themes + - [ ] Chart.js chart colors update on theme change without page reload + - [ ] Theme preference persists across page reloads via `localStorage` + - [ ] Default theme matches current dark theme (no visual regression) + +--- + +#### P11-T4: Add Keyboard Shortcuts & Command Palette +- **Description:** Add lightweight keyboard shortcuts for dashboard navigation. `1-4` to focus chart sections, `a` to jump to audit log, `r` to reset metrics (with confirmation), `e` to export JSON, `?` to show shortcut help overlay. Pure JS `keydown` listener with a shortcut map. Small modal overlay for `?` help. No library needed. +- **Priority:** P3 +- **Dependencies:** P10-T1 +- **Parallelizable:** yes +- **Outputs/Artifacts:** + - Updated `src/mcpbridge_wrapper/webui/static/dashboard.js` - shortcut handler + - Updated `src/mcpbridge_wrapper/webui/static/dashboard.css` - help overlay styling + - Updated `src/mcpbridge_wrapper/webui/static/index.html` - help overlay markup +- **Acceptance Criteria:** + - [ ] `?` key opens/closes shortcut help overlay + - [ ] Number keys `1-4` scroll to corresponding chart section + - [ ] `a` key scrolls to audit log section + - [ ] `r` key triggers reset metrics with confirmation dialog + - [ ] `e` key triggers JSON export download + - [ ] Shortcuts are disabled when focus is in an input field (audit filter) + - [ ] Help overlay lists all available shortcuts with descriptions + +--- + +### Phase 12: Data Collection Enhancements + +**Intent:** Enrich collected telemetry with client identity, parameter patterns, and structured error classification for deeper operational insight. + +#### P12-T1: Add MCP Client Identification +- **Description:** Detect the calling MCP client from the `initialize` handshake. The `clientInfo` field in the initialize request contains `{name, version}`. Capture this and tag all subsequent metrics with the client identity. Add `client` column to shared metrics SQLite schema. Dashboard: new KPI card "Active Client" showing the connected client name and version. Charts: optional client-based breakdown in tool usage. +- **Priority:** P0 +- **Dependencies:** P10-T1 +- **Parallelizable:** yes +- **Outputs/Artifacts:** + - Updated `src/mcpbridge_wrapper/__main__.py` - extract `clientInfo` from initialize request + - Updated `src/mcpbridge_wrapper/schemas.py` - add `MCPInitializeParams` model with `clientInfo` + - Updated `src/mcpbridge_wrapper/webui/metrics.py` - `client_name` field in metrics + - Updated `src/mcpbridge_wrapper/webui/shared_metrics.py` - `client` column in SQLite schema + - Updated `src/mcpbridge_wrapper/webui/server.py` - expose client info in metrics summary + - Updated `src/mcpbridge_wrapper/webui/static/index.html` - "Active Client" KPI card + - Updated `src/mcpbridge_wrapper/webui/static/dashboard.js` - render client KPI + - Tests in `tests/unit/test_main.py` and `tests/unit/webui/test_metrics.py` +- **Acceptance Criteria:** + - [ ] `initialize` request `clientInfo.name` and `clientInfo.version` are captured + - [ ] Metrics summary includes `client_name` and `client_version` fields + - [ ] Dashboard displays "Active Client" KPI card (e.g. "Cursor 1.2.3") + - [ ] Metrics reset clears client info + - [ ] If `initialize` has no `clientInfo`, fields default to "unknown" + - [ ] SQLite schema migration is backward-compatible (nullable column) + - [ ] Tests cover initialize parsing, missing clientInfo, and metric tagging + +--- + +#### P12-T2: Add Tool Parameter Frequency Analysis +- **Description:** Optionally capture and aggregate tool call parameter keys (not values by default) for pattern analysis. Config flag `capture_params: bool` (default off). On request capture, extract `params.arguments` key names. Store parameter key signatures per tool (e.g. `XcodeGrep(pattern, path, tabIdentifier)`). New API: `GET /api/analytics/param-patterns?tool=` returns top-N parameter combinations. Dashboard: expandable section in latency table showing common param combos. +- **Priority:** P3 +- **Dependencies:** P12-T1 +- **Parallelizable:** yes +- **Outputs/Artifacts:** + - Updated `src/mcpbridge_wrapper/__main__.py` - extract argument keys from tool call params + - New module or section in `src/mcpbridge_wrapper/webui/metrics.py` - param pattern aggregation + - Updated `src/mcpbridge_wrapper/webui/shared_metrics.py` - `param_keys` column in requests table + - New API endpoint `GET /api/analytics/param-patterns` in `src/mcpbridge_wrapper/webui/server.py` + - Updated `src/mcpbridge_wrapper/webui/config.py` - `capture_params` flag + - Updated `src/mcpbridge_wrapper/webui/static/dashboard.js` - param pattern display + - Tests in `tests/unit/webui/test_metrics.py` +- **Acceptance Criteria:** + - [ ] `capture_params: true` enables parameter key capture + - [ ] Only argument key names are stored (not values) by default + - [ ] `GET /api/analytics/param-patterns?tool=XcodeGrep` returns ranked param combos + - [ ] Dashboard shows expandable param pattern info per tool + - [ ] Default behavior (flag off) is unchanged — no extra capture overhead + - [ ] Tests cover param extraction, aggregation, and API response format + +--- + +#### P12-T3: Add Error Classification & Categorization +- **Description:** Parse JSON-RPC error codes and messages from responses. Categorize into buckets: protocol errors (-326xx), tool execution errors (Xcode-side failures), timeout errors, connection errors. Extend `record_response` to accept `error_code: Optional[int]` and `error_message: Optional[str]`. New metrics: `error_counts_by_code: Dict[int, int]`. Dashboard: replace single "Total Errors" KPI with error breakdown doughnut chart. Audit table: color-code error column by severity. +- **Priority:** P1 +- **Dependencies:** P10-T1 +- **Parallelizable:** yes +- **Outputs/Artifacts:** + - Updated `src/mcpbridge_wrapper/__main__.py` - extract error code and message from responses + - Updated `src/mcpbridge_wrapper/schemas.py` - expose `error.code` and `error.message` accessors + - Updated `src/mcpbridge_wrapper/webui/metrics.py` - `error_counts_by_code` tracking + - Updated `src/mcpbridge_wrapper/webui/shared_metrics.py` - `error_code` and `error_message` columns + - Updated `src/mcpbridge_wrapper/webui/server.py` - expose error breakdown in metrics summary + - Updated `src/mcpbridge_wrapper/webui/static/index.html` - error breakdown chart container + - Updated `src/mcpbridge_wrapper/webui/static/dashboard.js` - error doughnut chart + audit color-coding + - Updated `src/mcpbridge_wrapper/webui/static/dashboard.css` - error severity color classes + - Tests in `tests/unit/webui/test_metrics.py` and `tests/unit/webui/test_shared_metrics.py` +- **Acceptance Criteria:** + - [ ] JSON-RPC error code and message are extracted from error responses + - [ ] Metrics summary includes `error_counts_by_code` map (e.g. `{-32600: 5, -32601: 2}`) + - [ ] Dashboard displays error breakdown doughnut chart alongside or replacing "Total Errors" KPI + - [ ] Audit table error column is color-coded by severity (red for protocol, orange for tool, yellow for timeout) + - [ ] Error categories are defined: protocol (-326xx), tool (positive codes), timeout, unknown + - [ ] Non-error responses leave error code/message as null + - [ ] Tests cover code extraction, categorization, and metric aggregation + +--- + ## 4. Dependency Graph ```