|
| 1 | +"""MCP server configuration parsing and MCPClient factory. |
| 2 | +
|
| 3 | +This module handles parsing MCP server configurations from dictionaries or JSON files |
| 4 | +and creating MCPClient instances with the appropriate transport callables. |
| 5 | +
|
| 6 | +Supported transport types: |
| 7 | +- stdio: Local subprocess via stdin/stdout (auto-detected when 'command' is present) |
| 8 | +- sse: Server-Sent Events over HTTP (auto-detected when 'url' is present without explicit transport) |
| 9 | +- streamable-http: Streamable HTTP transport |
| 10 | +""" |
| 11 | + |
| 12 | +import json |
| 13 | +import logging |
| 14 | +import re |
| 15 | +from pathlib import Path |
| 16 | +from typing import Any |
| 17 | + |
| 18 | +import jsonschema |
| 19 | +from jsonschema import ValidationError |
| 20 | +from mcp import StdioServerParameters |
| 21 | +from mcp.client.sse import sse_client |
| 22 | +from mcp.client.stdio import stdio_client |
| 23 | +from mcp.client.streamable_http import streamable_http_client |
| 24 | + |
| 25 | +from ..tools.mcp.mcp_client import MCPClient, ToolFilters |
| 26 | + |
| 27 | +logger = logging.getLogger(__name__) |
| 28 | + |
| 29 | +_SCHEMA_PATH = Path(__file__).parent / "mcp_server_config.schema.json" |
| 30 | +with open(_SCHEMA_PATH) as _f: |
| 31 | + MCP_SERVER_CONFIG_SCHEMA: dict[str, Any] = json.load(_f) |
| 32 | + |
| 33 | +_SERVER_VALIDATOR = jsonschema.Draft7Validator(MCP_SERVER_CONFIG_SCHEMA) |
| 34 | + |
| 35 | + |
| 36 | +def _parse_tool_filters(config: dict[str, Any] | None) -> ToolFilters | None: |
| 37 | + """Parse a tool filter configuration into a ToolFilters instance. |
| 38 | +
|
| 39 | + All filter strings are compiled as regex patterns. Exact-match strings like ``"^echo$"`` |
| 40 | + work correctly as regex since they match themselves. |
| 41 | +
|
| 42 | + Args: |
| 43 | + config: Tool filter configuration dict with 'allowed' and/or 'rejected' lists, |
| 44 | + or None. |
| 45 | +
|
| 46 | + Returns: |
| 47 | + A ToolFilters instance, or None if config is None or empty. |
| 48 | +
|
| 49 | + Raises: |
| 50 | + ValueError: If a filter string is not a valid regex pattern. |
| 51 | + """ |
| 52 | + if not config: |
| 53 | + return None |
| 54 | + |
| 55 | + result: ToolFilters = {} |
| 56 | + |
| 57 | + if "allowed" in config: |
| 58 | + allowed: list[re.Pattern[str]] = [] |
| 59 | + for pattern_str in config["allowed"]: |
| 60 | + try: |
| 61 | + allowed.append(re.compile(pattern_str)) |
| 62 | + except re.error as e: |
| 63 | + raise ValueError(f"invalid regex pattern in tool_filters.allowed: '{pattern_str}': {e}") from e |
| 64 | + result["allowed"] = allowed |
| 65 | + |
| 66 | + if "rejected" in config: |
| 67 | + rejected: list[re.Pattern[str]] = [] |
| 68 | + for pattern_str in config["rejected"]: |
| 69 | + try: |
| 70 | + rejected.append(re.compile(pattern_str)) |
| 71 | + except re.error as e: |
| 72 | + raise ValueError(f"invalid regex pattern in tool_filters.rejected: '{pattern_str}': {e}") from e |
| 73 | + result["rejected"] = rejected |
| 74 | + |
| 75 | + return result if result else None |
| 76 | + |
| 77 | + |
| 78 | +def _create_mcp_client_from_config(server_name: str, config: dict[str, Any]) -> MCPClient: |
| 79 | + """Create an MCPClient instance from a server configuration dictionary. |
| 80 | +
|
| 81 | + Transport type is auto-detected based on the presence of 'command' (stdio) or 'url' (sse), |
| 82 | + unless explicitly specified via the 'transport' field. |
| 83 | +
|
| 84 | + Args: |
| 85 | + server_name: Name of the server (used in error messages). |
| 86 | + config: Server configuration dictionary. |
| 87 | +
|
| 88 | + Returns: |
| 89 | + A configured MCPClient instance. |
| 90 | +
|
| 91 | + Raises: |
| 92 | + ValueError: If the configuration is invalid or missing required fields. |
| 93 | + """ |
| 94 | + # Validate against schema |
| 95 | + try: |
| 96 | + _SERVER_VALIDATOR.validate(config) |
| 97 | + except ValidationError as e: |
| 98 | + error_path = " -> ".join(str(p) for p in e.absolute_path) if e.absolute_path else "root" |
| 99 | + raise ValueError(f"server '{server_name}' configuration validation error at {error_path}: {e.message}") from e |
| 100 | + |
| 101 | + # Determine transport type |
| 102 | + transport = config.get("transport") |
| 103 | + command = config.get("command") |
| 104 | + url = config.get("url") |
| 105 | + |
| 106 | + if transport is None: |
| 107 | + if command: |
| 108 | + transport = "stdio" |
| 109 | + elif url: |
| 110 | + transport = "sse" |
| 111 | + else: |
| 112 | + raise ValueError( |
| 113 | + f"server '{server_name}' must specify either 'command' (for stdio) or 'url' (for sse/http)" |
| 114 | + ) |
| 115 | + |
| 116 | + # Extract common MCPClient parameters |
| 117 | + prefix = config.get("prefix") |
| 118 | + startup_timeout = config.get("startup_timeout", 30) |
| 119 | + tool_filters = _parse_tool_filters(config.get("tool_filters")) |
| 120 | + |
| 121 | + # Build transport callable based on type |
| 122 | + if transport == "stdio": |
| 123 | + |
| 124 | + def _stdio_transport() -> Any: |
| 125 | + params = StdioServerParameters( |
| 126 | + command=config["command"], |
| 127 | + args=config.get("args", []), |
| 128 | + env=config.get("env"), |
| 129 | + cwd=config.get("cwd"), |
| 130 | + ) |
| 131 | + return stdio_client(params) |
| 132 | + |
| 133 | + transport_callable = _stdio_transport |
| 134 | + elif transport == "sse": |
| 135 | + if not url: |
| 136 | + raise ValueError(f"server '{server_name}': 'url' is required for sse transport") |
| 137 | + headers = config.get("headers") |
| 138 | + |
| 139 | + def _sse_transport() -> Any: |
| 140 | + return sse_client(url=url, headers=headers) |
| 141 | + |
| 142 | + transport_callable = _sse_transport |
| 143 | + elif transport == "streamable-http": |
| 144 | + if not url: |
| 145 | + raise ValueError(f"server '{server_name}': 'url' is required for streamable-http transport") |
| 146 | + headers = config.get("headers") |
| 147 | + |
| 148 | + def _streamable_http_transport() -> Any: |
| 149 | + return streamable_http_client(url=url, headers=headers) |
| 150 | + |
| 151 | + transport_callable = _streamable_http_transport |
| 152 | + else: |
| 153 | + raise ValueError(f"server '{server_name}': unsupported transport type '{transport}'") |
| 154 | + |
| 155 | + logger.debug( |
| 156 | + "server_name=<%s>, transport=<%s> | creating MCP client from config", |
| 157 | + server_name, |
| 158 | + transport, |
| 159 | + ) |
| 160 | + |
| 161 | + return MCPClient( |
| 162 | + transport_callable, |
| 163 | + startup_timeout=startup_timeout, |
| 164 | + tool_filters=tool_filters, |
| 165 | + prefix=prefix, |
| 166 | + ) |
| 167 | + |
| 168 | + |
| 169 | +def load_mcp_clients_from_config(config: str | dict[str, Any]) -> dict[str, MCPClient]: |
| 170 | + """Load MCP client instances from a configuration file or dictionary. |
| 171 | +
|
| 172 | + Expects the standard ``mcpServers`` wrapper format used by Claude Desktop, VS Code, etc:: |
| 173 | +
|
| 174 | + { |
| 175 | + "mcpServers": { |
| 176 | + "server_name": { "command": "...", ... } |
| 177 | + } |
| 178 | + } |
| 179 | +
|
| 180 | + Args: |
| 181 | + config: Either a file path (with optional file:// prefix) to a JSON config file, |
| 182 | + or a dictionary with a ``mcpServers`` key mapping server names to configs. |
| 183 | +
|
| 184 | + Returns: |
| 185 | + A dictionary mapping server names to MCPClient instances. |
| 186 | +
|
| 187 | + Raises: |
| 188 | + FileNotFoundError: If the config file does not exist. |
| 189 | + json.JSONDecodeError: If the config file contains invalid JSON. |
| 190 | + ValueError: If the config format is invalid or a server config is invalid. |
| 191 | + """ |
| 192 | + if isinstance(config, str): |
| 193 | + file_path = config |
| 194 | + if file_path.startswith("file://"): |
| 195 | + file_path = file_path[7:] |
| 196 | + |
| 197 | + config_path = Path(file_path) |
| 198 | + if not config_path.exists(): |
| 199 | + raise FileNotFoundError(f"MCP configuration file not found: {file_path}") |
| 200 | + |
| 201 | + with open(config_path) as f: |
| 202 | + config_dict: dict[str, Any] = json.load(f) |
| 203 | + elif isinstance(config, dict): |
| 204 | + config_dict = config |
| 205 | + else: |
| 206 | + raise ValueError("Config must be a file path string or dictionary") |
| 207 | + |
| 208 | + if "mcpServers" not in config_dict or not isinstance(config_dict["mcpServers"], dict): |
| 209 | + raise ValueError("Config must contain an 'mcpServers' key with a dictionary of server configurations") |
| 210 | + |
| 211 | + servers = config_dict["mcpServers"] |
| 212 | + clients: dict[str, MCPClient] = {} |
| 213 | + for server_name, server_config in servers.items(): |
| 214 | + clients[server_name] = _create_mcp_client_from_config(server_name, server_config) |
| 215 | + |
| 216 | + logger.debug("loaded_servers=<%d> | MCP clients created from config", len(clients)) |
| 217 | + |
| 218 | + return clients |
0 commit comments