@elliotding/ai-agent-mcp 0.1.25 → 0.1.27

package/src/tools/track-usage.ts

@@ -1,113 +0,0 @@
-/**
- * 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

@@ -1,199 +0,0 @@
-/**
- * uninstall_resource Tool
- * Uninstall a resource from local filesystem and clean up related configuration.
- *
- * For MCP resources this also removes the mcpServers entry from ~/.cursor/mcp.json.
- * For directory-based resources (skill, mcp) the entire install directory is removed.
- */
-
-import { logger, logToolCall } from '../utils/logger';
-import { apiClient } from '../api/client';
-import { getCursorTypeDirForClient, getCursorRootDirForClient } from '../utils/cursor-paths.js';
-import { MCPServerError, createValidationError } from '../types/errors';
-import type { UninstallResourceParams, UninstallResourceResult, LocalAction, ToolResult } from '../types/tools';
-import { promptManager } from '../prompts/index.js';
-
-
-export async function uninstallResource(params: unknown): Promise<ToolResult<UninstallResourceResult>> {
-  const startTime = Date.now();
-  const typedParams = params as UninstallResourceParams;
-
-  logger.info({ tool: 'uninstall_resource', params }, 'uninstall_resource called');
-
-  try {
-    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;
-
-    // ── Command / Skill: unregister MCP Prompt + delete cache ─────────────
-    // Match registered prompt names that contain the pattern.
-    const matchedPromptNames = promptManager.promptNames(typedParams.user_token ?? '').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, typedParams.user_token ?? '');
-
-        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: return LocalAction instructions for the AI to execute ────
-    // 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, 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`;
-
-    // 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 });
-      }
-    }
-
-    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(
-        pattern,
-        'resource_id_or_name',
-        'No installed Rule or MCP resources found matching pattern. Use search_resources to find available resources'
-      );
-    }
-
-    // Remove from server subscription if requested
-    if (removeFromAccount) {
-      try {
-        await apiClient.unsubscribe(pattern);
-        subscriptionRemoved = true;
-      } catch (err) {
-        logger.warn({ pattern, err }, 'Failed to unsubscribe resource from account');
-      }
-    }
-
-    const result: UninstallResourceResult = {
-      success: true,
-      removed_resources: removedResources,
-      subscription_removed: subscriptionRemoved,
-      message: [
-        `Prepared ${localActions.length} local uninstall action(s) for ${removedResources.length} resource(s).`,
-        'Execute every action in local_actions_required on the user\'s local machine.',
-        subscriptionRemoved ? 'Subscription removed from account.' : null,
-      ].filter(Boolean).join(' '),
-      local_actions_required: localActions,
-    };
-
-    const duration = Date.now() - startTime;
-    logToolCall('uninstall_resource', 'user-id', params as Record<string, unknown>, duration);
-    logger.info({ pattern, actionCount: localActions.length, subscriptionRemoved, duration }, 'uninstall_resource completed');
-
-    return { success: true, data: result };
-
-  } catch (error) {
-    logger.error({ error, pattern: typedParams.resource_id_or_name }, 'uninstall_resource failed');
-    return {
-      success: false,
-      error: {
-        code: error instanceof MCPServerError ? error.code : 'UNKNOWN_ERROR',
-        message: error instanceof Error ? error.message : String(error),
-      },
-    };
-  }
-}
-
-// Tool definition for registry
-export const uninstallResourceTool = {
-  name: 'uninstall_resource',
-  description:
-    'Uninstall a Rule or MCP resource from the user\'s local machine. ' +
-    'Returns `local_actions_required` — an ordered list of delete_file and ' +
-    'remove_mcp_json_entry actions that the AI Agent MUST execute on the USER\'S LOCAL MACHINE. ' +
-    'For delete_file actions: delete the file or directory at the given path. ' +
-    'For remove_mcp_json_entry actions: read ~/.cursor/mcp.json, delete the matching ' +
-    'mcpServers key, then write the file back. ' +
-    'Command and Skill resources are handled by unregistering their MCP Prompt (no local files). ' +
-    'Set remove_from_account: true to also cancel the server-side subscription.',
-  inputSchema: {
-    type: 'object' as const,
-    properties: {
-      resource_id_or_name: {
-        type: 'string',
-        description: 'Resource ID, name, or pattern (supports fuzzy matching)',
-      },
-      remove_from_account: {
-        type: 'boolean',
-        description: 'Also remove from subscription list (default: false)',
-        default: false,
-      },
-    },
-    required: ['resource_id_or_name'],
-  },
-  handler: uninstallResource,
-};