How ishanextreme/a2a_mcp-example works
Project type and purpose
• This is a full-stack, microservice-style application: an LLM-powered terminal assistant that allows users to issue natural-language commands which get executed on a Linux host.
• It leverages two backend services (A2A and MCP), a Python demo UI, and a reusable Python SDK to tie them together.
File structure
• Top-level directories:
• client/ – the demo UI app, the a2a-python-sdk, docs, sample code, and test suites
• a2a_server/ – the Agent-to-Agent server (“langgraph” module)
• mcp_server/ – the Model Context Protocol server
• Under client/demo/ui: Python UI code (FastAPI + Uvicorn) that renders pages and components and communicates with both backend services.
• client/a2a-python-sdk: the shared SDK used by the UI (and other clients) to call the A2A and MCP servers.
• a2a_server/langgraph: implements agent orchestration, task management, and OpenAI integration.
• mcp_server/mcp_server.py: implements the MCP protocol endpoint.
README for additional insights
• Three processes must run concurrently:
1. UI Server at http://localhost:12000
2. A2A Server (default port 10000)
3. MCP Server
• The UI allows users to register Linux Agents (at A2A endpoint) and send natural-language requests.
• Built with Python 3.12, FastAPI/Uvicorn, OpenAI GPT, A2A & MCP protocols.
Main components
a. Frontend (Demo UI)
• client/demo/ui/main.py + UI components/pages
• Uses a2a-python-sdk to call backends
b. Agent-to-Agent (A2A) Server
• a2a_server/langgraph/main.py (FastAPI app)
• Subcomponents: Agent, TaskManager, Helpers, StreamingResponseQueue
• Integrates with OpenAI GPT API
• Exposes REST/WebSocket endpoints on port 10000
c. Model Context Protocol (MCP) Server
• mcp_server/mcp_server.py (FastAPI app)
• Provides contextual model calls to OpenAI or other LLM providers
d. Linux Host Execution Environment
• The underlying shell where commands are actually run
e. External Service: OpenAI GPT
• External LLM API used by both A2A and MCP servers
f. (Optional) Python SDK
• client/a2a-python-sdk used by any other client to interact with A2A/MCP
Relationships and interactions
1. User in Browser → Demo UI (HTTP/WebSocket)
2. Demo UI → A2A Server (via a2a-python-sdk)
3. A2A Server → OpenAI GPT (for planning and interpretation)
4. A2A Server → Linux Shell (executes commands)
5. Demo UI → MCP Server (via a2a-python-sdk) for context-aware LLM calls
6. MCP Server → OpenAI GPT
Architectural patterns and design principles
• Microservice separation: UI, A2A, MCP as independent FastAPI services
• SDK abstraction: a2a-python-sdk provides a uniform client API
• Agent orchestration: A2A uses an internal task manager pattern
• Asynchronous streams: StreamingResponseQueue for real-time UI updates