Sampling

examples/mcp/mcp_prompts_and_resources/demo_server.py

@@ -1,54 +1,14 @@
 from mcp.server.fastmcp import FastMCP
-import datetime
+from mcp.types import ModelPreferences, ModelHint, SamplingMessage, TextContent
 import json
 
-# Store server start time
-SERVER_START_TIME = datetime.datetime.utcnow()
-
 mcp = FastMCP("Resource Demo MCP Server")
 
-# Define some static resources
-STATIC_RESOURCES = {
-    "demo://docs/readme": {
-        "name": "README",
-        "description": "A sample README file.",
-        "content_type": "text/markdown",
-        "content": "# Demo Resource Server\n\nThis is a sample README resource provided by the demo MCP server.",
-    },
-    "demo://data/users": {
-        "name": "User Data",
-        "description": "Sample user data in JSON format.",
-        "content_type": "application/json",
-        "content": json.dumps(
-            [
-                {"id": 1, "name": "Alice"},
-                {"id": 2, "name": "Bob"},
-                {"id": 3, "name": "Charlie"},
-            ],
-            indent=2,
-        ),
-    },
-}
-
 
 @mcp.resource("demo://docs/readme")
 def get_readme():
     """Provide the README file content."""
-    meta = STATIC_RESOURCES["demo://docs/readme"]
-    return meta["content"]
-
-
-@mcp.resource("demo://data/users")
-def get_users():
-    """Provide user data."""
-    meta = STATIC_RESOURCES["demo://data/users"]
-    return meta["content"]
-
-
-@mcp.resource("demo://{city}/weather")
-def get_weather(city: str) -> str:
-    """Provide a simple weather report for a given city."""
-    return f"It is sunny in {city} today!"
+    return "# Demo Resource Server\n\nThis is a sample README resource provided by the demo MCP server."
 
 
 @mcp.prompt()
@@ -60,6 +20,53 @@ def echo(message: str) -> str:
     return f"Prompt: {message}"
 
 
+@mcp.resource("demo://data/friends")
+def get_users():
+    """Provide my friend list."""
+    return (
+        json.dumps(
+            [
+                {"id": 1, "friend": "Alice"},
+            ],
+        ),
+    )
+
+
+@mcp.prompt()
+def get_haiku_prompt(topic: str) -> str:
+    """Get a haiku prompt about a given topic."""
+    return f"I am fascinated about {topic}. Can you generate a haiku combining {topic} + my friend name?"
+
+
+@mcp.tool()
+async def get_haiku(topic: str) -> str:
+    """Get a haiku about a given topic."""
+    haiku = await mcp.get_context().session.create_message(
+        messages=[
+            SamplingMessage(
+                role="user",
+                content=TextContent(
+                    type="text", text=f"Generate a haiku about {topic}."
+                ),
+            )
+        ],
+        system_prompt="You are a poet.",
+        max_tokens=100,
+        temperature=0.7,
+        model_preferences=ModelPreferences(
+            hints=[ModelHint(name="gpt-4o-mini")],
+            costPriority=0.1,
+            speedPriority=0.8,
+            intelligencePriority=0.1,
+        ),
+    )
+
+    if isinstance(haiku.content, TextContent):
+        return haiku.content.text
+    else:
+        return "Haiku generation failed, unexpected content type."
+
+
 def main():
     """Main entry point for the MCP server."""
     mcp.run()

examples/mcp/mcp_prompts_and_resources/main.py

@@ -11,6 +11,8 @@
 )
 from mcp_agent.agents.agent import Agent
 from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM
+from mcp_agent.human_input.handler import console_input_callback
+
 
 settings = Settings(
     execution_engine="asyncio",
@@ -30,7 +32,9 @@
 
 # Settings can either be specified programmatically,
 # or loaded from mcp_agent.config.yaml/mcp_agent.secrets.yaml
-app = MCPApp(name="mcp_basic_agent")  # settings=settings)
+app = MCPApp(
+    name="mcp_basic_agent", human_input_callback=console_input_callback
+)  # settings=settings)
 
 
 async def example_usage():
@@ -71,13 +75,16 @@ async def example_usage():
             )
 
             llm = await agent.attach_llm(OpenAIAugmentedLLM)
-            res = await llm.generate_str(
+            summary = await llm.generate_str(
                 [
                     "Summarise what are my prompts and resources?",
                     *combined_messages,
                 ]
             )
-            logger.info(f"Summary: {res}")
+            logger.info(f"Summary: {summary}")
+
+            haiku = await llm.generate_str("Write me a haiku")
+            logger.info(f"Haiku: {haiku}")
 
 
 if __name__ == "__main__":

examples/mcp/mcp_sampling/README.md

@@ -0,0 +1,101 @@
+# MCP Sampling Example
+
+This example demonstrates how to use **MCP sampling** in an agent application. 
+It shows how to connect to an MCP server that exposes a tool that uses a sampling request to generate a response.
+
+---
+
+## What is MCP sampling?
+Sampling in MCP allows servers to implement agentic behaviors, by enabling LLM calls to occur nested inside other MCP server features.
+Following the MCP recommendations, users are prompted to approve sampling requests, as well as the output produced by the LLM for the sampling request.
+More details can be found in the [MCP documentation](https://modelcontextprotocol.io/specification/2025-06-18/client/sampling).
+
+This example demonstrates sampling using [MCP agent servers](https://github.com/lastmile-ai/mcp-agent/blob/main/examples/mcp_agent_server/README.md).
+It is also possible to use sampling when explicitly creating an MCP client. The code for that would look like the following: 
+
+```python
+settings = ... # MCP agent configuration
+registry = ServerRegistry(settings)
+
+@mcp.tool()
+async def my_tool(input: str, ctx: Context) -> str:
+    async with gen_client("my_server", registry, upstream_session=ctx.session) as my_client:
+        result = await my_client.call_tool("some_tool", {"input": input})
+        ... # etc
+```
+
+---
+
+## Example Overview
+
+- **nested_server.py** implements a simple MCP server that uses sampling to generate a haiku about a given topic
+- **demo_server.py** implements a simple MCP server that implements an agent generating haikus using the tool exposed by `nested_server.py`
+- **main.py** shows how to:
+  1. Connect an agent to the demo MCP server, and then
+  2. Invoke the agent implemented by the demo MCP server, thereby triggering a sampling request.
+
+---
+
+## Architecture
+
+```plaintext
+┌────────────────────┐
+│   nested_server    │──────┐
+│   MCP Server       │      │
+└─────────┬──────────┘      │
+          │                 │
+          ▼                 │
+┌────────────────────┐      │
+│   demo_server      │      │
+│   MCP Server       │      │
+└─────────┬──────────┘      │
+          │            sampling, via user approval
+          ▼                 │
+┌────────────────────┐      │
+│  Agent (Python)    │      │      
+│  + LLM (OpenAI)    │◀─────┘
+└─────────┬──────────┘
+          │
+          ▼
+   [User/Developer]
+```
+
+---
+
+## 1. Setup
+
+Clone the repo and navigate to this example:
+
+```bash
+git clone https://github.com/lastmile-ai/mcp-agent.git
+cd mcp-agent/examples/mcp/mcp_sampling
+```
+
+---
+
+## 2. Run the Agent Example
+
+Run the agent script which should auto install all necessary dependencies:
+
+```bash
+uv run main.py
+```
+
+You should see logs showing:
+
+- The agent connecting to the demo server, and calling the tool
+- A request to approve the sampling request; type `approve` to approve (anything else will deny the request)
+- A request to approve the result of the sampling request
+- The final result of the tool call
+
+---
+
+## References
+
+- [Model Context Protocol (MCP) Introduction](https://modelcontextprotocol.io/introduction)
+- [MCP Agent Framework](https://github.com/lastmile-ai/mcp-agent)
+- [MCP Server Sampling](https://modelcontextprotocol.io/specification/2025-06-18/client/sampling)
+
+---
+
+This example is a minimal, practical demonstration of how to use **MCP sampling** as first-class context for agent applications.

examples/mcp/mcp_sampling/demo_server.py

@@ -0,0 +1,122 @@
+"""
+Workflow MCP Server Example
+
+This example demonstrates three approaches to creating agents and workflows:
+1. Traditional workflow-based approach with manual agent creation
+2. Programmatic agent configuration using AgentConfig
+3. Declarative agent configuration using FastMCPApp decorators
+"""
+
+import asyncio
+import logging
+
+import yaml
+from mcp.server.fastmcp import FastMCP
+
+from mcp_agent.app import MCPApp
+from mcp_agent.config import Settings, LoggerSettings, MCPSettings, MCPServerSettings
+from mcp_agent.server.app_server import create_mcp_server_for_app
+from mcp_agent.agents.agent import Agent
+from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM
+from mcp_agent.executor.workflow import Workflow, WorkflowResult
+
+# Initialize logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# Note: This is purely optional:
+# if not provided, a default FastMCP server will be created by MCPApp using create_mcp_server_for_app()
+mcp = FastMCP(name="haiku_generation_server", description="Server to generate haikus")
+
+# Create settings explicitly, as we want to use a different configuration from the main app
+secrets_file = Settings.find_secrets()
+if secrets_file and secrets_file.exists():
+    with open(secrets_file, "r", encoding="utf-8") as f:
+        yaml_secrets = yaml.safe_load(f) or {}
+        openai_secret = yaml_secrets["openai"]
+
+settings = Settings(
+    execution_engine="asyncio",
+    logger=LoggerSettings(type="console", level="debug"),
+    mcp=MCPSettings(
+        servers={
+            "haiku_server": MCPServerSettings(
+                command="uv",
+                args=["run", "nested_server.py"],
+                description="nested server providing a haiku generator"
+            )
+        }
+    ),
+    openai=openai_secret
+)
+
+# Define the MCPApp instance
+app = MCPApp(
+    name="haiku_server",
+    description="Haiku server",
+    mcp=mcp,
+    settings=settings
+)
+
+
+@app.workflow
+class HaikuWorkflow(Workflow[str]):
+    """
+    A workflow that generates haikus on request.
+    """
+
+    @app.workflow_run
+    async def run(self, input: str) -> WorkflowResult[str]:
+        """
+        Run the haiku agent workflow.
+
+        Args:
+            input: The topic to create a haiku about
+
+        Returns:
+            WorkflowResult containing the processed data.
+        """
+
+        logger = app.logger
+        context = app.context
+
+        haiku_agent = Agent(
+            name="poet",
+            instruction="""You are an agent with access to a tool that helps you write
+            haikus.""",
+            server_names=["haiku_server"],
+        )
+
+        async with haiku_agent:
+            llm = await haiku_agent.attach_llm(OpenAIAugmentedLLM)
+
+            result = await llm.generate_str(
+                message=f"Write a haiku about {input} using the tool at your disposal",
+            )
+            logger.info(f"Input: {input}, Result: {result}")
+
+            return WorkflowResult(value=result)
+
+
+async def main():
+    async with app.run() as agent_app:
+        # Log registered workflows and agent configurations
+        logger.info(f"Creating MCP server for {agent_app.name}")
+
+        logger.info("Registered workflows:")
+        for workflow_id in agent_app.workflows:
+            logger.info(f"  - {workflow_id}")
+
+        # Create the MCP server that exposes both workflows and agent configurations
+        fast_mcp_settings = (
+            {"host": "localhost", "port": 8001, "debug": True, "log_level": "DEBUG"}
+        )
+        mcp_server = create_mcp_server_for_app(agent_app, **({}))
+        logger.info(f"MCP Server settings: {mcp_server.settings}")
+
+        # Run the server
+        await mcp_server.run_stdio_async()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())