@juspay/neurolink 9.26.2 → 9.28.0

package/dist/mcp/serverCapabilities.d.ts

@@ -0,0 +1,341 @@
+/**
+ * MCP Server Capabilities - Resources and Prompts
+ *
+ * Extends MCP server functionality with resource and prompt handling
+ * according to MCP specification. This module provides:
+ * - Resource registration and management
+ * - Prompt template registration and execution
+ * - Resource subscription support
+ *
+ * @module mcp/serverCapabilities
+ * @since 8.39.0
+ */
+import { EventEmitter } from "events";
+import type { JsonObject, JsonValue } from "../types/common.js";
+/**
+ * MCP Resource definition
+ */
+export type MCPResource = {
+    /**
+     * Unique resource URI
+     */
+    uri: string;
+    /**
+     * Human-readable name
+     */
+    name: string;
+    /**
+     * Resource description
+     */
+    description?: string;
+    /**
+     * MIME type of the resource content
+     */
+    mimeType?: string;
+    /**
+     * Resource size in bytes (if known)
+     */
+    size?: number;
+    /**
+     * Whether the resource content can change
+     */
+    dynamic?: boolean;
+    /**
+     * Resource annotations/metadata
+     */
+    annotations?: {
+        /**
+         * Audience description
+         */
+        audience?: string[];
+        /**
+         * Priority hint (0-1)
+         */
+        priority?: number;
+    };
+};
+/**
+ * Resource content returned when reading a resource
+ */
+export type ResourceContent = {
+    /**
+     * Resource URI
+     */
+    uri: string;
+    /**
+     * MIME type
+     */
+    mimeType?: string;
+    /**
+     * Text content (for text/* MIME types)
+     */
+    text?: string;
+    /**
+     * Binary content as base64 (for non-text MIME types)
+     */
+    blob?: string;
+};
+/**
+ * Resource reader function type
+ */
+export type ResourceReader = (uri: string, context?: JsonObject) => Promise<ResourceContent>;
+/**
+ * Registered resource with reader
+ */
+export type RegisteredResource = MCPResource & {
+    reader: ResourceReader;
+};
+/**
+ * MCP Prompt definition
+ */
+export type MCPPrompt = {
+    /**
+     * Unique prompt name
+     */
+    name: string;
+    /**
+     * Human-readable description
+     */
+    description?: string;
+    /**
+     * Prompt arguments schema
+     */
+    arguments?: Array<{
+        /**
+         * Argument name
+         */
+        name: string;
+        /**
+         * Argument description
+         */
+        description?: string;
+        /**
+         * Whether the argument is required
+         */
+        required?: boolean;
+    }>;
+};
+/**
+ * Prompt message content
+ */
+export type PromptMessage = {
+    /**
+     * Message role
+     */
+    role: "user" | "assistant";
+    /**
+     * Message content
+     */
+    content: {
+        type: "text" | "image" | "resource";
+        text?: string;
+        data?: string;
+        mimeType?: string;
+        uri?: string;
+    };
+};
+/**
+ * Result of getting a prompt
+ */
+export type PromptResult = {
+    /**
+     * Optional description
+     */
+    description?: string;
+    /**
+     * Prompt messages
+     */
+    messages: PromptMessage[];
+};
+/**
+ * Prompt generator function type
+ */
+export type PromptGenerator = (args: Record<string, JsonValue>, context?: JsonObject) => Promise<PromptResult>;
+/**
+ * Registered prompt with generator
+ */
+export type RegisteredPrompt = MCPPrompt & {
+    generator: PromptGenerator;
+};
+/**
+ * Resource subscription callback
+ */
+export type ResourceSubscriptionCallback = (uri: string, content: ResourceContent) => void | Promise<void>;
+/**
+ * Server capabilities configuration
+ */
+export type ServerCapabilitiesConfig = {
+    /**
+     * Enable resource support
+     */
+    resources?: boolean;
+    /**
+     * Enable prompt support
+     */
+    prompts?: boolean;
+    /**
+     * Enable resource subscriptions
+     */
+    resourceSubscriptions?: boolean;
+};
+/**
+ * Server Capabilities Manager
+ *
+ * Manages resources and prompts for MCP servers.
+ *
+ * @example
+ * ```typescript
+ * const capabilities = new ServerCapabilitiesManager({
+ *   resources: true,
+ *   prompts: true,
+ * });
+ *
+ * // Register a resource
+ * capabilities.registerResource({
+ *   uri: "file:///data/config.json",
+ *   name: "Configuration",
+ *   mimeType: "application/json",
+ *   reader: async (uri) => ({
+ *     uri,
+ *     mimeType: "application/json",
+ *     text: JSON.stringify({ key: "value" }),
+ *   }),
+ * });
+ *
+ * // Register a prompt
+ * capabilities.registerPrompt({
+ *   name: "summarize",
+ *   description: "Summarize text content",
+ *   arguments: [{ name: "text", required: true }],
+ *   generator: async (args) => ({
+ *     messages: [
+ *       { role: "user", content: { type: "text", text: `Summarize: ${args.text}` } },
+ *     ],
+ *   }),
+ * });
+ * ```
+ */
+export declare class ServerCapabilitiesManager extends EventEmitter {
+    private config;
+    private resources;
+    private prompts;
+    private subscriptions;
+    private resourceTemplates;
+    constructor(config?: ServerCapabilitiesConfig);
+    /**
+     * Register a resource
+     */
+    registerResource(resource: RegisteredResource): this;
+    /**
+     * Register a resource template (with URI pattern)
+     */
+    registerResourceTemplate(pattern: string, template: Omit<RegisteredResource, "uri"> & {
+        uriPattern: string;
+    }): this;
+    /**
+     * Unregister a resource
+     */
+    unregisterResource(uri: string): boolean;
+    /**
+     * List all resources
+     */
+    listResources(): MCPResource[];
+    /**
+     * Read a resource
+     */
+    readResource(uri: string, context?: JsonObject): Promise<ResourceContent>;
+    /**
+     * Subscribe to resource changes
+     */
+    subscribeToResource(uri: string, callback: ResourceSubscriptionCallback): () => void;
+    /**
+     * Notify subscribers of resource change
+     */
+    notifyResourceChanged(uri: string): Promise<void>;
+    /**
+     * Get resource by URI
+     */
+    getResource(uri: string): RegisteredResource | undefined;
+    /**
+     * Validate resource URI
+     */
+    private validateResourceUri;
+    /**
+     * Find matching resource template
+     */
+    private findResourceTemplate;
+    /**
+     * Check if URI matches a pattern
+     */
+    private matchesPattern;
+    /**
+     * Register a prompt
+     */
+    registerPrompt(prompt: RegisteredPrompt): this;
+    /**
+     * Unregister a prompt
+     */
+    unregisterPrompt(name: string): boolean;
+    /**
+     * List all prompts
+     */
+    listPrompts(): MCPPrompt[];
+    /**
+     * Get a prompt
+     */
+    getPrompt(name: string, args?: Record<string, JsonValue>, context?: JsonObject): Promise<PromptResult>;
+    /**
+     * Get prompt by name
+     */
+    getPromptDefinition(name: string): RegisteredPrompt | undefined;
+    /**
+     * Validate prompt name
+     */
+    private validatePromptName;
+    /**
+     * Get capabilities object for MCP protocol
+     */
+    getCapabilities(): {
+        resources?: {
+            subscribe?: boolean;
+            listChanged?: boolean;
+        };
+        prompts?: {
+            listChanged?: boolean;
+        };
+    };
+    /**
+     * Get statistics
+     */
+    getStatistics(): {
+        resourceCount: number;
+        templateCount: number;
+        promptCount: number;
+        subscriptionCount: number;
+    };
+    /**
+     * Clear all resources and prompts
+     */
+    clear(): void;
+}
+/**
+ * Create a simple text resource
+ */
+export declare function createTextResource(uri: string, name: string, content: string | (() => string | Promise<string>), options?: {
+    description?: string;
+    dynamic?: boolean;
+}): RegisteredResource;
+/**
+ * Create a JSON resource
+ */
+export declare function createJsonResource<T extends JsonObject>(uri: string, name: string, content: T | (() => T | Promise<T>), options?: {
+    description?: string;
+    dynamic?: boolean;
+}): RegisteredResource;
+/**
+ * Create a simple prompt template
+ */
+export declare function createPrompt(name: string, template: string, options?: {
+    description?: string;
+    arguments?: MCPPrompt["arguments"];
+}): RegisteredPrompt;