@elliotding/ai-agent-mcp 0.1.3 → 0.1.4

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:
@@ -397,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
@@ -608,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) {
@@ -660,9 +785,8 @@ export const syncResourcesTool = {
       user_token: {
         type: 'string',
         description:
-          'CSP API token for the current user. Read this from the CSP_API_TOKEN environment ' +
-          'variable configured in the user\'s mcp.json. When provided, this token is used ' +
-          'for all CSP API calls in this request instead of the server-level fallback token.',
+          '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.',
       },
     },
   },

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) {

package/src/tools/upload-resource.ts

@@ -18,11 +18,25 @@ import { logger, logToolCall } from '../utils/logger';
 import { apiClient } from '../api/client';
 import { resourceLoader } from '../resources';
 import { MCPServerError, createValidationError } from '../types/errors';
+import { promptManager } from '../prompts/index.js';
 import type { UploadResourceParams, UploadResourceResult, ToolResult, FileEntry } from '../types/tools';
 import type { ResourceType } from '../types/resources';
 
 type ResourceCategory = 'command' | 'skill' | 'rule' | 'mcp';
 
+/** Extract the `description` field from YAML frontmatter (--- ... ---) in Markdown content. */
+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;
+}
+
 /**
  * Infer the resource type from the uploaded file list ONLY when the user has
  * not explicitly stated a type. If the user declared a type, that always wins.
@@ -254,6 +268,41 @@ export async function uploadResource(params: unknown): Promise<ToolResult<Upload
 
     logger.info({ finalResourceId, version, commitHash }, 'Upload finalized successfully');
 
+    // For Command / Skill: register the uploaded content as an MCP Prompt immediately,
+    // so the user can invoke it via slash-command without a full sync cycle.
+    if (resourceType === 'command' || resourceType === 'skill') {
+      try {
+        const primaryFile = resourceType === 'skill'
+          ? (fileEntries.find((f) => path.basename(f.path) === 'SKILL.md') ??
+             fileEntries.find((f) => f.path.endsWith('.md')) ??
+             fileEntries[0])
+          : (fileEntries.find((f) => path.basename(f.path).replace(/\.md$/, '') === resourceName) ??
+             fileEntries.find((f) => f.path.endsWith('.md')) ??
+             fileEntries[0]);
+
+        const rawContent = primaryFile?.content ?? '';
+        const team = (typedParams as any).team ?? 'general';
+        const frontmatterDesc = extractFrontmatterDescription(rawContent);
+        const description = frontmatterDesc ?? typedParams.message ?? resourceName;
+
+        await promptManager.registerPrompt({
+          resource_id: finalResourceId,
+          resource_type: resourceType as 'command' | 'skill',
+          resource_name: resourceName,
+          team,
+          description,
+          rawContent,
+        });
+        logger.info({ finalResourceId, resourceType }, 'MCP Prompt registered after upload');
+      } catch (promptErr) {
+        // Non-fatal: the resource is uploaded; Prompt registration is best-effort.
+        logger.warn(
+          { finalResourceId, error: (promptErr as Error).message },
+          'MCP Prompt registration after upload failed (non-fatal)',
+        );
+      }
+    }
+
     const result: UploadResourceResult = {
       resource_id: finalResourceId,
       version,
@@ -308,8 +357,7 @@ export const uploadResourceTool = {
     'path must be the original filename as-is (relative, no path traversal). ' +
     'No restriction on file extensions — mcp packages may include .py, .js, package.json, etc.\n' +
 
-    '\nIMPORTANT: Always read the CSP_API_TOKEN from the user\'s environment and pass it as user_token ' +
-    'so that each user\'s API calls use their own identity.',
+    '\nThe user_token is injected automatically by the server — do NOT read or pass it manually.',
   inputSchema: {
     type: 'object' as const,
     properties: {
@@ -373,9 +421,8 @@ export const uploadResourceTool = {
       user_token: {
         type: 'string',
         description:
-          'CSP API token for the current user. Read this from the CSP_API_TOKEN environment ' +
-          'variable configured in the user\'s mcp.json. When provided, this token is used ' +
-          'for all CSP API calls in this request instead of the server-level fallback token.',
+          '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: ['resource_id', 'message', 'files'],

package/src/utils/cursor-paths.ts

@@ -81,3 +81,16 @@ export function getCursorTypeDir(resourceType: string): string {
 export function getCursorResourcePath(resourceType: string, resourceName: string): string {
   return path.join(getCursorTypeDir(resourceType), resourceName);
 }
+
+/**
+ * Returns the path to the local AI resource telemetry file.
+ *
+ * Stored at the Cursor root level (not inside a resource-type subdirectory)
+ * so it persists independently of individual resource installs/uninstalls.
+ *
+ * macOS / Linux : ~/.cursor/ai-resource-telemetry.json
+ * Windows       : %APPDATA%\Cursor\User\ai-resource-telemetry.json
+ */
+export function getTelemetryFilePath(): string {
+  return path.join(getCursorRootDir(), 'ai-resource-telemetry.json');
+}