openapi-mcp-proxy

Instructions

Implementation Reference

• openapi_mcp_proxy/services/openapi_explorer.py:88-127 (handler)

  Core handler function in OpenAPIExplorer that fetches detailed endpoint information from the schema, including parameters, request body, security, and optionally responses.

  async def get_endpoint_details(
      self,
      api_identifier: str,
      path: str,
      method: str,
      include_responses: bool = True,
  ) -> Dict[str, Any]:
      """Get detailed information about a specific endpoint."""
      url, headers = self.config_manager.get_api_config(api_identifier)
      schema = await self.cache.get_schema(url, headers)
  
      paths = schema.get("paths", {})
      if path not in paths:
          raise ValueError(f"Path '{path}' not found")
  
      path_info = paths[path]
      method_lower = method.lower()
  
      if method_lower not in path_info:
          raise ValueError(f"Method '{method}' not found for path '{path}'")
  
      operation = path_info[method_lower]
  
      details = {
          "path": path,
          "method": method.upper(),
          "summary": operation.get("summary"),
          "description": operation.get("description"),
          "tags": operation.get("tags", []),
          "operation_id": operation.get("operationId"),
          "parameters": operation.get("parameters", []),
          "request_body": operation.get("requestBody"),
          "security": operation.get("security", []),
      }
  
      if include_responses:
          details["responses"] = operation.get("responses", {})
  
      logger.info(f"Retrieved details for {method.upper()} {path}")
      return details

• openapi_mcp_proxy/tools/base.py:140-155 (schema)

  Defines the JSON schema for the tool's input parameters: api, path, method, and optional include_responses.

  def create_endpoint_details_input_schema() -> Dict[str, Any]:
      """Create input schema for endpoint details."""
      return {
          "type": "object",
          "properties": {
              "api": {"type": "string", "description": "API name or direct URL"},
              "path": {"type": "string", "description": "Endpoint path"},
              "method": {"type": "string", "description": "HTTP method"},
              "include_responses": {
                  "type": "boolean",
                  "description": "Whether to include responses in details. Use it, for example, to get full details for a specific endpoint or pass False to get a summary.",
                  "default": True,
              },
          },
          "required": ["api", "path", "method"],
      }

• openapi_mcp_proxy/tools/api_exploration.py:177-208 (registration)

  MCP Tool class definition including name, description, input schema reference, and handle_call that delegates to the explorer service.

  class GetEndpointDetailsTool(APITool, ToolDefinitionMixin):
      """Tool for getting detailed endpoint information."""
  
      def __init__(self, config_manager, explorer):
          super().__init__(
              name="get_endpoint_details",
              description="Get detailed information about a specific endpoint",
              config_manager=config_manager,
              explorer=explorer,
          )
  
      def get_tool_definition(self) -> Tool:
          return Tool(
              name=self.name,
              description=self.description,
              inputSchema=self.create_endpoint_details_input_schema(),
          )
  
      async def handle_call(self, arguments: Dict[str, Any]) -> List[TextContent]:
          try:
              self._validate_api_identifier(arguments["api"])
              details = await self.explorer.get_endpoint_details(
                  arguments["api"],
                  arguments["path"],
                  arguments["method"],
                  arguments.get("include_responses", True),
              )
              result = self.explorer.format_endpoint_details(details)
              return self._create_text_response(result)
          except Exception as e:
              return self._create_error_response(e)

• openapi_mcp_proxy/services/tool_registry.py:37-56 (registration)

  Registers the GetEndpointDetailsTool instance in the central tool registry along with other tools.

  def _register_tools(self) -> None:
      """Register all available tools."""
      tools = [
          # API Management Tools
          AddApiTool(self.config_manager),
          ListSavedApisTool(self.config_manager),
          RemoveApiTool(self.config_manager),
          # API Exploration Tools
          GetApiInfoTool(self.config_manager, self.explorer),
          ListEndpointsTool(self.config_manager, self.explorer),
          SearchEndpointsTool(self.config_manager, self.explorer),
          GetEndpointDetailsTool(self.config_manager, self.explorer),
          ListModelsTool(self.config_manager, self.explorer),
          GetModelSchemaTool(self.config_manager, self.explorer),
      ]
  
      for tool in tools:
          self._tools[tool.name] = tool
          logger.debug(f"Registered tool: {tool.name}")

• openapi_mcp_proxy/services/openapi_explorer.py:306-317 (helper)

  Helper method to format the endpoint details output for user-friendly display, used by the tool's handle_call.

  def format_endpoint_details(self, details: Dict[str, Any]) -> str:
      """Format endpoint details for display."""
      result = f"{details['method']} {details['path']}\n"
      if details["summary"]:
          result += f"Summary: {details['summary']}\n"
      if details["description"]:
          result += f"Description: {details['description']}\n"
      if details["tags"]:
          result += f"Tags: {', '.join(details['tags'])}\n"
  
      result += f"\nFull schema:\n{json.dumps(details, indent=2)}"
      return result