aidputils.agents.tools.mcp.mcp_client

class aidputils.agents.tools.mcp.mcp_client.CacheEntry(session: mcp.client.session.ClientSession | None = None, lock: asyncio.locks.Lock = <factory>)

Bases: object

session: mcp.client.session.ClientSession | None = None

lock: Lock

class aidputils.agents.tools.mcp.mcp_client.MCPSessionCache

Bases: object

get(server_name: str, session_id: str) → mcp.client.session.ClientSession | None

Return a cached ClientSession for (server_name, session_id) if present.

set(server_name: str, session_id: str, session: mcp.client.session.ClientSession) → None

Store a ClientSession for (server_name, session_id).

delete(server_name: str, session_id: str) → None

Remove a cached ClientSession for (server_name, session_id).

async get_or_create(server_name: str, session_id: str, init_session: Callable[[str], Awaitable[mcp.client.session.ClientSession]]) → mcp.client.session.ClientSession

Return a session for (server_name, session_id) if cached, otherwise create one by awaiting init_session(session_id), store it, and return it. Uses a per-key lock to avoid duplicate concurrent initialization.

async close(server_name: str, session_id: str) → None

Best-effort closure of a single session; does not enforce underlying transport close semantics.

async close_all() → None

Best-effort closure of all cached sessions.

class aidputils.agents.tools.mcp.mcp_client.MCPHTTPClient(server_name, url, headers, auth: dict | None = None, transport: str = 'streamable_http', request_timeout_seconds: float = 30.0, sse_read_timeout_seconds: float = 30.0)

Bases: object

get_all_headers() → Dict[str, str]

Return effective headers by augmenting base headers with auth-derived headers. Authorization is computed via mcp_auth.build_headers_from_auth using self.auth.

async init_session(session_id: str) → mcp.client.session.ClientSession

Initialize and park a ClientSession for this server and session_id. Persist it into the global mcp_session_cache and return the session once ready.

async stop_session(session_id: str) → None

Stop a parked persistent session for the given session_id, if running, and remove it from the cache.

session(_server_name: str)

Ephemeral session context manager for single-call operations.

async get_tools(server_name: str, use_cached: bool = False, session_id: str | None = None)

List tools with transparent pagination. - If use_cached is False (default): use an on-demand ephemeral session. - If use_cached is True: reuse/create a persistent session associated with session_id from the cache. Accumulates all pages by following nextCursor when present. Returns a list of tool objects.

async get_resources(server_name: str, uris=None, use_cached: bool = False, session_id: str | None = None)

List resources. - If use_cached is False (default): use an on-demand ephemeral session. - If use_cached is True: reuse/create a persistent session associated with session_id from the cache. Returns a list of resource dicts when possible, otherwise raw objects.

async get_prompt(server_name: str, prompt: str, use_cached: bool = False, session_id: str | None = None)

Get a prompt by name. - If use_cached is False (default): use an on-demand ephemeral session. - If use_cached is True: reuse/create a persistent session associated with session_id from the cache. Returns a dict when possible, otherwise the raw result object.

async ping(server_name: str) → bool

Send a lightweight ping request to validate connectivity/auth. Returns True if completed within the configured timeout.

Note: Uses explicit request_read_timeout_seconds to avoid indefinite waits if a server streams or stalls.

async test_connection(server_name: str) → bool

Validate basic MCP connectivity/auth by establishing a session.

Some MCP servers do not implement ping, but a successful session initialization is still enough to verify that the endpoint is reachable and authentication is working.

async call_tool(server_name: str, tool_name: str, arguments: dict | None = None, timeout_secs: float | None = None, use_cached: bool = False, session_id: str | None = None)

Invoke a tool exposed by the MCP server. - If use_cached is False (default): use an on-demand ephemeral session. - If use_cached is True: reuse/create a persistent session associated with session_id from the cache. Returns the raw CallToolResult (caller is responsible for serialization).

async get_or_create_session(session_id: str) → mcp.client.session.ClientSession

Return an existing session for session_id or lazily initialize a new one via init_session.