search_server.py

# search_server.py — MCP server that exposes web search as a tool.
#
# Runs as a standalone process and communicates over stdio using the
# Model Context Protocol (MCP). Clients (agent.py via the Agents SDK,
# Claude Desktop, or test_search_mcp.py) connect to it and call web_search.
#
# To run directly (for testing):
#   uv run python search_server.py
#
# In normal use, main.py spawns this automatically on startup.

from mcp.server.fastmcp import FastMCP
from ddgs import DDGS

# FastMCP creates the MCP server. The string "search" is the server's name,
# visible to any client that connects.
mcp = FastMCP("search")


@mcp.tool()
def web_search(query: str) -> str:
    """Search the web for current information."""
    # DDGS is used as a context manager so it can clean up its HTTP session.
    # max_results=5 keeps responses concise enough for the model to process.
    with DDGS() as ddgs:
        results = list(ddgs.text(query, max_results=5))
    return "\n\n".join(f"{r['title']}\n{r['href']}\n{r['body']}" for r in results)


if __name__ == "__main__":
    # Start the MCP server and listen for connections over stdio.
    # This is the entry point used both when run directly and when
    # spawned as a subprocess by main.py.
    mcp.run()