@clip-qa/mcp-server

MCP server for clip.qa bug reports. Access, search, and annotate bug reports directly from Claude Code, Cursor, or Windsurf.

Quick Start

npx @clip-qa/mcp-server --api-key sk-your-key

Add to Claude Code

claude mcp add clip-qa -- npx @clip-qa/mcp-server --api-key sk-your-key

Add to Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "clip-qa": {
      "command": "npx",
      "args": ["@clip-qa/mcp-server", "--api-key", "sk-your-key"]
    }
  }
}

Environment Variable

Instead of --api-key, you can set:

export CLIP_QA_API_KEY=sk-your-key

Public Mode (No Key)

Without an API key, the server runs in read-only mode with access to public reports only.

Tools

| Tool | Description | Auth Required | |------|-------------|:---:| | get_report | Full bug report in markdown format | No | | get_report_for_llm | Optimized format with OCR, frame changes, transcript — everything an LLM needs to fix the bug | No | | list_reports | Paginated list with severity/project filters | No | | search_reports | Text search across title, behavior, steps, screen name, root cause | No | | get_report_diff | Compare two reports side-by-side (regression detection) | No | | get_project_summary | Aggregate stats: report count, severity distribution, recent bugs | No | | create_comment | Add a comment to a report (e.g., "Found root cause: ...") | Yes | | link_fix | Associate a commit/PR with a report | Yes |

Example Prompts

Find all critical bugs in my-app from the last week

What's the root cause of report abc-123?

Compare reports xyz and abc — is this a regression?

Get the LLM-optimized version of report abc-123 and fix the bug

Add a comment to report abc-123: "Root cause is null pointer in AuthService.login()"

Link commit a1b2c3d to report abc-123 as the fix

Quick start

npx @clip-qa/mcp-server login

This opens your browser. Sign in and approve the workspace you want to connect. Your token is saved to ~/.clipqa/auth.json (mode 0600).

Legacy: API keys

If you have an existing API key, you can still use it:

CLIP_QA_API_KEY=sk-... npx @clip-qa/mcp-server

Architecture

The MCP server connects to the same Firestore database used by the web platform (web/src/lib/firebase/firestore.ts) and the Flutter app (lib/services/sharing/report_sharing_service.dart). Reports are written by the mobile app via lib/state/report_generation_notifier.dart and the Chrome extension, then read/searched by the MCP server.

Key internal modules:

• src/firestore.ts — Firestore queries (shared schema with web/src/contracts/report.ts)
• src/auth.ts — API key validation and Firebase Auth token verification
• src/pii-redact.ts — strips PII before exposing report data (emails, IPs, credit cards). Same redaction logic applied in web/src/lib/export-llm.ts
• src/index.ts — MCP tool definitions, rate limiting, caching

Development

cd packages/mcp-server
npm install
npm run build
npm test

Local Testing

# Run directly
node dist/index.js --api-key sk-your-key

# Or with Claude Code
claude mcp add clip-qa-dev -- node /path/to/packages/mcp-server/dist/index.js