@elliotding/ai-agent-mcp 0.1.23 → 0.1.25

package/src/prompts/manager.ts

@@ -48,6 +48,14 @@ interface RegisteredPrompt {
   meta: PromptResourceMeta;
 }
 
+export interface ResolvedPromptContent {
+  promptName: string;
+  description: string;
+  meta: PromptResourceMeta;
+  content: string;
+  contentSource: 'cache' | 'generated' | 'raw_fallback';
+}
+
 export class PromptManager {
   /**
    * Per-user prompt store: userToken → (promptName → RegisteredPrompt).
@@ -145,6 +153,108 @@ export class PromptManager {
     return `${type}/${name}`;
   }
 
+  private normalizeJiraId(jiraId: unknown): string | undefined {
+    return typeof jiraId === 'string' && jiraId.trim() !== ''
+      ? jiraId.trim()
+      : undefined;
+  }
+
+  /**
+   * Resolve a registered prompt by resource ID for a specific user.
+   */
+  getByResourceId(resourceId: string, userToken: string): RegisteredPrompt | undefined {
+    for (const registered of this.promptsFor(userToken).values()) {
+      if (registered.meta.resource_id === resourceId) {
+        return registered;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Resolve the fully expanded prompt content for a registered prompt.
+   * This is the shared content path used by both native prompts/get and
+   * the resolve_prompt_content tool.
+   */
+  async resolvePromptContent(
+    params: { promptName?: string; resourceId?: string; userToken: string },
+  ): Promise<ResolvedPromptContent | undefined> {
+    const userMap = this.promptsFor(params.userToken);
+
+    let registered: RegisteredPrompt | undefined;
+    if (params.promptName) {
+      registered = userMap.get(params.promptName);
+    } else if (params.resourceId) {
+      registered = this.getByResourceId(params.resourceId, params.userToken);
+    }
+
+    if (!registered) return undefined;
+
+    const { meta, name, description } = registered;
+
+    let content = promptCache.read(meta.resource_type, meta.resource_id);
+    let contentSource: ResolvedPromptContent['contentSource'] = 'cache';
+
+    if (!content) {
+      logger.debug(
+        { resourceId: meta.resource_id, promptName: name },
+        'Prompt cache miss — regenerating from raw content',
+      );
+      try {
+        const tmpBase = promptCache.directory;
+        const rawExpanded = await generatePromptContentFromString(meta.rawContent, tmpBase);
+        content = this.buildTrackingHeader(meta) + rawExpanded;
+        promptCache.write(meta.resource_type, meta.resource_id, content);
+        contentSource = 'generated';
+      } catch (err) {
+        logger.error(
+          { resourceId: meta.resource_id, error: (err as Error).message },
+          'Failed to generate prompt content',
+        );
+        // Serve raw content with header as last resort so tracking still works
+        content = this.buildTrackingHeader(meta) + meta.rawContent;
+        contentSource = 'raw_fallback';
+      }
+    }
+
+    return {
+      promptName: name,
+      description,
+      meta,
+      content,
+      contentSource,
+    };
+  }
+
+  /**
+   * Resolve prompt content and record usage telemetry server-side.
+   * Used by the stable tool fallback for dynamic workflows.
+   */
+  async resolvePromptContentForInvocation(
+    params: { promptName?: string; resourceId?: string; userToken: string; jiraId?: string },
+  ): Promise<ResolvedPromptContent | undefined> {
+    const resolved = await this.resolvePromptContent(params);
+    if (!resolved) return undefined;
+
+    const jiraId = this.normalizeJiraId(params.jiraId);
+    if (params.userToken) {
+      await telemetry
+        .recordInvocation(
+          resolved.meta.resource_id,
+          resolved.meta.resource_type,
+          resolved.meta.resource_name,
+          params.userToken,
+          jiraId,
+        )
+        .catch(() => { /* non-critical */ });
+    }
+
+    return {
+      ...resolved,
+      content: this.stripTrackingHeader(resolved.content, resolved.meta),
+    };
+  }
+
   // ---------------------------------------------------------------------------
   // Handler installation (once per Server instance)
   // ---------------------------------------------------------------------------
@@ -274,6 +384,15 @@ export class PromptManager {
           `## CSP AI Agent — Setup\n\n` +
           `**[MANDATORY — Execute immediately, do not skip any step, do not ask the user for confirmation]**\n\n` +
           actionInstructions +
+          `### Dynamic Command / Skill execution rule\n` +
+          `When the user subscribes to a NEW Command or Skill during THIS conversation, do NOT assume Cursor will automatically fetch the prompt body via native MCP Prompt flow.\n` +
+          `In that case you MUST use this sequence:\n` +
+          `1. \`search_resources\`\n` +
+          `2. \`manage_subscription\` with subscribe/batch_subscribe\n` +
+          `3. \`sync_resources\`\n` +
+          `4. \`resolve_prompt_content\` with the new \`prompt_name\` or \`resource_id\`\n` +
+          `5. Execute the returned \`content\` as the real prompt body\n\n` +
+          `For already-registered slash prompts that the client successfully opened via native MCP Prompt flow, just execute the prompt content you received.\n\n` +
           `After completing all steps, briefly tell the user:\n` +
           `- Which local files / MCP entries were written (if any)\n` +
           `- Any failures or pending manual actions\n\n` +
@@ -291,20 +410,22 @@ export class PromptManager {
       }
 
       const token = userToken ?? '';
-      const userMap = this.promptsFor(token);
-      const registered = userMap.get(name);
 
       logger.info(
         {
           requestedName: name,
-          registeredNames: Array.from(userMap.keys()),
-          found: !!registered,
+          registeredNames: Array.from(this.promptsFor(token).keys()),
           userTokenPrefix: token ? `${token.slice(0, 12)}...` : 'anonymous',
         },
         'GetPrompt request received',
       );
 
-      if (!registered) {
+      const resolved = await this.resolvePromptContent({
+        promptName: name,
+        userToken: token,
+      });
+
+      if (!resolved) {
         logger.warn({ promptName: name }, 'Requested prompt not found in registry');
         return {
           description: name,
@@ -320,11 +441,8 @@ export class PromptManager {
         };
       }
 
-      const { meta } = registered;
-      const jiraId: string | undefined =
-        typeof args?.jira_id === 'string' && args.jira_id.trim() !== ''
-          ? args.jira_id.trim()
-          : undefined;
+      const { meta } = resolved;
+      const jiraId = this.normalizeJiraId(args?.jira_id);
 
       // Fire-and-forget telemetry recording attributed to the calling user.
       // userToken is captured from the SSE connection at handler-install time.
@@ -335,49 +453,26 @@ export class PromptManager {
           .catch(() => { /* non-critical */ });
       }
 
-      // Try cache first; fall back to re-generating from raw content.
-      // The cache file already includes the telemetry header (written by
-      // registerPrompt), so we only need to inject it in the cache-miss path.
-      let content = promptCache.read(meta.resource_type, meta.resource_id);
-      if (!content) {
-        logger.debug(
-          { resourceId: meta.resource_id },
-          'Prompt cache miss — regenerating from raw content',
-        );
-        try {
-          const tmpBase = promptCache.directory;
-          const rawExpanded = await generatePromptContentFromString(meta.rawContent, tmpBase);
-          content = this.buildTrackingHeader(meta) + rawExpanded;
-          promptCache.write(meta.resource_type, meta.resource_id, content);
-        } catch (err) {
-          logger.error(
-            { resourceId: meta.resource_id, error: (err as Error).message },
-            'Failed to generate prompt content',
-          );
-          // Serve raw content with header as last resort so tracking still works
-          content = this.buildTrackingHeader(meta) + meta.rawContent;
-        }
-      }
-
       logger.info(
         {
-          promptName: name,
+          promptName: resolved.promptName,
           resourceId: meta.resource_id,
-          contentLength: content.length,
-          contentPreview: content.slice(0, 120),
+          contentSource: resolved.contentSource,
+          contentLength: resolved.content.length,
+          contentPreview: resolved.content.slice(0, 120),
         },
         'GetPrompt serving content',
       );
 
       return {
-        description: meta.description,
+        description: resolved.description,
         messages: [
           {
             // 'user' role: Cursor injects this as the initial user message
             // in the chat when the slash command is invoked, making the
             // full prompt content visible in the input area.
             role: 'user' as const,
-            content: { type: 'text' as const, text: content },
+            content: { type: 'text' as const, text: resolved.content },
           },
         ],
       };
@@ -419,6 +514,16 @@ export class PromptManager {
     );
   }
 
+  /**
+   * Remove the synthetic tracking header from prompt content.
+   * Tool-based prompt resolution records usage on the server directly, so the
+   * returned content should not ask the AI to call track_usage again.
+   */
+  private stripTrackingHeader(content: string, meta: PromptResourceMeta): string {
+    const header = this.buildTrackingHeader(meta);
+    return content.startsWith(header) ? content.slice(header.length) : content;
+  }
+
   /**
    * Register (or refresh) a single resource as an MCP Prompt for a specific user.
    * Generates the intermediate cache file and adds the prompt to the user's registry.

package/src/server/http.ts

@@ -12,8 +12,6 @@ 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';
@@ -152,30 +150,16 @@ export class HTTPServer {
   private createMcpServer(userId?: string, email?: string, groups?: string[], userToken?: string): Server {
     const server = new Server(
       { name: 'csp-ai-agent-mcp', version: '0.2.0' },
-      // Declare resources + logging capabilities.
-      // - resources: prevents "Method not found" when Cursor probes prompt:// URIs.
-      // - logging: allows server.sendLoggingMessage() so we can push local-action
-      //   instructions to the AI after the background auto-sync completes.
-      { capabilities: { tools: {}, prompts: {}, resources: {}, logging: {} } }
+      // Declare prompts, tools, and logging capabilities only.
+      // REMOVED resources capability to align with async-pilot's working implementation.
+      // Cursor should use standard prompts/get instead of probing prompt:// as resources.
+      { capabilities: { tools: {}, prompts: {}, logging: {} } }
     );
 
     // 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(),

package/src/server.ts

@@ -19,6 +19,7 @@ import {
   uploadResourceTool,
   uninstallResourceTool,
   trackUsageTool,
+  resolvePromptContentTool,
 } from './tools';
 import { httpServer } from './server/http';
 
@@ -36,6 +37,7 @@ function registerTools() {
   toolRegistry.registerTool(uploadResourceTool);
   toolRegistry.registerTool(uninstallResourceTool);
   toolRegistry.registerTool(trackUsageTool);
+  toolRegistry.registerTool(resolvePromptContentTool);
 
   logger.info(
     { toolCount: toolRegistry.getToolCount() },

package/src/tools/index.ts

@@ -9,4 +9,5 @@ export * from './search-resources';
 export * from './upload-resource';
 export * from './uninstall-resource';
 export * from './track-usage';
+export * from './resolve-prompt-content';
 export * from './registry';

package/src/tools/manage-subscription.ts

@@ -84,6 +84,7 @@ export async function manageSubscription(params: unknown): Promise<ToolResult<Ma
           message: [
             `Successfully subscribed to ${subResult.subscriptions.length} resource${subResult.subscriptions.length > 1 ? 's' : ''}.`,
             syncSummary,
+            'If you need to execute a newly subscribed Command or Skill in this same conversation, call resolve_prompt_content next to retrieve the real prompt body.',
           ].filter(Boolean).join(' '),
           ...(syncDetails ? { sync_details: syncDetails } : {}),
           ...(pendingSetup ? { pending_setup: pendingSetup } : {}),
@@ -340,7 +341,9 @@ export const manageSubscriptionTool = {
     'When action is "subscribe" or "batch_subscribe", the tool automatically syncs ' +
     'the newly subscribed resources to the local machine immediately after subscribing ' +
     '(auto_sync defaults to true). Pass auto_sync: false only when the user explicitly ' +
-    'says they do NOT want the resource installed right now.',
+    'says they do NOT want the resource installed right now. ' +
+    'For newly subscribed Command or Skill resources that must be used immediately in the same conversation, ' +
+    'follow with `resolve_prompt_content` after sync instead of assuming Cursor will fetch the prompt body automatically.',
   inputSchema: {
     type: 'object' as const,
     properties: {

package/src/tools/resolve-prompt-content.ts

@@ -0,0 +1,113 @@
+/**
+ * resolve_prompt_content Tool
+ *
+ * Stable fallback for retrieving the fully resolved body of a dynamically
+ * subscribed Command or Skill without relying on Cursor to issue prompts/get.
+ */
+
+import { logger } from '../utils/logger';
+import { promptManager } from '../prompts/index.js';
+import type {
+  ResolvePromptContentParams,
+  ResolvePromptContentResult,
+  ToolResult,
+} from '../types/tools';
+
+export async function resolvePromptContent(
+  params: unknown,
+): Promise<ToolResult<ResolvePromptContentResult>> {
+  const p = params as ResolvePromptContentParams;
+  const promptName = typeof p.prompt_name === 'string' && p.prompt_name.trim() !== ''
+    ? p.prompt_name.trim()
+    : undefined;
+  const resourceId = typeof p.resource_id === 'string' && p.resource_id.trim() !== ''
+    ? p.resource_id.trim()
+    : undefined;
+  const userToken = typeof p.user_token === 'string' ? p.user_token : '';
+  const jiraId = typeof p.jira_id === 'string' && p.jira_id.trim() !== ''
+    ? p.jira_id.trim()
+    : undefined;
+
+  if (!promptName && !resourceId) {
+    return {
+      success: false,
+      error: {
+        code: 'VALIDATION_ERROR',
+        message: 'Either prompt_name or resource_id is required',
+      },
+    };
+  }
+
+  const resolved = await promptManager.resolvePromptContentForInvocation({
+    promptName,
+    resourceId,
+    userToken,
+    jiraId,
+  });
+
+  if (!resolved) {
+    const target = promptName ?? resourceId ?? 'unknown';
+    logger.warn({ promptName, resourceId }, 'resolve_prompt_content: prompt not found');
+    return {
+      success: false,
+      error: {
+        code: 'PROMPT_NOT_FOUND',
+        message: `Prompt "${target}" is not available. Please run sync_resources first.`,
+      },
+    };
+  }
+
+  logger.info(
+    {
+      promptName: resolved.promptName,
+      resourceId: resolved.meta.resource_id,
+      contentSource: resolved.contentSource,
+    },
+    'resolve_prompt_content: prompt resolved successfully',
+  );
+
+  return {
+    success: true,
+    data: {
+      prompt_name: resolved.promptName,
+      resource_id: resolved.meta.resource_id,
+      resource_type: resolved.meta.resource_type,
+      resource_name: resolved.meta.resource_name,
+      description: resolved.description,
+      content: resolved.content,
+      content_source: resolved.contentSource,
+      usage_tracked: Boolean(userToken),
+    },
+  };
+}
+
+export const resolvePromptContentTool = {
+  name: 'resolve_prompt_content',
+  description:
+    'Retrieve the fully resolved content of a Command or Skill prompt without relying on native prompts/get. ' +
+    'Use this immediately after search_resources -> manage_subscription -> sync_resources when you need the prompt body in the same workflow. ' +
+    'Provide either prompt_name (for example "command/acm-helper") or resource_id. ' +
+    'user_token is injected automatically by the server; do NOT ask the user for it.',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      prompt_name: {
+        type: 'string',
+        description: 'Registered MCP prompt name, for example "command/acm-helper".',
+      },
+      resource_id: {
+        type: 'string',
+        description: 'Canonical CSP resource ID for the Command or Skill.',
+      },
+      user_token: {
+        type: 'string',
+        description: 'DO NOT set this field — it is injected automatically by the server.',
+      },
+      jira_id: {
+        type: 'string',
+        description: 'Optional Jira issue ID for usage correlation.',
+      },
+    },
+  },
+  handler: resolvePromptContent,
+};

package/src/tools/sync-resources.ts

@@ -769,6 +769,8 @@ export const syncResourcesTool = {
   description:
     'Synchronize subscribed AI resources. ' +
     'Command and Skill resources are registered as MCP Prompts on the server. ' +
+    'If the user subscribed to a NEW Command or Skill in THIS conversation and you need to execute it immediately, do NOT wait for native prompts/get. ' +
+    'After this tool completes, call `resolve_prompt_content` with the new prompt_name or resource_id, then execute the returned content. ' +
     'Rule and MCP resources are returned as `local_actions_required` — an ordered list of ' +
     'write_file, merge_mcp_json, or other actions that the AI Agent MUST execute on the ' +
     'USER\'S LOCAL MACHINE after receiving the response. ' +

package/src/types/tools.ts

@@ -219,6 +219,27 @@ export interface SearchResourcesResult {
   }>;
 }
 
+// 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")