@elliotding/ai-agent-mcp 0.1.2 → 0.1.4

package/src/tools/manage-subscription.ts

@@ -9,6 +9,7 @@ import { MCPServerError, createValidationError } from '../types/errors';
 import type { ManageSubscriptionParams, ManageSubscriptionResult, ToolResult } from '../types/tools';
 import { syncResources } from './sync-resources';
 import { uninstallResource } from './uninstall-resource';
+import { promptManager } from '../prompts/index.js';
 
 export async function manageSubscription(params: unknown): Promise<ToolResult<ManageSubscriptionResult>> {
   const startTime = Date.now();
@@ -37,7 +38,9 @@ export async function manageSubscription(params: unknown): Promise<ToolResult<Ma
         // Subscribe to resources
         const subResult = await apiClient.subscribe(
           typedParams.resource_ids,
-          typedParams.auto_sync
+          typedParams.auto_sync,
+          undefined,
+          typedParams.user_token
         );
 
         logger.info({ count: subResult.subscriptions.length }, 'Resources subscribed successfully');
@@ -50,7 +53,11 @@ export async function manageSubscription(params: unknown): Promise<ToolResult<Ma
 
         if (shouldAutoSync && subResult.subscriptions.length > 0) {
           logger.info({ resourceIds: typedParams.resource_ids }, 'Auto-syncing newly subscribed resources...');
-          const syncResult = await syncResources({ mode: 'incremental', scope: typedParams.scope || 'global' });
+          const syncResult = await syncResources({
+            mode: 'incremental',
+            scope: typedParams.scope || 'global',
+            user_token: typedParams.user_token,
+          });
           if (syncResult.success && syncResult.data) {
             const sd = syncResult.data;
             syncSummary = `Auto-sync: ${sd.summary.synced} synced, ${sd.summary.cached} cached, ${sd.summary.failed} failed`;
@@ -97,12 +104,27 @@ export async function manageSubscription(params: unknown): Promise<ToolResult<Ma
         logger.debug({ resourceIds: typedParams.resource_ids }, 'Unsubscribing from resources...');
 
         // Cancel server-side subscription
-        await apiClient.unsubscribe(typedParams.resource_ids);
+        await apiClient.unsubscribe(typedParams.resource_ids, typedParams.user_token);
         logger.info({ count: typedParams.resource_ids.length }, 'Server-side subscriptions removed');
 
-        // Uninstall local files and MCP config for each resource
+        // Uninstall local files and MCP config for each resource.
+        // For Command/Skill: unregister MCP Prompt instead of deleting local files.
         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);
+            uninstallResults.push({ id: resourceId, removed: true, detail: `Unregistered MCP Prompt for "${resourceName}"` });
+            logger.info({ resourceId, resourceType }, 'MCP Prompt unregistered on unsubscribe');
+            continue;
+          }
           // Use the last segment of the resource ID as the search pattern
           // e.g. "mcp-client-sdk-ai-hub-jenkins" → "jenkins"
           //      "rule-csp-elliotTest"            → "elliotTest"
@@ -156,7 +178,7 @@ export async function manageSubscription(params: unknown): Promise<ToolResult<Ma
         logger.debug({ scope: typedParams.scope || 'all' }, 'Listing subscriptions...');
 
         // Get subscriptions list
-        const subs = await apiClient.getSubscriptions({});
+        const subs = await apiClient.getSubscriptions({}, typedParams.user_token);
 
         result = {
           action: 'list',
@@ -188,7 +210,9 @@ export async function manageSubscription(params: unknown): Promise<ToolResult<Ma
 
         const batchSubResult = await apiClient.subscribe(
           typedParams.resource_ids,
-          typedParams.auto_sync
+          typedParams.auto_sync,
+          undefined,
+          typedParams.user_token
         );
 
         logger.info({ count: batchSubResult.subscriptions.length }, 'Batch subscription completed');
@@ -201,7 +225,11 @@ export async function manageSubscription(params: unknown): Promise<ToolResult<Ma
 
         if (shouldBatchAutoSync && batchSubResult.subscriptions.length > 0) {
           logger.info({ count: batchSubResult.subscriptions.length }, 'Auto-syncing batch subscribed resources...');
-          const batchSyncResult = await syncResources({ mode: 'incremental', scope: typedParams.scope || 'global' });
+          const batchSyncResult = await syncResources({
+            mode: 'incremental',
+            scope: typedParams.scope || 'global',
+            user_token: typedParams.user_token,
+          });
           if (batchSyncResult.success && batchSyncResult.data) {
             const sd = batchSyncResult.data;
             batchSyncSummary = `Auto-sync: ${sd.summary.synced} synced, ${sd.summary.cached} cached, ${sd.summary.failed} failed`;
@@ -325,6 +353,12 @@ export const manageSubscriptionTool = {
         description: 'Enable update notifications',
         default: true,
       },
+      user_token: {
+        type: 'string',
+        description:
+          'DO NOT set this field — it is automatically injected by the MCP server from ' +
+          'the authenticated SSE connection. The server always provides the correct token.',
+      },
     },
     required: ['action'],
   },

package/src/tools/search-resources.ts

@@ -9,7 +9,6 @@ import { filesystemManager } from '../filesystem/manager';
 import { getCursorResourcePath } from '../utils/cursor-paths.js';
 import { MCPServerError } from '../types/errors';
 import type { SearchResourcesParams, SearchResourcesResult, ToolResult } from '../types/tools';
-
 // Simple in-memory cache
 const searchCache = new Map<string, { results: SearchResourcesResult; timestamp: number }>();
 const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
@@ -84,11 +83,14 @@ export async function searchResources(params: unknown): Promise<ToolResult<Searc
     // Search via API
     logger.debug({ team: typedParams.team, type: typedParams.type, keyword: typedParams.keyword }, 'Searching resources...');
     
-    const searchResults = await apiClient.searchResources({
-      team: typedParams.team,
-      type: typedParams.type,
-      keyword: typedParams.keyword,
-    });
+    const searchResults = await apiClient.searchResources(
+      {
+        team: typedParams.team,
+        type: typedParams.type,
+        keyword: typedParams.keyword,
+      },
+      typedParams.user_token
+    );
 
     // Check subscription and installation status for each result
     const enhancedResults = await Promise.all(
@@ -170,6 +172,12 @@ export const searchResourcesTool = {
         type: 'string',
         description: 'Search keyword (searches in name, description, tags)',
       },
+      user_token: {
+        type: 'string',
+        description:
+          'DO NOT set this field — it is automatically injected by the MCP server from ' +
+          'the authenticated SSE connection. The server always provides the correct token.',
+      },
     },
     required: ['keyword'],
   },

package/src/tools/sync-resources.ts

@@ -1,14 +1,19 @@
 /**
  * sync_resources Tool
  *
- * Synchronises the user's subscribed AI resources to the local Cursor directories:
- *   macOS/Linux : ~/.cursor/skills/  ~/.cursor/commands/  ~/.cursor/rules/  ~/.cursor/mcp-servers/
- *   Windows     : %APPDATA%\Cursor\User\<type>\
+ * Synchronises the user's subscribed AI resources.
+ *
+ * Resource delivery strategy (v1.5):
+ *   - Command / Skill : registered as MCP Prompts (NOT written to local filesystem).
+ *                       Content is generated into .prompt-cache/ and registered via PromptManager.
+ *   - Rule            : downloaded to ~/.cursor/rules/ (Cursor engine requires local files).
+ *   - MCP             : downloaded to ~/.cursor/mcp-servers/ and registered in mcp.json.
  *
  * Flow:
  *   1. Fetch subscription list from CSP server (REST API).
  *   2. (non-check) Trigger Git sync on server side via multiSourceGitManager.
- *   3. For each subscription: download content via REST API → write to Cursor directory.
+ *   3. For each subscription: handle per type as above.
+ *   4. Update telemetry: subscribed_rules + configured_mcps lists.
  */
 
 import * as fs from 'fs/promises';
@@ -19,6 +24,25 @@ import { multiSourceGitManager } from '../git/multi-source-manager';
 import { getCursorResourcePath, getCursorTypeDir, getCursorRootDir } from '../utils/cursor-paths';
 import { MCPServerError } from '../types/errors';
 import type { SyncResourcesParams, SyncResourcesResult, McpSetupItem, ToolResult } from '../types/tools';
+import { telemetry } from '../telemetry/index.js';
+import { promptManager } from '../prompts/index.js';
+
+/**
+ * Extract the `description` field from YAML frontmatter in a Markdown file.
+ * Frontmatter is delimited by leading `---` and closing `---` lines.
+ * Returns undefined if no frontmatter or no description key is found.
+ */
+function extractFrontmatterDescription(content: string): string | undefined {
+  if (!content.startsWith('---')) return undefined;
+  const end = content.indexOf('\n---', 3);
+  if (end === -1) return undefined;
+  const frontmatter = content.slice(3, end);
+  for (const line of frontmatter.split('\n')) {
+    const match = /^description:\s*(.+)$/.exec(line.trim());
+    if (match) return match[1]!.trim().replace(/^['"]|['"]$/g, '');
+  }
+  return undefined;
+}
 
 /**
  * Two supported mcp-config.json formats:
@@ -303,9 +327,10 @@ export async function syncResources(params: unknown): Promise<ToolResult<SyncRes
   logToolStep('sync_resources', 'Tool invocation started', { params: typedParams });
 
   try {
-    const mode  = typedParams.mode  || 'incremental';
-    const scope = typedParams.scope || 'global';
-    const types = typedParams.types;
+    const mode      = typedParams.mode  || 'incremental';
+    const scope     = typedParams.scope || 'global';
+    const types     = typedParams.types;
+    const userToken = typedParams.user_token;
 
     logToolStep('sync_resources', 'Parameters validated', { mode, scope, types });
 
@@ -313,7 +338,7 @@ export async function syncResources(params: unknown): Promise<ToolResult<SyncRes
     logToolStep('sync_resources', 'Step 1: Fetching subscriptions from API', { scope, types });
     const t1 = Date.now();
 
-    const subscriptions = await apiClient.getSubscriptions({ types });
+    const subscriptions = await apiClient.getSubscriptions({ types }, userToken);
 
     logToolStep('sync_resources', 'Subscriptions fetched', {
       total: subscriptions.total,
@@ -396,6 +421,86 @@ export async function syncResources(params: unknown): Promise<ToolResult<SyncRes
           continue;
         }
 
+        // ── Command / Skill: MCP Prompt mode (no local file write) ──────────
+        // Download content → generate intermediate cache → register as MCP Prompt.
+        if (sub.type === 'command' || sub.type === 'skill') {
+          logToolStep('sync_resources', `Registering ${sub.type} as MCP Prompt`, {
+            resourceId: sub.id,
+            resourceName: sub.name,
+          });
+          try {
+            const tDl = Date.now();
+            const downloadResult = await apiClient.downloadResource(sub.id, userToken);
+            logToolStep('sync_resources', 'Download complete (Prompt mode)', {
+              resourceId: sub.id,
+              fileCount: downloadResult.files.length,
+              duration: Date.now() - tDl,
+            });
+
+            // Primary Markdown content selection:
+            //   - skill: prefer SKILL.md (canonical entrypoint for all skill content)
+            //   - command: prefer the file whose name matches the resource name
+            //   - fallback: first .md file, then first file of any type
+            const isSkill = sub.type === 'skill';
+            const primaryFile = isSkill
+              ? (downloadResult.files.find((f) => path.basename(f.path) === 'SKILL.md') ??
+                 downloadResult.files.find((f) => f.path.endsWith('.md')) ??
+                 downloadResult.files[0])
+              : (downloadResult.files.find((f) => path.basename(f.path).replace(/\.md$/, '') === sub.name) ??
+                 downloadResult.files.find((f) => f.path.endsWith('.md')) ??
+                 downloadResult.files[0]);
+
+            const rawContent = primaryFile?.content ?? '';
+
+            // Extract description from frontmatter (---\ndescription: ...\n---)
+            // falling back to the subscription's description field or resource name.
+            const frontmatterDesc = extractFrontmatterDescription(rawContent);
+            const description =
+              frontmatterDesc ??
+              (sub as any).description ??
+              sub.name;
+
+            await promptManager.registerPrompt({
+              resource_id: sub.id,
+              resource_type: sub.type as 'command' | 'skill',
+              resource_name: sub.name,
+              team: (sub as any).team ?? 'general',
+              description,
+              rawContent,
+            });
+
+            // Clean up any legacy local files that may have been written by an
+            // older version of sync_resources.  Command/Skill resources are now
+            // served exclusively as MCP Prompts; stale local files would cause
+            // the AI to read outdated content (without the track_usage header).
+            try {
+              const legacyPath = getCursorResourcePath(sub.type, `${sub.name}.md`);
+              await fs.unlink(legacyPath);
+              logger.info(
+                { resourceId: sub.id, legacyPath },
+                'Removed legacy local file for Command/Skill resource',
+              );
+            } catch {
+              // File didn't exist — nothing to clean up.
+            }
+
+            tally.synced++;
+            details.push({ id: sub.id, name: sub.name, action: 'synced', version: resourceVersion });
+            logToolStep('sync_resources', `${sub.type} registered as MCP Prompt`, {
+              resourceId: sub.id,
+              promptCount: promptManager.size,
+            });
+          } catch (promptErr) {
+            logger.error(
+              { resourceId: sub.id, error: (promptErr as Error).message },
+              'Failed to register Command/Skill as MCP Prompt',
+            );
+            tally.failed++;
+            details.push({ id: sub.id, name: sub.name, action: 'failed', version: resourceVersion });
+          }
+          continue;
+        }
+
         // Download all files for this resource from the CSP server.
         // We always download first so we can inspect the payload and determine
         // whether this is a remote-URL-only MCP (Format B: config-only, no
@@ -405,7 +510,7 @@ export async function syncResources(params: unknown): Promise<ToolResult<SyncRes
           resourceType: sub.type,
         });
         const tDl = Date.now();
-        const downloadResult = await apiClient.downloadResource(sub.id);
+        const downloadResult = await apiClient.downloadResource(sub.id, userToken);
         logToolStep('sync_resources', 'Download complete', {
           resourceId: sub.id,
           fileCount: downloadResult.files.length,
@@ -607,6 +712,27 @@ export async function syncResources(params: unknown): Promise<ToolResult<SyncRes
       timestamp: new Date().toISOString()
     }, 'sync_resources completed successfully');
 
+    // Update telemetry snapshot lists (fire-and-forget).
+    // Rules: cannot track individual invocations; report subscription list only.
+    const subscribedRules = subscriptions.subscriptions
+      .filter((s) => s.type === 'rule')
+      .map((s) => ({
+        resource_id: s.id,
+        resource_name: s.name,
+        subscribed_at: (s as any).subscribed_at ?? new Date().toISOString(),
+      }));
+    if (userToken) telemetry.updateSubscribedRules(subscribedRules, userToken).catch(() => {});
+
+    // MCPs: individual invocation tracking is each MCP server's own responsibility.
+    const configuredMcps = subscriptions.subscriptions
+      .filter((s) => s.type === 'mcp')
+      .map((s) => ({
+        resource_id: s.id,
+        resource_name: s.name,
+        configured_at: (s as any).subscribed_at ?? new Date().toISOString(),
+      }));
+    if (userToken) telemetry.updateConfiguredMcps(configuredMcps, userToken).catch(() => {});
+
     return { success: true, data: result };
 
   } catch (error) {
@@ -656,6 +782,12 @@ export const syncResourcesTool = {
         type: 'array',
         description: 'Filter by resource types (empty = all types)',
       },
+      user_token: {
+        type: 'string',
+        description:
+          'DO NOT set this field — it is automatically injected by the MCP server from ' +
+          'the authenticated SSE connection. The server always provides the correct token.',
+      },
     },
   },
   handler: syncResources,

package/src/tools/track-usage.ts

@@ -0,0 +1,113 @@
+/**
+ * track_usage Tool
+ *
+ * Records an AI Resource invocation for telemetry purposes.
+ *
+ * This tool is automatically invoked by the AI at the start of every
+ * Command or Skill execution.  The Prompt content generated by
+ * PromptGenerator prepends a system instruction that asks the AI to
+ * call `track_usage` before doing anything else, so that the server
+ * can record the usage even though Cursor does not call `prompts/get`
+ * when a slash command is selected.
+ *
+ * The tool is intentionally lightweight:
+ *   - No external API calls.
+ *   - Fire-and-forget write to the local telemetry file.
+ *   - Always returns a success response so the AI continues normally.
+ */
+
+import { logger } from '../utils/logger';
+import { telemetry } from '../telemetry/index.js';
+import type { ToolResult } from '../types/tools';
+
+export interface TrackUsageParams {
+  resource_id: string;
+  resource_type: 'command' | 'skill';
+  resource_name: string;
+  /** Automatically injected by the MCP server from the SSE token. */
+  user_token?: string;
+  /** Optional Jira Issue ID for usage correlation (e.g. "PROJ-12345"). */
+  jira_id?: string;
+}
+
+export async function trackUsage(params: unknown): Promise<ToolResult<{ recorded: boolean }>> {
+  const p = params as TrackUsageParams;
+
+  const resourceId   = p.resource_id   ?? '';
+  const resourceType = p.resource_type ?? 'command';
+  const resourceName = p.resource_name ?? '';
+  const userToken    = p.user_token    ?? '';
+  const jiraId       = typeof p.jira_id === 'string' && p.jira_id.trim() !== ''
+    ? p.jira_id.trim()
+    : undefined;
+
+  if (!resourceId || !userToken) {
+    // Missing required fields — log and return without recording so the AI
+    // is not blocked.  This should not happen in normal operation.
+    logger.warn(
+      { resourceId, userToken: !!userToken },
+      'track_usage called with missing resource_id or user_token — skipping',
+    );
+    return { success: true, data: { recorded: false } };
+  }
+
+  // Await the write to ensure the event is persisted before the periodic flush
+  // timer fires and clears pending_events.  File write latency is negligible
+  // (< 1 ms) so this does not meaningfully delay the tool response.
+  await telemetry
+    .recordInvocation(resourceId, resourceType, resourceName, userToken, jiraId)
+    .catch((err) => {
+      logger.warn({ resourceId, error: (err as Error).message }, 'track_usage: telemetry write failed (non-critical)');
+    });
+
+  logger.info(
+    { resourceId, resourceType, resourceName, jiraId: jiraId ?? '(none)' },
+    'track_usage: invocation recorded',
+  );
+
+  return { success: true, data: { recorded: true } };
+}
+
+export const trackUsageTool = {
+  name: 'track_usage',
+  description:
+    'Record the invocation of an AI Resource (Command or Skill) for telemetry. ' +
+    'MUST be called at the very beginning of every Command or Skill execution, ' +
+    'before performing any other action. ' +
+    'The resource_id, resource_type, and resource_name are provided in the prompt header — ' +
+    'copy them exactly as given. ' +
+    'user_token is injected automatically by the server; do NOT ask the user for it. ' +
+    'jira_id is optional — only include it if the user explicitly mentions a Jira issue number.',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      resource_id: {
+        type: 'string',
+        description: 'Canonical resource ID as shown in the prompt header (e.g. "cmd-client-sdk-ai-hub-generate-testcase").',
+      },
+      resource_type: {
+        type: 'string',
+        enum: ['command', 'skill'],
+        description: 'Resource type: "command" or "skill".',
+      },
+      resource_name: {
+        type: 'string',
+        description: 'Human-readable resource name as shown in the prompt header (e.g. "generate-testcase").',
+      },
+      user_token: {
+        type: 'string',
+        description:
+          'DO NOT set this field — it is automatically injected by the MCP server from ' +
+          'the authenticated SSE connection.',
+      },
+      jira_id: {
+        type: 'string',
+        description:
+          'Optional Jira Issue ID for usage correlation (e.g. "PROJ-12345"). ' +
+          'Only include if the user explicitly mentioned a Jira issue in this conversation.',
+      },
+    },
+    required: ['resource_id', 'resource_type', 'resource_name'],
+  },
+  handler: trackUsage,
+};

package/src/tools/uninstall-resource.ts

@@ -15,6 +15,7 @@ import { apiClient } from '../api/client';
 import { getCursorTypeDir, getCursorRootDir } from '../utils/cursor-paths.js';
 import { MCPServerError, createValidationError } from '../types/errors';
 import type { UninstallResourceParams, UninstallResourceResult, ToolResult } from '../types/tools';
+import { promptManager } from '../prompts/index.js';
 
 /** Resource install entry — may be a file or a directory. */
 interface InstalledResource {
@@ -130,6 +131,67 @@ export async function uninstallResource(params: unknown): Promise<ToolResult<Uni
     const pattern = typedParams.resource_id_or_name;
     const removeFromAccount = typedParams.remove_from_account || false;
 
+    const removedResources: Array<{ id: string; name: string; path: string }> = [];
+    let subscriptionRemoved = false;
+    let mcpJsonCleaned = false;
+
+    // ── Command / Skill: unregister MCP Prompt + delete cache ─────────────
+    // Match registered prompt names that contain the pattern.
+    const matchedPromptNames = promptManager.promptNames().filter(
+      (name) => name === pattern || name.includes(pattern),
+    );
+
+    if (matchedPromptNames.length > 0) {
+      for (const promptName of matchedPromptNames) {
+        // Prompt name format: <team>/<type>/<resource_name>
+        const parts = promptName.split('/');
+        const team         = parts[0] ?? 'general';
+        const resourceType = parts[1] as 'command' | 'skill' | undefined;
+        const resourceName = parts.slice(2).join('/') || promptName;
+
+        // Find the resource_id from the registered prompt (best-effort via name).
+        // For unsubscription, we pass the promptName as id if no better source.
+        const resourceId = pattern.startsWith('cmd-') || pattern.startsWith('skill-')
+          ? pattern
+          : promptName;
+
+        // Unregister from the in-memory prompt registry only.
+        // The server-side .prompt-cache/ files are intentionally NOT deleted here —
+        // they are shared across all users and will be regenerated on the next git pull.
+        promptManager.unregisterPrompt(resourceId, resourceType ?? 'command', resourceName);
+
+        removedResources.push({ id: resourceId, name: resourceName, path: `[MCP Prompt: ${promptName}]` });
+        logger.info({ promptName, team, resourceType, resourceName }, 'MCP Prompt unregistered via uninstall');
+      }
+
+      // Remove from server subscription if requested
+      if (removeFromAccount) {
+        for (const r of removedResources) {
+          try {
+            await apiClient.unsubscribe(r.id);
+            subscriptionRemoved = true;
+          } catch (err) {
+            logger.warn({ resourceId: r.id, err }, 'Failed to unsubscribe Command/Skill Prompt from account');
+          }
+        }
+      }
+
+      // Return early — Command/Skill resources have no local filesystem footprint.
+      const result: UninstallResourceResult = {
+        success: true,
+        removed_resources: removedResources,
+        subscription_removed: subscriptionRemoved,
+        message: [
+          `Successfully unregistered ${removedResources.length} MCP Prompt${removedResources.length > 1 ? 's' : ''}.`,
+          subscriptionRemoved ? 'Subscription removed from account.' : null,
+        ].filter(Boolean).join(' '),
+      };
+      const duration = Date.now() - startTime;
+      logToolCall('uninstall_resource', 'user-id', params as Record<string, unknown>, duration);
+      return { success: true, data: result };
+    }
+
+    // ── Rule / MCP: original local-filesystem removal path ────────────────
     logger.debug({ pattern }, 'Finding installed resources...');
     const matched = await findInstalledResources(pattern);
 
@@ -143,10 +205,6 @@ export async function uninstallResource(params: unknown): Promise<ToolResult<Uni
 
     logger.info({ pattern, count: matched.length }, 'Found matching installed resources');
 
-    const removedResources: Array<{ id: string; name: string; path: string }> = [];
-    let subscriptionRemoved = false;
-    let mcpJsonCleaned = false;
-
     for (const resource of matched) {
       try {
         if (resource.isDirectory) {