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

feat!: refactor tool discovery into extensible parser registry pattern

Author: nallenscott

src/ocp_agent/__init__.py

@@ -17,6 +17,7 @@
 from .agent import OCPAgent
 from .storage import OCPStorage
 from .errors import OCPError, RegistryUnavailable, APINotFound, SchemaDiscoveryError, ValidationError
+from .parsers import APISpecParser, ParserRegistry, OpenAPIParser
 
 __version__ = "0.1.0"
 __all__ = [
@@ -30,7 +31,7 @@
     "extract_context_from_response",
     "validate_context",
 
-    # Convenience functions for cleaner API
+    # Convenience functions
     "parse_context",
     "add_context_headers",
 
@@ -39,6 +40,11 @@
     "OCPTool",
     "OCPAPISpec",
 
+    # Parser system
+    "APISpecParser",
+    "ParserRegistry",
+    "OpenAPIParser",
+    
     # Registry integration
     "OCPRegistry",
 

src/ocp_agent/parsers/__init__.py

@@ -0,0 +1,16 @@
+"""
+API Specification Parsers
+
+This module provides an extensible parser system for converting various API
+specification formats (OpenAPI, Postman, GraphQL, etc.) into OCP tools.
+"""
+
+from .base import APISpecParser
+from .registry import ParserRegistry
+from .openapi_parser import OpenAPIParser
+
+__all__ = [
+    'APISpecParser',
+    'ParserRegistry',
+    'OpenAPIParser',
+]

src/ocp_agent/parsers/base.py

@@ -0,0 +1,93 @@
+"""
+Base Parser Interface
+
+Defines the abstract interface that all API specification parsers must implement.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Optional, List
+from dataclasses import dataclass
+
+
+@dataclass
+class OCPTool:
+    """Represents a discovered API tool/endpoint"""
+    name: str
+    description: str
+    method: str
+    path: str
+    parameters: Dict[str, Any]
+    response_schema: Optional[Dict[str, Any]]
+    operation_id: Optional[str] = None
+    tags: Optional[List[str]] = None
+
+
+@dataclass 
+class OCPAPISpec:
+    """Represents a parsed API specification"""
+    base_url: str
+    title: str
+    version: str
+    description: str
+    tools: List[OCPTool]
+    raw_spec: Dict[str, Any]
+    name: Optional[str] = None
+
+
+class APISpecParser(ABC):
+    """
+    Abstract base class for API specification parsers.
+    
+    All parsers must implement three methods:
+    - can_parse(): Detect if this parser can handle a given spec
+    - parse(): Convert the spec into an OCPAPISpec with tools
+    - get_format_name(): Return a human-readable format name
+    """
+    
+    @abstractmethod
+    def can_parse(self, spec_data: Dict[str, Any]) -> bool:
+        """
+        Determine if this parser can handle the given specification.
+        
+        Args:
+            spec_data: The raw specification data as a dictionary
+            
+        Returns:
+            True if this parser can handle the format, False otherwise
+        """
+        pass
+    
+    @abstractmethod
+    def parse(
+        self, 
+        spec_data: Dict[str, Any], 
+        base_url_override: Optional[str] = None,
+        include_resources: Optional[List[str]] = None,
+        path_prefix: Optional[str] = None
+    ) -> OCPAPISpec:
+        """
+        Parse the specification and extract tools.
+        
+        Args:
+            spec_data: The raw specification data as a dictionary
+            base_url_override: Optional override for the API base URL
+            include_resources: Optional list of resource names to filter tools by
+            path_prefix: Optional path prefix to strip before filtering
+            
+        Returns:
+            OCPAPISpec containing extracted tools and metadata
+            
+        Raises:
+            Exception: If parsing fails
+        """
+        pass
+    
+    @abstractmethod
+    def get_format_name(self) -> str:
+        """
+        Get the human-readable name of the format this parser handles.
+        
+        Returns:
+            Format name (e.g., "OpenAPI", "Postman Collection", "GraphQL")
+        """
+        pass