@elliotding/ai-agent-mcp 0.1.25 → 0.1.27

package/src/types/tools.ts

@@ -1,305 +0,0 @@
-/**
- * MCP Tool Types
- */
-
-import type { MCPToolSchema } from './mcp';
-
-// ── LocalAction ────────────────────────────────────────────────────────────
-//
-// When the MCP server is deployed remotely it cannot write to the user's local
-// filesystem.  Instead it returns a list of LocalAction instructions that the
-// AI Agent (running inside the user's local Cursor) must execute.
-//
-// Action types:
-//   write_file          – create or overwrite a local file
-//   delete_file         – delete a local file or directory
-//   merge_mcp_json      – merge an MCP server entry into ~/.cursor/mcp.json
-//   remove_mcp_json_entry – remove an MCP server entry from ~/.cursor/mcp.json
-
-export interface WriteFileAction {
-  action: 'write_file';
-  /** Absolute path on the user's local machine (may start with ~). */
-  path: string;
-  /** UTF-8 file content to write. */
-  content: string;
-}
-
-export interface DeleteFileAction {
-  action: 'delete_file';
-  /** Absolute path on the user's local machine (may start with ~). */
-  path: string;
-  /** When true, recursively delete a directory. */
-  recursive?: boolean;
-}
-
-export interface MergeMcpJsonAction {
-  action: 'merge_mcp_json';
-  /** Absolute path to the user's mcp.json file. */
-  mcp_json_path: string;
-  /** Key under mcpServers to add or update. */
-  server_name: string;
-  /** The MCP server entry object to merge in. */
-  entry: Record<string, unknown>;
-  /** env keys that are currently empty and must be filled by the user. */
-  missing_env?: string[];
-  /** Human-readable hint when manual env configuration is required. */
-  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 {
-  action: 'remove_mcp_json_entry';
-  /** Absolute path to the user's mcp.json file. */
-  mcp_json_path: string;
-  /** Key under mcpServers to remove. */
-  server_name: string;
-}
-
-export type LocalAction =
-  | WriteFileAction
-  | DeleteFileAction
-  | MergeMcpJsonAction
-  | RemoveMcpJsonEntryAction;
-
-// Tool Handler Function Type (generic, accepts any params and returns any result)
-export type ToolHandler = (params: unknown) => Promise<ToolResult>;
-
-// Tool Definition
-export interface ToolDefinition {
-  name: string;
-  description: string;
-  inputSchema: MCPToolSchema;
-  handler: ToolHandler;
-}
-
-// Tool Result (generic)
-export interface ToolResult<T = unknown> {
-  success: boolean;
-  data?: T;
-  error?: {
-    code: string;
-    message: string;
-    details?: unknown;
-  };
-}
-
-//===============================================
-// Tool-specific Parameter and Result Types
-//===============================================
-
-// sync_resources
-export interface SyncResourcesParams {
-  mode?: 'check' | 'incremental' | 'full';
-  scope?: 'global' | 'workspace' | 'all';
-  types?: string[];
-  /**
-   * CSP API token from the user's mcp.json env configuration.
-   * Overrides the server-level fallback token so that each user
-   * makes API calls with their own identity.
-   */
-  user_token?: string;
-  /**
-   * List of MCP server names that are already configured in the user's
-   * ~/.cursor/mcp.json. The server will skip downloading and generating
-   * write_file actions for these MCP resources to reduce overhead.
-   * 
-   * Set this to the keys from mcpServers in ~/.cursor/mcp.json:
-   * Object.keys(JSON.parse(fs.readFileSync('~/.cursor/mcp.json')).mcpServers || {})
-   * 
-   * Only applies in 'incremental' mode; 'full' mode always downloads everything.
-   */
-  configured_mcp_servers?: string[];
-}
-
-export interface McpSetupItem {
-  /** MCP server name as it appears in mcp.json */
-  server_name: string;
-  /** Human-readable path to mcp.json on this platform */
-  mcp_json_path: string;
-  /** env keys that are currently empty and need user input */
-  missing_env: string[];
-  /** true when the registered command might not be correct for this machine */
-  command_needs_verification: boolean;
-  /** the command string that was registered */
-  command: string;
-  /** freeform guidance shown to the user */
-  setup_hint: string;
-  /** absolute path to a local setup/readme doc found in the install directory, if any */
-  setup_doc?: string;
-}
-
-export interface SyncResourcesResult {
-  mode: string;
-  health_score: number;
-  summary: {
-    total: number;
-    synced: number;
-    cached: number;
-    failed: number;
-  };
-  details: Array<{
-    id: string;
-    name: string;
-    action: string;
-    version: string;
-  }>;
-  /**
-   * MCP servers that were installed/updated but require manual configuration
-   * before they can be used. Present only when at least one server needs setup.
-   * @deprecated use local_actions_required MergeMcpJsonAction.missing_env instead
-   */
-  pending_setup?: McpSetupItem[];
-  /**
-   * Ordered list of file-system and mcp.json operations the AI Agent must
-   * execute on the user's LOCAL machine after receiving this response.
-   * Present only when at least one Rule or MCP resource was synced.
-   *
-   * The AI MUST execute every action in order before reporting success to the
-   * user.  See LocalAction type variants for details.
-   */
-  local_actions_required?: LocalAction[];
-}
-
-// manage_subscription
-export interface ManageSubscriptionParams {
-  action: 'subscribe' | 'unsubscribe' | 'list' | 'batch_subscribe' | 'batch_unsubscribe';
-  resource_ids?: string[];
-  auto_sync?: boolean;
-  scope?: 'global' | 'workspace';
-  notify?: boolean;
-  /** CSP API token from the user's mcp.json env configuration. */
-  user_token?: string;
-}
-
-export interface ManageSubscriptionResult {
-  action: string;
-  success: boolean;
-  subscriptions?: Array<{
-    id: string;
-    name: string;
-    type: string;
-    subscribed_at: string;
-  }>;
-  message?: string;
-  /** Sync results for each resource after auto-sync on subscribe */
-  sync_details?: Array<{ id: string; name: string; action: string }>;
-  /** MCP servers that need manual configuration after auto-sync */
-  pending_setup?: unknown[];
-}
-
-// search_resources
-export interface SearchResourcesParams {
-  team?: string;
-  type?: string;
-  keyword: string;
-  /** CSP API token from the user's mcp.json env configuration. */
-  user_token?: string;
-}
-
-export interface SearchResourcesResult {
-  total: number;
-  results: Array<{
-    id: string;
-    name: string;
-    type: string;
-    team: string;
-    version: string;
-    description: string;
-    score: number;
-    is_subscribed: boolean;
-    is_installed: boolean;
-  }>;
-}
-
-// resolve_prompt_content
-export interface ResolvePromptContentParams {
-  prompt_name?: string;
-  resource_id?: string;
-  /** CSP API token from the user's mcp.json env configuration. */
-  user_token?: string;
-  /** Optional Jira Issue ID for usage correlation. */
-  jira_id?: string;
-}
-
-export interface ResolvePromptContentResult {
-  prompt_name: string;
-  resource_id: string;
-  resource_type: 'command' | 'skill';
-  resource_name: string;
-  description: string;
-  content: string;
-  content_source: 'cache' | 'generated' | 'raw_fallback';
-  usage_tracked: boolean;
-}
-
-// upload_resource
-export interface FileEntry {
-  path: string;    // Relative path under the type subdir (e.g. "my-cmd.md" or "code-review/SKILL.md")
-  content: string; // File content string
-}
-
-export interface UploadResourceParams {
-  resource_id: string;
-  /** Resource category. Optional — auto-detected from file structure when omitted. */
-  type?: 'command' | 'skill' | 'rule' | 'mcp';
-  message: string;
-  /** Human-readable resource name sent to the CSP API. Defaults to the primary file name (without extension). */
-  name?: string;
-  /** Target source repo from ai-resources-config.json (e.g. "csp", "client-sdk-ai-hub"). Defaults to default_source. */
-  target_source?: string;
-  team?: string;
-
-  // ---- Three input modes (priority: files > directory > content) ----
-
-  /** File list to upload. Paths are relative to the type subdir of the chosen source. Any file extension allowed. */
-  files: FileEntry[];
-
-  // ---- Optional fields ----
-  title?: string;
-  metadata?: Record<string, unknown>;
-  /** CSP API token from the user's mcp.json env configuration. */
-  user_token?: string;
-}
-
-export interface UploadResourceResult {
-  resource_id: string;
-  version: string;
-  url: string;
-  commit_hash: string;
-  message: string;
-}
-
-// uninstall_resource
-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;
-}
-
-export interface UninstallResourceResult {
-  success: boolean;
-  removed_resources: Array<{
-    id: string;
-    name: string;
-    path: string;
-  }>;
-  subscription_removed: boolean;
-  message: string;
-  /**
-   * Ordered list of file-system and mcp.json operations the AI Agent must
-   * execute on the user's LOCAL machine after receiving this response.
-   * Present only for Rule and local-executable MCP resources.
-   */
-  local_actions_required?: LocalAction[];
-}

package/src/utils/cursor-paths.ts

@@ -1,135 +0,0 @@
-/**
- * Cursor IDE standard directory path resolver.
- *
- * Cursor stores user-level assets in platform-specific locations:
- *   macOS / Linux : ~/.cursor/<type>/
- *   Windows       : %APPDATA%\Cursor\User\<type>\
- *                   (typically C:\Users\<user>\AppData\Roaming\Cursor\User\<type>\)
- *
- * Resource type → subdirectory mapping mirrors the actual Cursor directory layout.
- */
-
-import * as os from 'os';
-import * as path from 'path';
-
-/** Supported Cursor resource types and their directory names. */
-export const CURSOR_TYPE_DIRS: Record<string, string> = {
-  skill:   'skills',
-  skills:  'skills',
-  command: 'commands',
-  commands:'commands',
-  rule:    'rules',
-  rules:   'rules',
-  mcp:     'mcp-servers',
-  'mcp-servers': 'mcp-servers',
-};
-
-/**
- * Returns the root of the Cursor user directory on the current platform.
- *
- * macOS / Linux : ~/.cursor
- * Windows       : %APPDATA%\Cursor\User
- *
- * NOTE: Only use this when running code on the USER's local machine.
- * When generating paths for LocalAction instructions (which are executed by the
- * AI on the user's machine, not on this server), use getCursorRootDirForClient()
- * instead to avoid returning the server's home directory.
- */
-export function getCursorRootDir(): string {
-  if (process.platform === 'win32') {
-    // APPDATA is always set on Windows; fall back to USERPROFILE as a safety net
-    const appData = process.env.APPDATA ?? path.join(os.homedir(), 'AppData', 'Roaming');
-    return path.join(appData, 'Cursor', 'User');
-  }
-  // macOS and Linux both use ~/.cursor
-  return path.join(os.homedir(), '.cursor');
-}
-
-/**
- * Returns a platform-neutral Cursor root path for use in LocalAction instructions.
- *
- * LocalAction paths are sent to the AI Agent running on the USER's local machine,
- * not executed on this (possibly remote) server.  Using os.homedir() here would
- * produce the server's home directory (e.g. /root/.cursor on a Linux server),
- * which is wrong when the user is on macOS or Windows.
- *
- * We return a tilde-prefixed path ("~/.cursor") which the AI / shell on the
- * user's machine will expand to the correct home directory automatically.
- * For Windows we still return the APPDATA-relative form as a hint, but note
- * that the AI is expected to expand %APPDATA% on the client side.
- */
-export function getCursorRootDirForClient(): string {
-  // Return a portable ~-based path; the AI on the user's machine expands it.
-  return '~/.cursor';
-}
-
-/**
- * Returns the Cursor subdirectory for a given resource type, using a
- * client-side portable path (tilde-based).  Use this when building paths
- * that will be included in LocalAction instructions.
- */
-export function getCursorTypeDirForClient(resourceType: string): string {
-  const subdir = CURSOR_TYPE_DIRS[resourceType.toLowerCase()];
-  if (!subdir) {
-    throw new Error(
-      `Unknown resource type "${resourceType}". ` +
-      `Supported types: ${Object.keys(CURSOR_TYPE_DIRS).join(', ')}`
-    );
-  }
-  return `${getCursorRootDirForClient()}/${subdir}`;
-}
-
-/**
- * Returns the Cursor subdirectory for a given resource type.
- *
- * @param resourceType  - API resource type string (e.g. 'skill', 'command', 'rule', 'mcp')
- * @returns Absolute path to the matching Cursor directory
- * @throws  Error if the resource type is not recognised
- *
- * @example
- *   getCursorTypeDir('skill')   // ~/.cursor/skills
- *   getCursorTypeDir('command') // ~/.cursor/commands
- *   getCursorTypeDir('rule')    // ~/.cursor/rules
- *   getCursorTypeDir('mcp')     // ~/.cursor/mcp-servers
- */
-export function getCursorTypeDir(resourceType: string): string {
-  const subdir = CURSOR_TYPE_DIRS[resourceType.toLowerCase()];
-  if (!subdir) {
-    throw new Error(
-      `Unknown resource type "${resourceType}". ` +
-      `Supported types: ${Object.keys(CURSOR_TYPE_DIRS).join(', ')}`
-    );
-  }
-  return path.join(getCursorRootDir(), subdir);
-}
-
-/**
- * Returns the install path for a specific named resource.
- *
- * For directory-based resources (skill, mcp) the result is a directory:
- *   ~/.cursor/skills/<name>/
- *
- * For file-based resources (command, rule) the result is the file path
- * preserving the original filename (caller should pass name with extension):
- *   ~/.cursor/commands/<name>         (e.g. generate-testcase.md)
- *   ~/.cursor/rules/<name>            (e.g. elliotTest.mdc)
- *
- * @param resourceType  - Resource type string
- * @param resourceName  - Resource name (with or without extension)
- */
-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');
-}

package/src/utils/log-cleaner.ts

@@ -1,92 +0,0 @@
-/**
- * Log Cleanup Module
- * Automatically deletes log files older than retention period
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { logger } from './logger';
-import { config } from '../config';
-
-// Matches both the canonical name (app-YYYY-MM-DD.log) produced after the
-// midnight rename, and the active pino-roll name (app.YYYY-MM-DD.1.log).
-const LOG_FILE_PATTERN = /^app[.-]\d{4}-\d{2}-\d{2}[\d.]*\.log$/;
-
-/**
- * Delete log files older than retention days
- */
-// eslint-disable-next-line @typescript-eslint/require-await
-export async function cleanupOldLogs(): Promise<void> {
-  const logsDir = path.resolve(process.cwd(), config.logging.dir);
-
-  if (!fs.existsSync(logsDir)) {
-    logger.debug('Logs directory does not exist, skipping cleanup');
-    return;
-  }
-
-  const retentionMs = config.logging.retentionDays * 24 * 60 * 60 * 1000;
-  const now = Date.now();
-
-  try {
-    const files = fs.readdirSync(logsDir);
-    let deletedCount = 0;
-
-    for (const file of files) {
-      const match = file.match(LOG_FILE_PATTERN);
-      if (!match) {
-        continue; // Skip non-log files
-      }
-
-      const filePath = path.join(logsDir, file);
-      const stats = fs.statSync(filePath);
-      const fileAge = now - stats.mtimeMs;
-
-      if (fileAge > retentionMs) {
-        fs.unlinkSync(filePath);
-        deletedCount++;
-        logger.info(
-          { file, agedays: Math.floor(fileAge / (24 * 60 * 60 * 1000)) },
-          `Deleted old log file: ${file}`
-        );
-      }
-    }
-
-    if (deletedCount > 0) {
-      logger.info(
-        { deletedCount },
-        `Log cleanup completed: ${deletedCount} old log files deleted`
-      );
-    } else {
-      logger.debug('Log cleanup completed: no old log files to delete');
-    }
-  } catch (error) {
-    logger.error({ error }, 'Failed to cleanup old log files');
-  }
-}
-
-/**
- * Start log cleanup scheduler
- * Runs cleanup once per day at 2 AM
- */
-export function startLogCleanupSchedule(): NodeJS.Timeout {
-  // Run cleanup immediately on startup
-  void cleanupOldLogs();
-
-  // Schedule cleanup every 7 days
-  const interval = 7 * 24 * 60 * 60 * 1000; // 7 days
-  const timer = setInterval(() => {
-    void cleanupOldLogs();
-  }, interval);
-
-  logger.info({ retentionDays: config.logging.retentionDays }, 'Log cleanup scheduler started');
-
-  return timer;
-}
-
-/**
- * Stop log cleanup scheduler
- */
-export function stopLogCleanupSchedule(timer: NodeJS.Timeout): void {
-  clearInterval(timer);
-  logger.info('Log cleanup scheduler stopped');
-}