mcp-orbit 0.1.0

package/src/index.ts

@@ -0,0 +1,92 @@
+/**
+ * mcp-orbit — Public API
+ *
+ * Everything a tool package needs to build its own MCP server.
+ */
+
+// ── Server ────────────────────────────────────────────────────────────────────
+export {
+  startServer,
+  registerTool,
+  registerPlugin,
+  executeTool,
+  createMCPServer,
+  getTool,
+  getToolCount,
+  getToolDefinitions,
+} from "./core/server.js";
+export type {ServerConfig, TransportMode} from "./core/server.js";
+
+export {startHttpServer} from "./core/server-http.js";
+export {startStdioServer} from "./core/server-stdio.js";
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+export type {
+  Tool,
+  MCPToolResult,
+  MCPToolDefinition,
+  MCPContent,
+  JsonSchema,
+  APIProvider,
+  ToolBuilderConfig,
+  MCPResource,
+  ResourceCapabilities,
+  ResourceAnnotations,
+  ResourceSchema,
+  ResourceContent,
+  ResourceProvider,
+  PromptArgument,
+  MCPPromptDefinition,
+  PromptMessage,
+  PromptProvider,
+  MCPPlugin,
+} from "./core/types.js";
+export {toSerializableToolDefinition} from "./core/types.js";
+
+// ── Registries ────────────────────────────────────────────────────────────────
+export {resourceRegistry, createAndRegisterResource, unregisterResource} from "./core/resource-registry.js";
+export {promptRegistry, createAndRegisterPrompt} from "./core/prompt-registry.js";
+
+// ── URI Templates ─────────────────────────────────────────────────────────────
+export {
+  parseURITemplate,
+  matchURITemplate,
+  resolveURITemplate,
+  TemplateRegistry,
+} from "./core/resource-uri-templates.js";
+export type {URITemplate, URIMatch} from "./core/resource-uri-templates.js";
+
+// ── Clients ───────────────────────────────────────────────────────────────────
+export {HttpMCPClient} from "./clients/mcp-http.js";
+export {StdioMCPClient} from "./clients/mcp-stdio.js";
+export type {
+  IMcpClient,
+  MCPToolSchema,
+  MCPToolResponse,
+  MCPResourceList,
+  MCPResourceContent,
+  MCPPrompt,
+  MCPPromptArgument,
+  MCPPromptList,
+  MCPPromptMessage,
+  MCPPromptResponse,
+  McpServerConfig,
+  McpHttpServerConfig,
+  McpStdioServerConfig,
+} from "./clients/types.js";
+
+// ── Utilities ─────────────────────────────────────────────────────────────────
+export {default as logger, createLogger, log} from "./utils/logger.js";
+export type {Logger, LogLevel} from "./utils/logger.js";
+
+export {zodToMcpJsonSchema, isZodArray, fixAdditionalProperties} from "./utils/zod-to-mcp-schema.js";
+export type {McpSchemaOptions} from "./utils/zod-to-mcp-schema.js";
+
+export {HTTPClient, httpClient} from "./utils/http-client.js";
+export type {HTTPClientConfig, HTTPClientResponse} from "./utils/http-client.js";
+
+export {dynamicResourceManager, DynamicResourceManager} from "./utils/dynamic-resource-manager.js";
+export type {ResourceMetadata, StoreOptions} from "./utils/dynamic-resource-manager.js";
+
+// ── CLI helpers ───────────────────────────────────────────────────────────────
+export {parseArgs} from "./cli.js";

package/src/utils/dynamic-resource-manager.ts

@@ -0,0 +1,581 @@
+/**
+ * Dynamic Resource Manager
+ *
+ * Manages automatic resource creation for large tool results.
+ * Key features:
+ * - Auto-detection of large responses
+ * - Dynamic resource registration
+ * - Persistent storage with TTL
+ * - Schema generation for safe querying
+ */
+
+import {promises as fs} from "node:fs";
+import path from "node:path";
+import {resourceRegistry} from "../core/resource-registry.js";
+import {getTool} from "../core/server.js";
+import type {ResourceAnnotations, ResourceSchema} from "../core/types.js";
+import logger from "./logger.js";
+
+const resourceLogger = logger.child("resource-manager");
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+export interface ResourceMetadata {
+  uri: string;
+  toolName: string;
+  source?: string;
+  timestamp: number;
+  size: number;
+  expiresAt: number;
+  schema: ResourceSchema;
+  itemCount?: number;
+  filePath: string;
+  title?: string;
+  annotations?: ResourceAnnotations;
+}
+
+interface StoredResourceMetadata {
+  uri: string;
+  toolName: string;
+  source?: string;
+  timestamp: number;
+  size: number;
+  expiresAt: number;
+  schema?: ResourceSchema;
+  itemCount?: number;
+}
+
+export interface StoreOptions {
+  ttl?: number; // Time-to-live in milliseconds (default: 72 hours)
+  namespace?: string; // Resource namespace (default: 'cache')
+  schema?: ResourceSchema; // Optional override: provide known output schema of the dataset
+  toolDefinitionName?: string; // Optional: fully-qualified tool name (to pick up output schema)
+  source?: string; // Optional: resource origin (e.g., external)
+}
+
+// ============================================================================
+// DYNAMIC RESOURCE MANAGER
+// ============================================================================
+
+export class DynamicResourceManager {
+  dataDir = path.join(process.cwd(), "data", "resources");
+  metadata: Map<string, ResourceMetadata> = new Map();
+  private defaultTTL = 72 * 60 * 60 * 1000; // 72 hours
+  private largeDataThreshold = 5000; // 5KB
+  private maxSchemaDepth = 4;
+  private maxSchemaProperties = 32;
+  private cacheDisabledLogged = false;
+  private readonly allowedStoredMetaKeys = new Set([
+    "uri",
+    "toolName",
+    "source",
+    "timestamp",
+    "size",
+    "expiresAt",
+    "schema",
+    "itemCount",
+  ]);
+
+  constructor() {
+    this.initialize();
+  }
+
+  /**
+   * Initialize resource manager
+   */
+  private async initialize(): Promise<void> {
+    try {
+      await fs.mkdir(this.dataDir, {recursive: true});
+      await this.loadResourcesFromDisk();
+    } catch (error) {
+      resourceLogger.error("Initialization failed:", error);
+    }
+  }
+
+  /**
+   * Load resources from disk (scan directory and read metadata from files)
+   */
+  private async loadResourcesFromDisk(): Promise<void> {
+    try {
+      const files = await fs.readdir(this.dataDir);
+
+      for (const file of files) {
+        if (!file.endsWith(".json")) continue;
+
+        const filePath = path.join(this.dataDir, file);
+        const resourceId = path.basename(file, ".json");
+
+        try {
+          const fileContent = await fs.readFile(filePath, "utf-8");
+          const parsed = JSON.parse(fileContent);
+          const data = parsed.data;
+          const rawMeta = parsed._meta ?? {};
+
+          const storedMeta = this.normalizeStoredMetadata(rawMeta, data, resourceId);
+          const metadata = this.buildRuntimeMetadata(storedMeta, filePath, data);
+
+          this.metadata.set(metadata.uri, metadata);
+          this.registerResource(metadata.uri, metadata, filePath);
+
+          const sanitizedMeta = this.toStoredMetadata(metadata);
+          const hasDeprecatedKeys = Object.keys(rawMeta ?? {}).some((key) => !this.allowedStoredMetaKeys.has(key));
+          const metaMismatch = JSON.stringify(rawMeta ?? {}) !== JSON.stringify(sanitizedMeta);
+
+          if (hasDeprecatedKeys || metaMismatch) {
+            await fs.writeFile(filePath, JSON.stringify({_meta: sanitizedMeta, data}, null, 2), "utf-8");
+          }
+        } catch (error) {
+          resourceLogger.error(`Failed to load resource ${file}:`, error);
+        }
+      }
+
+      if (this.metadata.size > 0) {
+        resourceLogger.info(`Loaded ${this.metadata.size} resources from disk`);
+      }
+
+      this.cleanupExpiredResources();
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+        resourceLogger.error("Failed to load resources from disk:", error);
+      }
+    }
+  }
+
+  private normalizeStoredMetadata(rawMeta: any, data: unknown, resourceId: string): StoredResourceMetadata {
+    const toolName = this.resolveToolName(rawMeta?.toolName, resourceId);
+    const source = typeof rawMeta?.source === "string" ? rawMeta.source : undefined;
+    const timestamp = typeof rawMeta?.timestamp === "number" ? rawMeta.timestamp : Date.now();
+    const uri = typeof rawMeta?.uri === "string" ? rawMeta.uri : `cache://tools/${toolName}-${timestamp}`;
+    const size =
+      typeof rawMeta?.size === "number" ? rawMeta.size : data !== undefined ? JSON.stringify(data).length : 0;
+    const expiresAt = typeof rawMeta?.expiresAt === "number" ? rawMeta.expiresAt : timestamp + this.defaultTTL;
+    const schema =
+      rawMeta?.schema && typeof rawMeta.schema === "object" ? (rawMeta.schema as ResourceSchema) : undefined;
+    const itemCount =
+      typeof rawMeta?.itemCount === "number" ? rawMeta.itemCount : Array.isArray(data) ? data.length : undefined;
+
+    return {
+      uri,
+      toolName,
+      source,
+      timestamp,
+      size,
+      expiresAt,
+      schema,
+      itemCount,
+    };
+  }
+
+  private buildRuntimeMetadata(storedMeta: StoredResourceMetadata, filePath: string, data: unknown): ResourceMetadata {
+    const schema = storedMeta.schema ?? this.generateSchema(data);
+    const itemCount = storedMeta.itemCount ?? (Array.isArray(data) ? data.length : undefined);
+
+    return {
+      ...storedMeta,
+      schema,
+      itemCount,
+      filePath,
+      title: this.buildTitle(storedMeta.toolName),
+      annotations: this.createAnnotations(storedMeta.timestamp),
+    };
+  }
+
+  private toStoredMetadata(metadata: ResourceMetadata): StoredResourceMetadata {
+    return {
+      uri: metadata.uri,
+      toolName: metadata.toolName,
+      source: metadata.source,
+      timestamp: metadata.timestamp,
+      size: metadata.size,
+      expiresAt: metadata.expiresAt,
+      schema: metadata.schema,
+      itemCount: metadata.itemCount,
+    };
+  }
+
+  private resolveToolName(toolNameCandidate: unknown, resourceId: string): string {
+    if (typeof toolNameCandidate === "string" && toolNameCandidate.length > 0) {
+      return toolNameCandidate;
+    }
+
+    const segments = resourceId.split("-");
+    if (segments.length <= 1) {
+      return resourceId || "unknown-tool";
+    }
+    segments.pop(); // remove timestamp segment
+    const name = segments.join("-");
+    return name.length > 0 ? name : "unknown-tool";
+  }
+
+  private buildTitle(toolName: string): string {
+    return `Cached dataset from ${toolName}`;
+  }
+
+  /**
+   * Store tool result as MCP resource if it's large
+   * Returns resource URI if stored, undefined if result is small
+   */
+  async storeIfLarge(toolName: string, result: any, options: StoreOptions = {}): Promise<string | undefined> {
+    if (this.isCacheDisabled()) {
+      if (!this.cacheDisabledLogged) {
+        resourceLogger.warn("Caching disabled via MCP_DISABLE_CACHE");
+        this.cacheDisabledLogged = true;
+      }
+      return undefined;
+    }
+
+    const resultSize = JSON.stringify(result).length;
+
+    if (resultSize < this.largeDataThreshold) {
+      return undefined;
+    }
+
+    return await this.store(toolName, result, options);
+  }
+
+  /**
+   * Store tool result as MCP resource (regardless of size)
+   */
+  async store(toolName: string, result: any, options: StoreOptions = {}): Promise<string> {
+    const {ttl = this.defaultTTL, namespace = "cache"} = options;
+
+    const timestamp = Date.now();
+    const resourceId = `${toolName}-${timestamp}`;
+    const uri = `${namespace}://tools/${resourceId}`;
+    const filePath = path.join(this.dataDir, `${resourceId}.json`);
+
+    const schema = this.resolveSchema(result, options);
+    const itemCount = Array.isArray(result) ? result.length : undefined;
+    const annotations = this.createAnnotations(timestamp);
+
+    const metadata: ResourceMetadata = {
+      uri,
+      toolName,
+      source: options.source,
+      timestamp,
+      size: JSON.stringify(result).length,
+      filePath,
+      expiresAt: timestamp + ttl,
+      schema,
+      itemCount,
+      title: this.buildTitle(toolName),
+      annotations,
+    };
+
+    this.metadata.set(uri, metadata);
+
+    const fileContent = {
+      _meta: this.toStoredMetadata(metadata),
+      data: result,
+    };
+    await fs.writeFile(filePath, JSON.stringify(fileContent, null, 2), "utf-8");
+
+    this.registerResource(uri, metadata, filePath);
+
+    resourceLogger.info(`Stored ${metadata.size} bytes at ${uri} (expires in ${ttl / 1000}s)`);
+
+    return uri;
+  }
+
+  /**
+   * Register resource with MCP resource registry
+   */
+  private registerResource(uri: string, metadata: ResourceMetadata, filePath: string): void {
+    const title = metadata.title ?? `Cached result from ${metadata.toolName}`;
+
+    resourceRegistry.register({
+      uri,
+      name: `Tool result: ${metadata.toolName}`,
+      title,
+      description: this.describeSchema(metadata),
+      mimeType: "application/json",
+      size: metadata.size,
+      schema: metadata.schema,
+      annotations: metadata.annotations,
+      async read() {
+        const file = await fs.readFile(metadata.filePath ?? filePath, "utf-8");
+        const parsed = JSON.parse(file);
+        return {
+          text: JSON.stringify(parsed.data, null, 2),
+        };
+      },
+    });
+  }
+
+  /**
+   * Generate schema description for logs / chat messages
+   */
+  private describeSchema(metadata: ResourceMetadata): string {
+    const schemaText = this.describeSchemaNode(metadata.schema);
+    if (metadata.itemCount !== undefined) {
+      return `${schemaText} (${metadata.itemCount} items, ${this.formatBytes(metadata.size)})`;
+    }
+    return `${schemaText} (${this.formatBytes(metadata.size)})`;
+  }
+
+  private describeSchemaNode(schema: ResourceSchema | undefined, depth = 0): string {
+    if (!schema) {
+      return "unknown structure";
+    }
+
+    const type = Array.isArray(schema.type) ? schema.type.join("|") : schema.type;
+
+    if (type === "array" && schema.items) {
+      return `array of ${this.describeSchemaNode(schema.items, depth + 1)}`;
+    }
+
+    if (type === "object" && schema.properties) {
+      const keys = Object.keys(schema.properties).slice(0, 5);
+      if (keys.length > 0) {
+        return depth === 0 ? `object (keys: ${keys.join(", ")})` : `object (${keys.join(", ")})`;
+      }
+      return "object";
+    }
+
+    return type ?? "unknown";
+  }
+
+  private createAnnotations(timestamp: number): ResourceAnnotations {
+    return {
+      audience: ["assistant"],
+      priority: 0.5,
+      lastModified: new Date(timestamp).toISOString(),
+    };
+  }
+
+  private pickSample<T>(items: T[]): T | undefined {
+    for (const item of items) {
+      if (item !== undefined && item !== null) {
+        return item;
+      }
+    }
+    return undefined;
+  }
+
+  private generateSchema(data: unknown, depth = 0): ResourceSchema {
+    if (depth >= this.maxSchemaDepth) {
+      return {type: "unknown"};
+    }
+
+    if (data === null || data === undefined) {
+      return {type: "null"};
+    }
+
+    if (Array.isArray(data)) {
+      const sample = this.pickSample(data);
+      if (sample === undefined) {
+        return {type: "array"};
+      }
+      return {type: "array", items: this.generateSchema(sample, depth + 1)};
+    }
+
+    const valueType = typeof data;
+    if (valueType !== "object") {
+      return {type: valueType};
+    }
+
+    // Objects: capture up to maxSchemaProperties keys for better schema details
+    const entries = Object.entries(data as Record<string, unknown>);
+    if (entries.length === 0) {
+      return {type: "object"};
+    }
+
+    const properties: Record<string, ResourceSchema> = {};
+    for (const [key, value] of entries.slice(0, this.maxSchemaProperties)) {
+      properties[key] = this.generateSchema(value, depth + 1);
+    }
+
+    const schema: ResourceSchema = {
+      type: "object",
+      properties,
+    };
+
+    if (entries.length > this.maxSchemaProperties) {
+      const remainingSample = this.pickSample(entries.slice(this.maxSchemaProperties).map(([, value]) => value));
+      if (remainingSample !== undefined) {
+        schema.additionalProperties = this.generateSchema(remainingSample, depth + 1);
+      }
+    }
+
+    return schema;
+  }
+
+  /**
+   * Get metadata for a resource
+   */
+  getMetadata(uri: string): ResourceMetadata | undefined {
+    return this.metadata.get(uri);
+  }
+
+  /**
+   * Get sanitized metadata for clients (no internal paths)
+   */
+  getPublicMetadata(uri: string): StoredResourceMetadata | undefined {
+    const metadata = this.metadata.get(uri);
+    if (!metadata) {
+      return undefined;
+    }
+    return this.toStoredMetadata(metadata);
+  }
+
+  /**
+   * List all active resources
+   */
+  listResources(): ResourceMetadata[] {
+    this.cleanupExpiredResources();
+    return Array.from(this.metadata.values())
+      .filter((m) => m.expiresAt > Date.now())
+      .sort((a, b) => b.timestamp - a.timestamp);
+  }
+
+  /**
+   * Generate chat-friendly message about stored resource
+   */
+  getChatMessage(uri: string): string {
+    const metadata = this.metadata.get(uri);
+    if (!metadata) {
+      return [`resourceUri: "${uri}"`, "size: unknown", "data_schema: type: unknown, properties: none"].join("\n");
+    }
+
+    const resourceUriLine = `resourceUri: "${uri}"`;
+    const sizeLine = `size: ${this.formatBytes(metadata.size)}`;
+    const dataSchemaLine = this.buildDataSchemaLine(metadata.schema);
+
+    return [resourceUriLine, sizeLine, dataSchemaLine].join("\n");
+  }
+
+  private formatBytes(bytes: number): string {
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  }
+
+  private buildDataSchemaLine(schema: ResourceSchema | undefined): string {
+    const type = this.describeSchemaType(schema);
+    const properties = this.extractSchemaPropertyNames(schema);
+    const propertiesText = properties.length > 0 ? properties.join(", ") : "none";
+
+    return `data_schema: type: ${type}, properties: ${propertiesText}`;
+  }
+
+  private describeSchemaType(schema: ResourceSchema | undefined): string {
+    if (!schema) {
+      return "unknown";
+    }
+
+    const types = this.normalizeSchemaTypes(schema.type);
+
+    if (types.includes("array")) {
+      const itemType = this.describeSchemaType(schema.items);
+      return itemType === "unknown" ? "array" : `array<${itemType}>`;
+    }
+
+    if (types.includes("object")) {
+      return "object";
+    }
+
+    return types[0] ?? "unknown";
+  }
+
+  private extractSchemaPropertyNames(schema: ResourceSchema | undefined): string[] {
+    if (!schema) {
+      return [];
+    }
+
+    const types = this.normalizeSchemaTypes(schema.type);
+
+    if (types.includes("array")) {
+      const fromItems = this.extractSchemaPropertyNames(schema.items);
+      if (fromItems.length > 0) {
+        return fromItems;
+      }
+      return ["items"];
+    }
+
+    if (types.includes("object")) {
+      if (schema.properties) {
+        return Object.keys(schema.properties).slice(0, this.maxSchemaProperties);
+      }
+      if (schema.additionalProperties) {
+        return this.extractSchemaPropertyNames(schema.additionalProperties);
+      }
+    }
+
+    return [];
+  }
+
+  private normalizeSchemaTypes(type: string | string[] | undefined): string[] {
+    if (!type) {
+      return [];
+    }
+
+    return Array.isArray(type) ? type : [type];
+  }
+
+  private resolveSchema(result: unknown, options: StoreOptions): ResourceSchema {
+    const provided = this.sanitizeSchema(options.schema);
+    if (provided) {
+      return provided;
+    }
+
+    const fromTool = this.getToolOutputSchema(options.toolDefinitionName);
+    if (fromTool) {
+      return fromTool;
+    }
+
+    return this.generateSchema(result);
+  }
+
+  private sanitizeSchema(schema: unknown): ResourceSchema | undefined {
+    if (!schema || typeof schema !== "object") {
+      return undefined;
+    }
+    try {
+      return JSON.parse(JSON.stringify(schema)) as ResourceSchema;
+    } catch {
+      return undefined;
+    }
+  }
+
+  private getToolOutputSchema(toolDefinitionName?: string): ResourceSchema | undefined {
+    if (!toolDefinitionName) {
+      return undefined;
+    }
+
+    const tool = getTool(toolDefinitionName);
+    if (!tool?.definition?.outputSchema) {
+      return undefined;
+    }
+
+    return this.sanitizeSchema(tool.definition.outputSchema);
+  }
+
+  private cleanupExpiredResources(): void {
+    const now = Date.now();
+    for (const [uri, metadata] of Array.from(this.metadata.entries())) {
+      if (metadata.expiresAt <= now) {
+        this.metadata.delete(uri);
+        resourceRegistry.unregister(uri);
+        void fs.unlink(metadata.filePath).catch(() => undefined);
+        resourceLogger.info(`Expired resource removed: ${uri}`);
+      }
+    }
+  }
+
+  private isCacheDisabled(): boolean {
+    const raw = process.env.MCP_DISABLE_CACHE;
+    if (!raw) {
+      return false;
+    }
+    const normalized = raw.trim().toLowerCase();
+    return normalized === "1" || normalized === "true" || normalized === "yes";
+  }
+}
+
+// ============================================================================
+// SINGLETON INSTANCE
+// ============================================================================
+
+export const dynamicResourceManager = new DynamicResourceManager();