cursor-mcp-feedback 2.0.0

package/hooks/session-utils.js

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+// Shared session utilities for all hooks.
+// Manages per-session file structure under ~/.cursor-mcp-feedback/sessions/
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const crypto = require("crypto");
+
+const BASE_DIR = path.join(os.homedir(), ".cursor-mcp-feedback");
+const SESSIONS_DIR = path.join(BASE_DIR, "sessions");
+const ACTIVE_FILE = path.join(BASE_DIR, "active-sessions.json");
+const SUBAGENT_FILE = path.join(BASE_DIR, "subagent-ids.json");
+
+// Legacy global pending file (for backward compat with CLI)
+const GLOBAL_PENDING = path.join(BASE_DIR, "pending.json");
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function sessionDir(convId) {
+  return path.join(SESSIONS_DIR, convId);
+}
+
+function readJson(filePath, fallback) {
+  try { return JSON.parse(fs.readFileSync(filePath, "utf8")); }
+  catch { return fallback; }
+}
+
+function writeJson(filePath, data) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+}
+
+function appendJsonl(filePath, event) {
+  ensureDir(path.dirname(filePath));
+  fs.appendFileSync(filePath, JSON.stringify({ ...event, ts: Date.now() }) + "\n");
+}
+
+// ── Session CRUD ──
+
+function createSession(convId, meta) {
+  const dir = sessionDir(convId);
+  ensureDir(dir);
+  writeJson(path.join(dir, "meta.json"), {
+    conversation_id: convId,
+    created_at: Date.now(),
+    is_active: true,
+    ...meta,
+  });
+  writeJson(path.join(dir, "pending.json"), []);
+  appendJsonl(path.join(dir, "events.jsonl"), {
+    type: "session_start",
+    conversation_id: convId,
+    ...meta,
+  });
+  updateActiveList(convId, meta, true);
+}
+
+function ensureSession(convId, meta) {
+  const metaPath = path.join(sessionDir(convId), "meta.json");
+  if (fs.existsSync(metaPath)) return;
+  createSession(convId, { ...meta, _lazy: true });
+}
+
+const STALE_MS = 2 * 60 * 60 * 1000; // 2 hours
+
+function cleanupStaleSessions() {
+  const list = readJson(ACTIVE_FILE, []);
+  const now = Date.now();
+  const active = list.filter((s) => now - (s.last_activity || 0) < STALE_MS);
+  if (active.length !== list.length) writeJson(ACTIVE_FILE, active);
+  for (const removed of list.filter((s) => now - (s.last_activity || 0) >= STALE_MS)) {
+    const metaPath = path.join(sessionDir(removed.id), "meta.json");
+    const meta = readJson(metaPath, null);
+    if (meta && meta.is_active) {
+      meta.is_active = false;
+      meta.ended_at = now;
+      meta.end_reason = "stale_cleanup";
+      writeJson(metaPath, meta);
+      appendJsonl(path.join(sessionDir(removed.id), "events.jsonl"), {
+        type: "session_end",
+        conversation_id: removed.id,
+        reason: "stale_cleanup",
+      });
+    }
+  }
+}
+
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000;
+const CLEANUP_TS_FILE = path.join(BASE_DIR, ".last-cleanup");
+
+function maybeCleanup() {
+  try {
+    const lastTs = fs.existsSync(CLEANUP_TS_FILE)
+      ? parseInt(fs.readFileSync(CLEANUP_TS_FILE, "utf8"), 10)
+      : 0;
+    if (Date.now() - lastTs < CLEANUP_INTERVAL_MS) return;
+    cleanupStaleSessions();
+    ensureDir(BASE_DIR);
+    fs.writeFileSync(CLEANUP_TS_FILE, String(Date.now()));
+  } catch { /* best effort */ }
+}
+
+function endSession(convId, reason) {
+  const dir = sessionDir(convId);
+  const metaPath = path.join(dir, "meta.json");
+  const meta = readJson(metaPath, null);
+  if (meta) {
+    meta.is_active = false;
+    meta.ended_at = Date.now();
+    meta.end_reason = reason;
+    writeJson(metaPath, meta);
+  }
+  appendJsonl(path.join(dir, "events.jsonl"), {
+    type: "session_end",
+    conversation_id: convId,
+    reason,
+  });
+  updateActiveList(convId, null, false);
+}
+
+function updateActiveList(convId, meta, active) {
+  const list = readJson(ACTIVE_FILE, []);
+  const idx = list.findIndex((s) => s.id === convId);
+  if (active) {
+    const entry = {
+      id: convId,
+      workspace: meta?.workspace || "",
+      mode: meta?.mode || "agent",
+      model: meta?.model || "",
+      started_at: meta?.created_at || Date.now(),
+      last_activity: Date.now(),
+    };
+    if (idx >= 0) list[idx] = { ...list[idx], ...entry };
+    else list.push(entry);
+  } else {
+    if (idx >= 0) list.splice(idx, 1);
+  }
+  writeJson(ACTIVE_FILE, list);
+}
+
+function touchSessionActivity(convId) {
+  const list = readJson(ACTIVE_FILE, []);
+  const entry = list.find((s) => s.id === convId);
+  if (entry) {
+    entry.last_activity = Date.now();
+    writeJson(ACTIVE_FILE, list);
+  }
+}
+
+// ── Per-session pending ──
+
+function readSessionPending(convId) {
+  return readJson(path.join(sessionDir(convId), "pending.json"), []);
+}
+
+function writeSessionPending(convId, msgs) {
+  writeJson(path.join(sessionDir(convId), "pending.json"), msgs);
+}
+
+function addSessionPending(convId, text, source) {
+  const msgs = readSessionPending(convId);
+  const msg = { id: crypto.randomUUID(), text, createdAt: Date.now(), source: source || "cli" };
+  msgs.push(msg);
+  writeSessionPending(convId, msgs);
+  appendJsonl(path.join(sessionDir(convId), "events.jsonl"), {
+    type: "pending_queued",
+    text,
+    msg_id: msg.id,
+    source: msg.source,
+  });
+  return msgs;
+}
+
+function consumeSessionPending(convId, toolName) {
+  const msgs = readSessionPending(convId);
+  if (msgs.length === 0) return null;
+  writeSessionPending(convId, []);
+  const combined = msgs.map((m) => m.text).join("\n\n---\n\n");
+  appendJsonl(path.join(sessionDir(convId), "events.jsonl"), {
+    type: "pending_consumed",
+    text: combined,
+    count: msgs.length,
+    consumed_by_tool: toolName,
+    ts: Date.now(),
+  });
+  return { text: combined, count: msgs.length };
+}
+
+// ── Subagent tracking ──
+
+function recordSubagent(subagentId, parentConvId) {
+  const data = readJson(SUBAGENT_FILE, {});
+  const FOUR_HOURS = 4 * 60 * 60 * 1000;
+  for (const [k, v] of Object.entries(data)) {
+    if (Date.now() - (v.ts || 0) > FOUR_HOURS) delete data[k];
+  }
+  data[subagentId] = { parent: parentConvId, ts: Date.now() };
+  writeJson(SUBAGENT_FILE, data);
+}
+
+function removeSubagent(subagentId) {
+  const data = readJson(SUBAGENT_FILE, {});
+  delete data[subagentId];
+  writeJson(SUBAGENT_FILE, data);
+}
+
+function isSubagent(convId) {
+  const data = readJson(SUBAGENT_FILE, {});
+  return !!data[convId];
+}
+
+// ── Most recent active session ──
+
+function getMostRecentSession() {
+  const list = readJson(ACTIVE_FILE, []);
+  if (list.length === 0) return null;
+  list.sort((a, b) => (b.last_activity || 0) - (a.last_activity || 0));
+  return list[0];
+}
+
+// ── Legacy: read global pending (for backward compat) ──
+
+function readGlobalPending() {
+  return readJson(GLOBAL_PENDING, []);
+}
+
+function writeGlobalPending(msgs) {
+  writeJson(GLOBAL_PENDING, msgs);
+}
+
+// ── Hook I/O ──
+
+function readHookInput() {
+  return JSON.parse(fs.readFileSync("/dev/stdin", "utf8"));
+}
+
+function writeHookOutput(obj) {
+  process.stdout.write(JSON.stringify(obj) + "\n");
+}
+
+module.exports = {
+  BASE_DIR, SESSIONS_DIR, ACTIVE_FILE, SUBAGENT_FILE, GLOBAL_PENDING,
+  ensureDir, sessionDir, readJson, writeJson, appendJsonl,
+  createSession, ensureSession, endSession, cleanupStaleSessions, maybeCleanup,
+  updateActiveList, touchSessionActivity,
+  readSessionPending, writeSessionPending, addSessionPending, consumeSessionPending,
+  recordSubagent, removeSubagent, isSubagent,
+  getMostRecentSession, readGlobalPending, writeGlobalPending,
+  readHookInput, writeHookOutput,
+};

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "cursor-mcp-feedback",
+  "version": "2.0.0",
+  "description": "MCP App for interactive feedback — renders a chat UI directly inside MCP hosts (Claude, Cursor, etc.)",
+  "type": "module",
+  "main": "dist/main.js",
+  "bin": {
+    "cursor-mcp-feedback": "dist/main.js"
+  },
+  "files": [
+    "dist/main.js",
+    "dist/main.d.ts",
+    "dist/server.js",
+    "dist/server.d.ts",
+    "dist/session-store.js",
+    "dist/session-store.d.ts",
+    "dist/logger.js",
+    "dist/logger.d.ts",
+    "dist/mcp-app.html",
+    "rules/",
+    "hooks/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build:ui": "INPUT=mcp-app.html vite build",
+    "build:server": "tsc && chmod +x dist/main.js",
+    "build": "npm run build:ui && npm run build:server",
+    "prepack": "npm run build",
+    "pack": "npm pack",
+    "release:patch": "npm version patch && npm publish",
+    "release:minor": "npm version minor && npm publish",
+    "release:major": "npm version major && npm publish",
+    "postinstall": "node dist/main.js --install-only 2>/dev/null || true",
+    "build:restart": "npm run build && pkill -f 'node.*cursor-mcp-feedback' || true",
+    "serve": "npx tsx main.ts",
+    "dev": "npx tsx main.ts",
+    "dev:watch": "npx tsx --watch main.ts",
+    "start": "node dist/main.js",
+    "restart": "pkill -f 'node.*cursor-mcp-feedback' || true"
+  },
+  "keywords": [
+    "mcp",
+    "feedback",
+    "mcp-app",
+    "interactive"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^1.7.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "cors": "^2.8.5",
+    "express": "^4.21.0",
+    "marked": "^18.0.2",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "zod": "^4.4.1"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.3.0",
+    "vite-plugin-singlefile": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/rules/cursor-mcp-feedback.mdc

@@ -0,0 +1,27 @@
+---
+alwaysApply: true
+---
+
+[Cursor MCP Feedback] USAGE RULES:
+These rules apply ONLY to the main agent in Agent mode (direct user conversation).
+Do NOT call interactive_feedback if you are a subagent, or in Plan/Ask/Debug mode.
+
+SUBAGENT PROHIBITION (CRITICAL):
+- If you were launched via the Task tool, you ARE a subagent. DO NOT call interactive_feedback.
+- Subagents MUST NEVER call any tool from the cursor-mcp-feedback MCP server.
+- This includes: interactive_feedback, submit_feedback, get_system_info.
+- A beforeMCPExecution hook will DENY the call and waste your turn. Do not attempt it.
+- If you need to report results, return them as text in your final response to the parent agent.
+
+WHY: User responses through feedback are FREE, but each user message in Cursor costs a request.
+Always prefer feedback over ending your turn with plain text alone.
+
+HARD GATE — turn completion:
+- If you are about to end your turn and you have NOT called interactive_feedback in this turn, you are NOT done. Call it first.
+- MUST use interactive_feedback as your LAST tool call when wrapping up (hand off, summarize, or ask the user).
+- NEVER end your turn with only assistant-visible text and zero interactive_feedback call in that turn.
+
+You have access to the interactive_feedback MCP tool (server: cursor-mcp-feedback) for communicating with the user:
+- Use it to present results, ask questions, or check in with the user.
+- You do not need to call it between every tool call during multi-step execution.
+- When blocked, uncertain, or facing a decision with trade-offs, call feedback immediately to ask the user — do NOT guess or make assumptions on your own.