cursor-mcp-feedback 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 yuanmingchen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,263 @@
+# MCP Feedback App
+
+Interactive feedback UI that renders directly inside MCP hosts (Claude, Cursor, etc.) using the [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview) extension. Includes a **macOS floating companion app** for bidirectional feedback and pending message management.
+
+When an AI agent calls the `interactive_feedback` tool, a feedback panel appears inline in the conversation — and optionally in the floating app. The user can respond from either side.
+
+## Features
+
+### MCP App Panel (in-conversation UI)
+
+- **Inline feedback UI** — summary with Markdown rendering + input area, directly in the conversation
+- **Dark mode** — auto-detects host theme (transparent background adapts to light/dark)
+- **Image support** — paste (Cmd+V), drag & drop, file picker with preview
+- **Quick replies** — Continue, LGTM, Fix, Pause one-click buttons
+- **Auto-append** — automatically appends a configurable reminder to every feedback
+- **Keyboard shortcut** — Ctrl/Cmd+Enter to submit feedback
+- **Blocking tool pattern** — `interactive_feedback` blocks until user submits via the UI
+
+### Floating Companion App (macOS)
+
+- **Bidirectional feedback** — both the MCP App panel and floating app receive AI summaries; respond from either side
+- **Pending messages** — queue messages that redirect the agent mid-task (delivered via `preToolUse` hook)
+- **Per-session tabs** — manage multiple agent sessions with project directory info
+- **Chat history** — full conversation history loaded from `events.jsonl` per session
+- **Image support** — paste images (Cmd+V), file picker, thumbnails in chat, click to preview
+- **Global hotkey** — Cmd+Shift+M to toggle the panel
+- **Floating button** — collapsible/expandable, draggable, always-on-top
+- **State persistence** — window position, size, expanded state, input draft all persist across restarts
+- **Enter to send** — Enter sends, Shift+Enter for newline, IME-safe
+- **Menu bar icon** — quick access via status bar
+
+### Cursor Integration
+
+- **Auto-install** — MCP server config, Cursor rules, and hooks are all auto-configured on first startup
+- **Subagent protection** — hooks prevent subagents from calling `interactive_feedback`
+- **Session lifecycle** — automatic session tracking via hooks (`sessionStart`, `preToolUse`, etc.)
+- **Event logging** — all interactions logged to `events.jsonl` per session for chat history
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│          MCP Host (Cursor / Claude)             │
+│  ┌──────────┐    ┌────────────────────┐         │
+│  │ AI Agent │    │ MCP App Panel      │         │
+│  │          │    │ (sandboxed iframe)  │         │
+│  │ calls    │    │ sessionId embedded │         │
+│  │ tool ────┼────┼─► renders inline   │         │
+│  └──────────┘    └────────┬───────────┘         │
+└────────────────────────────┼────────────────────┘
+                             │ callServerTool
+                             ▼
+               ┌───────────────────────────┐
+               │       MCP Server          │
+               │  interactive_feedback     │ ← polls session file
+               │  submit_feedback          │ ← writes resolved file
+               │  get_system_info          │
+               └───────────┬───────────────┘
+                           │
+               ┌───────────▼───────────────┐
+               │  ~/.cursor-mcp-feedback/     │
+               │    sessions/{uuid}.json   │  ← bidirectional channel
+               │    sessions/{convId}/     │
+               │      events.jsonl         │  ← chat history
+               │      pending.json         │  ← queued messages
+               │      meta.json            │  ← session metadata
+               │    active-sessions.json   │
+               └───────────┬───────────────┘
+                           │ file watch
+               ┌───────────▼───────────────┐
+               │  Floating App (macOS)     │
+               │  SwiftUI + AppKit         │
+               │  - bidirectional feedback │
+               │  - pending messages       │
+               │  - per-session chat UI    │
+               └───────────────────────────┘
+```
+
+## Installation
+
+### Quick Install (npm)
+
+```bash
+npm install -g cursor-mcp-feedback
+```
+
+On install, `postinstall` automatically configures Cursor (mcp.json, rules, hooks). Just restart Cursor and the MCP server is ready.
+
+### From Source
+
+```bash
+git clone git@repo.advai.net:cash/incubating/cusor-feedback-v2.git cursor-mcp-feedback
+cd cursor-mcp-feedback
+npm install
+npm run build
+```
+
+### Floating Companion App (macOS)
+
+```bash
+cd floating-app
+swift build -c release
+# Binary: .build/release/MCPPending
+```
+
+To auto-launch on login, add `.build/release/MCPPending` to System Settings > General > Login Items, or run manually.
+
+### CLI: Queue Pending Messages
+
+```bash
+# List active sessions
+cursor-mcp-feedback queue sessions
+
+# Queue a message to the most recent session
+cursor-mcp-feedback queue "please focus on the API layer"
+
+# Queue to a specific session
+cursor-mcp-feedback queue "fix the bug" --session <session-id>
+
+# List pending messages
+cursor-mcp-feedback queue list
+
+# Clear pending messages
+cursor-mcp-feedback queue clear
+```
+
+### Configure your MCP host
+
+#### Cursor (auto-configured)
+
+On first startup (or `npm install -g`), the MCP server **automatically configures** itself in `~/.cursor/mcp.json` with the correct absolute paths. It also auto-installs:
+
+- **Cursor rule** (`~/.cursor/rules/cursor-mcp-feedback.mdc`) — instructs the agent to call `interactive_feedback`
+- **Cursor hooks** (`~/.cursor/hooks/`) — subagent protection + pending message delivery + event logging
+- **hooks.json entries** — registers `sessionStart`, `subagentStart`, `subagentStop`, `beforeMCPExecution`, `preToolUse`, `afterMCPExecution` hooks
+
+All auto-installed files are kept in sync on every startup (hash-based diffing, idempotent).
+
+To manually configure instead, add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cursor-mcp-feedback": {
+      "command": "node",
+      "args": ["/absolute/path/to/cursor-mcp-feedback/dist/main.js"],
+      "timeout": 86400,
+      "env": {
+        "MCP_FEEDBACK_TIMEOUT": "86400"
+      }
+    }
+  }
+}
+```
+
+#### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "cursor-mcp-feedback": {
+      "command": "node",
+      "args": ["/absolute/path/to/cursor-mcp-feedback/dist/main.js"],
+      "timeout": 86400,
+      "env": {
+        "MCP_FEEDBACK_TIMEOUT": "86400"
+      }
+    }
+  }
+}
+```
+
+## Cursor Hooks
+
+| Hook | Event | Purpose |
+|------|-------|---------|
+| `block-cursor-mcp-feedback.js` | `subagentStart` | Record subagent_id to negative list |
+| `block-cursor-mcp-feedback.js` | `subagentStop` | Remove subagent_id on completion |
+| `block-cursor-mcp-feedback.js` | `beforeMCPExecution` | Deny cursor-mcp-feedback calls from subagents |
+| `block-cursor-mcp-feedback.js` | `afterMCPExecution` | Log feedback_request/response events to events.jsonl |
+| `consume-pending.js` | `preToolUse` | Consume pending messages and inject as agent feedback |
+
+## Keyboard Shortcuts
+
+| Shortcut | Context | Action |
+|----------|---------|--------|
+| `⌘+Enter` / `Ctrl+Enter` | MCP App Panel | Submit feedback |
+| `Enter` | Floating App | Send message / feedback |
+| `Shift+Enter` | Floating App | Insert newline |
+| `⌘+Shift+M` | Global | Toggle floating panel |
+| `Esc` | Floating App | Collapse to floating button |
+| `⌘+V` | Floating App | Paste image from clipboard |
+
+## UI Settings
+
+| Setting | Default | Persistence | Description |
+|---------|---------|-------------|-------------|
+| Auto-append reminder | On | `~/.cursor-mcp-feedback-settings.json` | Appends text to every feedback |
+| Auto-append text | `After completing, call interactive_feedback...` | Server-side | The text appended after each feedback |
+
+## Server Configuration
+
+| Environment Variable | Default | Description |
+|---------------------|---------|-------------|
+| `MCP_FEEDBACK_TIMEOUT` | `86400` (24h) | Server-side timeout in seconds |
+
+## Development
+
+```bash
+npm run build:ui     # Build the UI (Vite → single-file HTML)
+npm run build:server # Compile TypeScript server
+npm run build        # Both
+npm run dev          # Run with tsx (dev mode, stdio)
+```
+
+### Project Structure
+
+```
+src/
+  App.tsx              # Main React component (MCP App Panel UI)
+  mcp-app.tsx          # React entry point
+  styles/app.css       # Styles (light + dark theme)
+server.ts              # MCP server (tools + resources)
+main.ts                # Entry point (stdio/HTTP + auto-install)
+session-store.ts       # File-based session CRUD
+logger.ts              # File logging
+hooks/
+  block-cursor-mcp-feedback.js  # Subagent protection + event logging
+  consume-pending.js         # Pending message delivery
+  session-utils.js           # Shared session utilities
+floating-app/
+  Sources/
+    FloatingApp.swift        # App delegate, menu bar, window management
+    FloatingPanel.swift      # NSPanel subclass (keyboard, IME handling)
+    FloatingButtonView.swift # Collapsed floating button
+    PendingPanelView.swift   # Main panel UI (chat, input, tabs)
+    SessionManager.swift     # Session data, chat history, file I/O
+    FileWatcher.swift        # File system event monitoring
+    ImagePreviewWindow.swift # Image preview via system Preview.app
+  Package.swift              # Swift Package Manager config
+rules/
+  cursor-mcp-feedback.mdc      # Cursor rule (auto-installed)
+```
+
+## MCP Tools
+
+| Tool | Visibility | Description |
+|------|-----------|-------------|
+| `interactive_feedback` | model | Presents summary (Markdown), blocks until user responds |
+| `submit_feedback` | app-only | Submits user feedback with optional images (called from UI) |
+| `get_system_info` | model | Returns OS, architecture, Node.js version |
+
+## Prerequisites
+
+- Node.js >= 18
+- macOS 13+ (for floating companion app)
+- MCP host with [MCP Apps](https://modelcontextprotocol.io/extensions/client-matrix) support
+
+## License
+
+MIT

package/dist/logger.d.ts

@@ -0,0 +1,3 @@
+export declare function log(msg: string): void;
+export declare function logError(msg: string): void;
+export declare function logObj(msg: string, obj: Record<string, unknown>): void;

package/dist/logger.js

@@ -0,0 +1,25 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+const LOG_FILE = path.join(os.homedir(), ".cursor-mcp-feedback.log");
+const PID = process.pid;
+function formatLine(level, msg) {
+    const ts = new Date().toISOString();
+    return `[${ts}] [pid=${PID}] [${level}] ${msg}\n`;
+}
+export function log(msg) {
+    const line = formatLine("INFO", msg);
+    fs.appendFileSync(LOG_FILE, line);
+    console.error("[mcp-feedback]", msg);
+}
+export function logError(msg) {
+    const line = formatLine("ERROR", msg);
+    fs.appendFileSync(LOG_FILE, line);
+    console.error("[mcp-feedback] ERROR:", msg);
+}
+export function logObj(msg, obj) {
+    const extra = Object.entries(obj)
+        .map(([k, v]) => `${k}=${typeof v === "string" ? v : JSON.stringify(v)}`)
+        .join(" ");
+    log(`${msg} (${extra})`);
+}

package/dist/main.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * MCP Feedback App entry point.
+ *
+ * Modes:
+ *   --stdio   : stdio transport (default, for Claude Desktop / Cursor)
+ *   --http    : HTTP transport on port 3001 (for Claude Web / remote testing)
+ *
+ * The blocking feedback pattern (interactive_feedback waits for submit_feedback)
+ * requires a persistent connection, so stdio is the primary transport.
+ * HTTP mode creates a new server per request for stateless tool calls.
+ */
+export {};