fast-agent-mcp 0.1.10__py3-none-any.whl → 0.1.11__py3-none-any.whl

{fast_agent_mcp-0.1.10.dist-info → fast_agent_mcp-0.1.11.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fast-agent-mcp
-Version: 0.1.10
+Version: 0.1.11
 Summary: Define, Prompt and Test MCP enabled Agents and Workflows
 Author-email: Shaun Smith <fastagent@llmindset.co.uk>, Sarmad Qadri <sarmad@lastmileai.dev>
 License:                                  Apache License
@@ -212,7 +212,7 @@ Requires-Python: >=3.10
 Requires-Dist: aiohttp>=3.11.13
 Requires-Dist: anthropic>=0.49.0
 Requires-Dist: fastapi>=0.115.6
-Requires-Dist: mcp>=1.4.1
+Requires-Dist: mcp>=1.5.0
 Requires-Dist: numpy>=2.2.1
 Requires-Dist: openai>=1.63.2
 Requires-Dist: opentelemetry-distro>=0.50b0
@@ -241,10 +241,9 @@ Provides-Extra: temporal
 Requires-Dist: temporalio>=1.8.0; extra == 'temporal'
 Description-Content-Type: text/markdown
 
-## fast-agent
-
 <p align="center">
 <a href="https://pypi.org/project/fast-agent-mcp/"><img src="https://img.shields.io/pypi/v/fast-agent-mcp?color=%2334D058&label=pypi" /></a>
+<a href="#"><img src="https://github.com/evalstate/fast-agent/actions/workflows/main-checks.yml/badge.svg" /></a>
 <a href="https://github.com/evalstate/fast-agent/issues"><img src="https://img.shields.io/github/issues-raw/evalstate/fast-agent" /></a>
 <a href="https://lmai.link/discord/mcp-agent"><img src="https://shields.io/discord/1089284610329952357" alt="discord" /></a>
 <img alt="Pepy Total Downloads" src="https://img.shields.io/pepy/dt/fast-agent-mcp?label=pypi%20%7C%20downloads"/>
@@ -253,16 +252,14 @@ Description-Content-Type: text/markdown
 
 ## Overview
 
-**`fast-agent`** enables you to create and interact with sophisticated Agents and Workflows in minutes.
+**`fast-agent`** enables you to create and interact with sophisticated Agents and Workflows in minutes. It is the first framework with complete, end-to-end tested MCP Feature support including Sampling. Both Anthropic (Haiku, Sonnet, Opus) and OpenAI models (gpt-4o family, o1/o3 family) are supported.
 
 The simple declarative syntax lets you concentrate on composing your Prompts and MCP Servers to [build effective agents](https://www.anthropic.com/research/building-effective-agents).
 
-Evaluate how different models handle Agent and MCP Server calling tasks, then build multi-model workflows using the best provider for each task.
-
-`fast-agent` is now multi-modal, supporting Images and PDFs for both Anthropic and OpenAI endpoints (for supported models), via Prompts, Resources and MCP Tool Call results.
+`fast-agent` is multi-modal, supporting Images and PDFs for both Anthropic and OpenAI endpoints via Prompts, Resources and MCP Tool Call results. The inclusion of passthrough and playback LLMs enable rapid development and test of Python glue-code for your applications.
 
 > [!TIP]
-> `fast-agent` is now MCP Native! Coming Soon - Full Documentation Site.
+> `fast-agent` is now MCP Native! Coming Soon - Full Documentation Site and Further MCP Examples.
 
 ### Agent Application Development
 
@@ -272,7 +269,7 @@ Chat with individual Agents and Components before, during and after workflow exe
 
 Simple model selection makes testing Model <-> MCP Server interaction painless. You can read more about the motivation behind this project [here](https://llmindset.co.uk/resources/fast-agent/)
 
-![fast-agent](https://github.com/user-attachments/assets/3e692103-bf97-489a-b519-2d0fee036369)
+![2025-03-23-fast-agent](https://github.com/user-attachments/assets/8f6dbb69-43e3-4633-8e12-5572e9614728)
 
 ## Get started:
 
@@ -597,6 +594,14 @@ agent["greeter"].send("Good Evening!")          # Dictionary access is supported
 
 Add Resources to prompts using either the inbuilt `prompt-server` or MCP Types directly. Convenience class are made available to do so simply, for example:
 
+```python
+  summary: str =  await agent.with_resource(
+      "Summarise this PDF please",
+      "mcp_server",
+      "resource://fast-agent/sample.pdf",
+  )
+```
+
 #### MCP Tool Result Conversion
 
 LLM APIs have restrictions on the content types that can be returned as Tool Calls/Function results via their Chat Completions API's:
@@ -612,40 +617,33 @@ MCP Prompts are supported with `apply_prompt(name,arguments)`, which always retu
 
 Prompts can also be applied interactively through the interactive interface by using the `/prompt` command.
 
+### Sampling
+
+Sampling LLMs are configured per Client/Server pair. Specify the model name in fastagent.config.yaml as follows:
+
+```yaml
+mcp:
+  servers:
+    sampling_resource:
+      command: "uv"
+      args: ["run", "sampling_resource_server.py"]
+      sampling:
+        model: "haiku"
+```
+
 ### Secrets File
 
 > [!TIP]
 > fast-agent will look recursively for a fastagent.secrets.yaml file, so you only need to manage this at the root folder of your agent definitions.
 
+### Interactive Shell
+
+![fast-agent](https://github.com/user-attachments/assets/3e692103-bf97-489a-b519-2d0fee036369)
+
 ## Project Notes
 
 `fast-agent` builds on the [`mcp-agent`](https://github.com/lastmile-ai/mcp-agent) project by Sarmad Qadri.
 
-### llmindset.co.uk fork:
-
-- Addition of MCP Prompts including Prompt Server and agent save/replay ability.
-- Overhaul of Eval/Opt for Conversation Management
-- Removed instructor/double-llm calling - native structured outputs for OAI.
-- Improved handling of Parallel/Fan-In and respose option
-- XML based generated prompts
-- "FastAgent" style prototyping, with per-agent models
-- API keys through Environment Variables
-- Warm-up / Post-Workflow Agent Interactions
-- Quick Setup
-- Interactive Prompt Mode
-- Simple Model Selection with aliases
-- User/Assistant and Tool Call message display
-- MCP Sever Environment Variable support
-- MCP Roots support
-- Comprehensive Progress display
-- JSONL file logging with secret revokation
-- OpenAI o1/o3-mini support with reasoning level
-- Enhanced Human Input Messaging and Handling
-- Declarative workflows
-- Numerous defect fixes
-
-### Features to add (Commmitted)
-
-- Run Agent as MCP Server, with interop
-- Multi-part content types supporing Vision, PDF and multi-part Text.
-- Improved test automation (supported by prompt_server.py and augmented_llm_playback.py)
+### Contributing
+
+Contributions and PRs are welcome - feel free to raise issues to discuss. Full guidelines for contributing and roadmap coming very soon. Get in touch!

{fast_agent_mcp-0.1.10.dist-info → fast_agent_mcp-0.1.11.dist-info}/RECORD

@@ -1,6 +1,6 @@
 mcp_agent/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mcp_agent/app.py,sha256=0_C1xmNZlk9qZoewnNI_mC7sSfO9oJgkOyiKkQ62MHU,10606
-mcp_agent/config.py,sha256=OpPTsk9gNm2IA1laUomAMkGA-pAlp5uILQpEPBjavQs,10644
+mcp_agent/config.py,sha256=cEiY_J5MqKj23KkHtzP1h04yalaGgO2OiXErduiVf2M,10890
 mcp_agent/console.py,sha256=Gjf2QLFumwG1Lav__c07X_kZxxEUSkzV-1_-YbAwcwo,813
 mcp_agent/context.py,sha256=m1S5M9a2Kdxy5rEGG6Uwwmi19bDEpU6u-e5ZgPmVXfY,8031
 mcp_agent/context_dependent.py,sha256=TGqRLzYCOnsWGoaD1HtrliYtWo8MeaWCQk6ePUmyYCw,1446
@@ -17,7 +17,7 @@ mcp_agent/cli/commands/bootstrap.py,sha256=Rmwbuwl52eHfnya7fnwKk2J7nCsHpSh6irka4
 mcp_agent/cli/commands/config.py,sha256=32YTS5jmsYAs9QzAhjkG70_daAHqOemf4XbZBBSMz6g,204
 mcp_agent/cli/commands/setup.py,sha256=_SCpd6_PrixqbSaE72JQ7erIRkZnJGmh_3TvvwSzEiE,6392
 mcp_agent/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mcp_agent/core/agent_app.py,sha256=6fzvExSmVSXyNo-Rq9Xvu0qUKjKHKjOpuhRfzCthV8o,29735
+mcp_agent/core/agent_app.py,sha256=coAbhzGT34SV_S0AsLbHuOkxyovOZFlpk_HUphRNU78,30807
 mcp_agent/core/agent_types.py,sha256=yKiMbv9QO2dduq4zXmoMZlOZpXJZhM4oNwIq1-134FE,318
 mcp_agent/core/agent_utils.py,sha256=QMvwmxZyCqYhBzSyL9xARsxTuwdmlyjQvrPpsH36HnQ,1888
 mcp_agent/core/decorators.py,sha256=dkAah1eIuYsEfQISDryG0u2GrzNnsO_jyN7lhpQfNlM,16191
@@ -28,7 +28,7 @@ mcp_agent/core/factory.py,sha256=MhlYS0G0IyFy_j46HVJdjEznJzfCFjx_NRhUPcbQIJI,190
 mcp_agent/core/fastagent.py,sha256=jJmO0DryFGwSkse_3q5Ll-5XONDvj7k_Oeb-ETBKFkA,19620
 mcp_agent/core/mcp_content.py,sha256=rXT2C5gP9qgC-TI5F362ZLJi_erzcEOnlP9D2ZKK0i0,6860
 mcp_agent/core/prompt.py,sha256=R-X3kptu3ehV_SQeiGnP6F9HMN-92I8e73gnkQ1tDVs,4317
-mcp_agent/core/proxies.py,sha256=a5tNv-EVcv67XNAkbzaybQVbRgkNEfhIkcveS1LBp2s,10242
+mcp_agent/core/proxies.py,sha256=qsIqyJgiIh-b9ehHiZrM39YutQFJPHaHO14GOMFE1KI,10289
 mcp_agent/core/types.py,sha256=Zhi9iW7uiOfdpSt9NC0FCtGRFtJPg4mpZPK2aYi7a7M,817
 mcp_agent/core/validation.py,sha256=x0fsx5eLTawASFm9MDtEukwGOj_RTdY1OW064UihMR8,8309
 mcp_agent/eval/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -51,17 +51,19 @@ mcp_agent/logging/rich_progress.py,sha256=IEVFdFGA0nwg6pSt9Ydni5LCNYZZPKYMe-6DCi
 mcp_agent/logging/tracing.py,sha256=jQivxKYl870oXakmyUk7TXuTQSvsIzpHwZlSQfy4b0c,5203
 mcp_agent/logging/transport.py,sha256=MFgiCQ-YFP0tSMhDMpZCj585vflWcMydM4oyCFduVf0,17203
 mcp_agent/mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mcp_agent/mcp/gen_client.py,sha256=u0HwdJiw9YCerS5JC7JDuGgBh9oTcLd7vv9vPjwibXc,3025
+mcp_agent/mcp/gen_client.py,sha256=D92Yo088CAeuWG6M82Vlkq0H8igUTw9SwwOQinZZCkg,3052
+mcp_agent/mcp/interfaces.py,sha256=hUA9R7RA1tF1td9RCfzWHBUVCLXF6FC1a4I1EZ5Fnh4,4629
 mcp_agent/mcp/mcp_activity.py,sha256=CajXCFWZ2cKEX9s4-HfNVAj471ePTVs4NOkvmIh65tE,592
-mcp_agent/mcp/mcp_agent_client_session.py,sha256=lfz38wzIoMfZyH3dAgclHohOVX0tR7Y2FCE2t7CVsPw,3956
+mcp_agent/mcp/mcp_agent_client_session.py,sha256=3xZbhr48YV5SkBTQGMdNrT_KIGWOBSFPqCZLCSOK2HA,4156
 mcp_agent/mcp/mcp_agent_server.py,sha256=xP09HZTeguJi4Fq0p3fjLBP55uSYe5AdqM90xCgn9Ho,1639
-mcp_agent/mcp/mcp_aggregator.py,sha256=NuFslY5-0as2VAfcg6t-k3sgpX-mh3AWttuS9KHL4n4,37684
+mcp_agent/mcp/mcp_aggregator.py,sha256=1DYZpmq1IJZo7cYKfahH6LeyVKuNkosGhSq6k59lrlM,37941
 mcp_agent/mcp/mcp_connection_manager.py,sha256=PdLia-rxbhUdAdEnW7TQbkf1qeI9RR3xhQw1j11Bi6o,13612
 mcp_agent/mcp/mime_utils.py,sha256=difepNR_gpb4MpMLkBRAoyhDk-AjXUHTiqKvT_VwS1o,1805
 mcp_agent/mcp/prompt_message_multipart.py,sha256=U7IN0JStmy26akTXcqE4x90oWzm8xs1qa0VeKIyPKmE,1962
 mcp_agent/mcp/prompt_serialization.py,sha256=StcXV7V4fqqtCmOCXGCyYXx5vpwNhL2xr3RG_awwdqI,16056
 mcp_agent/mcp/resource_utils.py,sha256=G9IBWyasxKKcbq3T_fSpM6mHE8PjBargEdfQnBPrkZY,6650
-mcp_agent/mcp/stdio.py,sha256=QJcxEw2CXJrhR7PHyhuwUekzaXoDng_cNjai-rdZNg0,4479
+mcp_agent/mcp/sampling.py,sha256=iHjjI5ViCe2CYm_7EtJiHr-WPYug6MQyAuBtru0AnkI,4601
+mcp_agent/mcp/stdio.py,sha256=fZr9yVqPvmPC8pkaf95rZtw0uD8BGND0UI_cUYyuSsE,4478
 mcp_agent/mcp/prompts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mcp_agent/mcp/prompts/__main__.py,sha256=gr1Tdz9fcK0EXjEuZg_BOnKUmvhYq5AH2lFZicVyNb0,237
 mcp_agent/mcp/prompts/prompt_server.py,sha256=6K4FeKNW_JApWUNB055gl8UnWyC1mvtl_kPEvgUnPjk,17348
@@ -72,8 +74,8 @@ mcp_agent/resources/examples/data-analysis/analysis-campaign.py,sha256=EG-HhaDHl
 mcp_agent/resources/examples/data-analysis/analysis.py,sha256=5zLoioZQNKUfXt1EXLrGX3TU06-0N06-L9Gtp9BIr6k,2611
 mcp_agent/resources/examples/data-analysis/fastagent.config.yaml,sha256=ini94PHyJCfgpjcjHKMMbGuHs6LIj46F1NwY0ll5HVk,1609
 mcp_agent/resources/examples/data-analysis/mount-point/WA_Fn-UseC_-HR-Employee-Attrition.csv,sha256=pcMeOL1_r8m8MziE6xgbBrQbjl5Ijo98yycZn7O-dlk,227977
-mcp_agent/resources/examples/internal/agent.py,sha256=4EXhVJcX5mw2LuDqmZL4B4SM0zxMFmMou7NCEeoVeQ0,391
-mcp_agent/resources/examples/internal/fastagent.config.yaml,sha256=NF-plJ2ZMLZL8_YfdwmfsvRyafgsNEEHzsjm_p8vNlY,1858
+mcp_agent/resources/examples/internal/agent.py,sha256=orShmYKkrjMc7qa3ZtfzoO80uOClZaPaw2Wvc4_FIH8,406
+mcp_agent/resources/examples/internal/fastagent.config.yaml,sha256=U2s0Asc06wC04FstKnBMeB3J5gIa3xa-Rao-1-74XTk,1935
 mcp_agent/resources/examples/internal/job.py,sha256=WEKIAANMEAuKr13__rYf3PqJeTAsNB_kqYqbqVYQlUM,4093
 mcp_agent/resources/examples/internal/prompt_category.py,sha256=b3tjkfrVIW1EPoDjr4mG87wlZ7D0Uju9eg6asXAYYpI,551
 mcp_agent/resources/examples/internal/prompt_sizing.py,sha256=UtQ_jvwS4yMh80PHhUQXJ9WXk-fqNYlqUMNTNkZosKM,2003
@@ -120,7 +122,7 @@ mcp_agent/workflows/llm/anthropic_utils.py,sha256=OFmsVmDQ22880duDWQrEeQEB47xtvu
 mcp_agent/workflows/llm/augmented_llm.py,sha256=9cWy-4yNG13w4oQgXmisgWTcm6aoJIRCYTX85Bkf-MI,30554
 mcp_agent/workflows/llm/augmented_llm_anthropic.py,sha256=opV4PTai2eoYUzJS0gCPGEy4pe-lT2Eo1Sao6Y_EIiY,20140
 mcp_agent/workflows/llm/augmented_llm_openai.py,sha256=OUSmvY2m6HU1JOK5nEzKDHpHReT0ffjoHDFHk6aYhoc,21002
-mcp_agent/workflows/llm/augmented_llm_passthrough.py,sha256=IoMNOKK9l46bp4OxfXrB4uK7_4X7ufjuFyXSQCH4YnM,6219
+mcp_agent/workflows/llm/augmented_llm_passthrough.py,sha256=aeQ2WWNIzdzgYWHijE-RWgzFzSUcRJNRv5zq0ug3B2U,7891
 mcp_agent/workflows/llm/augmented_llm_playback.py,sha256=5ypv3owJU6pscktqg9tkLQVKNgaA50e8OWmC1hAhrtE,4328
 mcp_agent/workflows/llm/llm_selector.py,sha256=G7pIybuBDwtmyxUDov_QrNYH2FoI0qFRu2JfoxWUF5Y,11045
 mcp_agent/workflows/llm/model_factory.py,sha256=UHePE5Ow03kpE44kjYtFGEhVFSYp0AY2yGri58yCBKU,7688
@@ -151,8 +153,8 @@ mcp_agent/workflows/swarm/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJW
 mcp_agent/workflows/swarm/swarm.py,sha256=-lAIeSWDqbGHGRPTvjiP9nIKWvxxy9DAojl9yQzO1Pw,11050
 mcp_agent/workflows/swarm/swarm_anthropic.py,sha256=pW8zFx5baUWGd5Vw3nIDF2oVOOGNorij4qvGJKdYPcs,1624
 mcp_agent/workflows/swarm/swarm_openai.py,sha256=wfteywvAGkT5bLmIxX_StHJq8144whYmCRnJASAjOes,1596
-fast_agent_mcp-0.1.10.dist-info/METADATA,sha256=Kum2eRyw2tDXTb1rG7JIf-2IrkOC-xWOnFyQpulgXq4,29760
-fast_agent_mcp-0.1.10.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-fast_agent_mcp-0.1.10.dist-info/entry_points.txt,sha256=qPM7vwtN1_KmP3dXehxgiCxUBHtqP7yfenZigztvY-w,226
-fast_agent_mcp-0.1.10.dist-info/licenses/LICENSE,sha256=cN3FxDURL9XuzE5mhK9L2paZo82LTfjwCYVT7e3j0e4,10939
-fast_agent_mcp-0.1.10.dist-info/RECORD,,
+fast_agent_mcp-0.1.11.dist-info/METADATA,sha256=ff0dlOdPoM72tfefKvN6bdVwszZIKE-5wIkSAI3qJTU,29678
+fast_agent_mcp-0.1.11.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+fast_agent_mcp-0.1.11.dist-info/entry_points.txt,sha256=qPM7vwtN1_KmP3dXehxgiCxUBHtqP7yfenZigztvY-w,226
+fast_agent_mcp-0.1.11.dist-info/licenses/LICENSE,sha256=cN3FxDURL9XuzE5mhK9L2paZo82LTfjwCYVT7e3j0e4,10939
+fast_agent_mcp-0.1.11.dist-info/RECORD,,

mcp_agent/config.py

@@ -18,6 +18,12 @@ class MCPServerAuthSettings(BaseModel):
     model_config = ConfigDict(extra="allow", arbitrary_types_allowed=True)
 
 
+class MCPSamplingSettings(BaseModel):
+    model: str = "haiku"
+
+    model_config = ConfigDict(extra="allow", arbitrary_types_allowed=True)
+
+
 class MCPRootSettings(BaseModel):
     """Represents a root directory configuration for an MCP server."""
 
@@ -81,6 +87,9 @@ class MCPServerSettings(BaseModel):
     env: Dict[str, str] | None = None
     """Environment variables to pass to the server process."""
 
+    sampling: MCPSamplingSettings | None = None
+    """Sampling settings for this Client/Server pair"""
+
 
 class MCPSettings(BaseModel):
     """Configuration for all MCP servers."""

mcp_agent/core/agent_app.py

@@ -112,6 +112,35 @@ class AgentApp:
 
         proxy = self._agents[target]
         return await proxy.apply_prompt(prompt_name, arguments)
+        
+    async def with_resource(
+        self,
+        prompt_content: Union[str, PromptMessageMultipart],
+        server_name: str,
+        resource_name: str,
+        agent_name: Optional[str] = None,
+    ) -> str:
+        """
+        Create a prompt with the given content and resource, then send it to the agent.
+
+        Args:
+            prompt_content: Either a string message or an existing PromptMessageMultipart
+            server_name: Name of the MCP server to retrieve the resource from
+            resource_name: Name or URI of the resource to retrieve
+            agent_name: The name of the agent to use (uses default if None)
+
+        Returns:
+            The agent's response as a string
+        """
+        target = agent_name or self._default
+        if not target:
+            raise ValueError("No default agent available")
+
+        if target not in self._agents:
+            raise ValueError(f"No agent named '{target}'")
+
+        proxy = self._agents[target]
+        return await proxy.with_resource(prompt_content, server_name, resource_name)
 
     async def prompt(self, agent_name: Optional[str] = None, default: str = "") -> str:
         """

mcp_agent/core/proxies.py

@@ -1,6 +1,9 @@
 """
 Proxy classes for agent interactions.
 These proxies provide a consistent interface for interacting with different types of agents.
+
+FOR COMPATIBILITY WITH LEGACY MCP-AGENT CODE
+
 """
 
 from typing import List, Optional, Dict, Union, TYPE_CHECKING

mcp_agent/mcp/gen_client.py

@@ -6,7 +6,7 @@ from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStre
 from mcp import ClientSession
 
 from mcp_agent.logging.logger import get_logger
-from mcp_agent.mcp_server_registry import ServerRegistry
+from mcp_agent.mcp.interfaces import ServerRegistryProtocol
 from mcp_agent.mcp.mcp_agent_client_session import MCPAgentClientSession
 
 logger = get_logger(__name__)
@@ -15,7 +15,7 @@ logger = get_logger(__name__)
 @asynccontextmanager
 async def gen_client(
     server_name: str,
-    server_registry: ServerRegistry,
+    server_registry: ServerRegistryProtocol,
     client_session_factory: Callable[
         [MemoryObjectReceiveStream, MemoryObjectSendStream, timedelta | None],
         ClientSession,
@@ -41,7 +41,7 @@ async def gen_client(
 
 async def connect(
     server_name: str,
-    server_registry: ServerRegistry,
+    server_registry: ServerRegistryProtocol,
     client_session_factory: Callable[
         [MemoryObjectReceiveStream, MemoryObjectSendStream, timedelta | None],
         ClientSession,
@@ -67,7 +67,7 @@ async def connect(
 
 async def disconnect(
     server_name: str | None,
-    server_registry: ServerRegistry,
+    server_registry: ServerRegistryProtocol,
 ) -> None:
     """
     Disconnect from the specified server. If server_name is None, disconnect from all servers.

mcp_agent/mcp/interfaces.py

@@ -0,0 +1,152 @@
+"""
+Interface definitions to prevent circular imports.
+This module defines protocols (interfaces) that can be used to break circular dependencies.
+"""
+
+from contextlib import asynccontextmanager
+from typing import Any, AsyncGenerator, Callable, Generic, List, Optional, Protocol, Type, TypeVar
+
+from mcp import ClientSession
+from mcp.types import CreateMessageRequestParams
+from pydantic import Field
+
+
+class ServerRegistryProtocol(Protocol):
+    """
+    Protocol defining the minimal interface of ServerRegistry needed by gen_client.
+    This allows gen_client to depend on this protocol rather than the full ServerRegistry class.
+    """
+
+    @asynccontextmanager
+    async def initialize_server(
+        self,
+        server_name: str,
+        client_session_factory=None,
+        init_hook=None,
+    ) -> AsyncGenerator[ClientSession, None]:
+        """Initialize a server and yield a client session."""
+        ...
+
+    @property
+    def connection_manager(self) -> "ConnectionManagerProtocol":
+        """Get the connection manager."""
+        ...
+
+
+class ConnectionManagerProtocol(Protocol):
+    """
+    Protocol defining the minimal interface of ConnectionManager needed.
+    """
+
+    async def get_server(
+        self,
+        server_name: str,
+        client_session_factory=None,
+    ):
+        """Get a server connection."""
+        ...
+
+    async def disconnect_server(self, server_name: str) -> None:
+        """Disconnect from a server."""
+        ...
+
+    async def disconnect_all_servers(self) -> None:
+        """Disconnect from all servers."""
+        ...
+
+
+# Type variables for generic protocols
+MessageParamT = TypeVar("MessageParamT")
+"""A type representing an input message to an LLM."""
+
+MessageT = TypeVar("MessageT")
+"""A type representing an output message from an LLM."""
+
+ModelT = TypeVar("ModelT")
+"""A type representing a structured output message from an LLM."""
+
+
+class RequestParams(CreateMessageRequestParams):
+    """
+    Parameters to configure the AugmentedLLM 'generate' requests.
+    """
+
+    messages: None = Field(exclude=True, default=None)
+    """
+    Ignored. 'messages' are removed from CreateMessageRequestParams 
+    to avoid confusion with the 'message' parameter on 'generate' method.
+    """
+
+    maxTokens: int = 2048
+    """The maximum number of tokens to sample, as requested by the server."""
+
+    model: str | None = None
+    """
+    The model to use for the LLM generation.
+    If specified, this overrides the 'modelPreferences' selection criteria.
+    """
+
+    use_history: bool = True
+    """
+    Include the message history in the generate request.
+    """
+
+    max_iterations: int = 10
+    """
+    The maximum number of iterations to run the LLM for.
+    """
+
+    parallel_tool_calls: bool = True
+    """
+    Whether to allow multiple tool calls per iteration.
+    Also known as multi-step tool use.
+    """
+
+
+class AugmentedLLMProtocol(Protocol, Generic[MessageParamT, MessageT]):
+    """Protocol defining the interface for augmented LLMs"""
+
+    async def generate(
+        self,
+        message: str | MessageParamT | List[MessageParamT],
+        request_params: RequestParams | None = None,
+    ) -> List[MessageT]:
+        """Request an LLM generation, which may run multiple iterations, and return the result"""
+
+    async def generate_str(
+        self,
+        message: str | MessageParamT | List[MessageParamT],
+        request_params: RequestParams | None = None,
+    ) -> str:
+        """Request an LLM generation and return the string representation of the result"""
+
+    async def generate_structured(
+        self,
+        message: str | MessageParamT | List[MessageParamT],
+        response_model: Type[ModelT],
+        request_params: RequestParams | None = None,
+    ) -> ModelT:
+        """Request a structured LLM generation and return the result as a Pydantic model."""
+
+
+class ModelFactoryClassProtocol(Protocol):
+    """
+    Protocol defining the minimal interface of the ModelFactory class needed by sampling.
+    This allows sampling.py to depend on this protocol rather than the concrete ModelFactory class.
+    """
+    
+    @classmethod
+    def create_factory(
+        cls, model_string: str, request_params: Optional[RequestParams] = None
+    ) -> Callable[..., AugmentedLLMProtocol[Any, Any]]:
+        """
+        Creates a factory function that can be used to construct an LLM instance.
+
+        Args:
+            model_string: The model specification string
+            request_params: Optional parameters to configure LLM behavior
+
+        Returns:
+            A factory function that can create an LLM instance
+        """
+        ...

mcp_agent/mcp/mcp_agent_client_session.py

@@ -24,6 +24,7 @@ from pydantic import AnyUrl
 from mcp_agent.config import MCPServerSettings
 from mcp_agent.context_dependent import ContextDependent
 from mcp_agent.logging.logger import get_logger
+from mcp_agent.mcp.sampling import sample
 
 logger = get_logger(__name__)
 
@@ -40,7 +41,12 @@ async def list_roots(ctx: ClientSession) -> ListRootsResult:
         and ctx.session.server_config.roots
     ):
         roots = [
-            Root(uri=AnyUrl(root.uri), name=root.name)
+            Root(
+                uri=AnyUrl(
+                    root.server_uri_alias or root.uri,
+                ),
+                name=root.name,
+            )
             for root in ctx.session.server_config.roots
         ]
     return ListRootsResult(roots=roots or [])
@@ -58,7 +64,9 @@ class MCPAgentClientSession(ClientSession, ContextDependent):
     """
 
     def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs, list_roots_callback=list_roots)
+        super().__init__(
+            *args, **kwargs, list_roots_callback=list_roots, sampling_callback=sample
+        )
         self.server_config: Optional[MCPServerSettings] = None
 
     async def send_request(
@@ -115,4 +123,4 @@ class MCPAgentClientSession(ClientSession, ContextDependent):
         )
         return await super().send_progress_notification(
             progress_token=progress_token, progress=progress, total=total
-        )
+        )

mcp_agent/mcp/mcp_aggregator.py

@@ -16,6 +16,7 @@ from mcp.server.stdio import stdio_server
 from mcp.types import (
     CallToolResult,
     ListToolsResult,
+    TextContent,
     Tool,
     Prompt,
 )
@@ -459,7 +460,10 @@ class MCPAggregator(ContextDependent):
 
         if server_name is None or local_tool_name is None:
             logger.error(f"Error: Tool '{name}' not found")
-            return CallToolResult(isError=True, message=f"Tool '{name}' not found")
+            return CallToolResult(
+                isError=True, 
+                content=[TextContent(type="text", text=f"Tool '{name}' not found")]
+            )
 
         logger.info(
             "Requesting tool call",
@@ -477,7 +481,10 @@ class MCPAggregator(ContextDependent):
             operation_name=local_tool_name,
             method_name="call_tool",
             method_args={"name": local_tool_name, "arguments": arguments},
-            error_factory=lambda msg: CallToolResult(isError=True, message=msg),
+            error_factory=lambda msg: CallToolResult(
+                isError=True, 
+                content=[TextContent(type="text", text=msg)]
+            ),
         )
 
     async def get_prompt(
@@ -898,7 +905,10 @@ class MCPCompoundServer(Server):
             result = await self.aggregator.call_tool(name=name, arguments=arguments)
             return result.content
         except Exception as e:
-            return CallToolResult(isError=True, message=f"Error calling tool: {e}")
+            return CallToolResult(
+                isError=True, 
+                content=[TextContent(type="text", text=f"Error calling tool: {e}")]
+            )
 
     async def _get_prompt(
         self, name: str = None, arguments: dict[str, str] = None

mcp_agent/mcp/sampling.py

@@ -0,0 +1,133 @@
+"""
+Module for handling MCP Sampling functionality without causing circular imports.
+This module is carefully designed to avoid circular imports in the agent system.
+"""
+
+from mcp import ClientSession
+from mcp.types import (
+    CreateMessageRequestParams,
+    CreateMessageResult,
+    TextContent,
+)
+
+from mcp_agent.logging.logger import get_logger
+from mcp_agent.mcp.interfaces import AugmentedLLMProtocol
+from mcp_agent.mcp.prompt_message_multipart import PromptMessageMultipart
+
+# Protocol is sufficient to describe the interface - no need for TYPE_CHECKING imports
+
+logger = get_logger(__name__)
+
+
+def create_sampling_llm(
+    mcp_ctx: ClientSession, model_string: str
+) -> AugmentedLLMProtocol:
+    """
+    Create an LLM instance for sampling without tools support.
+    This utility function creates a minimal LLM instance based on the model string.
+
+    Args:
+        mcp_ctx: The MCP ClientSession
+        model_string: The model to use (e.g. "passthrough", "claude-3-5-sonnet-latest")
+
+    Returns:
+        An initialized LLM instance ready to use
+    """
+    from mcp_agent.workflows.llm.model_factory import ModelFactory
+    from mcp_agent.agents.agent import Agent, AgentConfig
+
+    # Get application context from global state if available
+    # We don't try to extract it from mcp_ctx as they're different contexts
+    app_context = None
+    try:
+        from mcp_agent.context import get_current_context
+
+        app_context = get_current_context()
+    except Exception:
+        logger.warning("App context not available for sampling call")
+
+    # Create a minimal agent configuration
+    agent_config = AgentConfig(
+        name="sampling_agent",
+        instruction="You are a sampling agent.",
+        servers=[],  # No servers needed
+    )
+
+    # Create agent with our application context (not the MCP context)
+    # Set connection_persistence=False to avoid server connections
+    agent = Agent(
+        config=agent_config,
+        context=app_context,
+        server_names=[],  # Make sure no server connections are attempted
+        connection_persistence=False,  # Avoid server connection management
+    )
+
+    # Create the LLM using the factory
+    factory = ModelFactory.create_factory(model_string)
+    llm = factory(agent=agent)
+
+    # Attach the LLM to the agent
+    agent._llm = llm
+
+    return llm
+
+
+async def sample(
+    mcp_ctx: ClientSession, params: CreateMessageRequestParams
+) -> CreateMessageResult:
+    """
+    Handle sampling requests from the MCP protocol.
+    This function extracts the model from the server config and
+    returns a simple response using the specified model.
+    """
+    model = None
+    try:
+        # Extract model from server config
+        if (
+            hasattr(mcp_ctx, "session")
+            and hasattr(mcp_ctx.session, "server_config")
+            and mcp_ctx.session.server_config
+            and hasattr(mcp_ctx.session.server_config, "sampling")
+            and mcp_ctx.session.server_config.sampling.model
+        ):
+            model = mcp_ctx.session.server_config.sampling.model
+
+        if model is None:
+            raise ValueError("No model configured")
+
+        # Create an LLM instance using our utility function
+        llm = create_sampling_llm(mcp_ctx, model)
+
+        # Get user message from the request params
+        user_message = params.messages[0].content.text
+
+        # Create a multipart prompt message with the user's input
+        prompt = PromptMessageMultipart(
+            role="user", content=[TextContent(type="text", text=user_message)]
+        )
+
+        try:
+            # Use the LLM to generate a response
+            logger.info(f"Processing input: {user_message[:50]}...")
+            llm_response = await llm.generate_prompt(prompt, None)
+            logger.info(f"Generated response: {llm_response[:50]}...")
+        except Exception as e:
+            # If there's an error in LLM processing, fall back to echo
+            logger.error(f"Error generating response: {str(e)}")
+            llm_response = f"Echo response: {user_message}"
+
+        # Return the LLM-generated response
+        return CreateMessageResult(
+            role="assistant",
+            content=TextContent(type="text", text=llm_response),
+            model=model,
+            stopReason="endTurn",
+        )
+    except Exception as e:
+        logger.error(f"Error in sampling: {str(e)}")
+        return CreateMessageResult(
+            role="assistant",
+            content=TextContent(type="text", text=f"Error in sampling: {str(e)}"),
+            model=model or "unknown",
+            stopReason="error",
+        )

mcp_agent/mcp/stdio.py

@@ -14,7 +14,7 @@ from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStre
 logger = get_logger(__name__)
 
 
-# TODO this will be removed when client library 1.4.2 is released
+# TODO this will be removed when client library with https://github.com/modelcontextprotocol/python-sdk/pull/343 is released
 @asynccontextmanager
 async def stdio_client_with_rich_stderr(server: StdioServerParameters):
     """
@@ -95,7 +95,6 @@ async def stdio_client_with_rich_stderr(server: StdioServerParameters):
             async with write_stream_reader:
                 async for message in write_stream_reader:
                     json = message.model_dump_json(by_alias=True, exclude_none=True)
-                    print(f"**********{id(process.stdin)}")
                     await process.stdin.send(
                         (json + "\n").encode(
                             encoding=server.encoding,

mcp_agent/resources/examples/internal/agent.py

@@ -6,7 +6,7 @@ fast = FastAgent("FastAgent Example")
 
 
 # Define the agent
-@fast.agent(servers=["fetch"])
+@fast.agent(servers=["fetch", "mcp_hfspace"])
 async def main():
     # use the --model command line switch or agent arguments to change model
     async with fast.run() as agent:

mcp_agent/resources/examples/internal/fastagent.config.yaml

@@ -50,3 +50,6 @@ mcp:
     category:
       command: "uv"
       args: ["run", "prompt_category.py"]
+    mcp_hfspace:
+      command: "npx"
+      args: ["@llmindset/mcp-hfspace"]

mcp_agent/workflows/llm/augmented_llm_passthrough.py

@@ -1,5 +1,5 @@
 from typing import Any, List, Optional, Type, Union
-import json
+import json  # Import at the module level
 from mcp import GetPromptResult
 from mcp.types import PromptMessage
 from pydantic_core import from_json
@@ -52,6 +52,13 @@ class PassthroughLLM(AugmentedLLM):
         self.show_user_message(message, model="fastagent-passthrough", chat_turn=0)
         await self.show_assistant_message(message, title="ASSISTANT/PASSTHROUGH")
 
+        # Handle PromptMessage by concatenating all parts
+        if isinstance(message, PromptMessage):
+            parts_text = []
+            for part in message.content:
+                parts_text.append(str(part))
+            return "\n".join(parts_text)
+
         return str(message)
 
     async def _call_tool_and_return_result(self, command: str) -> str:
@@ -65,42 +72,73 @@ class PassthroughLLM(AugmentedLLM):
             Tool result as a string
         """
         try:
-            # Parse the tool name and optional arguments
-            parts = command.split(" ", 2)
-            if len(parts) < 2:
-                return "Error: Invalid format. Expected '***CALL_TOOL <tool_name> [arguments_json]'"
-
-            tool_name = parts[1].strip()
-            arguments = None
-
-            # Parse optional JSON arguments if provided
-            if len(parts) > 2:
-                try:
-                    arguments = json.loads(parts[2])
-                except json.JSONDecodeError:
-                    return f"Error: Invalid JSON arguments: {parts[2]}"
-
-            # Call the tool and get the result
-            self.logger.info(f"Calling tool {tool_name} with arguments {arguments}")
+            tool_name, arguments = self._parse_tool_command(command)
             result = await self.aggregator.call_tool(tool_name, arguments)
+            return self._format_tool_result(tool_name, result)
+        except Exception as e:
+            self.logger.error(f"Error calling tool: {str(e)}")
+            return f"Error calling tool: {str(e)}"
+
+    def _parse_tool_command(self, command: str) -> tuple[str, Optional[dict]]:
+        """
+        Parse a tool command string into tool name and arguments.
+
+        Args:
+            command: The command string in format "***CALL_TOOL <tool_name> [arguments_json]"
+
+        Returns:
+            Tuple of (tool_name, arguments_dict)
+
+        Raises:
+            ValueError: If command format is invalid
+        """
+        parts = command.split(" ", 2)
+        if len(parts) < 2:
+            raise ValueError(
+                "Invalid format. Expected '***CALL_TOOL <tool_name> [arguments_json]'"
+            )
+
+        tool_name = parts[1].strip()
+        arguments = None
 
-            # Format the result as a string
-            if result.isError:
-                return f"Error calling tool '{tool_name}': {result.message}"
+        if len(parts) > 2:
+            try:
+                arguments = json.loads(parts[2])
+            except json.JSONDecodeError:
+                raise ValueError(f"Invalid JSON arguments: {parts[2]}")
 
-            # Extract text content from result
-            result_text = []
+        self.logger.info(f"Calling tool {tool_name} with arguments {arguments}")
+        return tool_name, arguments
+
+    def _format_tool_result(self, tool_name: str, result) -> str:
+        """
+        Format tool execution result as a string.
+
+        Args:
+            tool_name: The name of the tool that was called
+            result: The result returned from the tool
+
+        Returns:
+            Formatted result as a string
+        """
+        if result.isError:
+            error_text = []
             for content_item in result.content:
                 if hasattr(content_item, "text"):
-                    result_text.append(content_item.text)
+                    error_text.append(content_item.text)
                 else:
-                    result_text.append(str(content_item))
+                    error_text.append(str(content_item))
+            error_message = "\n".join(error_text) if error_text else "Unknown error"
+            return f"Error calling tool '{tool_name}': {error_message}"
 
-            return "\n".join(result_text)
+        result_text = []
+        for content_item in result.content:
+            if hasattr(content_item, "text"):
+                result_text.append(content_item.text)
+            else:
+                result_text.append(str(content_item))
 
-        except Exception as e:
-            self.logger.error(f"Error calling tool: {str(e)}")
-            return f"Error calling tool: {str(e)}"
+        return "\n".join(result_text)
 
     async def generate_structured(
         self,
@@ -123,10 +161,25 @@ class PassthroughLLM(AugmentedLLM):
     async def generate_prompt(
         self, prompt: "PromptMessageMultipart", request_params: RequestParams | None
     ) -> str:
-        message = prompt.content[0].text if prompt.content else ""
-        if isinstance(message, str) and message.startswith("***CALL_TOOL "):
-            return await self._call_tool_and_return_result(message)
-        return await self.generate_str(message, request_params)
+        # Check if this prompt contains a tool call command
+        if (
+            prompt.content
+            and prompt.content[0].text
+            and prompt.content[0].text.startswith("***CALL_TOOL ")
+        ):
+            return await self._call_tool_and_return_result(prompt.content[0].text)
+
+        # Process all parts of the PromptMessageMultipart
+        parts_text = []
+        for part in prompt.content:
+            parts_text.append(str(part))
+
+        # If no parts found, return empty string
+        if not parts_text:
+            return ""
+
+        # Join all parts and process with generate_str
+        return await self.generate_str("\n".join(parts_text), request_params)
 
     async def apply_prompt_template(
         self, prompt_result: GetPromptResult, prompt_name: str