fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/services/compute/executors/mcp.py

@@ -0,0 +1,454 @@
+"""Model Context Protocol (MCP) Client Bridge & Tool Adapter for FleetMesh Compute.
+
+Provides:
+- `McpToolSpec`: Schema descriptor for an MCP tool (`name`, `description`, `inputSchema`).
+- `McpResourceSpec`: Schema descriptor for an MCP resource (`uri`, `name`, `description`, `mimeType`).
+- `McpServerConfig`: Connection & capability configuration for an MCP server (`builtin_mesh`,
+  `http_jsonrpc`, or `http_sse`).
+- `McpToolAdapter`: Adapts any MCP tool into FleetMesh's `AgentToolProtocol` so `AgentExecutor`
+  can invoke MCP tools inside the ReAct reasoning loop with fuel accounting.
+- `McpClientBridge`: Executes JSON-RPC 2.0 `tools/list`, `tools/call`, `resources/list`, and
+  `resources/read` against remote HTTP MCP endpoints or in-process FleetMesh/MeshTube handlers.
+"""
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Callable, Mapping, Optional, Sequence
+
+from node.transport import netfetch
+from .agent import AgentExecutionContext, AgentToolResult
+
+
+@dataclass(frozen=True)
+class McpToolSpec:
+    """Descriptor for a tool exposed by an MCP server."""
+
+    name: str
+    description: str
+    input_schema: Mapping[str, Any] = field(default_factory=lambda: {'type': 'object', 'properties': {}})
+    server_id: str = ''
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            'name': self.name,
+            'description': self.description,
+            'inputSchema': dict(self.input_schema),
+            'server_id': self.server_id,
+        }
+
+    @classmethod
+    def from_mapping(cls, data: Mapping[str, Any], server_id: str = '') -> McpToolSpec:
+        schema = data.get('inputSchema') or data.get('input_schema') or data.get('parameters') or {
+            'type': 'object',
+            'properties': {},
+        }
+        return cls(
+            name=str(data.get('name') or '').strip(),
+            description=str(data.get('description') or '').strip(),
+            input_schema=dict(schema) if isinstance(schema, Mapping) else {'type': 'object', 'properties': {}},
+            server_id=str(data.get('server_id') or server_id).strip(),
+        )
+
+
+@dataclass(frozen=True)
+class McpResourceSpec:
+    """Descriptor for a context resource exposed by an MCP server."""
+
+    uri: str
+    name: str
+    description: str = ''
+    mime_type: str = 'application/json'
+    server_id: str = ''
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            'uri': self.uri,
+            'name': self.name,
+            'description': self.description,
+            'mimeType': self.mime_type,
+            'server_id': self.server_id,
+        }
+
+    @classmethod
+    def from_mapping(cls, data: Mapping[str, Any], server_id: str = '') -> McpResourceSpec:
+        return cls(
+            uri=str(data.get('uri') or '').strip(),
+            name=str(data.get('name') or '').strip(),
+            description=str(data.get('description') or '').strip(),
+            mime_type=str(data.get('mimeType') or data.get('mime_type') or 'application/json').strip(),
+            server_id=str(data.get('server_id') or server_id).strip(),
+        )
+
+
+@dataclass
+class McpServerConfig:
+    """Configuration and discovered capabilities for an MCP server."""
+
+    server_id: str
+    name: str
+    transport: str = 'http_jsonrpc'  # 'builtin_mesh' | 'http_jsonrpc' | 'http_sse'
+    endpoint: str = ''
+    description: str = ''
+    auth_header: str = 'Authorization'
+    auth_token: str = ''
+    enabled: bool = True
+    tools: tuple[McpToolSpec, ...] = ()
+    resources: tuple[McpResourceSpec, ...] = ()
+    status: str = 'connected'
+    last_synced_at: int = 0
+
+    def build_headers(self) -> dict[str, str]:
+        headers: dict[str, str] = {
+            'Content-Type': 'application/json',
+            'Accept': 'application/json, text/event-stream',
+        }
+        tok = self.auth_token.strip()
+        if tok:
+            hdr = self.auth_header.strip() or 'Authorization'
+            if hdr.lower() == 'authorization' and not tok.lower().startswith(('bearer ', 'basic ', 'cashu')):
+                headers[hdr] = f'Bearer {tok}'
+            else:
+                headers[hdr] = tok
+        return headers
+
+    def to_dict(self, *, redact_secrets: bool = True) -> dict[str, Any]:
+        tok = self.auth_token.strip()
+        masked_tok = f'{tok[:6]}...{tok[-4:]}' if len(tok) > 10 else ('***' if tok else '')
+        return {
+            'server_id': self.server_id,
+            'name': self.name,
+            'transport': self.transport,
+            'endpoint': self.endpoint,
+            'description': self.description,
+            'auth_header': self.auth_header,
+            'has_auth_token': bool(tok),
+            'auth_token_preview': masked_tok if redact_secrets else tok,
+            'enabled': self.enabled,
+            'tools': [t.to_dict() for t in self.tools],
+            'resources': [r.to_dict() for r in self.resources],
+            'status': self.status,
+            'last_synced_at': self.last_synced_at,
+        }
+
+
+class McpToolAdapter:
+    """Wraps an MCP tool so it satisfies `AgentToolProtocol` inside `AgentExecutor`."""
+
+    def __init__(
+        self,
+        spec: McpToolSpec,
+        bridge: McpClientBridge,
+        *,
+        qualify_name: bool = False,
+    ) -> None:
+        self.spec = spec
+        self.bridge = bridge
+        self.name: str = f"mcp_{spec.server_id}_{spec.name}" if (qualify_name and spec.server_id) else spec.name
+        self.description: str = f"[MCP:{spec.server_id or 'server'}] {spec.description}"
+        self.parameters_schema: Mapping[str, Any] = spec.input_schema
+
+    def execute(self, params: Any, context: AgentExecutionContext) -> AgentToolResult:
+        arguments: Mapping[str, Any]
+        if isinstance(params, Mapping):
+            arguments = dict(params)
+        elif isinstance(params, str):
+            s = params.strip()
+            if s.startswith('{'):
+                try:
+                    arguments = json.loads(s)
+                except Exception:
+                    arguments = {'query': s}
+            else:
+                arguments = {'query': s}
+        else:
+            arguments = {}
+
+        res = self.bridge.call_tool(self.spec.server_id, self.spec.name, arguments)
+        if not res.get('ok', False):
+            return {
+                'error': str(res.get('error') or 'MCP tool call failed'),
+                'fuel_consumed': int(res.get('fuel_consumed', 75)),
+            }
+        return {
+            'output': res.get('output'),
+            'fuel_consumed': int(res.get('fuel_consumed', 120)),
+        }
+
+
+class McpClientBridge:
+    """Manages local & remote Model Context Protocol (MCP) servers and dispatches tool/resource calls."""
+
+    def __init__(self, timeout_seconds: float = 15.0) -> None:
+        self.timeout_seconds = timeout_seconds
+        self._servers: dict[str, McpServerConfig] = {}
+        self._local_tool_handlers: dict[tuple[str, str], Callable[[Mapping[str, Any]], Any]] = {}
+        self._local_resource_handlers: dict[tuple[str, str], Callable[[str], Any]] = {}
+
+    def register_server(self, server: McpServerConfig) -> McpServerConfig:
+        self._servers[server.server_id] = server
+        return server
+
+    def remove_server(self, server_id: str) -> bool:
+        return self._servers.pop(server_id, None) is not None
+
+    def get_server(self, server_id: str) -> Optional[McpServerConfig]:
+        return self._servers.get(server_id)
+
+    def list_servers(self, *, enabled_only: bool = False) -> list[McpServerConfig]:
+        items = list(self._servers.values())
+        if enabled_only:
+            items = [s for s in items if s.enabled]
+        return items
+
+    def register_local_tool_handler(
+        self,
+        server_id: str,
+        tool_name: str,
+        handler: Callable[[Mapping[str, Any]], Any],
+    ) -> None:
+        self._local_tool_handlers[(server_id, tool_name)] = handler
+
+    def register_local_resource_handler(
+        self,
+        server_id: str,
+        uri: str,
+        handler: Callable[[str], Any],
+    ) -> None:
+        self._local_resource_handlers[(server_id, uri)] = handler
+
+    def _jsonrpc_request(
+        self,
+        server: McpServerConfig,
+        method: str,
+        params: Optional[Mapping[str, Any]] = None,
+    ) -> dict[str, Any]:
+        if not server.endpoint or not server.endpoint.startswith(('http://', 'https://')):
+            raise ValueError(f"MCP server '{server.server_id}' has no valid HTTP/HTTPS endpoint")
+        req_id = f"mcp-{uuid.uuid4().hex[:8]}"
+        rpc_body = {
+            'jsonrpc': '2.0',
+            'id': req_id,
+            'method': method,
+            'params': dict(params or {}),
+        }
+        raw_bytes, _ = netfetch.fetch(
+            server.endpoint,
+            max_bytes=4 * 1024 * 1024,
+            timeout=self.timeout_seconds,
+            method='POST',
+            data=json.dumps(rpc_body).encode('utf-8'),
+            headers=server.build_headers(),
+            allow_private=True,
+        )
+        text = raw_bytes.decode('utf-8', errors='replace').strip()
+        # Handle SSE-wrapped JSON-RPC responses (`data: {...}`)
+        if text.startswith('event:') or text.startswith('data:'):
+            for line in text.splitlines():
+                line_s = line.strip()
+                if line_s.startswith('data:'):
+                    candidate = line_s[5:].strip()
+                    if candidate.startswith('{'):
+                        text = candidate
+                        break
+        parsed = json.loads(text)
+        if not isinstance(parsed, dict):
+            raise ValueError('MCP server returned non-object JSON-RPC payload')
+        if 'error' in parsed and parsed['error']:
+            err_obj = parsed['error']
+            msg = err_obj.get('message') if isinstance(err_obj, Mapping) else str(err_obj)
+            raise ValueError(f"MCP JSON-RPC error: {msg}")
+        res = parsed.get('result')
+        return dict(res) if isinstance(res, Mapping) else {'value': res}
+
+    def sync_server_capabilities(self, server_id: str) -> McpServerConfig:
+        """Discover `tools/list` and `resources/list` from an MCP server."""
+        server = self._servers.get(server_id)
+        if server is None:
+            raise KeyError(f"Unknown MCP server: {server_id}")
+        now_ts = int(time.time())
+        if server.transport == 'builtin_mesh':
+            server.status = 'connected'
+            server.last_synced_at = now_ts
+            return server
+
+        try:
+            tools_res = self._jsonrpc_request(server, 'tools/list', {})
+            raw_tools = tools_res.get('tools') or []
+            discovered_tools = tuple(
+                McpToolSpec.from_mapping(t, server_id=server.server_id)
+                for t in raw_tools
+                if isinstance(t, Mapping) and t.get('name')
+            )
+            resources_res: Mapping[str, Any] = {}
+            try:
+                resources_res = self._jsonrpc_request(server, 'resources/list', {})
+            except Exception:
+                resources_res = {}
+            raw_resources = resources_res.get('resources') or []
+            discovered_resources = tuple(
+                McpResourceSpec.from_mapping(r, server_id=server.server_id)
+                for r in raw_resources
+                if isinstance(r, Mapping) and r.get('uri')
+            )
+            if discovered_tools:
+                server.tools = discovered_tools
+            if discovered_resources:
+                server.resources = discovered_resources
+            server.status = 'connected'
+            server.last_synced_at = now_ts
+        except Exception as exc:
+            server.status = f'error: {exc}'
+            server.last_synced_at = now_ts
+        return server
+
+    def call_tool(
+        self,
+        server_id: str,
+        tool_name: str,
+        arguments: Optional[Mapping[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """Invoke a tool on a registered MCP server (local handler or remote JSON-RPC `tools/call`)."""
+        t0 = time.time()
+        args = dict(arguments or {})
+        server = self._servers.get(server_id)
+        if server is None:
+            # Search across enabled servers if server_id was omitted or generic
+            for candidate in self._servers.values():
+                if candidate.enabled and any(t.name == tool_name for t in candidate.tools):
+                    server = candidate
+                    server_id = candidate.server_id
+                    break
+        if server is None:
+            return {
+                'ok': False,
+                'server_id': server_id,
+                'tool_name': tool_name,
+                'error': f"MCP server '{server_id}' not found",
+                'duration_ms': int((time.time() - t0) * 1000),
+                'fuel_consumed': 25,
+            }
+        if not server.enabled:
+            return {
+                'ok': False,
+                'server_id': server_id,
+                'tool_name': tool_name,
+                'error': f"MCP server '{server.name}' is currently disabled",
+                'duration_ms': int((time.time() - t0) * 1000),
+                'fuel_consumed': 10,
+            }
+
+        local_fn = self._local_tool_handlers.get((server_id, tool_name))
+        if local_fn is not None:
+            try:
+                out = local_fn(args)
+                dur_ms = max(1, int((time.time() - t0) * 1000))
+                return {
+                    'ok': True,
+                    'server_id': server_id,
+                    'server_name': server.name,
+                    'tool_name': tool_name,
+                    'arguments': args,
+                    'output': out,
+                    'duration_ms': dur_ms,
+                    'fuel_consumed': 120,
+                }
+            except Exception as exc:
+                dur_ms = max(1, int((time.time() - t0) * 1000))
+                return {
+                    'ok': False,
+                    'server_id': server_id,
+                    'server_name': server.name,
+                    'tool_name': tool_name,
+                    'arguments': args,
+                    'error': str(exc),
+                    'duration_ms': dur_ms,
+                    'fuel_consumed': 40,
+                }
+
+        try:
+            rpc_res = self._jsonrpc_request(
+                server,
+                'tools/call',
+                {'name': tool_name, 'arguments': args},
+            )
+            content_list = rpc_res.get('content')
+            if isinstance(content_list, Sequence) and not isinstance(content_list, (str, bytes)):
+                texts = []
+                for item in content_list:
+                    if isinstance(item, Mapping):
+                        if item.get('type') == 'text' and 'text' in item:
+                            texts.append(str(item['text']))
+                        else:
+                            texts.append(json.dumps(dict(item)))
+                output_val: Any = '\n'.join(texts) if len(texts) == 1 else (texts or rpc_res)
+            else:
+                output_val = rpc_res
+            dur_ms = max(1, int((time.time() - t0) * 1000))
+            return {
+                'ok': True,
+                'server_id': server_id,
+                'server_name': server.name,
+                'tool_name': tool_name,
+                'arguments': args,
+                'output': output_val,
+                'duration_ms': dur_ms,
+                'fuel_consumed': 180,
+            }
+        except Exception as exc:
+            dur_ms = max(1, int((time.time() - t0) * 1000))
+            return {
+                'ok': False,
+                'server_id': server_id,
+                'server_name': server.name,
+                'tool_name': tool_name,
+                'arguments': args,
+                'error': str(exc),
+                'duration_ms': dur_ms,
+                'fuel_consumed': 50,
+            }
+
+    def read_resource(self, server_id: str, uri: str) -> dict[str, Any]:
+        """Read an MCP resource by URI from a local or remote MCP server."""
+        server = self._servers.get(server_id)
+        if server is None:
+            for candidate in self._servers.values():
+                if candidate.enabled and any(r.uri == uri for r in candidate.resources):
+                    server = candidate
+                    server_id = candidate.server_id
+                    break
+        if server is None:
+            return {'ok': False, 'error': f"MCP server '{server_id}' not found", 'uri': uri}
+
+        local_fn = self._local_resource_handlers.get((server_id, uri))
+        if local_fn is not None:
+            try:
+                return {
+                    'ok': True,
+                    'server_id': server_id,
+                    'uri': uri,
+                    'contents': local_fn(uri),
+                }
+            except Exception as exc:
+                return {'ok': False, 'server_id': server_id, 'uri': uri, 'error': str(exc)}
+
+        try:
+            res = self._jsonrpc_request(server, 'resources/read', {'uri': uri})
+            return {'ok': True, 'server_id': server_id, 'uri': uri, 'contents': res.get('contents', res)}
+        except Exception as exc:
+            return {'ok': False, 'server_id': server_id, 'uri': uri, 'error': str(exc)}
+
+    def as_agent_tools(self, *, server_ids: Optional[Sequence[str]] = None) -> list[McpToolAdapter]:
+        """Return `McpToolAdapter` instances for all enabled MCP servers (or the specified subset)."""
+        allowed = set(server_ids) if server_ids is not None else None
+        adapters: list[McpToolAdapter] = []
+        for srv in self._servers.values():
+            if not srv.enabled:
+                continue
+            if allowed is not None and srv.server_id not in allowed:
+                continue
+            for t_spec in srv.tools:
+                adapters.append(McpToolAdapter(t_spec, self))
+        return adapters