---
name: MCP Grid Consolidated Review
overview: Consolidated findings from 3 independent review agents analyzing code completeness, user requirements alignment, and security/deployment readiness. This plan covers what's done, what's broken, what's missing, and the prioritized execution path to go public.
todos:
  - id: security-xss
    content: "Phase 0: Fix XSS in dashboardPanel.ts and site/index.html (escape HTML, add CSP)"
    status: pending
  - id: security-errors
    content: "Phase 0: Replace str(e) with generic messages in management.py API responses"
    status: pending
  - id: security-gitignore
    content: "Phase 0: Add chat export and CONTEXT_HANDOFF.md to .gitignore, ensure no real tokens committed"
    status: pending
  - id: git-commit-push
    content: "Phase 0: Git commit and push all 3 repos (mcp-grid-ws, public, wiki)"
    status: pending
  - id: install-first-model
    content: "Phase 1: Implement install-first model -- Marketplace shows catalog, My Servers only shows user-installed"
    status: pending
  - id: webview-add-server
    content: "Phase 1: Build webview panel for Add Server (OpenAPI, manual, WebSocket) replacing command palette"
    status: pending
  - id: configure-ux
    content: "Phase 1: Improve Configure Server flow with server name, option name, current value, confirmation"
    status: pending
  - id: fix-ci-workflows
    content: "Phase 1: Fix validate-site job for missing branch, fix release.yml empty artifacts guard"
    status: pending
  - id: cloudflare-dns
    content: "Phase 1: Configure Cloudflare DNS CNAME for grid.mcpstudio.qabots.diy"
    status: pending
  - id: e2e-verification
    content: "Phase 1: Full E2E test: fresh install, bridge start, panels load, activate, call tool, deactivate"
    status: pending
  - id: catalog-sync
    content: "Phase 2: Implement hourly catalog sync in extension from gh-pages manifest.json"
    status: pending
  - id: force-update
    content: "Phase 2: Implement force-update mechanism checking security.force_update_versions"
    status: pending
  - id: secret-storage
    content: "Phase 2: Use VS Code SecretStorage API for encrypted credential persistence"
    status: pending
  - id: dashboard-metrics
    content: "Phase 2: Add success/failure counts and tokenization stats to dashboard"
    status: pending
  - id: swagger-import
    content: "Phase 3: Import and test Open Arena Swagger spec"
    status: pending
  - id: auth-plugins
    content: "Phase 3: Build OAuth2 auth flow helpers for Microsoft and GitHub"
    status: pending
  - id: first-release
    content: "Phase 4: Set up GitHub secrets, tag v1.0.0-beta-rc, publish to PyPI and VS Code Marketplace"
    status: pending
isProject: false
---

# MCP Grid Studio -- Consolidated 3-Agent Review and Execution Plan

## Repository Overview

- **mcp-grid-ws** (PRIVATE): Python bridge (FastMCP) + VS Code/Cursor extension. Core codebase.
- **mcp-marketplace-grid-studio** (PUBLIC): Documentation, releases, GitHub Pages marketplace site, catalog JSON.
- **mcp-marketplace-grid-studio.wiki**: 16 GitHub Wiki documentation pages.

---

## What Is DONE (Confirmed by All 3 Agents)

- All 21 MCP tools implemented (9 core + 6 OpenAPI + 6 Enterprise Platform) -- no stubs
- All tool parameters use `Annotated[type, Field(description="...")]` for proper agent display
- Extension sidebar: 4 panels (Servers, Instances, Metrics, Marketplace) implemented
- Dashboard webview panel with metrics grid and instance/server tables
- Management REST API with all required endpoints including `POST /api/instances`
- Bridge auto-setup in `~/.cursor/mcp.json` preferring `mcp-grid` binary over `python3 -m`
- Port binding retry with exponential backoff and `SO_REUSEADDR`
- Config passed to child servers via `MCP_CFG_<KEY>` environment variables
- Version strings updated to `1.0.0-beta-rc` / `1.0.0rc1` across both repos
- CI/CD workflows created for both repos (ci.yml, build.yml, release.yml, deploy-catalog.yml)
- Public repo: catalog JSON (11 servers), gh-pages site (index.html), build script
- Wiki: 16 pages covering all aspects (Home, Architecture, Tools, Security, etc.)
- Extension README with full feature documentation and 21-tool reference table

---

## SECURITY ISSUES (Must Fix Before Public -- Agent 3)

### S1. XSS in Dashboard WebView (CRITICAL)

- **File:** [dashboardPanel.ts](mcp-grid-ws/extension/src/panels/dashboardPanel.ts) lines 173-205
- **Issue:** `innerHTML` used with unescaped dynamic data (`instance_id`, `server_id`, `tool_name`, `server.name`)
- **Fix:** Escape all dynamic values before inserting into HTML, or use `textContent`. Add Content Security Policy to webview.

### S2. Raw Exception Leaking in API Responses (HIGH)

- **File:** [management.py](mcp-grid-ws/src/mcp_bridge/api/management.py) lines 93, 138, 154, 202-207
- **Issue:** `return JSONResponse({"error": str(e)})` exposes internal paths, DB errors, stack traces
- **Fix:** Return generic error messages to clients. Keep detailed logging server-side only.

### S3. Chat Export Contains Real Tokens (CRITICAL)

- **File:** `cursor_mcp_server_plugin_feasibility_di.md` in workspace root
- **Issue:** Contains real JWT tokens, Azure DevOps PATs, session cookies from the browser capture session
- **Fix:** Add to `.gitignore` immediately. Never commit this file. Ensure `CONTEXT_HANDOFF.md` also has no real tokens.

### S4. gh-pages Site innerHTML XSS (MEDIUM)

- **File:** [index.html](mcp-marketplace-grid-studio/site/index.html) lines 256-276
- **Issue:** Catalog data rendered via `innerHTML` without escaping
- **Fix:** Use `textContent` for user-facing strings, or sanitize before insertion.

### S5. WebSocket Error Swallowed Silently (LOW)

- **File:** [management.py](mcp-grid-ws/src/mcp_bridge/api/management.py) line 322-324
- **Issue:** `except Exception: pass` in websocket endpoint
- **Fix:** Log the error, close the connection cleanly.

---

## USER REQUIREMENTS NOT MET (Agent 2 -- 16 Items)

### UX Critical (User Explicitly Frustrated):

1. **Webview panels for Add Server** -- still uses command palette. User said: "I don't like... our plugin should be able to give a pop-up window"
2. **Install-first model** -- 11 servers auto-listed in Servers panel. User said: "why are we keeping those servers in the server list unless the user adds them"
3. **Install button visibility** -- inline Install exists but user still finds it hidden
4. **Configure flow clarity** -- "where did it say for which one it saved?" still unresolved
5. **E2E verification** -- User said "ensure everything has to work out - No Exceptions" -- not confirmed

### Enterprise/Client:

1. **Open Arena Swagger import** from `aiopenarena.thomsonreuters.com/swagger-ui.html` -- not attempted
2. **Auth provider plugins** (Microsoft OAuth2, GitHub PAT, token vs browser) -- not implemented
3. **Open Arena connection webview** (base URL, auth mode, WebSocket schema capture) -- not built

### Infrastructure:

1. **Cloudflare DNS** for `grid.mcpstudio.qabots.diy` -- not configured
2. **Git commit and push** all 3 repos -- uncommitted changes exist
3. **Encrypted config storage** via VS Code SecretStorage API -- not implemented
4. **Hourly catalog sync** from gh-pages manifest -- not implemented
5. **Force-update mechanism** for security patches -- not implemented

### Polish:

1. **Dashboard tokenization stats and cost estimation** -- not implemented
2. **Video/GIF demo** for README -- placeholder not added
3. **Marketplace admin portal** with login -- not built

---

## DEPLOYMENT BLOCKERS (Agent 3)

### CI Workflow Issues:

- **validate-site job** in `mcp-marketplace-grid-studio/.github/workflows/ci.yml` checks out `mcp-grid-marketplace-pages` branch which may not exist on first run. Needs conditional check.
- **release.yml** in public repo: when download step is disabled (`if: false`), `files: artifacts/*` is empty, which may cause the release step to fail or produce no assets. Needs guard.

### Missing Secrets:

- `PYPI_API_TOKEN` needed in mcp-grid-ws repo for PyPI publish
- `VSCE_PAT` needed for VS Code Marketplace publish (currently disabled)
- `PRIVATE_REPO_PAT` needed in public repo for cross-repo artifact download (currently disabled)

### DNS:

- Cloudflare CNAME for `grid.mcpstudio.qabots.diy` pointing to `ib-qa.github.io` not configured

---

## FEATURE GAPS (Agent 1 -- 19 Items)

Cross-referencing chat discussions with actual code:


| #   | Gap                                                   | Priority        |
| --- | ----------------------------------------------------- | --------------- |
| 1   | Cloudflare DNS setup                                  | P0              |
| 2   | Extension hourly catalog sync                         | P0              |
| 3   | Force-update for security patches                     | P0              |
| 4   | Webview panels for Add Server (not command palette)   | P1              |
| 5   | Install-first model (servers only after user adds)    | P1              |
| 6   | Encrypted config storage (SecretStorage API)          | P1              |
| 7   | Configure UX: clear feedback on which server/option   | P1              |
| 8   | Dashboard: success/failure counts, tokenization, cost | P1              |
| 9   | Open Arena Swagger import                             | P1              |
| 10  | Auth provider plugins (Microsoft, GitHub)             | P1              |
| 11  | Push notification from admin config updates           | P2              |
| 12  | Marketplace admin portal with login                   | P2              |
| 13  | TR AI Platform dedicated plugin                       | P2              |
| 14  | Open Arena connection webview                         | P2              |
| 15  | Video/GIF demo for README                             | P2              |
| 16  | Chat UI for workflow chains                           | P3 (Roadmap)    |
| 17  | qabots.diy homepage                                   | P3 (Roadmap)    |
| 18  | Publish to PyPI                                       | P3 (after beta) |
| 19  | Publish to VS Code Marketplace                        | P3 (after beta) |


---

## EXECUTION PLAN (Prioritized Phases)

### Phase 0: Security and Git Hygiene (IMMEDIATE)

- Fix XSS in dashboardPanel.ts (escape HTML, add CSP)
- Fix XSS in site/index.html (use textContent)
- Replace `str(e)` with generic messages in management.py
- Add `cursor_mcp_server_plugin_feasibility_di.md` and `CONTEXT_HANDOFF.md` to `.gitignore`
- Fix WebSocket silent exception swallowing
- Git commit and push all 3 repos

### Phase 1: Core UX Fixes (Before Public Beta)

- Implement install-first model: Marketplace shows catalog, "My Servers" only shows user-installed
- Build webview panel for "Add Server" (OpenAPI spec, manual config, WebSocket endpoint)
- Improve Configure Server flow: show server name, option name, current value, save confirmation
- Fix CI validate-site job to handle missing gh-pages branch
- Fix release.yml guard for empty artifacts
- Configure Cloudflare DNS CNAME
- Full E2E verification: fresh install, bridge start, panel load, activate server, call tool, deactivate

### Phase 2: Marketplace Infrastructure

- Implement hourly catalog sync in extension (fetch manifest.json, compare checksum, update local catalog)
- Implement force-update mechanism (check `security.force_update_versions`)
- Implement SecretStorage for encrypted credential persistence
- Add dashboard metrics: tool call success/failure counts, tokenization stats placeholder

### Phase 3: Enterprise Features

- Import and test Open Arena Swagger spec
- Build OAuth2 auth flow helpers for Microsoft and GitHub
- Build Open Arena connection webview (base URL, auth mode, WebSocket schema)
- Create standalone TR AI Platform plugin scaffold

### Phase 4: Polish and Publish

- Add video/GIF demo to README (user to capture)
- Set up GitHub secrets (PYPI_API_TOKEN, VSCE_PAT, PRIVATE_REPO_PAT)
- First tagged release (v1.0.0-beta-rc)
- Publish to PyPI (mcp-grid)
- Publish VSIX to VS Code Marketplace

---

## KEY USER DECISIONS TO HONOR

These are explicit decisions the user made that must NOT be overridden:

- `qabots.diy` = IB-QA homepage; `grid.mcpstudio.qabots.diy` = marketplace
- AI Platform capability is a plugin feature, NOT on the web portal
- Codebase repo stays PRIVATE; public repo is for docs/releases/marketplace only
- Chat UI for workflow chains is a FUTURE/SEPARATE plugin
- Never expose config location to users
- Never list servers before user explicitly installs them
- Never use command palette for multi-step config (use webview panels)
- Version string: `1.0.0-beta-rc` (extension/catalog) / `1.0.0rc1` (pyproject.toml PEP 440)
- CI should not expose unnecessary artifacts

