@webtrack/feedback-mcp

Model Context Protocol (MCP) server that exposes Webtrack feedback data to AI agents. The server runs as a standalone stdio process so tools like Claude Code can triage, inspect, and update feedback collected by the universal widget without depending on the main Webtrack webapp.

Status: Package scaffolding is in place. Placeholder tool handlers are registered while full Convex integrations are implemented in subsequent work packages.

Features

• Stdio-based MCP server compatible with Claude Code and other MCP-capable hosts.
• Convex HTTP client wrapper (ConvexClient) with first-class error handling and optional AGENT_SECRET authentication.
• Strict TypeScript configuration targeting modern Node.js runtimes.
• Executable binary entry point published as feedback-mcp.

Requirements

• Node.js 20 or later
• pnpm 9+
• Access to a Convex deployment that hosts the feedback functions described in the universal feedback specification.

Installation

cd packages/feedback-mcp
pnpm install

This installs the MCP SDK and development dependencies required to build the server locally.

Scripts

| Script | Description | | --- | --- | | pnpm build | Compile TypeScript to dist/ (ESM output). | | pnpm start | Run the compiled MCP server (node dist/server.js). | | pnpm dev | Watch & recompile TypeScript sources (handy alongside a separate pnpm start). |

Environment Variables

| Variable | Required | Description | | --- | --- | --- | | CONVEX_URL | ✅ | Base URL of the Convex deployment (e.g. https://<deployment>.convex.cloud). | | AGENT_SECRET | ⬜️ | Optional bearer token validated by Convex HTTP endpoints for agent access. | | CONVEX_TIMEOUT | ⬜️ | Request timeout in milliseconds (defaults to 30000). |

The placeholder tool handlers validate CONVEX_URL on startup so configuration issues surface immediately.

Claude Code Integration

Claude Code reads MCP server definitions from claude_desktop_config.json (macOS / Windows) or ~/.config/claude/claude_config.json (Linux). Add an entry that launches the built binary or a dev script:

{
  "mcpServers": {
    "webtrack-feedback": {
      "transport": {
        "type": "stdio",
        "command": "pnpm",
        "args": ["--dir", "/path/to/repo/packages/feedback-mcp", "start"],
        "env": {
          "CONVEX_URL": "https://your-deployment.convex.cloud",
          "AGENT_SECRET": "optional-shared-secret"
        }
      }
    }
  }
}

Tips:

• Replace /path/to/repo with the absolute path on your workstation.
• Use pnpm dev in another terminal to recompile automatically while Claude Code restarts the server.
• When distributing to teammates, prefer packaging the compiled binary (dist/server.js) so the command can be ["node", "/path/to/dist/server.js"].

Tool Surface (planned)

| Tool | Purpose | Notes | | --- | --- | --- | | list | List feedback entries filtered by status, project, route, etc. | Maps to feedback:listByStatus Convex query. | | get | Retrieve a single feedback record including screenshot URLs. | Maps to feedback:list (filtered) or dedicated query. | | update | Transition a feedback item through the state machine. | Uses feedback:updateStatus Convex mutation. |

Each tool will live under src/tools/ with JSON Schema input definitions and structured outputs so Claude Code can render results intelligently.

Development Notes

• TypeScript uses strict mode with NodeNext module resolution (tsconfig.json).
• The package exports a feedback-mcp binary so downstream tooling can reference it directly once published.
• Commit any spec-aligned changes to docs/project/phases/07-UniversalFeedbackMCP/ to keep the phase documentation current.

Next Steps

• Implement the list/get/update tool handlers using the shared ConvexClient.
• Add Vitest coverage for MCP tool behavior and Convex error scenarios.
• Flesh out README with troubleshooting guidance once the tools are feature-complete.