@elliotding/ai-agent-mcp 0.1.15 → 0.1.18

package/src/server/http.ts

@@ -307,11 +307,33 @@ export class HTTPServer {
       // Build the absolute message URL for the SSE endpoint event.
       // Cursor (and other MCP clients) resolve the endpoint event data as a URL;
       // using a relative path causes some clients to misinterpret it as a redirect.
-      // We use the Host header when available so the URL matches what the client
-      // actually connected to (important behind proxies / ngrok / etc.).
+      //
+      // Priority order for determining the public base URL:
+      //   1. PUBLIC_URL env var — explicit override for reverse-proxy / Docker deployments
+      //      where the Host header reflects the internal address (e.g. 0.0.0.0:5080)
+      //      rather than the externally reachable hostname.
+      //      Set this to the full external origin, e.g. https://mcp.example.com
+      //   2. X-Forwarded-Host / X-Forwarded-Proto headers — set by well-configured proxies
+      //   3. Host header from the incoming request (may be the internal address behind nginx)
+      //   4. Fallback to HTTP_HOST:HTTP_PORT from config
       const basePath = config.http?.basePath ?? '';
-      const host = request.headers.host ?? `${config.http?.host ?? '127.0.0.1'}:${config.http?.port ?? 3000}`;
-      const messageUrl = `http://${host}${basePath}/message`;
+      let messageUrl: string;
+
+      const publicUrl = process.env['PUBLIC_URL'];
+      if (publicUrl) {
+        // Strip trailing slash, then append basePath + /message
+        messageUrl = `${publicUrl.replace(/\/$/, '')}${basePath}/message`;
+      } else {
+        const forwardedProto = request.headers['x-forwarded-proto'];
+        const forwardedHost  = request.headers['x-forwarded-host'];
+        const proto = Array.isArray(forwardedProto) ? forwardedProto[0] : (forwardedProto ?? 'http');
+        const host  = Array.isArray(forwardedHost)
+          ? forwardedHost[0]
+          : (forwardedHost ?? request.headers.host ?? `${config.http?.host ?? '127.0.0.1'}:${config.http?.port ?? 3000}`);
+        messageUrl = `${proto}://${host}${basePath}/message`;
+      }
+
+      logger.info({ messageUrl }, 'Message endpoint constructed for SSE client');
       const transport = new SSEServerTransport(messageUrl, reply.raw);
       const sdkSessionId = transport.sessionId;
       this.sseTransports.set(sdkSessionId, transport);

package/src/tools/manage-subscription.ts

@@ -103,6 +103,18 @@ export async function manageSubscription(params: unknown): Promise<ToolResult<Ma
 
         logger.debug({ resourceIds: typedParams.resource_ids }, 'Unsubscribing from resources...');
 
+        // Build a resource_id → type map from the current subscription list so
+        // uninstall actions can be scoped precisely to rule vs mcp resources.
+        let idToType: Map<string, string> = new Map();
+        try {
+          const currentSubs = await apiClient.getSubscriptions({}, typedParams.user_token);
+          for (const s of currentSubs.subscriptions) {
+            idToType.set(s.id, s.type);
+          }
+        } catch (e) {
+          logger.warn({ error: (e as Error).message }, 'Could not fetch subscriptions for type resolution — uninstall will emit both rule+mcp actions as fallback');
+        }
+
         // Cancel server-side subscription
         await apiClient.unsubscribe(typedParams.resource_ids, typedParams.user_token);
         logger.info({ count: typedParams.resource_ids.length }, 'Server-side subscriptions removed');
@@ -112,17 +124,22 @@ export async function manageSubscription(params: unknown): Promise<ToolResult<Ma
         const uninstallResults: Array<{ id: string; removed: boolean; detail: string }> = [];
         for (const resourceId of typedParams.resource_ids) {
           // Determine if this is a Command or Skill by checking the prompt registry.
-          // Resource IDs follow the pattern: cmd-<source>-<name> or skill-<source>-<name>.
-          const isCommand = resourceId.startsWith('cmd-');
-          const isSkill   = resourceId.startsWith('skill-');
-          if (isCommand || isSkill) {
-            const resourceType = isCommand ? 'command' : 'skill';
-            // Extract resource name from the ID (cmd-<team>-<name> or skill-<team>-<name>).
-            const parts = resourceId.split('-');
-            const resourceName = parts.slice(2).join('-') || resourceId;
-            promptManager.unregisterPrompt(resourceId, resourceType as 'command' | 'skill', resourceName, typedParams.user_token ?? '');
+          // API resource IDs are UUIDs (e.g. "0ccd800f..."), NOT prefixed with "cmd-"/"skill-".
+          // Check whether any registered prompt for this user matches the resource_id.
+          const matchedPromptName = promptManager.promptNames(typedParams.user_token ?? '').find(
+            (name) => {
+              // Prompt names are "<type>/<resource_name>"; check by looking up the registered meta.
+              const registered = promptManager.getByPromptName(name, typedParams.user_token ?? '');
+              return registered?.meta?.resource_id === resourceId;
+            },
+          );
+          if (matchedPromptName) {
+            const parts = matchedPromptName.split('/');
+            const resourceType = (parts[0] ?? 'command') as 'command' | 'skill';
+            const resourceName = parts.slice(1).join('/') || matchedPromptName;
+            promptManager.unregisterPrompt(resourceId, resourceType, resourceName, typedParams.user_token ?? '');
             uninstallResults.push({ id: resourceId, removed: true, detail: `Unregistered MCP Prompt for "${resourceName}"` });
-            logger.info({ resourceId, resourceType }, 'MCP Prompt unregistered on unsubscribe');
+            logger.info({ resourceId, resourceType, matchedPromptName }, 'MCP Prompt unregistered on unsubscribe');
             continue;
           }
           // Use the last segment of the resource ID as the search pattern
@@ -139,11 +156,13 @@ export async function manageSubscription(params: unknown): Promise<ToolResult<Ma
             namePart,
           ]));
 
+          const resolvedType = idToType.get(resourceId) as 'rule' | 'mcp' | undefined;
           let uninstalled = false;
           for (const pattern of patternsToTry) {
             const uninstallResult = await uninstallResource({
               resource_id_or_name: pattern,
               remove_from_account: false, // already unsubscribed above
+              ...(resolvedType ? { resource_type: resolvedType } : {}),
             });
             if (uninstallResult.success && uninstallResult.data && uninstallResult.data.removed_resources.length > 0) {
               uninstallResults.push({ id: resourceId, removed: true, detail: `Removed local files for "${pattern}"` });

package/src/tools/sync-resources.ts

@@ -18,6 +18,7 @@
 
 import * as fs from 'fs/promises';
 import * as path from 'path';
+import { createHash } from 'crypto';
 import { logger, logToolCall, logToolStep, logToolResult } from '../utils/logger';
 import { apiClient } from '../api/client';
 import { multiSourceGitManager } from '../git/multi-source-manager';
@@ -36,6 +37,39 @@ import type {
 import { telemetry } from '../telemetry/index.js';
 import { promptManager } from '../prompts/index.js';
 
+/**
+ * Server-side in-memory download cache.
+ *
+ * Purpose: avoid redundant API download calls for resources whose content has
+ * not changed between syncs IN THE SAME SERVER SESSION.
+ *
+ * IMPORTANT — this cache ONLY skips the network download; it NEVER skips
+ * generating LocalAction instructions.  Whether the user's local files are
+ * already up-to-date is determined client-side via the `content_hash` field
+ * on write_file actions and `skip_if_exists` on merge_mcp_json actions.
+ * This ensures a manual sync always re-delivers actions so the user can
+ * recover deleted local files, even when the resource content is unchanged.
+ *
+ * Key format: `${userToken}::${resourceId}`
+ * Value: the last downloadResource() response (hash + files).
+ *
+ * The cache is process-scoped and cleared on server restart.
+ */
+interface CachedDownload {
+  hash: string;
+  files: Array<{ path: string; content: string }>;
+}
+const downloadCache = new Map<string, CachedDownload>();
+
+function syncCacheKey(userToken: string, resourceId: string): string {
+  return `${userToken}::${resourceId}`;
+}
+
+/** Compute SHA-256 hex digest of a UTF-8 string. */
+function sha256(content: string): string {
+  return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+
 /**
  * Extract the `description` field from YAML frontmatter in a Markdown file.
  * Frontmatter is delimited by leading `---` and closing `---` lines.
@@ -153,21 +187,40 @@ export async function syncResources(params: unknown): Promise<ToolResult<SyncRes
         // getCursorResourcePath throws for unrecognised types, caught below.
         const destPath = getCursorResourcePath(sub.type, sub.name);
 
-        // In check mode: just report whether the resource already exists locally.
+        // In check mode: report whether the resource is already available.
+        // Command/Skill: check the in-memory Prompt registry (no local files).
+        // Rule/MCP: check whether the local file / mcp.json entry exists.
         if (mode === 'check') {
-          try {
-            await fs.access(destPath);
-            tally.cached++;
-            details.push({ id: sub.id, name: sub.name, action: 'cached', version: resourceVersion });
-            logToolStep('sync_resources', 'Resource already present (check mode)', {
-              resourceId: sub.id, destPath,
-            });
-          } catch {
-            tally.failed++;
-            details.push({ id: sub.id, name: sub.name, action: 'failed', version: resourceVersion });
-            logToolStep('sync_resources', 'Resource missing (check mode)', {
-              resourceId: sub.id, destPath,
-            });
+          if (sub.type === 'command' || sub.type === 'skill') {
+            const meta = {
+              resource_id: sub.id,
+              resource_type: sub.type as 'command' | 'skill',
+              resource_name: sub.name,
+              team: (sub as any).team ?? 'general',
+            };
+            const isRegistered = promptManager.has(promptManager.buildPromptName(meta), userToken ?? '');
+            if (isRegistered) {
+              tally.cached++;
+              details.push({ id: sub.id, name: sub.name, action: 'cached', version: resourceVersion });
+            } else {
+              tally.failed++;
+              details.push({ id: sub.id, name: sub.name, action: 'failed', version: resourceVersion });
+            }
+          } else {
+            try {
+              await fs.access(destPath);
+              tally.cached++;
+              details.push({ id: sub.id, name: sub.name, action: 'cached', version: resourceVersion });
+              logToolStep('sync_resources', 'Resource already present (check mode)', {
+                resourceId: sub.id, destPath,
+              });
+            } catch {
+              tally.failed++;
+              details.push({ id: sub.id, name: sub.name, action: 'failed', version: resourceVersion });
+              logToolStep('sync_resources', 'Resource missing (check mode)', {
+                resourceId: sub.id, destPath,
+              });
+            }
           }
           continue;
         }
@@ -280,18 +333,40 @@ export async function syncResources(params: unknown): Promise<ToolResult<SyncRes
           continue;
         }
 
-        // Download all files for this resource from the CSP server.
-        logToolStep('sync_resources', 'Downloading resource', {
-          resourceId: sub.id,
-          resourceType: sub.type,
-        });
-        const tDl = Date.now();
-        const downloadResult = await apiClient.downloadResource(sub.id, userToken);
-        logToolStep('sync_resources', 'Download complete', {
-          resourceId: sub.id,
-          fileCount: downloadResult.files.length,
-          duration: Date.now() - tDl,
-        });
+        // ── Download (with server-session cache) ─────────────────────────────
+        // The download cache avoids redundant API calls when the same resource
+        // is synced multiple times within one server session without any content
+        // change.  It ONLY caches the network response; LocalAction generation
+        // always proceeds so that users can recover deleted local files by
+        // re-running sync — even when the resource content is unchanged.
+        const cacheKey = syncCacheKey(userToken ?? '', sub.id);
+        let downloadResult: { hash: string; files: Array<{ path: string; content: string }> };
+
+        const cached = downloadCache.get(cacheKey);
+        if (mode === 'incremental' && cached) {
+          // Reuse the previously downloaded content without hitting the API.
+          // full mode always bypasses this branch to guarantee a fresh download.
+          downloadResult = cached;
+          logToolStep('sync_resources', 'Using cached download (no API call)', {
+            resourceId: sub.id,
+            cachedHash: cached.hash,
+          });
+        } else {
+          logToolStep('sync_resources', 'Downloading resource', {
+            resourceId: sub.id,
+            resourceType: sub.type,
+          });
+          const tDl = Date.now();
+          const apiResult = await apiClient.downloadResource(sub.id, userToken);
+          logToolStep('sync_resources', 'Download complete', {
+            resourceId: sub.id,
+            fileCount: apiResult.files.length,
+            duration: Date.now() - tDl,
+          });
+          downloadResult = { hash: apiResult.hash, files: apiResult.files };
+          // Refresh cache with the latest download.
+          downloadCache.set(cacheKey, downloadResult);
+        }
 
         // When the API returns no files (expected when the MCP server is deployed
         // remotely and content lives in the server-side git repo), fall back to
@@ -374,7 +449,14 @@ export async function syncResources(params: unknown): Promise<ToolResult<SyncRes
                 const normalised = path.normalize(file.path);
                 if (normalised.startsWith('..')) continue;
                 const fileDest = `${installDir}/${normalised}`;
-                localActions.push({ action: 'write_file', path: fileDest, content: file.content });
+                // Carry content_hash so the AI can skip the write when the
+                // local file already has identical content.
+                localActions.push({
+                  action: 'write_file',
+                  path: fileDest,
+                  content: file.content,
+                  content_hash: sha256(file.content),
+                });
                 writeActions.push(fileDest);
               }
               const env = (cfg['env'] ?? {}) as Record<string, string>;
@@ -390,6 +472,9 @@ export async function syncResources(params: unknown): Promise<ToolResult<SyncRes
                 mcp_json_path: mcpJsonPath,
                 server_name: serverName,
                 entry: { ...cfg, args },
+                // skip_if_exists: preserve user-edited env values; the entry
+                // is already configured if the key exists in mcp.json.
+                skip_if_exists: true,
                 ...(missingEnv.length > 0 ? {
                   missing_env: missingEnv,
                   setup_hint: `Fill in env vars in ${mcpJsonPath} under mcpServers["${sub.name}"]: ${missingEnv.join(', ')}.`,
@@ -421,6 +506,9 @@ export async function syncResources(params: unknown): Promise<ToolResult<SyncRes
                   mcp_json_path: mcpJsonPath,
                   server_name: serverName,
                   entry: e,
+                  // skip_if_exists: user may have customised env values; do
+                  // not overwrite an existing entry on every incremental sync.
+                  skip_if_exists: true,
                   ...(missingEnv.length > 0 ? {
                     missing_env: missingEnv,
                     setup_hint: `Fill in env vars in ${mcpJsonPath} under mcpServers["${serverName}"]: ${missingEnv.join(', ')}.`,
@@ -450,7 +538,12 @@ export async function syncResources(params: unknown): Promise<ToolResult<SyncRes
               const normalised = path.normalize(file.path);
               if (normalised.startsWith('..')) continue;
               const fileDest = `${installDir}/${normalised}`;
-              localActions.push({ action: 'write_file', path: fileDest, content: file.content });
+              localActions.push({
+                action: 'write_file',
+                path: fileDest,
+                content: file.content,
+                content_hash: sha256(file.content),
+              });
               writeActions.push(fileDest);
             }
             const jsEntry = resourceFiles.find((f) => f.path.endsWith('.js'));
@@ -463,6 +556,7 @@ export async function syncResources(params: unknown): Promise<ToolResult<SyncRes
               mcp_json_path: mcpJsonPath,
               server_name: sub.name,
               entry: { command: cmd, args: [entryPath] },
+              skip_if_exists: true,
             });
             logger.info(
               {
@@ -487,7 +581,8 @@ export async function syncResources(params: unknown): Promise<ToolResult<SyncRes
 
         // ── Rule resource ─────────────────────────────────────────────────────
         // Return write_file actions; the AI writes the files locally.
-        // Use client-side path so the path resolves on the user's machine.
+        // Each action carries content_hash so the AI can skip the write when
+        // the local file already has identical content.
         if (sub.type === 'rule') {
           const typeDir = getCursorTypeDirForClient(sub.type);
           const writeActions: string[] = [];
@@ -503,6 +598,7 @@ export async function syncResources(params: unknown): Promise<ToolResult<SyncRes
               action: 'write_file',
               path: destPath,
               content: file.content,
+              content_hash: sha256(file.content),
             });
             writeActions.push(destPath);
           }
@@ -638,10 +734,17 @@ export const syncResourcesTool = {
     'Rule and MCP resources are returned as `local_actions_required` — an ordered list of ' +
     'write_file, merge_mcp_json, or other actions that the AI Agent MUST execute on the ' +
     'USER\'S LOCAL MACHINE after receiving the response. ' +
-    'Execute every action in the list before reporting success to the user. ' +
-    'For merge_mcp_json actions: read the existing ~/.cursor/mcp.json, smart-merge the ' +
-    'provided entry (preserve existing user env values), then write the file back. ' +
-    'For write_file actions: create any missing parent directories then write the file.',
+    'Execute every action in the list in order before reporting success to the user. ' +
+    'For write_file actions: ' +
+    '  (1) If the action has a `content_hash` field, read the existing file (if any), compute its SHA-256, ' +
+    '      and SKIP the write if the digests match — the file is already up-to-date. ' +
+    '  (2) Otherwise create any missing parent directories then write the file. ' +
+    'For merge_mcp_json actions: ' +
+    '  (1) If the action has `skip_if_exists: true` AND `mcpServers[server_name]` already exists ' +
+    '      in ~/.cursor/mcp.json, SKIP this action entirely — the server is already configured ' +
+    '      and any user-edited env values must not be overwritten. ' +
+    '  (2) Otherwise read the existing ~/.cursor/mcp.json, smart-merge the provided entry ' +
+    '      (preserve existing user env values), then write the file back.',
   inputSchema: {
     type: 'object' as const,
     properties: {

package/src/tools/uninstall-resource.ts

@@ -87,32 +87,38 @@ export async function uninstallResource(params: unknown): Promise<ToolResult<Uni
     // The MCP server may be running remotely; we must NOT touch the server's
     // own filesystem.  Instead we return delete/remove instructions so the AI
     // Agent performs them on the user's LOCAL machine.
-    logger.debug({ pattern }, 'Building local uninstall actions for Rule/MCP resource...');
+    logger.debug({ pattern, resourceType: typedParams.resource_type }, 'Building local uninstall actions for Rule/MCP resource...');
 
     const localActions: LocalAction[] = [];
     // Use client-side tilde-based paths; the MCP server may be running remotely
     // and its os.homedir() would resolve to the server's home, not the user's.
     const mcpJsonPath = `${getCursorRootDirForClient()}/mcp.json`;
 
-    // Rule: queue delete for ~/.cursor/rules/<pattern>.mdc and .md variants.
-    // We cannot scan the server's filesystem for the user's rules, so we emit
-    // delete actions for the two common extensions and let the AI skip missing files.
-    const rulesDir = getCursorTypeDirForClient('rule');
-    for (const ext of ['.mdc', '.md']) {
-      const filePath = `${rulesDir}/${pattern}${ext}`;
-      localActions.push({ action: 'delete_file', path: filePath });
-      removedResources.push({ id: pattern, name: pattern, path: filePath });
+    // When resource_type is provided, only emit the relevant actions.
+    // When unknown, emit both (AI skips missing files gracefully).
+    const knownType = typedParams.resource_type;
+    const isRule = !knownType || knownType === 'rule';
+    const isMcp  = !knownType || knownType === 'mcp';
+
+    if (isRule) {
+      // Rule: delete ~/.cursor/rules/<pattern>.mdc and .md variants.
+      const rulesDir = getCursorTypeDirForClient('rule');
+      for (const ext of ['.mdc', '.md']) {
+        const filePath = `${rulesDir}/${pattern}${ext}`;
+        localActions.push({ action: 'delete_file', path: filePath });
+        removedResources.push({ id: pattern, name: pattern, path: filePath });
+      }
     }
 
-    // MCP: queue delete of install directory (Format A) + remove mcp.json entry.
-    // For Format B (remote URL only) there is no local directory, but we still
-    // need to remove the mcp.json entry — the AI will skip the delete if the
-    // directory does not exist.
-    const mcpDir = getCursorTypeDirForClient('mcp');
-    const mcpInstallDir = `${mcpDir}/${pattern}`;
-    localActions.push({ action: 'delete_file', path: mcpInstallDir, recursive: true });
-    localActions.push({ action: 'remove_mcp_json_entry', mcp_json_path: mcpJsonPath, server_name: pattern });
-    removedResources.push({ id: pattern, name: pattern, path: mcpInstallDir });
+    if (isMcp) {
+      // MCP: delete install directory (Format A — may not exist for remote-URL MCPs)
+      // and remove the mcpServers entry from mcp.json.
+      const mcpDir = getCursorTypeDirForClient('mcp');
+      const mcpInstallDir = `${mcpDir}/${pattern}`;
+      localActions.push({ action: 'delete_file', path: mcpInstallDir, recursive: true });
+      localActions.push({ action: 'remove_mcp_json_entry', mcp_json_path: mcpJsonPath, server_name: pattern });
+      removedResources.push({ id: pattern, name: pattern, path: mcpInstallDir });
+    }
 
     if (removedResources.length === 0 && localActions.length === 0) {
       throw createValidationError(

package/src/types/tools.ts

@@ -22,6 +22,13 @@ export interface WriteFileAction {
   path: string;
   /** UTF-8 file content to write. */
   content: string;
+  /**
+   * SHA-256 hex digest of `content` (without leading "sha256:").
+   * When present, the AI MUST read the existing file at `path` (if any),
+   * compute its SHA-256, and SKIP the write if the digests match.
+   * This prevents redundant writes on incremental syncs.
+   */
+  content_hash?: string;
 }
 
 export interface DeleteFileAction {
@@ -46,6 +53,13 @@ export interface MergeMcpJsonAction {
   setup_hint?: string;
   /** Path to a local setup/readme doc if one exists in the install dir. */
   setup_doc?: string;
+  /**
+   * When true, the AI MUST skip this action if `mcpServers[server_name]`
+   * already exists in mcp.json (regardless of content).
+   * Use this for idempotent installs where re-writing would clobber
+   * user-customised values (e.g. env vars the user has already filled in).
+   */
+  skip_if_exists?: boolean;
 }
 
 export interface RemoveMcpJsonEntryAction {
@@ -242,6 +256,8 @@ export interface UploadResourceResult {
 export interface UninstallResourceParams {
   resource_id_or_name: string;
   remove_from_account?: boolean;
+  /** When known, the resource type — narrows which local_actions are emitted. */
+  resource_type?: 'command' | 'skill' | 'rule' | 'mcp';
   /** CSP API token from the user's mcp.json env configuration. */
   user_token?: string;
 }