Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 97 additions & 7 deletions nodes/src/nodes/tool_mcp_client/IGlobal.py
Original file line number Diff line number Diff line change
Expand Up @@ -30,11 +30,16 @@
- Spawns MCP server process
- Performs MCP initialize handshake
- Discovers tools at startup via tools/list and caches them
- Re-reads the catalog on every discovery query and on every lookup miss
(rate-limited), so tools added or renamed on a running server become
callable without restarting the engine (issue #1402)
"""

from __future__ import annotations

import shlex
import threading
import time
from typing import Any, Dict, List, Optional

from ai.common.config import Config
Expand All @@ -46,6 +51,31 @@
from .mcp_streamable_http_client import McpStreamableHttpClient


# The catalog is re-read from the server on every discovery query (a new
# agent instance building its tool list, or the agent host re-querying this
# node after a miss) and on every lookup miss — but at most this often, so a
# burst of queries or repeated misses for one unknown tool (schema lookup,
# then invoke) costs the server a single tools/list.
REFRESH_MIN_INTERVAL_S = 1.0


def _monotonic() -> float:
"""Clock used for the refresh rate limit.

Indirection on purpose: tests drive this instead of patching
``time.monotonic`` on the stdlib module, which is process-wide and would
reach anything else relying on it.
"""
return time.monotonic()


class ToolUnavailableError(Exception):
"""A tool the agent asked for is not on the MCP server, even after a
catalog refresh. Distinct from a transport failure so callers can tell
"this tool does not exist" from "the server did not answer".
"""


class IGlobal(IGlobalBase):
"""Global state for mcp_client."""

Expand Down Expand Up @@ -219,26 +249,86 @@ def endGlobal(self) -> None:
# Tool cache + accessors for IInstance hooks
# ------------------------------------------------------------------
def _cache_tools(self, tools: List[McpToolDef]) -> None:
self._tools_by_original: Dict[str, McpToolDef] = {}
self._tools_by_namespaced: Dict[str, McpToolDef] = {}
"""Replace the cached catalog atomically.

Both maps are built locally and swapped in with plain attribute
assignment, so a reader iterating the previous maps never observes a
half-filled catalog.
"""
by_original: Dict[str, McpToolDef] = {}
by_namespaced: Dict[str, McpToolDef] = {}
for t in tools:
self._tools_by_original[t.name] = t
self._tools_by_namespaced[f'{self.serverName}.{t.name}'] = t
by_original[t.name] = t
by_namespaced[f'{self.serverName}.{t.name}'] = t
self._tools_by_original = by_original
self._tools_by_namespaced = by_namespaced
self._catalog_fetched_at = _monotonic()

def refresh_tools(self, *, reason: str, min_age_s: float = 0.0) -> bool:
"""Re-read tools/list from the server and swap the cache.

Returns True when the catalog was refreshed, False when there is no
connected client, the catalog is younger than ``min_age_s``, or the
server did not answer (the previous catalog is kept in that case).
Serialized so concurrent misses trigger one tools/list, not a
stampede. Emits a warning naming the tools that appeared or
disappeared, so a changed catalog is visible in the run.
"""
client = getattr(self, '_client', None)
if client is None:
return False
lock = self.__dict__.setdefault('_refresh_lock', threading.Lock())
with lock:
fetched_at = getattr(self, '_catalog_fetched_at', None)
if fetched_at is not None and min_age_s > 0 and (_monotonic() - fetched_at) < min_age_s:
return False
try:
tools = client.list_tools()
except Exception as e:
warning(f"mcp_client '{self.serverName}': tool catalog refresh ({reason}) failed: {e}")
return False
before = set((getattr(self, '_tools_by_original', None) or {}).keys())
self._cache_tools(tools)
after = set(self._tools_by_original.keys())
added, removed = sorted(after - before), sorted(before - after)
if added or removed:
warning(
f"mcp_client '{self.serverName}': tool catalog changed on refresh ({reason}); "
f'added={added} removed={removed}'
)
return True

def list_namespaced_tools(self) -> List[Dict[str, Any]]:
self.refresh_tools(reason='catalog query', min_age_s=REFRESH_MIN_INTERVAL_S)
out: List[Dict[str, Any]] = []
for namespaced, tool in (self._tools_by_namespaced or {}).items():
for namespaced, tool in (getattr(self, '_tools_by_namespaced', None) or {}).items():
out.append({'name': namespaced, 'description': tool.description, 'inputSchema': tool.inputSchema})
return out

def get_tool(self, *, server_name: str, tool_name: str) -> Optional[McpToolDef]:
if server_name != self.serverName:
return None
return (self._tools_by_original or {}).get(tool_name)
tool = (getattr(self, '_tools_by_original', None) or {}).get(tool_name)
if tool is None:
self.refresh_tools(reason=f'lookup miss for {tool_name!r}', min_age_s=REFRESH_MIN_INTERVAL_S)
# Re-read whatever the attempt returned: False also means "another
# thread refreshed inside the rate-limit window", and that refresh
# may be the one carrying this tool.
tool = (getattr(self, '_tools_by_original', None) or {}).get(tool_name)
return tool
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

def call_tool(self, *, server_name: str, tool_name: str, arguments: Dict[str, Any]) -> Dict[str, Any]:
if server_name != self.serverName:
raise Exception(f'Unknown MCP serverName {server_name!r} (this node configured as {self.serverName!r})')
if self._client is None:
if getattr(self, '_client', None) is None:
raise Exception('MCP client is not connected')
# A tool the catalog does not know is refreshed once, then refused
# loudly rather than handed to the server (whose "not found" a weak
# planner narrates around).
if self.get_tool(server_name=server_name, tool_name=tool_name) is None:
known = sorted((getattr(self, '_tools_by_original', None) or {}).keys())
raise ToolUnavailableError(
f"Tool {tool_name!r} is not available on MCP server '{self.serverName}' "
f'(catalog refreshed; known tools: {known})'
)
return self._client.call_tool(name=tool_name, arguments=arguments or {})
2 changes: 1 addition & 1 deletion nodes/src/nodes/tool_mcp_client/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Connects to an MCP server over one of three transports (STDIO (local subprocess)

This node has no pipeline lanes: it is a control-plane tool node, connected to agents via the `tools` invoke channel.

Tools are namespaced as `serverName.toolName` (e.g. `mcp.search_docs`), where `serverName` is set in configuration. Tools are discovered **once at pipeline startup** and cached; a server that adds tools later requires a pipeline restart to pick them up.
Tools are namespaced as `serverName.toolName` (e.g. `mcp.search_docs`), where `serverName` is set in configuration. Tools are discovered at pipeline startup and cached, and the cache is re-read from the server whenever an agent discovers its tools or asks for a tool the cache does not know (at most once per second), so a server that adds or renames tools while the pipeline runs is picked up without a restart. A changed catalog is reported as a pipeline warning naming the added and removed tools. A tool that is still unknown after that refresh is refused with an explicit `ToolUnavailableError` and is never sent to the server, so an agent sees a clear failure rather than a plausible-looking answer.

The implementation is pure Python standard library (`subprocess`, `urllib`, JSON-RPC 2.0), no MCP SDK dependency and no extra packages to install. Each request has a 20-second timeout.

Expand Down
20 changes: 13 additions & 7 deletions nodes/src/nodes/tool_mcp_client/mcp_stdio_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@
import json
import os
import subprocess
import threading
import time
from dataclasses import dataclass
from typing import Any, Dict, List, Optional
Expand Down Expand Up @@ -85,6 +86,10 @@ def __init__(

self._proc: subprocess.Popen[str] | None = None
self._next_id = 1
# One request in flight at a time: responses are matched by id but read
# line-by-line by whichever thread is receiving, and a foreign id is
# dropped — so two concurrent requests would starve each other.
self._request_lock = threading.Lock()

def start(self) -> None:
if self._proc is not None:
Expand Down Expand Up @@ -212,13 +217,14 @@ def _notify(self, method: str, params: Any) -> None: # noqa: ANN401
self._send(msg)

def _request(self, method: str, params: Any) -> Any: # noqa: ANN401
req_id = self._next_id
self._next_id += 1
msg: Dict[str, Any] = {'jsonrpc': '2.0', 'id': req_id, 'method': method}
if params is not None:
msg['params'] = params
self._send(msg)
return self._recv_response(req_id=req_id)
with self._request_lock:
req_id = self._next_id
self._next_id += 1
msg: Dict[str, Any] = {'jsonrpc': '2.0', 'id': req_id, 'method': method}
if params is not None:
msg['params'] = params
self._send(msg)
return self._recv_response(req_id=req_id)

def _send(self, msg: Dict[str, Any]) -> None:
proc = self._proc
Expand Down
25 changes: 23 additions & 2 deletions nodes/test/tool_mcp_client/stub_mcp_server.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,16 @@
``tools/call`` echoes back the exact ``arguments`` object the server received
under ``received_arguments`` so tests can assert that the synthesized no-op
placeholder (``rr_no_args``) is stripped before the call reaches the server.

If ``STUB_MCP_TOOLS_FILE`` names a readable JSON file holding a list of tool
definitions, that list is re-read on every ``tools/list`` and ``tools/call``,
so a test can add or rename tools while the server keeps running (the
catalog-staleness scenario of issue #1402). Otherwise the static ``TOOLS`` list
above is served.
"""

import json
import os
import sys

TOOLS = [
Expand All @@ -48,6 +55,20 @@
]


def _current_tools():
"""Return the live tool list: the JSON file if configured, else ``TOOLS``."""
path = os.environ.get('STUB_MCP_TOOLS_FILE')
if path:
try:
with open(path, 'r', encoding='utf-8') as f:
tools = json.load(f)
if isinstance(tools, list):
return tools
except (OSError, ValueError):
pass
return TOOLS


def _write(msg):
sys.stdout.write(json.dumps(msg, ensure_ascii=False) + '\n')
sys.stdout.flush()
Expand Down Expand Up @@ -77,12 +98,12 @@ def _handle(msg):
}

if method == 'tools/list':
return {'jsonrpc': '2.0', 'id': msg_id, 'result': {'tools': TOOLS}}
return {'jsonrpc': '2.0', 'id': msg_id, 'result': {'tools': _current_tools()}}

if method == 'tools/call':
name = params.get('name')
arguments = params.get('arguments', {})
known = {t['name'] for t in TOOLS}
known = {t['name'] for t in _current_tools()}
if name not in known:
return {
'jsonrpc': '2.0',
Expand Down
Loading
Loading