super-feedback-mcp 0.1.0

package/README.md

@@ -0,0 +1,145 @@
+# Super Feedback MCP Server
+
+An MCP (Model Context Protocol) server that enables AI agents in Cursor to query and resolve client feedback from Super Feedback projects.
+
+## Installation
+
+```bash
+cd mcp-server
+npm install
+npm run build
+```
+
+## Configuration
+
+Add to your Cursor MCP settings (`~/.cursor/mcp.json` or workspace settings):
+
+```json
+{
+  "mcpServers": {
+    "super-feedback": {
+      "command": "node",
+      "args": ["/path/to/super-feedback/mcp-server/dist/index.js"],
+      "env": {
+        "SUPER_FEEDBACK_ACCESS_CODE": "your-project-access-code",
+        "SUPER_FEEDBACK_ADMIN_CODE": "your-project-admin-code"
+      }
+    }
+  }
+}
+```
+
+Or if published to npm:
+
+```json
+{
+  "mcpServers": {
+    "super-feedback": {
+      "command": "npx",
+      "args": ["super-feedback-mcp"],
+      "env": {
+        "SUPER_FEEDBACK_ACCESS_CODE": "your-project-access-code",
+        "SUPER_FEEDBACK_ADMIN_CODE": "your-project-admin-code"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `SUPER_FEEDBACK_ACCESS_CODE` | Yes* | Your project's access code (for reading feedback) |
+| `SUPER_FEEDBACK_ADMIN_CODE` | Yes* | Your project's admin code (required for marking resolved) |
+| `CONVEX_URL` | No | Custom Convex HTTP URL (defaults to production). Use `.convex.site` domain, not `.convex.cloud` |
+
+*At least one of `ACCESS_CODE` or `ADMIN_CODE` is required. For full functionality (read + resolve), provide both.
+
+**Where to find these codes:**
+- Go to your Super Feedback dashboard
+- Select your project
+- Click "Settings" or the gear icon
+- Copy the "Access Code" and "Admin Code"
+
+## Available Tools
+
+### 1. `get_open_feedback`
+
+Retrieves all open (unresolved) feedback comments for your project.
+
+**Parameters:**
+- `includeResolved` (boolean, optional): Include resolved comments too
+- `pageFilter` (string, optional): Filter to a specific page path (e.g., `/pricing`)
+
+**Returns:**
+- Project name
+- Total count of matching feedback
+- Array of feedback items with:
+  - Feedback text
+  - Element context (tag, text, test IDs, CSS classes)
+  - Page URL and extracted route path
+  - Hints for locating code (possible file paths, search terms)
+
+### 2. `mark_feedback_resolved`
+
+Marks a feedback comment as resolved after you've fixed the issue.
+
+**Parameters:**
+- `commentId` (string): The comment ID to mark as resolved
+
+### 3. `get_feedback_details`
+
+Gets full details for a specific feedback comment.
+
+**Parameters:**
+- `commentId` (string): The comment ID to get details for
+
+## Usage Example
+
+In Cursor, you can ask the AI agent:
+
+> "Get all open feedback for my project and fix them"
+
+The agent will:
+1. Call `get_open_feedback` to retrieve all open comments
+2. For each comment, use the hints to search your codebase
+3. Make the necessary code changes
+4. Call `mark_feedback_resolved` to update the status
+
+## How It Works
+
+The MCP server connects to your Super Feedback project via the Convex API using your access code. It transforms the raw feedback data into AI-friendly format with:
+
+- **Element identification**: Multiple selector strategies (ID, test ID, CSS path, XPath)
+- **Route mapping**: Extracts page path and suggests likely source files
+- **Search hints**: Generates terms to grep for in your codebase
+
+## Development
+
+```bash
+# Watch mode
+npm run dev
+
+# Build
+npm run build
+
+# Test locally
+SUPER_FEEDBACK_ACCESS_CODE=your-access-code \
+SUPER_FEEDBACK_ADMIN_CODE=your-admin-code \
+node dist/index.js
+```
+
+## Troubleshooting
+
+### "ACCESS_CODE environment variable is required"
+
+Make sure you've set the `SUPER_FEEDBACK_ACCESS_CODE` in your MCP config's `env` section.
+
+### "API error: 401"
+
+Your access code is invalid or expired. Check your project settings in Super Feedback.
+
+### "API error: 404"
+
+The project may have been deleted or the Convex deployment URL is incorrect.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import * as z from "zod";
+// Configuration from environment
+// Note: HTTP endpoints use .convex.site, not .convex.cloud
+const CONVEX_URL = process.env.CONVEX_URL || "https://energized-eel-335.convex.site";
+const ACCESS_CODE = process.env.SUPER_FEEDBACK_ACCESS_CODE;
+const ADMIN_CODE = process.env.SUPER_FEEDBACK_ADMIN_CODE;
+if (!ACCESS_CODE && !ADMIN_CODE) {
+    console.error("Error: Either SUPER_FEEDBACK_ACCESS_CODE or SUPER_FEEDBACK_ADMIN_CODE environment variable is required");
+    process.exit(1);
+}
+// API call helper
+async function callConvexAPI(endpoint, options) {
+    const url = `${CONVEX_URL}${endpoint}`;
+    const response = await fetch(url, {
+        ...options,
+        headers: {
+            "Content-Type": "application/json",
+            ...options?.headers,
+        },
+    });
+    if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`API error: ${response.status} - ${error}`);
+    }
+    return response.json();
+}
+// Create MCP server
+const server = new McpServer({
+    name: "super-feedback",
+    version: "0.1.0",
+});
+// Tool 1: Get open feedback
+server.registerTool("get_open_feedback", {
+    title: "Get Open Feedback",
+    description: `Retrieves all open (unresolved) feedback comments for the configured Super Feedback project.
+    
+Returns feedback formatted for AI consumption with:
+- The actual feedback/comment text
+- Element context (tag, text content, CSS classes, test IDs)
+- Page URL and likely file paths
+- Search hints to help locate the code
+
+Use this to understand what changes clients have requested.`,
+    inputSchema: {
+        includeResolved: z.boolean().optional().describe("Include resolved comments too (default: false)"),
+        pageFilter: z.string().optional().describe("Filter to specific page path (e.g., '/pricing')"),
+    },
+    outputSchema: {
+        projectName: z.string(),
+        totalCount: z.number(),
+        comments: z.array(z.object({
+            id: z.string(),
+            index: z.number(),
+            feedback: z.string(),
+            author: z.string(),
+            status: z.string(),
+            createdAt: z.string(),
+            element: z.any().nullable(),
+            page: z.object({
+                url: z.string(),
+                path: z.string(),
+            }),
+            hints: z.object({
+                possibleFiles: z.array(z.string()),
+                searchTerms: z.array(z.string()),
+            }),
+        })),
+    },
+}, async ({ includeResolved = false, pageFilter }) => {
+    try {
+        // Build query params
+        const params = new URLSearchParams();
+        if (ACCESS_CODE)
+            params.set("accessCode", ACCESS_CODE);
+        if (ADMIN_CODE)
+            params.set("adminCode", ADMIN_CODE);
+        if (!includeResolved)
+            params.set("status", "open");
+        if (pageFilter)
+            params.set("page", pageFilter);
+        // Use the AI-optimized endpoint
+        const response = await callConvexAPI(`/api/feedback/ai?${params.toString()}`);
+        const output = {
+            projectName: response.project?.name || "Unknown Project",
+            totalCount: response.totalCount,
+            comments: response.comments,
+        };
+        // Create human-readable summary
+        const summary = response.comments.map(c => `#${c.index} [${c.status}] "${c.feedback}" on <${c.element?.tag || "element"}> "${c.element?.text || ""}" (${c.page.path})`).join("\n");
+        return {
+            content: [{
+                    type: "text",
+                    text: `Found ${response.totalCount} feedback item(s):\n\n${summary}\n\nFull data available in structuredContent.`,
+                }],
+            structuredContent: output,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+            content: [{ type: "text", text: `Error fetching feedback: ${message}` }],
+            isError: true,
+        };
+    }
+});
+// Tool 2: Mark feedback as resolved
+server.registerTool("mark_feedback_resolved", {
+    title: "Mark Feedback Resolved",
+    description: `Marks a feedback comment as resolved after you've fixed the issue.
+    
+Call this after making the code changes to update the feedback status.
+The comment ID can be obtained from get_open_feedback.
+
+Note: Requires SUPER_FEEDBACK_ADMIN_CODE to be configured.`,
+    inputSchema: {
+        commentId: z.string().describe("The comment ID to mark as resolved"),
+    },
+    outputSchema: {
+        success: z.boolean(),
+        message: z.string(),
+    },
+}, async ({ commentId }) => {
+    if (!ADMIN_CODE) {
+        return {
+            content: [{ type: "text", text: "Error: SUPER_FEEDBACK_ADMIN_CODE is required to update feedback status" }],
+            structuredContent: { success: false, message: "Admin code not configured" },
+            isError: true,
+        };
+    }
+    try {
+        await callConvexAPI(`/api/feedback/ai/status`, {
+            method: "POST",
+            body: JSON.stringify({
+                adminCode: ADMIN_CODE,
+                commentId,
+                status: "resolved",
+            }),
+        });
+        const output = {
+            success: true,
+            message: `Comment ${commentId} marked as resolved`,
+        };
+        return {
+            content: [{ type: "text", text: output.message }],
+            structuredContent: output,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            structuredContent: { success: false, message },
+            isError: true,
+        };
+    }
+});
+// Tool 3: Get feedback details
+server.registerTool("get_feedback_details", {
+    title: "Get Feedback Details",
+    description: `Gets full details for a specific feedback comment, including all element data and metadata.
+    
+Use this when you need more context about a specific piece of feedback.`,
+    inputSchema: {
+        commentId: z.string().describe("The comment ID to get details for"),
+    },
+    outputSchema: {
+        found: z.boolean(),
+        comment: z.any().nullable(),
+    },
+}, async ({ commentId }) => {
+    try {
+        // Build query params - get all comments and find the specific one
+        const params = new URLSearchParams();
+        if (ACCESS_CODE)
+            params.set("accessCode", ACCESS_CODE);
+        if (ADMIN_CODE)
+            params.set("adminCode", ADMIN_CODE);
+        params.set("status", "all"); // Get all statuses
+        const response = await callConvexAPI(`/api/feedback/ai?${params.toString()}`);
+        const comment = response.comments?.find(c => c.id === commentId);
+        if (!comment) {
+            return {
+                content: [{ type: "text", text: `Comment ${commentId} not found` }],
+                structuredContent: { found: false, comment: null },
+            };
+        }
+        const output = {
+            found: true,
+            comment: comment,
+        };
+        return {
+            content: [{
+                    type: "text",
+                    text: `Feedback: "${comment.feedback}"\nElement: <${comment.element?.tag || "unknown"}> "${comment.element?.text || ""}"\nPage: ${comment.page.path}\nSearch terms: ${comment.hints.searchTerms.join(", ")}`,
+                }],
+            structuredContent: output,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            structuredContent: { found: false, comment: null },
+            isError: true,
+        };
+    }
+});
+// Start the server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Log to stderr so it doesn't interfere with MCP protocol on stdout
+    console.error("Super Feedback MCP server running...");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "super-feedback-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Super Feedback - enables AI agents to query and resolve client feedback",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "super-feedback-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "feedback",
+    "cursor",
+    "ai-agent"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/index.ts

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import * as z from "zod";
+
+// Types for API responses
+interface FeedbackComment {
+  id: string;
+  index: number;
+  feedback: string;
+  author: string;
+  status: string;
+  createdAt: string;
+  element: {
+    tag?: string;
+    text?: string;
+    testId?: string;
+    id?: string;
+    cssPath?: string;
+    section?: string;
+    nearbyText?: string;
+    selector?: string;
+  } | null;
+  page: { url: string; path: string };
+  hints: { possibleFiles: string[]; searchTerms: string[] };
+  raw?: { elementSelector?: string; elementXPath?: string };
+}
+
+interface FeedbackResponse {
+  project: { id: string; name: string; url: string };
+  isAdmin?: boolean;
+  totalCount: number;
+  comments: FeedbackComment[];
+}
+
+// Configuration from environment
+// Note: HTTP endpoints use .convex.site, not .convex.cloud
+const CONVEX_URL = process.env.CONVEX_URL || "https://energized-eel-335.convex.site";
+const ACCESS_CODE = process.env.SUPER_FEEDBACK_ACCESS_CODE;
+const ADMIN_CODE = process.env.SUPER_FEEDBACK_ADMIN_CODE;
+
+if (!ACCESS_CODE && !ADMIN_CODE) {
+  console.error("Error: Either SUPER_FEEDBACK_ACCESS_CODE or SUPER_FEEDBACK_ADMIN_CODE environment variable is required");
+  process.exit(1);
+}
+
+// API call helper
+async function callConvexAPI<T>(endpoint: string, options?: RequestInit): Promise<T> {
+  const url = `${CONVEX_URL}${endpoint}`;
+  const response = await fetch(url, {
+    ...options,
+    headers: {
+      "Content-Type": "application/json",
+      ...options?.headers,
+    },
+  });
+  
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`API error: ${response.status} - ${error}`);
+  }
+  
+  return response.json();
+}
+
+// Create MCP server
+const server = new McpServer({
+  name: "super-feedback",
+  version: "0.1.0",
+});
+
+// Tool 1: Get open feedback
+server.registerTool(
+  "get_open_feedback",
+  {
+    title: "Get Open Feedback",
+    description: `Retrieves all open (unresolved) feedback comments for the configured Super Feedback project.
+    
+Returns feedback formatted for AI consumption with:
+- The actual feedback/comment text
+- Element context (tag, text content, CSS classes, test IDs)
+- Page URL and likely file paths
+- Search hints to help locate the code
+
+Use this to understand what changes clients have requested.`,
+    inputSchema: {
+      includeResolved: z.boolean().optional().describe("Include resolved comments too (default: false)"),
+      pageFilter: z.string().optional().describe("Filter to specific page path (e.g., '/pricing')"),
+    },
+    outputSchema: {
+      projectName: z.string(),
+      totalCount: z.number(),
+      comments: z.array(z.object({
+        id: z.string(),
+        index: z.number(),
+        feedback: z.string(),
+        author: z.string(),
+        status: z.string(),
+        createdAt: z.string(),
+        element: z.any().nullable(),
+        page: z.object({
+          url: z.string(),
+          path: z.string(),
+        }),
+        hints: z.object({
+          possibleFiles: z.array(z.string()),
+          searchTerms: z.array(z.string()),
+        }),
+      })),
+    },
+  },
+  async ({ includeResolved = false, pageFilter }) => {
+    try {
+      // Build query params
+      const params = new URLSearchParams();
+      if (ACCESS_CODE) params.set("accessCode", ACCESS_CODE);
+      if (ADMIN_CODE) params.set("adminCode", ADMIN_CODE);
+      if (!includeResolved) params.set("status", "open");
+      if (pageFilter) params.set("page", pageFilter);
+      
+      // Use the AI-optimized endpoint
+      const response = await callConvexAPI<FeedbackResponse>(
+        `/api/feedback/ai?${params.toString()}`
+      );
+      
+      const output = {
+        projectName: response.project?.name || "Unknown Project",
+        totalCount: response.totalCount,
+        comments: response.comments,
+      };
+      
+      // Create human-readable summary
+      const summary = response.comments.map(c => 
+        `#${c.index} [${c.status}] "${c.feedback}" on <${c.element?.tag || "element"}> "${c.element?.text || ""}" (${c.page.path})`
+      ).join("\n");
+      
+      return {
+        content: [{
+          type: "text",
+          text: `Found ${response.totalCount} feedback item(s):\n\n${summary}\n\nFull data available in structuredContent.`,
+        }],
+        structuredContent: output,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      return {
+        content: [{ type: "text", text: `Error fetching feedback: ${message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// Tool 2: Mark feedback as resolved
+server.registerTool(
+  "mark_feedback_resolved",
+  {
+    title: "Mark Feedback Resolved",
+    description: `Marks a feedback comment as resolved after you've fixed the issue.
+    
+Call this after making the code changes to update the feedback status.
+The comment ID can be obtained from get_open_feedback.
+
+Note: Requires SUPER_FEEDBACK_ADMIN_CODE to be configured.`,
+    inputSchema: {
+      commentId: z.string().describe("The comment ID to mark as resolved"),
+    },
+    outputSchema: {
+      success: z.boolean(),
+      message: z.string(),
+    },
+  },
+  async ({ commentId }) => {
+    if (!ADMIN_CODE) {
+      return {
+        content: [{ type: "text", text: "Error: SUPER_FEEDBACK_ADMIN_CODE is required to update feedback status" }],
+        structuredContent: { success: false, message: "Admin code not configured" },
+        isError: true,
+      };
+    }
+    
+    try {
+      await callConvexAPI(`/api/feedback/ai/status`, {
+        method: "POST",
+        body: JSON.stringify({
+          adminCode: ADMIN_CODE,
+          commentId,
+          status: "resolved",
+        }),
+      });
+      
+      const output = {
+        success: true,
+        message: `Comment ${commentId} marked as resolved`,
+      };
+      
+      return {
+        content: [{ type: "text", text: output.message }],
+        structuredContent: output,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        structuredContent: { success: false, message },
+        isError: true,
+      };
+    }
+  }
+);
+
+// Tool 3: Get feedback details
+server.registerTool(
+  "get_feedback_details",
+  {
+    title: "Get Feedback Details",
+    description: `Gets full details for a specific feedback comment, including all element data and metadata.
+    
+Use this when you need more context about a specific piece of feedback.`,
+    inputSchema: {
+      commentId: z.string().describe("The comment ID to get details for"),
+    },
+    outputSchema: {
+      found: z.boolean(),
+      comment: z.any().nullable(),
+    },
+  },
+  async ({ commentId }) => {
+    try {
+      // Build query params - get all comments and find the specific one
+      const params = new URLSearchParams();
+      if (ACCESS_CODE) params.set("accessCode", ACCESS_CODE);
+      if (ADMIN_CODE) params.set("adminCode", ADMIN_CODE);
+      params.set("status", "all"); // Get all statuses
+      
+      const response = await callConvexAPI<FeedbackResponse>(
+        `/api/feedback/ai?${params.toString()}`
+      );
+      
+      const comment = response.comments?.find(c => c.id === commentId);
+      
+      if (!comment) {
+        return {
+          content: [{ type: "text", text: `Comment ${commentId} not found` }],
+          structuredContent: { found: false, comment: null },
+        };
+      }
+      
+      const output = {
+        found: true,
+        comment: comment,
+      };
+      
+      return {
+        content: [{
+          type: "text",
+          text: `Feedback: "${comment.feedback}"\nElement: <${comment.element?.tag || "unknown"}> "${comment.element?.text || ""}"\nPage: ${comment.page.path}\nSearch terms: ${comment.hints.searchTerms.join(", ")}`,
+        }],
+        structuredContent: output,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        structuredContent: { found: false, comment: null },
+        isError: true,
+      };
+    }
+  }
+);
+
+// Start the server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  
+  // Log to stderr so it doesn't interfere with MCP protocol on stdout
+  console.error("Super Feedback MCP server running...");
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}