Merge pull request #1 from opencontextprotocol/feat/parser-registry-pattern

feat!: refactor tool discovery into extensible parser registry pattern

Author: nallenscott

src/index.ts

@@ -59,6 +59,13 @@ export {
     type OCPAPISpec
 } from './schema_discovery.js';
 
+// Parser system
+export {
+    APISpecParser,
+    ParserRegistry,
+    OpenAPIParser
+} from './parsers/index.js';
+
 // Registry
 export { OCPRegistry } from './registry.js';
 

src/parsers/base.ts

@@ -0,0 +1,69 @@
+/**
+ * Base parser interface and shared types for API specification parsing.
+ */
+
+/**
+ * Tool definition extracted from API specification
+ */
+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;
+}
+
+/**
+ * Abstract base class for API specification parsers.
+ * 
+ * Implement this interface to add support for new API specification formats
+ * (e.g., Postman Collections, GraphQL schemas, Google Discovery format).
+ */
+export abstract class APISpecParser {
+    /**
+     * Determine if this parser can handle the given spec data.
+     * 
+     * @param specData - The raw specification data
+     * @returns True if this parser can parse the spec
+     */
+    abstract canParse(specData: Record<string, any>): boolean;
+
+    /**
+     * Parse the specification and extract tools.
+     * 
+     * @param specData - The raw specification data
+     * @param baseUrlOverride - Optional base URL override
+     * @param includeResources - Optional resource filter
+     * @param pathPrefix - Optional path prefix for filtering
+     * @returns Parsed API specification with tools
+     */
+    abstract parse(
+        specData: Record<string, any>,
+        baseUrlOverride?: string,
+        includeResources?: string[],
+        pathPrefix?: string
+    ): OCPAPISpec;
+
+    /**
+     * Get the human-readable name of this parser's format.
+     * 
+     * @returns Format name (e.g., "OpenAPI", "Postman Collection")
+     */
+    abstract getFormatName(): string;
+}

src/parsers/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Parser system exports for API specification parsing.
+ */
+
+export { APISpecParser, OCPTool, OCPAPISpec } from './base.js';
+export { ParserRegistry } from './registry.js';
+export { OpenAPIParser } from './openapi_parser.js';