pdbe-mcp-server 1.0.0__py3-none-any.whl

pdbe_mcp_server/__init__.py

@@ -0,0 +1,16 @@
+from pathlib import Path
+from typing import cast
+
+from omegaconf import DictConfig, OmegaConf
+
+
+def get_config() -> DictConfig:
+    """
+    Load and return configuration from config.yaml using OmegaConf.
+
+    Returns:
+        DictConfig: Configuration object from config.yaml
+    """
+    config_path: Path = Path(__file__).parent / "config.yaml"
+    config = cast(DictConfig, OmegaConf.load(config_path))
+    return config

pdbe_mcp_server/api_tools.py

@@ -0,0 +1,291 @@
+import json
+from typing import Any
+from urllib.parse import urljoin
+
+import mcp.types as types
+import requests
+from omegaconf import DictConfig
+
+from pdbe_mcp_server import get_config
+from pdbe_mcp_server.utils import HTTPClient
+
+conf: DictConfig = get_config()
+
+
+class OpenAPIToMCPGenerator:
+    def __init__(self, openapi_url: str) -> None:
+        """
+        Initialize the generator with an OpenAPI JSON URL.
+
+        Args:
+            openapi_url: URL to the OpenAPI JSON specification
+        """
+        self.openapi_url: str = openapi_url
+        self.openapi_spec: dict[str, Any] = {}
+        self.base_url: str = str(conf.api.base_url)
+        self.tools: list[dict[str, Any]] = []
+
+    def load_openapi_spec(self) -> dict[str, Any]:
+        """
+        Load the OpenAPI specification from the remote URL.
+
+        Returns:
+            The parsed OpenAPI specification as a dictionary
+        """
+        try:
+            spec = HTTPClient.get(self.openapi_url)
+            self.openapi_spec = spec
+            return spec
+
+        except requests.HTTPError as e:
+            raise Exception(
+                f"Failed to load OpenAPI spec from {self.openapi_url}: {e}"
+            ) from e
+
+    def _convert_openapi_type_to_json_schema(
+        self, param_schema: dict[str, Any]
+    ) -> dict[str, Any]:
+        """
+        Convert OpenAPI parameter schema to JSON Schema format.
+
+        Args:
+            param_schema: OpenAPI parameter schema
+
+        Returns:
+            JSON Schema compatible dictionary
+        """
+        json_schema = {}
+
+        # Map OpenAPI types to JSON Schema types
+        if "type" in param_schema:
+            json_schema["type"] = param_schema["type"]
+
+        if "description" in param_schema:
+            json_schema["description"] = param_schema["description"]
+
+        if "enum" in param_schema:
+            json_schema["enum"] = param_schema["enum"]
+
+        if "default" in param_schema:
+            json_schema["default"] = param_schema["default"]
+
+        if "format" in param_schema:
+            json_schema["format"] = param_schema["format"]
+
+        # Handle array types
+        if param_schema.get("type") == "array" and "items" in param_schema:
+            json_schema["items"] = self._convert_openapi_type_to_json_schema(
+                param_schema["items"]
+            )
+
+        return json_schema
+
+    def _extract_parameters(
+        self, path_params: list[dict[str, Any]], query_params: list[dict[str, Any]]
+    ) -> tuple[dict[str, Any], list[str]]:
+        """
+        Extract and convert parameters to JSON Schema format.
+
+        Args:
+            path_params: List of path parameters
+            query_params: List of query parameters
+
+        Returns:
+            JSON Schema properties and required fields
+        """
+        properties = {}
+        required = []
+
+        # Process path parameters
+        for param in path_params:
+            param_name = param["name"]
+            properties[param_name] = self._convert_openapi_type_to_json_schema(
+                param.get("schema", {})
+            )
+            schema = param.get("schema", {})
+            description = schema.get("description", "")
+            for key in schema:
+                description += f"\n{key}: {schema[key]}"
+
+            properties[param_name]["description"] = description
+            if param.get("required", False):
+                required.append(param_name)
+
+        # Process query parameters
+        for param in query_params:
+            param_name = param["name"]
+            properties[param_name] = self._convert_openapi_type_to_json_schema(
+                param.get("schema", {})
+            )
+            if param.get("description"):
+                properties[param_name]["description"] = param["description"]
+            if param.get("required", False):
+                required.append(param_name)
+
+        return properties, required
+
+    def list_tools(self) -> list[types.Tool]:
+        """
+        Generate MCP tools from the OpenAPI specification.
+
+        Returns:
+            List of MCP Tool objects
+        """
+        if not self.openapi_spec:
+            self.load_openapi_spec()
+
+        tools = []
+        paths = self.openapi_spec.get("paths", {})
+
+        for path, path_item in paths.items():
+            for method, operation in path_item.items():
+                # Skip POST methods and non-HTTP methods
+                if method.upper() == "POST" or method.startswith("x-"):
+                    continue
+
+                # skip APIs which are not enabled for MCP
+                if not operation.get("enableMCP") or not operation["enableMCP"]:
+                    continue
+
+                # Generate tool name from operationId or path/method
+                if "operationId" in operation:
+                    tool_name = operation["operationId"]
+                else:
+                    # Create tool name from path and method
+                    clean_path = (
+                        path.replace("/", "_")
+                        .replace("{", "")
+                        .replace("}", "")
+                        .strip("_")
+                    )
+                    tool_name = f"{method}_{clean_path}".replace("__", "_")
+
+                # trim tool name to at most 60 characters
+                tool_name = tool_name[:60]
+
+                # Get description
+                description = operation.get("description", operation.get("summary"))
+
+                # Extract parameters
+                parameters = operation.get("parameters", [])
+                path_params = [p for p in parameters if p.get("in") == "path"]
+                query_params = [p for p in parameters if p.get("in") == "query"]
+
+                properties, required = self._extract_parameters(
+                    path_params, query_params
+                )
+
+                # Create input schema
+                input_schema = {
+                    "type": "object",
+                    "properties": properties,
+                    "additionalProperties": False,
+                }
+
+                if required:
+                    input_schema["required"] = required
+
+                # Create tool
+                tool = types.Tool(
+                    name=tool_name,
+                    description=description,
+                    inputSchema=input_schema,
+                    annotations=types.ToolAnnotations(
+                        title=description,
+                        destructiveHint=False,
+                        readOnlyHint=True,
+                        idempotentHint=False,
+                    ),
+                )
+                tools.append(tool)
+
+                # Store tool metadata for call_tool function
+                self.tools.append(
+                    {
+                        "name": tool_name,
+                        "method": method.upper(),
+                        "path": path,
+                        "path_params": [p["name"] for p in path_params],
+                        "query_params": [p["name"] for p in query_params],
+                    }
+                )
+
+        return tools
+
+    def call_tool(
+        self, name: str, arguments: dict[str, Any]
+    ) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
+        """
+        Execute a tool call by making the appropriate API request.
+
+        Args:
+            name: Tool name to execute
+            arguments: Arguments for the tool
+
+        Returns:
+            List of TextContent with the API response
+        """
+        # Find the tool metadata
+        tool_info = None
+        for tool in self.tools:
+            if tool["name"] == name:
+                tool_info = tool
+                break
+
+        if not tool_info:
+            raise ValueError(f"Unknown tool: {name}")
+
+        # Build the URL
+        url_path = tool_info["path"]
+
+        # Replace path parameters
+        for param_name in tool_info["path_params"]:
+            if param_name not in arguments:
+                raise ValueError(f"Missing required path parameter: {param_name}")
+            url_path = url_path.replace(f"{{{param_name}}}", str(arguments[param_name]))
+
+        # Build full URL
+        full_url = urljoin(self.base_url, url_path.lstrip("/"))
+
+        # Build path parameters
+        path_params = {}
+        for param_name in tool_info["path_params"]:
+            if param_name in arguments:
+                path_params[param_name] = arguments[param_name]
+
+        try:
+            if tool_info["method"] == "GET":
+                data = HTTPClient.get(full_url)
+            elif tool_info["method"] == "POST":
+                data = HTTPClient.post(full_url)
+            else:
+                # unsupported method, raise an error
+                raise ValueError(f"Unsupported method: {tool_info['method']}")
+
+            result_text = json.dumps(data, indent=2)
+            return [types.TextContent(type="text", text=result_text)]
+
+        except requests.RequestException as e:
+            error_message = f"API request failed: {e}"
+            if hasattr(e, "response") and e.response is not None:
+                error_message += f"\nStatus Code: {e.response.status_code}"
+                error_message += f"\nResponse: {e.response.text}"
+
+            return [types.TextContent(type="text", text=error_message)]
+
+
+def create_mcp_tools_from_openapi(
+    openapi_url: str,
+) -> tuple[OpenAPIToMCPGenerator, list[types.Tool]]:
+    """
+    Main function to create MCP tools from an OpenAPI specification.
+
+    Args:
+        openapi_url: URL to the OpenAPI JSON specification
+
+    Returns:
+        Tuple of (generator_instance, list_of_tools)
+    """
+    generator = OpenAPIToMCPGenerator(openapi_url)
+    tools = generator.list_tools()
+    return generator, tools

pdbe_mcp_server/config.yaml

@@ -0,0 +1,8 @@
+api:
+  openapi_url: "https://www.ebi.ac.uk/pdbe/api/v2/openapi.json"
+  base_url: "https://www.ebi.ac.uk/pdbe/api/v2/"
+graph:
+  schema_url: "https://www.ebi.ac.uk/pdbe/static/files/graph_schema.json"
+search:
+  schema_url: "https://www.ebi.ac.uk/pdbe/static/files/search_schema.json"
+  search_api: "https://www.ebi.ac.uk/pdbe/search/pdb/select?wt=json"

pdbe_mcp_server/graph_tools.py

@@ -0,0 +1,224 @@
+from typing import Any
+
+import mcp.types as types
+from omegaconf import DictConfig
+
+from pdbe_mcp_server import get_config
+from pdbe_mcp_server.utils import HTMLStripper, HTTPClient
+
+conf: DictConfig = get_config()
+
+
+class GraphTools:
+    """
+    A class to handle PDBe graph-related operations.
+    """
+
+    def __init__(self) -> None:
+        """
+        Initialize the GraphTools object, load the graph schema, and prepare node and edge lists.
+        """
+        self.graph_schema: dict[str, Any] = self._get_graph_schema()
+        self.node_dict: dict[Any, str] = {}
+        self.nodes: list[dict[str, Any]] = self.get_nodes()
+        self.edges: list[dict[str, Any]] = self.get_edges()
+
+    def get_pdbe_graph_nodes_tool(self) -> types.Tool:
+        return types.Tool(
+            name="pdbe_graph_nodes",
+            description="""
+    Retrieves metadata about all node types (also known as "labels") defined in the PDBe (PDBe-KB) graph database schema.
+    This tool can be used to understand the different types of entities represented in the PDBe graph database, along with
+    their properties and descriptions and then can be used to explore the graph more effectively by writing Cypher queries.
+    This tool returns detailed information about each node label in the graph database. For every node label, it includes:
+    - The label name (e.g., 'ValAngleOutlier', 'Antibody', 'Atom')
+    - A human-readable description of the node type
+    - A list of properties/parameters associated with this node type
+    - For each property: the name and a brief description
+
+    Expected Output Format (text):
+    Label: ValAngleOutlier
+    Description: Bond angle outliers based on wwPDB validation data.
+    Properties:
+      - ATOM0/1/2/3: Names of atoms involved in the angle which is an outlier.
+      - MEAN: The ideal value of the bond angle.
+      - OBS: The observed value of the bond angle.
+
+    (Additional node labels follow the same format...)
+    """,
+            inputSchema={
+                "type": "object",
+                "properties": {},
+                "additionalProperties": False,
+            },
+            annotations=types.ToolAnnotations(
+                title="Get PDBe Graph Nodes",
+                destructiveHint=False,
+                readOnlyHint=True,
+                idempotentHint=True,
+            ),
+        )
+
+    def get_pdbe_graph_edges_tool(self) -> types.Tool:
+        return types.Tool(
+            name="pdbe_graph_edges",
+            description="""
+    Retrieves metadata about all relationship types (edges) defined in the PDBe (PDBe-KB) graph database schema.
+    This tool can be used to understand the different types of relationships represented in the PDBe graph database, along with
+    their start and end nodes, properties and descriptions and then can be used to explore the graph more effectively by writing Cypher queries.
+    This tool returns detailed information about each relationship (edge) in the graph. For every relationship type, it includes:
+    - The relationship label (e.g., 'HAS_OUTLIER', 'CONNECTS_TO')
+    - A human-readable description of the relationship
+    - The 'from' node label and 'to' node label, defining the direction and connectivity
+    - A list of properties associated with the relationship
+    - For each property: the name and a brief description
+
+    Expected Output Format (text):
+    Label: HAS_OUTLIER
+    Description: Indicates a structure has validation outliers
+    From: Structure
+    To: ValAngleOutlier
+    Properties:
+      - since: The date when the outlier was detected
+      - severity: The severity level of the outlier
+
+    (Additional relationship types follow the same format...)
+    """,
+            inputSchema={
+                "type": "object",
+                "properties": {},
+                "additionalProperties": False,
+            },
+            annotations=types.ToolAnnotations(
+                title="Get PDBe Graph Edges",
+                destructiveHint=False,
+                readOnlyHint=True,
+                idempotentHint=True,
+            ),
+        )
+
+    def _get_graph_schema(self) -> dict[str, Any]:
+        """
+        Retrieve the PDBe graph schema from the remote server and return it as a dictionary.
+        """
+        return HTTPClient.get(str(conf.graph.schema_url))
+
+    def get_nodes(self) -> list[dict[str, Any]]:
+        """
+        Get the nodes from the graph schema, clean up their descriptions and titles, and store them in a list.
+        Also populates the node_dict for quick label lookup.
+
+        Returns:
+            List of node dictionaries.
+        """
+        nodes = []
+        for node in self.graph_schema.get("nodes", []):
+            # clean up the node data
+            node["description"] = HTMLStripper.strip_tags(node.get("description", ""))
+            node["title"] = HTMLStripper.strip_tags(node.get("title", ""))
+            for prop in node.get("properties", []):
+                prop["value"] = HTMLStripper.strip_tags(prop.get("value", ""))
+            nodes.append(node)
+
+            # store the node label in a dictionary for quick access
+            self.node_dict[node.get("id")] = node["label"]
+
+        return nodes
+
+    def get_edges(self) -> list[dict[str, Any]]:
+        """
+        Get the edges from the graph schema, clean up their descriptions and titles, and store them in a list.
+
+        Returns:
+            List of edge dictionaries.
+        """
+        edges = []
+        for edge in self.graph_schema.get("edges", []):
+            # clean up the edge data
+            edge["description"] = HTMLStripper.strip_tags(edge.get("description", ""))
+            edge["title"] = HTMLStripper.strip_tags(edge.get("title", ""))
+            for prop in edge.get("properties", []):
+                prop["value"] = HTMLStripper.strip_tags(prop.get("value", ""))
+            edges.append(edge)
+
+        return edges
+
+    def format_nodes(self) -> str:
+        """
+        Format the nodes as a string for LLM or human-readable output.
+
+        Returns:
+            A formatted string listing all nodes and their properties.
+        """
+        return "\n\n".join(
+            f"Label: {node['label']}\nDescription: {node.get('description', '')}\n"
+            + (
+                "Properties:\n"
+                + "\n".join(
+                    f"  - {prop.get('name', '')}: {prop.get('value', '')}"
+                    for prop in node.get("properties", [])
+                )
+                if node.get("properties")
+                else "Properties: None"
+            )
+            for node in self.nodes
+        )
+
+    def format_edges(self) -> str:
+        """
+        Format the edges as a string for LLM or human-readable output.
+
+        Returns:
+            A formatted string listing all edges and their properties.
+        """
+        return "\n\n".join(
+            f"Label: {edge['label']}\n"
+            f"Description: {edge.get('description', '')}\n"
+            f"From: {self.node_dict.get(edge.get('from'), edge.get('from'))}\n"
+            f"To: {self.node_dict.get(edge.get('to'), edge.get('to'))}\n"
+            + (
+                "Properties:\n"
+                + "\n".join(
+                    f"  - {prop.get('name', '')}: {prop.get('value', '')}"
+                    for prop in edge.get("properties", [])
+                )
+                if edge.get("properties")
+                else "Properties: None"
+            )
+            for edge in self.edges
+        )
+
+    def get_node_by_label(self, node_label: str) -> str | None:
+        """
+        Get a formatted string for a node by its label.
+
+        Args:
+            node_label: The label of the node to search for.
+
+        Returns:
+            A formatted string with node information, or None if not found.
+        """
+        for node in self.nodes:
+            if node.get("label") == node_label:
+                # format the node
+                return f"""
+                Label: {node_label}
+                Description: {node.get("description")}
+                """
+
+        return None
+
+    def get_edge_by_label(self, edge_label: str) -> dict[str, Any] | None:
+        """
+        Get an edge dictionary by its label.
+
+        Args:
+            edge_label: The label of the edge to search for.
+
+        Returns:
+            The edge dictionary if found, otherwise None.
+        """
+        for edge in self.edges:
+            if edge.get("label") == edge_label:
+                return edge
+        return None

pdbe_mcp_server/helper.py

@@ -0,0 +1,45 @@
+from typing import Any
+
+
+def format_graph_info(graph_data: dict[str, Any]) -> str:
+    output = []
+
+    # Format Nodes
+    output.append("Nodes\n" + "=" * 5 + "\n")
+
+    for node in graph_data.get("nodes", []):
+        output.append(f"Label: {node['label']}")
+        output.append(f"Description: {node['description']}")
+        output.append("Properties:")
+
+        if node.get("properties"):
+            for prop in node["properties"]:
+                name = prop.get("name", "<No name>")
+                value = prop.get("value", "<No description>")
+                output.append(f"  - {name}: {value}")
+        else:
+            output.append("  None")
+
+        output.append("")  # Blank line between nodes
+
+    # Format Edges (Relationships)
+    output.append("Relationships\n" + "=" * 12 + "\n")
+
+    for edge in graph_data.get("edges", []):
+        output.append(f"Label: {edge['label']}")
+        output.append(f"Description: {edge['description']}")
+        output.append(f"From Node ID: {edge['from']}")
+        output.append(f"To Node ID: {edge['to']}")
+        output.append("Properties:")
+
+        if edge.get("properties"):
+            for prop in edge["properties"]:
+                name = prop.get("name", "<No name>")
+                value = prop.get("value", "<No description>")
+                output.append(f"  - {name}: {value}")
+        else:
+            output.append("  None")
+
+        output.append("")  # Blank line between edges
+
+    return "\n".join(output)

pdbe_mcp_server/py.typed

@@ -0,0 +1,2 @@
+# Marker file for PEP 561.
+# This package provides inline type annotations.