@opencontextprotocol/agent 0.1.0

package/dist/src/registry.js

@@ -0,0 +1,164 @@
+/**
+ * OCP Registry Client
+ *
+ * Client for accessing pre-discovered API specifications from the OCP registry.
+ */
+import { RegistryUnavailable, APINotFound } from './errors.js';
+const DEFAULT_REGISTRY_URL = 'https://opencontextprotocol.io/api/v1';
+const DEFAULT_TIMEOUT = 10000;
+const SEARCH_TIMEOUT = 5000;
+const DEFAULT_PER_PAGE = 10;
+const MAX_SUGGESTIONS = 3;
+const DEFAULT_API_VERSION = '1.0.0';
+/**
+ * OCP Registry Client
+ *
+ * Access pre-discovered API specifications from the OCP community registry.
+ */
+export class OCPRegistry {
+    /**
+     * Initialize registry client.
+     *
+     * @param registryUrl - Registry URL (defaults to OCP_REGISTRY_URL env var or registry.ocp.dev)
+     */
+    constructor(registryUrl) {
+        this.registryUrl = (registryUrl || process.env.OCP_REGISTRY_URL || DEFAULT_REGISTRY_URL).replace(/\/$/, '');
+        // Validate URL format
+        if (!this.registryUrl.startsWith('http://') && !this.registryUrl.startsWith('https://')) {
+            throw new Error(`Invalid registry URL: ${this.registryUrl}`);
+        }
+    }
+    /**
+     * Get API specification from registry.
+     *
+     * @param name - API name in registry
+     * @param baseUrl - Optional override for API base URL
+     * @returns API specification with tools
+     * @throws RegistryUnavailable if registry is unreachable
+     * @throws APINotFound if API is not found in registry
+     */
+    async getApiSpec(name, baseUrl) {
+        try {
+            const response = await fetch(`${this.registryUrl}/registry/${name}`, {
+                timeout: DEFAULT_TIMEOUT
+            });
+            if (response.status === 404) {
+                const suggestions = await this._getSuggestions(name);
+                throw new APINotFound(name, suggestions);
+            }
+            if (!response.ok) {
+                throw new RegistryUnavailable(this.registryUrl, `${response.statusText}`);
+            }
+            const entry = await response.json();
+            return await this._entryToSpec(entry, baseUrl);
+        }
+        catch (error) {
+            if (error instanceof APINotFound || error instanceof RegistryUnavailable) {
+                throw error;
+            }
+            if (error instanceof TypeError && error.message.includes('fetch')) {
+                throw new RegistryUnavailable(this.registryUrl, `Could not connect to registry`);
+            }
+            throw new RegistryUnavailable(this.registryUrl, String(error));
+        }
+    }
+    /**
+     * Search for APIs in the registry.
+     *
+     * @param query - Search query string
+     * @returns List of API names matching query
+     */
+    async searchApis(query) {
+        try {
+            const params = new URLSearchParams({
+                q: query,
+                per_page: DEFAULT_PER_PAGE.toString()
+            });
+            const url = `${this.registryUrl}/search?${params.toString()}`;
+            const response = await fetch(url, {
+                timeout: SEARCH_TIMEOUT
+            });
+            if (!response.ok) {
+                return [];
+            }
+            const searchResults = await response.json();
+            return (searchResults.results || []).map(r => r.name);
+        }
+        catch {
+            // If search fails, return empty list (non-critical)
+            return [];
+        }
+    }
+    /**
+     * List all APIs in the registry.
+     *
+     * @returns List of API names
+     */
+    async listApis() {
+        try {
+            const response = await fetch(`${this.registryUrl}/registry`, {
+                timeout: DEFAULT_TIMEOUT
+            });
+            if (!response.ok) {
+                return [];
+            }
+            const apis = await response.json();
+            return apis.map(api => api.name);
+        }
+        catch {
+            // If list fails, return empty list (non-critical)
+            return [];
+        }
+    }
+    /**
+     * Convert registry entry to API spec.
+     */
+    async _entryToSpec(entry, baseUrlOverride) {
+        // Use override base_url if provided, otherwise use registry's base_url
+        const baseUrl = baseUrlOverride || entry.base_url || '';
+        // Convert tools from registry format to OCPTool objects
+        const tools = [];
+        if (entry.tools) {
+            for (const toolDict of entry.tools) {
+                const tool = {
+                    name: toolDict.name,
+                    description: toolDict.description,
+                    method: toolDict.method,
+                    path: toolDict.path,
+                    parameters: toolDict.parameters || {},
+                    response_schema: toolDict.response_schema || {},
+                    operation_id: toolDict.operation_id,
+                    tags: toolDict.tags || []
+                };
+                tools.push(tool);
+            }
+        }
+        // Create OCPAPISpec (matching dataclass field order)
+        return {
+            base_url: baseUrl,
+            title: entry.display_name || entry.name,
+            version: DEFAULT_API_VERSION, // Registry doesn't store version
+            description: entry.description || '',
+            tools,
+            raw_spec: entry // Store the original registry entry
+        };
+    }
+    /**
+     * Get API name suggestions for error messages.
+     */
+    async _getSuggestions(apiName) {
+        try {
+            // Try exact search first
+            let suggestions = await this.searchApis(apiName);
+            // If no results, try partial matches
+            if (suggestions.length === 0 && apiName.length > 2) {
+                suggestions = await this.searchApis(apiName.slice(0, 3));
+            }
+            return suggestions.slice(0, MAX_SUGGESTIONS);
+        }
+        catch {
+            return [];
+        }
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/src/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/registry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/D,MAAM,oBAAoB,GAAG,uCAAuC,CAAC;AACrE,MAAM,eAAe,GAAG,KAAK,CAAC;AAC9B,MAAM,cAAc,GAAG,IAAI,CAAC;AAC5B,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAC5B,MAAM,eAAe,GAAG,CAAC,CAAC;AAC1B,MAAM,mBAAmB,GAAG,OAAO,CAAC;AAsBpC;;;;GAIG;AACH,MAAM,OAAO,WAAW;IAGpB;;;;OAIG;IACH,YAAY,WAAoB;QAC5B,IAAI,CAAC,WAAW,GAAG,CAAC,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,oBAAoB,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAE5G,sBAAsB;QACtB,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YACtF,MAAM,IAAI,KAAK,CAAC,yBAAyB,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;QACjE,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,UAAU,CAAC,IAAY,EAAE,OAAgB;QAC3C,IAAI,CAAC;YACD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,WAAW,aAAa,IAAI,EAAE,EAAE;gBACjE,OAAO,EAAE,eAAe;aACpB,CAAC,CAAC;YAEV,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;gBAC1B,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;gBACrD,MAAM,IAAI,WAAW,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAC7C,CAAC;YAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACf,MAAM,IAAI,mBAAmB,CACzB,IAAI,CAAC,WAAW,EAChB,GAAG,QAAQ,CAAC,UAAU,EAAE,CAC3B,CAAC;YACN,CAAC;YAED,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAsB,CAAC;YACxD,OAAO,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAEnD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,IAAI,KAAK,YAAY,WAAW,IAAI,KAAK,YAAY,mBAAmB,EAAE,CAAC;gBACvE,MAAM,KAAK,CAAC;YAChB,CAAC;YAED,IAAI,KAAK,YAAY,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;gBAChE,MAAM,IAAI,mBAAmB,CACzB,IAAI,CAAC,WAAW,EAChB,+BAA+B,CAClC,CAAC;YACN,CAAC;YAED,MAAM,IAAI,mBAAmB,CACzB,IAAI,CAAC,WAAW,EAChB,MAAM,CAAC,KAAK,CAAC,CAChB,CAAC;QACN,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CAAC,KAAa;QAC1B,IAAI,CAAC;YACD,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC;gBAC/B,CAAC,EAAE,KAAK;gBACR,QAAQ,EAAE,gBAAgB,CAAC,QAAQ,EAAE;aACxC,CAAC,CAAC;YAEH,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,WAAW,WAAW,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;YAC9D,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBAC9B,OAAO,EAAE,cAAc;aACnB,CAAC,CAAC;YAEV,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACf,OAAO,EAAE,CAAC;YACd,CAAC;YAED,MAAM,aAAa,GAAG,MAAM,QAAQ,CAAC,IAAI,EAA2C,CAAC;YACrF,OAAO,CAAC,aAAa,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAE1D,CAAC;QAAC,MAAM,CAAC;YACL,oDAAoD;YACpD,OAAO,EAAE,CAAC;QACd,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,QAAQ;QACV,IAAI,CAAC;YACD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,WAAW,WAAW,EAAE;gBACzD,OAAO,EAAE,eAAe;aACpB,CAAC,CAAC;YAEV,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACf,OAAO,EAAE,CAAC;YACd,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAA6B,CAAC;YAC9D,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAErC,CAAC;QAAC,MAAM,CAAC;YACL,kDAAkD;YAClD,OAAO,EAAE,CAAC;QACd,CAAC;IACL,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,YAAY,CAAC,KAAuB,EAAE,eAAwB;QACxE,uEAAuE;QACvE,MAAM,OAAO,GAAG,eAAe,IAAI,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC;QAExD,wDAAwD;QACxD,MAAM,KAAK,GAAc,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YACd,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;gBACjC,MAAM,IAAI,GAAY;oBAClB,IAAI,EAAE,QAAQ,CAAC,IAAI;oBACnB,WAAW,EAAE,QAAQ,CAAC,WAAW;oBACjC,MAAM,EAAE,QAAQ,CAAC,MAAM;oBACvB,IAAI,EAAE,QAAQ,CAAC,IAAI;oBACnB,UAAU,EAAE,QAAQ,CAAC,UAAU,IAAI,EAAE;oBACrC,eAAe,EAAE,QAAQ,CAAC,eAAe,IAAI,EAAE;oBAC/C,YAAY,EAAE,QAAQ,CAAC,YAAY;oBACnC,IAAI,EAAE,QAAQ,CAAC,IAAI,IAAI,EAAE;iBAC5B,CAAC;gBACF,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACrB,CAAC;QACL,CAAC;QAED,qDAAqD;QACrD,OAAO;YACH,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,KAAK,CAAC,YAAY,IAAI,KAAK,CAAC,IAAI;YACvC,OAAO,EAAE,mBAAmB,EAAG,iCAAiC;YAChE,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,EAAE;YACpC,KAAK;YACL,QAAQ,EAAE,KAAK,CAAE,oCAAoC;SACxD,CAAC;IACN,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,eAAe,CAAC,OAAe;QACzC,IAAI,CAAC;YACD,yBAAyB;YACzB,IAAI,WAAW,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;YAEjD,qCAAqC;YACrC,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACjD,WAAW,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YAC7D,CAAC;YAED,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC;QAEjD,CAAC;QAAC,MAAM,CAAC;YACL,OAAO,EAAE,CAAC;QACd,CAAC;IACL,CAAC;CACJ"}

package/dist/src/schema_discovery.d.ts

@@ -0,0 +1,149 @@
+/**
+ * OCP Schema Discovery
+ *
+ * Automatic OpenAPI schema discovery and tool extraction for OCP agents.
+ */
+/**
+ * Tool definition extracted from OpenAPI operation
+ */
+export interface OCPTool {
+    name: string;
+    description: string;
+    method: string;
+    path: string;
+    parameters: Record<string, any>;
+    response_schema?: Record<string, any>;
+    operation_id?: string;
+    tags?: string[];
+}
+/**
+ * Complete API specification with tools
+ */
+export interface OCPAPISpec {
+    base_url: string;
+    title: string;
+    version: string;
+    description: string;
+    tools: OCPTool[];
+    raw_spec: Record<string, any>;
+    name?: string;
+}
+/**
+ * OCP Schema Discovery Client
+ *
+ * Discovers and parses OpenAPI specifications to extract available tools.
+ */
+export declare class OCPSchemaDiscovery {
+    private cache;
+    private _specVersion?;
+    constructor();
+    /**
+     * Discover API from OpenAPI specification.
+     *
+     * @param specPath - URL or file path to OpenAPI specification (JSON or YAML)
+     * @param baseUrl - Optional override for API base URL
+     * @param includeResources - Optional list of resource names to filter tools by (case-insensitive, first resource segment matching)
+     * @param pathPrefix - Optional path prefix to strip before filtering (e.g., '/v1', '/api/v2')
+     * @returns API specification with extracted tools
+     */
+    discoverApi(specPath: string, baseUrl?: string, includeResources?: string[], pathPrefix?: string): Promise<OCPAPISpec>;
+    /**
+     * Normalize cache key: URLs as-is, file paths to absolute.
+     */
+    private _normalizeCacheKey;
+    /**
+     * Fetch OpenAPI spec from URL or local file.
+     */
+    private _fetchSpec;
+    /**
+     * Fetch OpenAPI specification from URL without resolving $refs.
+     * References are resolved lazily during tool creation.
+     */
+    private _fetchFromUrl;
+    /**
+     * Load OpenAPI specification from local JSON or YAML file.
+     */
+    private _fetchFromFile;
+    /**
+     * Detect OpenAPI/Swagger version from spec.
+     *
+     * @returns Version string: 'swagger_2', 'openapi_3.0', 'openapi_3.1', 'openapi_3.2'
+     */
+    private _detectSpecVersion;
+    /**
+     * Recursively resolve $ref references in OpenAPI spec with polymorphic keyword handling.
+     *
+     * @param obj - Current object being processed (object, array, or primitive)
+     * @param root - Root spec document for looking up references
+     * @param resolutionStack - Stack of refs currently being resolved (for circular detection)
+     * @param memo - Memoization cache to store resolved references
+     * @param insidePolymorphicKeyword - True if currently inside anyOf/oneOf/allOf
+     * @returns Object with all resolvable $refs replaced by their definitions
+     */
+    private _resolveRefs;
+    /**
+     * Look up a reference path in the spec document.
+     *
+     * @param root - Root spec document
+     * @param refPath - Reference path like '#/components/schemas/User'
+     * @returns The referenced object, or null if not found
+     */
+    private _lookupRef;
+    /**
+     * Parse OpenAPI specification and extract tools with lazy $ref resolution.
+     */
+    private _parseOpenApiSpec;
+    /**
+     * Extract base URL from spec (version-aware).
+     */
+    private _extractBaseUrl;
+    /**
+     * Create tool definition from OpenAPI operation.
+     */
+    private _createToolFromOperation;
+    /**
+     * Normalize tool name to camelCase, removing special characters.
+     */
+    private _normalizeToolName;
+    /**
+     * Check if a normalized tool name is valid.
+     */
+    private _isValidToolName;
+    /**
+     * Parse OpenAPI parameters with lazy $ref resolution.
+     */
+    private _parseParameters;
+    /**
+     * Parse OpenAPI 3.x request body with lazy $ref resolution.
+     */
+    private _parseOpenApi3RequestBody;
+    /**
+     * Parse Swagger 2.0 body parameter into parameters.
+     */
+    private _parseSwagger2BodyParameter;
+    /**
+     * Parse OpenAPI responses with lazy $ref resolution (version-aware).
+     */
+    private _parseResponses;
+    /**
+     * Get tools filtered by tag.
+     */
+    getToolsByTag(apiSpec: OCPAPISpec, tag: string): OCPTool[];
+    /**
+     * Filter tools to only include those whose first resource segment matches includeResources.
+     */
+    private _filterToolsByResources;
+    /**
+     * Search tools by name or description.
+     */
+    searchTools(apiSpec: OCPAPISpec, query: string): OCPTool[];
+    /**
+     * Generate human-readable tool documentation.
+     */
+    generateToolDocumentation(tool: OCPTool): string;
+    /**
+     * Clear the discovery cache.
+     */
+    clearCache(): void;
+}
+//# sourceMappingURL=schema_discovery.d.ts.map

package/dist/src/schema_discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema_discovery.d.ts","sourceRoot":"","sources":["../../src/schema_discovery.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAaH;;GAEG;AACH,MAAM,WAAW,OAAO;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAChC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,qBAAa,kBAAkB;IAC3B,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,YAAY,CAAC,CAAS;;IAM9B;;;;;;;;OAQG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,EAAE,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAsC5H;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAY1B;;OAEG;YACW,UAAU;IAQxB;;;OAGG;YACW,aAAa;IAiB3B;;OAEG;IACH,OAAO,CAAC,cAAc;IAuDtB;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAwB1B;;;;;;;;;OASG;IACH,OAAO,CAAC,YAAY;IAsIpB;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;IAqBlB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA6CzB;;OAEG;IACH,OAAO,CAAC,eAAe;IAqBvB;;OAEG;IACH,OAAO,CAAC,wBAAwB;IA8EhC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA6B1B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAkBxB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAwCxB;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAgDjC;;OAEG;IACH,OAAO,CAAC,2BAA2B;IAyCnC;;OAEG;IACH,OAAO,CAAC,eAAe;IA8BvB;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,EAAE;IAM1D;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAgC/B;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE;IAS1D;;OAEG;IACH,yBAAyB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM;IA2BhD;;OAEG;IACH,UAAU,IAAI,IAAI;CAGrB"}