@elliotding/ai-agent-mcp 0.1.0

package/src/types/tools.ts

@@ -0,0 +1,175 @@
+/**
+ * MCP Tool Types
+ */
+
+import type { MCPToolSchema } from './mcp';
+
+// 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[];
+}
+
+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.
+   */
+  pending_setup?: McpSetupItem[];
+}
+
+// manage_subscription
+export interface ManageSubscriptionParams {
+  action: 'subscribe' | 'unsubscribe' | 'list' | 'batch_subscribe' | 'batch_unsubscribe';
+  resource_ids?: string[];
+  auto_sync?: boolean;
+  scope?: 'global' | 'workspace';
+  notify?: boolean;
+}
+
+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;
+}
+
+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;
+  }>;
+}
+
+// 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;
+  type: 'command' | 'skill' | 'rule' | 'mcp';
+  message: string;
+  /** Human-readable resource name sent to the CSP API. Defaults to resource_id. */
+  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>;
+}
+
+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;
+}
+
+export interface UninstallResourceResult {
+  success: boolean;
+  removed_resources: Array<{
+    id: string;
+    name: string;
+    path: string;
+  }>;
+  subscription_removed: boolean;
+  message: string;
+}

package/src/utils/cursor-paths.ts

@@ -0,0 +1,83 @@
+/**
+ * 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
+ */
+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 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);
+}

package/src/utils/log-cleaner.ts

@@ -0,0 +1,92 @@
+/**
+ * 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');
+}

package/src/utils/logger.ts

@@ -0,0 +1,333 @@
+/**
+ * Logging Module
+ * Structured logging using pino with daily file rotation.
+ *
+ * Files are named app-YYYY-MM-DD.log. Rotation is implemented by:
+ *   1. Starting pino/file pointing at today's file (fixed fd, opened at startup).
+ *   2. A midnight timer in the main thread spawns a fresh child process for the
+ *      next day's file via a second pino instance — but that would mean two loggers.
+ *
+ * Practical solution used here:
+ *   - Use pino-roll (daily, dateFormat: 'yyyy-MM-dd').
+ *   - pino-roll produces  Logs/app.YYYY-MM-DD.1.log  (date + sequential counter).
+ *   - At midnight + 2 s we rename the *previous* day's  app.YYYY-MM-DD.1.log
+ *     → app-YYYY-MM-DD.log  so the canonical name is clean.
+ *   - The active (today's) file keeps the pino-roll name until it rotates.
+ *   - log-cleaner scans by mtime so it handles both naming conventions.
+ */
+
+import pino from 'pino';
+import * as path from 'path';
+import * as fs from 'fs';
+import { config } from '../config';
+
+// Ensure logs directory exists (relative to project root)
+const logsDir = path.resolve(process.cwd(), config.logging.dir);
+if (!fs.existsSync(logsDir)) {
+  fs.mkdirSync(logsDir, { recursive: true });
+}
+
+/** ms until the next local midnight + 1 s buffer. */
+function msUntilMidnight(): number {
+  const now = new Date();
+  const next = new Date(now.getFullYear(), now.getMonth(), now.getDate() + 1, 0, 0, 1);
+  return next.getTime() - now.getTime();
+}
+
+/**
+ * Rename yesterday's pino-roll file (app.YYYY-MM-DD.1.log)
+ * to the canonical name (app-YYYY-MM-DD.log) once it has been rotated away.
+ */
+function renameYesterdayLog(): void {
+  const d = new Date();
+  d.setDate(d.getDate() - 1);
+  const dateStr = [
+    d.getFullYear(),
+    String(d.getMonth() + 1).padStart(2, '0'),
+    String(d.getDate()).padStart(2, '0'),
+  ].join('-');
+
+  const src = path.join(logsDir, `app.${dateStr}.1.log`);
+  const dst = path.join(logsDir, `app-${dateStr}.log`);
+  if (fs.existsSync(src) && !fs.existsSync(dst)) {
+    try { fs.renameSync(src, dst); } catch { /* non-fatal */ }
+  }
+}
+
+// Fire rename at midnight + 2 s, then every 24 h.
+setTimeout(() => {
+  renameYesterdayLog();
+  setInterval(renameYesterdayLog, 24 * 60 * 60 * 1000).unref();
+}, msUntilMidnight() + 2000).unref();
+
+// Create pino logger with multi-target transport
+export const logger = pino({
+  level: config.logLevel,
+  timestamp: pino.stdTimeFunctions.isoTime,
+  base: {
+    service: 'csp-ai-agent-mcp',
+  },
+  transport: {
+    targets: [
+      // Console output (pretty format in development)
+      {
+        target: 'pino-pretty',
+        level: config.logLevel,
+        options: {
+          colorize: true,
+          translateTime: 'SYS:standard',
+          ignore: 'pid,hostname',
+          singleLine: false,
+        },
+      },
+      // Daily-rotating file output.
+      // Active file: Logs/app.YYYY-MM-DD.1.log
+      // After midnight rename: Logs/app-YYYY-MM-DD.log
+      {
+        target: 'pino-roll',
+        level: config.logLevel,
+        options: {
+          file: path.join(logsDir, 'app'),
+          frequency: 'daily',
+          dateFormat: 'yyyy-MM-dd',
+          mkdir: true,
+          sync: false,
+        },
+      },
+    ],
+  },
+});
+
+/**
+ * Log MCP Tool call
+ */
+export function logToolCall(
+  toolName: string,
+  userId: string,
+  params: Record<string, unknown>,
+  durationMs: number
+): void {
+  logger.info(
+    {
+      type: 'tool_call',
+      toolName,
+      userId,
+      params,
+      durationMs,
+    },
+    `Tool ${toolName} called by ${userId} (${durationMs}ms)`
+  );
+}
+
+/**
+ * Log error with context
+ */
+export function logError(error: Error, context?: Record<string, unknown>): void {
+  logger.error(
+    {
+      type: 'error',
+      error: {
+        message: error.message,
+        stack: error.stack,
+        name: error.name,
+      },
+      ...context,
+    },
+    error.message
+  );
+}
+
+/**
+ * Log performance metrics
+ */
+export function logPerformance(
+  operation: string,
+  durationMs: number,
+  metadata?: Record<string, unknown>
+): void {
+  logger.info(
+    {
+      type: 'performance',
+      operation,
+      durationMs,
+      ...metadata,
+    },
+    `${operation} completed in ${durationMs}ms`
+  );
+}
+
+/**
+ * Log API request with detailed information
+ */
+export function logApiRequest(
+  method: string,
+  url: string,
+  statusCode: number,
+  durationMs: number,
+  requestData?: unknown,
+  responseData?: unknown,
+  headers?: Record<string, string>
+): void {
+  logger.info(
+    {
+      type: 'api_request',
+      method,
+      url,
+      statusCode,
+      durationMs,
+      requestData: requestData ? JSON.stringify(requestData).substring(0, 500) : undefined,
+      responseData: responseData ? JSON.stringify(responseData).substring(0, 1000) : undefined,
+      headers: headers ? sanitizeHeaders(headers) : undefined,
+    },
+    `${method} ${url} - ${statusCode} (${durationMs}ms)`
+  );
+}
+
+/**
+ * Log API error with full details
+ */
+export function logApiError(
+  method: string,
+  url: string,
+  error: Error,
+  requestData?: unknown,
+  statusCode?: number
+): void {
+  logger.error(
+    {
+      type: 'api_error',
+      method,
+      url,
+      statusCode,
+      requestData: requestData ? JSON.stringify(requestData).substring(0, 500) : undefined,
+      error: {
+        message: error.message,
+        stack: error.stack,
+        name: error.name,
+      },
+    },
+    `API Error: ${method} ${url} - ${error.message}`
+  );
+}
+
+/**
+ * Log tool execution step
+ */
+export function logToolStep(
+  toolName: string,
+  step: string,
+  details?: Record<string, unknown>
+): void {
+  logger.debug(
+    {
+      type: 'tool_step',
+      toolName,
+      step,
+      ...details,
+    },
+    `[${toolName}] ${step}`
+  );
+}
+
+/**
+ * Log tool execution result
+ */
+export function logToolResult(
+  toolName: string,
+  success: boolean,
+  result?: unknown,
+  error?: Error
+): void {
+  const level = success ? 'info' : 'error';
+  logger[level](
+    {
+      type: 'tool_result',
+      toolName,
+      success,
+      result: result ? JSON.stringify(result).substring(0, 1000) : undefined,
+      error: error ? {
+        message: error.message,
+        stack: error.stack,
+        name: error.name,
+      } : undefined,
+    },
+    `[${toolName}] ${success ? 'Success' : 'Failed'}`
+  );
+}
+
+/**
+ * Log authentication attempt
+ */
+export function logAuthAttempt(
+  type: 'token_validation' | 'permission_check',
+  success: boolean,
+  details?: Record<string, unknown>
+): void {
+  const level = success ? 'info' : 'warn';
+  logger[level](
+    {
+      type: 'auth',
+      operation: type,
+      success,
+      ...details,
+    },
+    `Auth ${type}: ${success ? 'Success' : 'Failed'}`
+  );
+}
+
+/**
+ * Log cache operation
+ */
+export function logCacheOperation(
+  operation: 'get' | 'set' | 'delete' | 'hit' | 'miss',
+  key: string,
+  details?: Record<string, unknown>
+): void {
+  logger.debug(
+    {
+      type: 'cache',
+      operation,
+      key,
+      ...details,
+    },
+    `Cache ${operation}: ${key}`
+  );
+}
+
+/**
+ * Sanitize headers to remove sensitive information
+ */
+function sanitizeHeaders(headers: Record<string, string>): Record<string, string> {
+  const sanitized = { ...headers };
+  
+  // Mask Authorization header
+  if (sanitized['Authorization'] || sanitized['authorization']) {
+    const authKey = sanitized['Authorization'] ? 'Authorization' : 'authorization';
+    const authValue = sanitized[authKey];
+    if (authValue && authValue.startsWith('Bearer ')) {
+      const token = authValue.substring(7);
+      sanitized[authKey] = `Bearer ${token.substring(0, 10)}...${token.substring(token.length - 10)}`;
+    }
+  }
+  
+  return sanitized;
+}
+
+/**
+ * Log Git operation
+ */
+export function logGitOperation(
+  operation: string,
+  details: Record<string, unknown>,
+  durationMs: number
+): void {
+  logger.info(
+    {
+      type: 'git_operation',
+      operation,
+      ...details,
+      durationMs,
+    },
+    `Git ${operation} completed (${durationMs}ms)`
+  );
+}