@elliotding/ai-agent-mcp 0.1.2 → 0.1.4

package/src/server/http.ts

@@ -12,8 +12,12 @@ import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import { syncResources } from '../tools/sync-resources.js';
+import { telemetry } from '../telemetry/index.js';
+import { promptManager } from '../prompts/index.js';
 import { config } from '../config';
 import { logger } from '../utils/logger';
 import { sessionManager } from '../session/manager';
@@ -103,17 +107,19 @@ export class HTTPServer {
   // ─────────────────────────────────────────────────────────────────────────
 
   private setupRoutes(): void {
+    const basePath = config.http?.basePath ?? '';
+
     // Health check
-    this.fastify.get('/health', this.handleHealth.bind(this));
+    this.fastify.get(`${basePath}/health`, this.handleHealth.bind(this));
 
     // SSE connection — GET establishes the stream (SDK standard)
-    this.fastify.get('/sse', {
+    this.fastify.get(`${basePath}/sse`, {
       preHandler: tokenAuthOrLegacyMiddleware,
       handler: this.handleSSEConnection.bind(this),
     });
 
     // Message endpoint — POST delivers JSON-RPC messages, sessionId in query
-    this.fastify.post('/message', this.handleMessage.bind(this));
+    this.fastify.post(`${basePath}/message`, this.handleMessage.bind(this));
 
     // OAuth discovery — return 404 so Cursor skips OAuth handshake
     this.fastify.get('/.well-known/oauth-authorization-server', async (_req, reply) => {
@@ -125,10 +131,11 @@ export class HTTPServer {
       server: 'CSP AI Agent MCP Server',
       version: '1.0.0',
       transport: 'sse',
+      basePath: basePath || '(none)',
       endpoints: {
-        health: 'GET /health',
-        sse: 'GET /sse',
-        message: 'POST /message?sessionId=<id>',
+        health:  `GET ${basePath}/health`,
+        sse:     `GET ${basePath}/sse`,
+        message: `POST ${basePath}/message?sessionId=<id>`,
       },
     }));
   }
@@ -142,12 +149,31 @@ export class HTTPServer {
    * A fresh instance is created per SSE connection so that each session is
    * isolated (matching ACM's createMCPServer-per-connection pattern).
    */
-  private createMcpServer(userId?: string, email?: string, groups?: string[]): Server {
+  private createMcpServer(userId?: string, email?: string, groups?: string[], userToken?: string): Server {
     const server = new Server(
       { name: 'csp-ai-agent-mcp', version: '0.2.0' },
-      { capabilities: { tools: {} } }
+      // Declare resources capability so Cursor does not emit "Method not found"
+      // when it probes prompt:// URIs via the resources/read protocol.
+      { capabilities: { tools: {}, prompts: {}, resources: {} } }
     );
 
+    // Install Prompt list/get handlers synchronously on this Server instance.
+    // Pass userToken so GetPrompt can attribute telemetry to the correct user.
+    promptManager.installHandlers(server, userToken);
+
+    // resources/list — return an empty list; we don't publish static resources.
+    server.setRequestHandler(ListResourcesRequestSchema, () => ({ resources: [] }));
+
+    // resources/read — Cursor probes `prompt://<name>` URIs to check if a
+    // prompt can be read as a resource.  Return an empty text content so the
+    // client does not display an error; it will fall back to prompts/get for
+    // actual content.
+    server.setRequestHandler(ReadResourceRequestSchema, (request) => {
+      const uri = request.params.uri;
+      logger.debug({ uri }, 'resources/read probe received — returning empty content');
+      return { contents: [{ uri, text: '' }] };
+    });
+
     // tools/list
     server.setRequestHandler(ListToolsRequestSchema, () => ({
       tools: toolRegistry.getMCPToolDefinitions(),
@@ -157,7 +183,10 @@ export class HTTPServer {
     // Runs in the background so it never blocks the connection setup.
     server.oninitialized = () => {
       logger.info({ userId }, 'MCP initialized — triggering background sync_resources');
-      syncResources({ mode: 'incremental', scope: 'global' }).then((result) => {
+      // Flush any pending telemetry immediately on (re)connect so events from
+      // before a disconnect are not held until the next 10-second tick.
+      telemetry.flushOnReconnect();
+      syncResources({ mode: 'incremental', scope: 'global', user_token: userToken }).then((result) => {
         if (result.success) {
           logger.info(
             { userId, synced: result.data?.summary?.synced, cached: result.data?.summary?.cached },
@@ -186,8 +215,17 @@ export class HTTPServer {
         }
       }
 
+      // Inject the authenticated token so every tool can call the CSP API without
+      // requiring the AI to know about or pass user_token explicitly.
+      // The AI-supplied user_token (if any) takes precedence; otherwise we fall back
+      // to the token from the SSE connection that created this session.
+      const enrichedArgs: Record<string, unknown> = {
+        user_token: userToken,
+        ...args,
+      };
+
       try {
-        const result = await toolRegistry.callTool(name, args as Record<string, unknown>);
+        const result = await toolRegistry.callTool(name, enrichedArgs);
         const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
         return { content: [{ type: 'text' as const, text }] };
       } catch (err) {
@@ -224,6 +262,11 @@ export class HTTPServer {
       return;
     }
 
+    // Update telemetry with the authenticated token so flush() can report even
+    // when CSP_API_TOKEN is not injected via process env (SSE transport delivers
+    // the token through the Authorization header, not via mcp.json env injection).
+    telemetry.setUserToken(token);
+
     try {
       // Keep our session manager in sync for health/monitoring endpoints
       const sessionOptions = request.user
@@ -249,8 +292,15 @@ export class HTTPServer {
         }
       }, 30_000);
 
-      // Create SDK transport — it takes ownership of reply.raw
-      const transport = new SSEServerTransport('/message', reply.raw);
+      // Build the absolute message URL for the SSE endpoint event.
+      // Cursor (and other MCP clients) resolve the endpoint event data as a URL;
+      // using a relative path causes some clients to misinterpret it as a redirect.
+      // We use the Host header when available so the URL matches what the client
+      // actually connected to (important behind proxies / ngrok / etc.).
+      const basePath = config.http?.basePath ?? '';
+      const host = request.headers.host ?? `${config.http?.host ?? '127.0.0.1'}:${config.http?.port ?? 3000}`;
+      const messageUrl = `http://${host}${basePath}/message`;
+      const transport = new SSEServerTransport(messageUrl, reply.raw);
       const sdkSessionId = transport.sessionId;
       this.sseTransports.set(sdkSessionId, transport);
 
@@ -269,7 +319,8 @@ export class HTTPServer {
       const mcpServer = this.createMcpServer(
         request.user?.userId,
         request.user?.email,
-        request.user?.groups
+        request.user?.groups,
+        token,
       );
       await mcpServer.connect(transport);
 
@@ -377,13 +428,14 @@ export class HTTPServer {
     try {
       const host = config.http?.host || '0.0.0.0';
       const port = config.http?.port || 3000;
+      const basePath = config.http?.basePath ?? '';
 
       await this.fastify.listen({ host, port });
 
-      logger.info({ host, port }, 'HTTP server started');
-      logger.info(`Health check: http://${host}:${port}/health`);
-      logger.info(`SSE endpoint:  http://${host}:${port}/sse`);
-      logger.info(`Message endpoint: http://${host}:${port}/message?sessionId=<id>`);
+      logger.info({ host, port, basePath }, 'HTTP server started');
+      logger.info(`Health check: http://${host}:${port}${basePath}/health`);
+      logger.info(`SSE endpoint:  http://${host}:${port}${basePath}/sse`);
+      logger.info(`Message endpoint: http://${host}:${port}${basePath}/message?sessionId=<id>`);
     } catch (error) {
       logger.error({ error }, 'Failed to start HTTP server');
       throw error;

package/src/server.ts

@@ -18,6 +18,7 @@ import {
   searchResourcesTool,
   uploadResourceTool,
   uninstallResourceTool,
+  trackUsageTool,
 } from './tools';
 import { httpServer } from './server/http';
 
@@ -34,6 +35,7 @@ function registerTools() {
   toolRegistry.registerTool(searchResourcesTool);
   toolRegistry.registerTool(uploadResourceTool);
   toolRegistry.registerTool(uninstallResourceTool);
+  toolRegistry.registerTool(trackUsageTool);
 
   logger.info(
     { toolCount: toolRegistry.getToolCount() },
@@ -56,10 +58,16 @@ async function startStdioServer(): Promise<void> {
     {
       capabilities: {
         tools: {},
+        prompts: {},
       },
     }
   );
 
+  // Install Prompt list/get handlers so Command and Skill resources are
+  // exposed as MCP Prompts (Cursor slash commands).
+  const { promptManager } = await import('./prompts/index.js');
+  promptManager.installHandlers(server);
+
   // Handle tools/list request
   server.setRequestHandler(ListToolsRequestSchema, () => {
     const tools = toolRegistry.getMCPToolDefinitions();
@@ -134,6 +142,11 @@ async function startStdioServer(): Promise<void> {
   const transport = new StdioServerTransport();
   await server.connect(transport);
 
+  // Flush any pending telemetry immediately — stdio reconnects when Cursor
+  // restarts the process, so treat connect as a reconnect event.
+  const { telemetry: tel } = await import('./telemetry/index.js');
+  tel.flushOnReconnect();
+
   logger.info('✅ MCP Server started successfully (stdio transport)');
 }
 

package/src/telemetry/index.ts

@@ -0,0 +1,10 @@
+export { TelemetryManager, telemetry } from './manager.js';
+export type {
+  ResourceCategory,
+  InvocationEvent,
+  SubscribedRule,
+  ConfiguredMcp,
+  TelemetryFile,
+  TelemetryReportPayload,
+  ReportFn,
+} from './manager.js';

package/src/telemetry/manager.ts

@@ -0,0 +1,419 @@
+/**
+ * TelemetryManager: records local AI resource invocation events and periodically
+ * flushes them to the remote telemetry API.
+ *
+ * Local storage: {MCP Server CWD}/ai-resource-telemetry.json
+ *
+ * Multi-user design:
+ * - The file is keyed by user token so that data for different users is stored
+ *   and reported independently.  Each top-level key in the `users` map is a
+ *   user token; all events, rules and MCPs belong to that token's owner.
+ * - On flush, each user's data is sent with that user's own token, so the
+ *   server can attribute the telemetry to the correct account.
+ *
+ * Other design notes:
+ * - File is stored in the MCP Server's runtime working directory (not ~/.cursor/).
+ * - Atomic write-then-rename pattern prevents file corruption on concurrent
+ *   writes or unexpected process termination.
+ * - Periodic flush is fire-and-forget; failures retry up to MAX_RETRIES times
+ *   with exponential back-off, then silently drop — main tool flow is never blocked.
+ * - Rules cannot track individual invocations (Cursor injects them silently).
+ *   We report the subscribed list as a snapshot on every flush instead.
+ * - MCPs are tracked as a configured-list snapshot only.
+ * - jira_id is an optional per-invocation annotation stored separately per key.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+export type ResourceCategory = 'command' | 'skill' | 'mcp';
+
+export interface InvocationEvent {
+  resource_id: string;
+  resource_type: ResourceCategory;
+  resource_name: string;
+  invocation_count: number;
+  first_invoked_at: string;
+  last_invoked_at: string;
+  /** Optional Jira Issue ID for usage correlation (e.g. "PROJ-12345"). */
+  jira_id?: string;
+}
+
+export interface SubscribedRule {
+  resource_id: string;
+  resource_name: string;
+  subscribed_at: string;
+}
+
+export interface ConfiguredMcp {
+  resource_id: string;
+  resource_name: string;
+  configured_at: string;
+}
+
+/** Per-user telemetry data stored under `users[token]`. */
+export interface UserTelemetry {
+  last_reported_at: string | null;
+  pending_events: InvocationEvent[];
+  subscribed_rules: SubscribedRule[];
+  configured_mcps: ConfiguredMcp[];
+}
+
+/** Top-level file structure (v2: multi-user). */
+export interface TelemetryFile {
+  client_version: string;
+  /** Map of user token → per-user telemetry data. */
+  users: Record<string, UserTelemetry>;
+}
+
+export interface TelemetryReportPayload {
+  client_version: string;
+  reported_at: string;
+  events: InvocationEvent[];
+  subscribed_rules: SubscribedRule[];
+  configured_mcps: ConfiguredMcp[];
+}
+
+// Injected at flush time by the server; avoids circular import with api/client
+export type ReportFn = (payload: TelemetryReportPayload, userToken: string) => Promise<void>;
+
+/** Default file name placed in the MCP Server's CWD. */
+const DEFAULT_FILE_NAME = 'ai-resource-telemetry.json';
+
+const DEFAULT_VERSION = '0.1.5';
+const MAX_RETRIES = 3;
+const RETRY_BASE_MS = 500;
+
+/** Build the aggregation key for an invocation event. */
+function aggregationKey(resourceId: string, jiraId?: string): string {
+  return jiraId ? `${resourceId}|${jiraId}` : resourceId;
+}
+
+/** Return an empty per-user telemetry record. */
+function emptyUserTelemetry(): UserTelemetry {
+  return {
+    last_reported_at: null,
+    pending_events: [],
+    subscribed_rules: [],
+    configured_mcps: [],
+  };
+}
+
+export class TelemetryManager {
+  private filePath: string;
+  private clientVersion: string;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private reportFn: ReportFn | null = null;
+  private userTokenFn: (() => string | undefined) | null = null;
+  /** Tracks all tokens seen from active SSE connections for multi-user flush. */
+  private activeTokens: Set<string> = new Set();
+  /** Simple mutex: true while a file write is in progress. */
+  private writing = false;
+  private writeQueue: Array<() => void> = [];
+
+  /**
+   * @param filePath       Absolute path to the telemetry JSON file.
+   *                       Defaults to `{CWD}/ai-resource-telemetry.json`.
+   * @param clientVersion  Reported client version string.
+   */
+  constructor(filePath?: string, clientVersion?: string) {
+    this.filePath = filePath ?? path.join(process.cwd(), DEFAULT_FILE_NAME);
+    this.clientVersion = clientVersion ?? DEFAULT_VERSION;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Configure the function used to send telemetry to the server.
+   * Called during server initialisation to inject the API client without
+   * creating a circular dependency.
+   */
+  configure(reportFn: ReportFn, userTokenFn: () => string | undefined): void {
+    this.reportFn = reportFn;
+    this.userTokenFn = userTokenFn;
+  }
+
+  /**
+   * Register a token from a newly authenticated SSE connection.
+   *
+   * - Adds the token to the active-token set (used for multi-user flush).
+   * - Initialises the per-user slot in the file if it does not yet exist.
+   */
+  setUserToken(token: string): void {
+    this.activeTokens.add(token);
+    // Ensure the user slot exists without overwriting existing data.
+    this.withFileLock(async () => {
+      const data = this.readFile();
+      if (!data.users[token]) {
+        data.users[token] = emptyUserTelemetry();
+        this.writeFile(data);
+      }
+    }).catch(() => { /* best-effort */ });
+  }
+
+  /**
+   * Record one invocation of a Command or Skill resource for a specific user.
+   *
+   * Events are aggregated by (resource_id, jira_id) key — successive calls for
+   * the same key increment the counter rather than appending duplicate entries.
+   *
+   * @param resourceId    Canonical resource ID.
+   * @param resourceType  'command' | 'skill'
+   * @param resourceName  Human-readable name.
+   * @param userToken     Token of the user who invoked the resource.
+   * @param jiraId        Optional Jira Issue ID for correlation.
+   */
+  async recordInvocation(
+    resourceId: string,
+    resourceType: ResourceCategory,
+    resourceName: string,
+    userToken: string,
+    jiraId?: string,
+  ): Promise<void> {
+    await this.withFileLock(async () => {
+      const data = this.readFile();
+      const user = this.ensureUserSlot(data, userToken);
+      const now = new Date().toISOString();
+      const key = aggregationKey(resourceId, jiraId);
+
+      const existing = user.pending_events.find(
+        (e) => aggregationKey(e.resource_id, e.jira_id) === key,
+      );
+
+      if (existing) {
+        existing.invocation_count += 1;
+        existing.last_invoked_at = now;
+      } else {
+        const event: InvocationEvent = {
+          resource_id: resourceId,
+          resource_type: resourceType,
+          resource_name: resourceName,
+          invocation_count: 1,
+          first_invoked_at: now,
+          last_invoked_at: now,
+        };
+        // Only attach jira_id when defined (field must be absent, not null).
+        if (jiraId) event.jira_id = jiraId;
+        user.pending_events.push(event);
+      }
+      this.writeFile(data);
+    });
+  }
+
+  /**
+   * Replace the full list of subscribed Rules for a specific user.
+   * Called after sync_resources or manage_subscription completes.
+   */
+  async updateSubscribedRules(rules: SubscribedRule[], userToken: string): Promise<void> {
+    await this.withFileLock(async () => {
+      const data = this.readFile();
+      this.ensureUserSlot(data, userToken).subscribed_rules = rules;
+      this.writeFile(data);
+    });
+  }
+
+  /**
+   * Replace the full list of configured MCPs for a specific user.
+   * Called after sync_resources or manage_subscription completes for MCP resources.
+   */
+  async updateConfiguredMcps(mcps: ConfiguredMcp[], userToken: string): Promise<void> {
+    await this.withFileLock(async () => {
+      const data = this.readFile();
+      this.ensureUserSlot(data, userToken).configured_mcps = mcps;
+      this.writeFile(data);
+    });
+  }
+
+  /**
+   * Flush pending telemetry for ALL active users.
+   *
+   * Each user's data is sent with that user's own token so the server can
+   * attribute it to the correct account.  The periodic timer calls this so
+   * that all connected users are reported in the same tick.
+   */
+  async flush(): Promise<void> {
+    if (!this.reportFn) return;
+
+    // Collect tokens: active SSE tokens + env fallback (stdio / tests)
+    const tokens = new Set(this.activeTokens);
+    const envToken = this.userTokenFn?.();
+    if (envToken) tokens.add(envToken);
+
+    if (tokens.size === 0) return;
+
+    const data = await new Promise<TelemetryFile>((resolve) => {
+      this.withFileLock(async () => {
+        resolve(this.readFile());
+      }).catch(() => resolve(this.readFile()));
+    });
+
+    await Promise.all(
+      Array.from(tokens).map((token) => this.flushUser(token, data)),
+    );
+  }
+
+  /** Start the periodic flush timer (flushes all active users each tick). */
+  startPeriodicFlush(intervalMs = 10_000): void {
+    if (this.timer) return;
+    this.timer = setInterval(() => {
+      this.flush().catch(() => { /* already handled inside flush */ });
+    }, intervalMs);
+    if (this.timer.unref) this.timer.unref();
+  }
+
+  /** Stop the periodic flush timer (call before final flush on shutdown). */
+  stopPeriodicFlush(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  /**
+   * Trigger an immediate flush when a client reconnects to the MCP server.
+   * Fire-and-forget — errors are already handled inside flush().
+   */
+  flushOnReconnect(): void {
+    this.flush().catch(() => { /* handled inside flush */ });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  /** Flush one user's pending data using that user's own token. */
+  private async flushUser(token: string, data: TelemetryFile): Promise<void> {
+    if (!this.reportFn) return;
+    const user = data.users[token];
+    if (!user) return;
+
+    const payload: TelemetryReportPayload = {
+      client_version: this.clientVersion,
+      reported_at: new Date().toISOString(),
+      events: user.pending_events,
+      subscribed_rules: user.subscribed_rules,
+      configured_mcps: user.configured_mcps,
+    };
+
+    await this.reportWithRetry(payload, token);
+  }
+
+  /** Get or create the per-user slot, mutating `data.users` in place. */
+  private ensureUserSlot(data: TelemetryFile, token: string): UserTelemetry {
+    if (!data.users[token]) {
+      data.users[token] = emptyUserTelemetry();
+    }
+    return data.users[token]!;
+  }
+
+  private readFile(): TelemetryFile {
+    try {
+      const raw = fs.readFileSync(this.filePath, 'utf8');
+      const parsed = JSON.parse(raw) as Partial<TelemetryFile> & {
+        // v1 compat: flat structure without `users`
+        pending_events?: InvocationEvent[];
+        subscribed_rules?: SubscribedRule[];
+        configured_mcps?: ConfiguredMcp[];
+      };
+
+      // Migrate v1 flat file to v2 multi-user structure.
+      // We cannot recover the original token, so v1 data is discarded.
+      if (!parsed.users) {
+        return { client_version: this.clientVersion, users: {} };
+      }
+
+      return {
+        client_version: parsed.client_version ?? this.clientVersion,
+        users: parsed.users,
+      };
+    } catch {
+      return { client_version: this.clientVersion, users: {} };
+    }
+  }
+
+  private writeFile(data: TelemetryFile): void {
+    const dir = path.dirname(this.filePath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const tmp = `${this.filePath}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf8');
+    fs.renameSync(tmp, this.filePath);
+  }
+
+  /** Serialises file access to prevent concurrent write conflicts. */
+  private async withFileLock(fn: () => Promise<void>): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      const run = async () => {
+        this.writing = true;
+        try {
+          await fn();
+          resolve();
+        } catch (err) {
+          reject(err);
+        } finally {
+          this.writing = false;
+          const next = this.writeQueue.shift();
+          if (next) next();
+        }
+      };
+
+      if (this.writing) {
+        this.writeQueue.push(run);
+      } else {
+        run();
+      }
+    });
+  }
+
+  private async reportWithRetry(payload: TelemetryReportPayload, token: string): Promise<void> {
+    let lastErr: unknown;
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+      try {
+        await this.reportFn!(payload, token);
+        // Success — subtract only the events that were included in this payload.
+        // New events may have been appended to the file between the time we read
+        // the snapshot and now, so we must NOT blindly wipe pending_events=[].
+        // Instead, re-read the file under lock and decrement each reported
+        // event's invocation_count; remove it only when the count reaches zero.
+        await this.withFileLock(async () => {
+          const data = this.readFile();
+          const user = data.users[token];
+          if (!user) return;
+
+          for (const reported of payload.events) {
+            const key = aggregationKey(reported.resource_id, reported.jira_id);
+            const idx = user.pending_events.findIndex(
+              (e) => aggregationKey(e.resource_id, e.jira_id) === key,
+            );
+            if (idx === -1) continue;
+            const live = user.pending_events[idx]!;
+            live.invocation_count -= reported.invocation_count;
+            if (live.invocation_count <= 0) {
+              user.pending_events.splice(idx, 1);
+            }
+          }
+
+          user.last_reported_at = payload.reported_at;
+          this.writeFile(data);
+        });
+        return;
+      } catch (err) {
+        lastErr = err;
+        if (attempt < MAX_RETRIES - 1) {
+          await sleep(RETRY_BASE_MS * Math.pow(2, attempt));
+        }
+      }
+    }
+    if (process.env.NODE_ENV !== 'test') {
+      process.stderr.write(`[telemetry] flush failed after ${MAX_RETRIES} retries: ${lastErr}\n`);
+    }
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((res) => setTimeout(res, ms));
+}
+
+/** Singleton instance shared across the server process. */
+export const telemetry = new TelemetryManager();

package/src/tools/index.ts

@@ -8,4 +8,5 @@ export * from './manage-subscription';
 export * from './search-resources';
 export * from './upload-resource';
 export * from './uninstall-resource';
+export * from './track-usage';
 export * from './registry';