ڎj<dZddlZddlmZmZddlmZmZddlZddl Z ddl m Z m Z m Z ddlmZddlmZddlmZmZmZd d lmZmZd d lmZer d d lmZmZneZeZGddeZdS)z1Unified MCP client implementation for AgentScope.N)AsyncExitStack_AsyncGeneratorContextManager)Any TYPE_CHECKING) ClientSession stdio_clientStdioServerParameters) sse_client)streamable_http_client)Field BaseModel PrivateAttr)StdioMCPConfig HttpMCPConfig)logger)MCPToolToolBaseceZdZUdZeddZeed<eddZe ed<ed d d Z e e zed <dZ eedzed< dZeedzed< dZedzed< edZeed<edZedzed<edZedzed<edZe ed<edZeejjdzed<ede fdZdeddfdZ d(dZ!de"efdZ#d(dZ$d)d!e ddfd"Z%de"efd#Z&deejjfd$Z'dee(fd%Z)dede*fd&Z+d(d'Z,dS)* MCPClientaGThe unified MCP client in AgentScope. This class provides a unified interface for MCP connections, handling both stateful (persistent) and stateless (ephemeral) connections. - Stateful: Requires explicit connect() and close(), maintains session - Stateless: No connect() needed, creates temporary session per call Private attributes: - _client: The underlying MCP client context manager - _session: The MCP ClientSession (for stateful connections only) - _stack: AsyncExitStack for managing connection lifecycle - _is_connected: Connection state flag - _cached_tools: Cached list of tools Example: .. code-block:: python # Stateful connection (STDIO or HTTP) client = MCPClient( name="file_system", is_stateful=True, mcp_config=StdioMCPConfig( command="mcp-server-filesystem" ) ) await client.connect() tools = await client.list_tools() await client.close() # Stateless connection (HTTP only) client = MCPClient( name="weather_search", is_stateful=False, mcp_config=HttpMCPConfig( url="https://api.weather.com/mcp" ) ) # No connect() needed tools = await client.list_tools() zMCP Namez The MCP name.)title descriptionnameStatefulzWhether this is a stateful connection that requires explicit connect() and close(). STDIO MCP must be stateful. HTTP MCP can be either stateful or stateless. is_statefultypez MCP ConfigzThe MCP server configuration.) discriminatorrr mcp_configN enable_tools disable_toolsexecution_timeout)default_client_session_stackF _is_connected _cached_toolsreturnc|jS)zuWhether the client is currently connected. Returns: True if connected, False otherwise. )r'selfs HC:\Projects\DSCons\.venv\Lib\site-packages\agentscope\mcp\_mcp_client.py is_connectedzMCPClient.is_connectedls !!_MCPClient__contextctjd|jstd|jd|jjdkr|jstd|jPt|jtrtd|jDrtd|jd |j Pt|j trtd |j Drtd |j d |jf|j _t|j t|j }t|d krtd |d |dS)z-Validate configuration and initialize client.z[a-zA-Z0-9_-]+zMCPClient name 'zh' contains characters not allowed by LLM providers (only [a-zA-Z0-9_-] are permitted). Please rename it. stdio_mcpz.STDIO MCP must be stateful (is_stateful=True).Nc3BK|]}t|t VdSN isinstancestr.0_s r- z,MCPClient.model_post_init..s@>>+,Jq#&&&>>>>>>r/z2Enable tools should be a list of strings, but got .c3BK|]}t|t VdSr4r5r8s r-r;z,MCPClient.model_post_init..s@??+,Jq#&&&??????r/z3Disable tools should be a list of strings, but got rzHThe tools in enable_tools and disable_tools should not overlap, but got )re fullmatchr ValueErrorrrrr r6listanyr!set intersectionlen_initialize_client)r,r0rDs r-model_post_initzMCPClient.model_post_initus |-ty99 149111  ? ; . .t7G .@    (d/66 #>>040A>>>;; !,(,,,   )d0$77 3??040B???<< !-)---   (T-?-Kt011>>D&''L<  A%% C3?CCC !!!!!r/c |jjdkra|j}tt|j|jpg|j|jrt|jndd|j |_ dSdS)uPre-build the stdio client context manager. Only the stdio transport is materialised at construction time — ``StdioServerParameters`` carry process-launch details that are cheap to bind upfront. HTTP transports are built lazily inside :meth:`connect` (or per-call inside :meth:`_get_client_gen` for stateless mode), since each ``streamable_http_client`` / ``sse_client`` is a one-shot context manager. r2Nzutf-8)commandargsenvcwdencodingencoding_error_handler) rrrr rIrJrKrLr7rNr$)r,configs r-rFzMCPClient._initialize_clients} ? ; . ._F'%"N* +1:?FJ4$+1+H   DLLL / .r/cF|j}|jds|jdr!t|j|j|jSd}|js|jr t j|j|j}t|j|S)z3Create an HTTP MCP client (SSE or streamable HTTP).z/ssez /messages/)urlheaderstimeoutN)rRrS)rQ http_client) rrQendswithr rRrShttpx AsyncClientr )r,rOrTs r-_create_http_clientzMCPClient._create_http_clients :  v & & &**=*=l*K*K J  > V^ +K& #    r/cK|jstjd|jdS|jrt d|jd|j)|jjdkr| |_t|_ |j |jd{V}|d|d}}t|||_|j |jd{V|jd{Vd|_tjd |jdS#t"$r(|j d{Vd|_ wxYw) zConnect to the MCP server (for stateful connections only). For stateless connections, this method does nothing. Raises: RuntimeError: If already connected. z5Stateless MCP '%s' does not require explicit connect.NMCP 'z9' is already connected. Call close() before reconnecting.http_mcprrTzMCP connected: %s)rrdebugrr' RuntimeErrorr$rrrXrr&enter_async_contextrr% initializeinfo Exceptionaclose)r,context read_stream write_streams r-connectzMCPClient.connects  LG     F   4 444  < DO$8J$F$F3355DL$&&   K;;DLIIIIIIIIG(/ GAJK)+|DDDM+11$-@@ @ @ @ @ @ @ @-**,, , , , , , , ,!%D  K+TY 7 7 7 7 7   +$$&& & & & & & & &DK  s B/D::2E,T ignore_errorscK|jstjd|jdS|jst d|jd |jd{VnC#t$r6}|s|tj d|jt|Yd}~nd}~wwxYwd|_d|_ d|_tj d|jdS#d|_d|_ d|_tj d|jwxYw)aClose the MCP connection (for stateful connections only). For stateless connections, this method does nothing. Args: ignore_errors: Whether to ignore errors during cleanup. Raises: RuntimeError: If not connected. z3Stateless MCP '%s' does not require explicit close.NrZ)' is not connected. Call connect() first.zError closing MCP '%s': %sFzMCP closed: %s) rrr\rr'r]r&rbrawarningr7r%r`)r,rges r-closezMCPClient.closesj  LE     F! ( (((   5+$$&& & & & & & & & &      N, A         DK DM!&D  K($) 4 4 4 4 4DK DM!&D  K($) 4 4 4 4s0A&%C& B&0,B!C!B&&C1D cX|jjdkr|jS|S)z/Get client generator for stateless connections.r2)rrr$rXr+s r-_get_client_genzMCPClient._get_client_gen(s, ? ; . .< ++-- -r/cKjsʉ4d{V}|d|d}}t||4d{V }|d{V|d{V}|j_dddd{Vn#1d{VswxYwYdddd{Vn#1d{VswxYwYn?jd{V}|j_j}j fd|D}j fd|D}|S)aList available tools from the MCP server in raw :class:`mcp.types.Tool` form, applying ``enable_tools`` and ``disable_tools`` filtering. The full (unfiltered) tool list is cached on ``_cached_tools`` so :meth:`get_tool` can resolve names that were filtered out as well. Returns: `list[mcp.types.Tool]`: Raw MCP tool descriptors after filtering. Raises: RuntimeError: If not connected (for stateful connections). Nrrc0g|]}|jjv|S)rr )r9toolr,s r- z,MCPClient.list_raw_tools..Qs39 111111r/c0g|]}|jjv|Srq)rr!r9r:r,s r-rsz,MCPClient.list_raw_tools..Ws/afD.js=???dmmAF++++++++???r/)r})r, raw_toolss` r-rvzMCPClient.list_tools\sX--//////// ????Y??????????r/crKddlm}|j|d{Vd}|jD]}|j|kr|}n|t d|d|jd|js||j||j|jS| ||j||j |jS) aGet a tool by name from the MCP server. The returned MCPTool object implements ToolProtocol and can be: - Called directly: `await tool(arg1=val1)` - Registered to toolkit: `toolkit.register_tool(tool)` Args: name: The name of the tool function to get. Returns: A tool object that implements ToolProtocol. Raises: ValueError: If the tool is not found. RuntimeError: If not connected (for stateful connections). r)rNzTool 'z' not found in MCP server '')mcp_namerr client_genrS)rrrrzrS) rrrr(r}rr@rrnr"rxr%)r,rr target_toolrrs r-rzMCPClient.get_toolls** #"""""   %%%'' ' ' ' ' ' ' ' &  DyD  " !  JJJdiJJJ   7 /.    % % ' ' '7  .  r/c|jstd|jd|jstd|jddS)zValidate connection state for stateful connections. Raises: RuntimeError: If not connected or session not initialized. rZriz3' session is not initialized. Call connect() first.N)r'r]rr%r+s r-rxzMCPClient._validate_connectionsy ! ( ((( } ( (((   r/)r)N)T)-__name__ __module__ __qualname____doc__r rr7__annotations__rboolrrrr rAr!r"floatrr$rr%rr&rr'r(mcptypesToolpropertyr.rGrFrrXrfrlrnr}rrvrrrxrqr/r-rrs**X#D#  3K273222J. &*L$s)d")))'+M49t#***'+ut|***O;t,,,GS,,,%0[%>%>%>Hmd">>>$/K$=$=$=FNT !===%+e444M44441<T1J1J1JM4 '$.JJJ "d"""X"/"/"/"/"/"/"b. &s +    4''''R&5&5&5&5&5&5&5P.!>s!C....+d39>&:++++Z@$x.@@@@ 99 9999vr/r)rr> contextlibrrtypingrrrV mcp.typesrrrr mcp.client.sser mcp.client.streamable_httpr pydanticr r r_configrr_loggingrrrrrrrqr/r-rsN77 DDDDDDDD%%%%%%%% BBBBBBBBBB%%%%%%======222222222222222222(((((((((GH^^^^^ ^^^^^r/