A terminal-based agentic search and synthesis engine. A Gemini-powered agent discovers tools from MCP servers over SSE, uses them recursively to research a query, and synthesises a final answer.
User Query → Agent Client (client/src/main.py)
├─ Connects to MCP server(s) over SSE (HTTP)
├─ Discovers tools via list_tools()
├─ Calls Gemini API (raw HTTP) with tool schemas
├─ Executes tool calls → feeds results back to Gemini
└─ Repeats until Gemini returns a final text answer
The project is split into components:
| Component | Description |
|---|---|
| Agent Client | CLI tool — connects to MCP servers over SSE, runs the Gemini agentic loop, prints the answer |
| Search MCP Server | Long-running HTTP service exposing a web_search tool (DuckDuckGo) over SSE |
| Coderunner MCP Server | Long-running HTTP service exposing a run_python execution tool over SSE |
- Python 3.12+
uvpackage manager- A Gemini API key
# Install all workspace dependencies
uv sync
# Set your Gemini API key
export GEMINI_API_KEY="your-key-here"Start the MCP servers before running the client. In separate terminals:
# Terminal 1 — start the Search MCP server (port 8000)
uv run python -m server_web_search.src.main
# Terminal 2 — start the Coderunner MCP server (port 8002)
uv run python -m server_coderunner.src.main# Terminal 3 — ask a question
uv run python -m client.src.main "What is the Model Context Protocol?"
# Verbose — see full Gemini JSON and tool results
uv run python -m client.src.main --debug "What is the Model Context Protocol?"agentic-web-search/
├── client/ # Agent client (Gemini loop + CLI)
├── server_web_search/ # DuckDuckGo MCP server (SSE/HTTP)
├── server_coderunner/ # Python code runner MCP server (SSE/HTTP)
└── docs/ # Architecture and design docs
For detailed usage of each component, see their individual READMEs: