Skip to content

Commit 563e212

Browse files
andrewginnsandrewginns
committed
docs: Updates and corrections to repo information
1 parent c294f0b commit 563e212

File tree

3 files changed

+219
-32
lines changed

3 files changed

+219
-32
lines changed

‎README.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,17 +23,20 @@ Tracing is done through Pydantic Logfire.
2323
- [Optional] Add `LOGFIRE_TOKEN` to visualise evaluations in Logfire web ui
2424

2525
Run an Agent framework script e.g.:
26-
- `uv run basic_mcp_use/pydantic_mcp.py` - Requires `GEMINI_API_KEY` by default
26+
- `uv run basic_mcp_use/pydantic_mcp.py`
27+
- Requires `GEMINI_API_KEY` by default
2728

28-
- `uv run basic_mcp_use/oai-agent_mcp.py` - Requires `OPENAI_API_KEY` by default
29+
- `uv run basic_mcp_use/oai-agent_mcp.py`
30+
- Requires `OPENAI_API_KEY` by default
2931

3032
Check console or Logfire for output
3133

3234
## Project Overview
3335

3436
This project aims to teach:
3537
1. How to use MCP with multiple LLM Agent frameworks
36-
- Single MCP server usage and Multi-MCP server usage
38+
- Agent using a single MCP server
39+
- Agent using multi-MCP servers
3740
2. How to see traces LLM Agents with Logfire
3841
3. How to evaluate LLMs with PydanticAI evals
3942

‎agents_mcp_usage/basic_mcp/README.md‎

Lines changed: 89 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,27 @@ This directory contains examples of integrating Model Context Protocol (MCP) wit
44

55
Each script demonstrates how to connect to a single local MCP server and use it with a different agent framework.
66

7+
## Quickstart
8+
9+
1. Configure `.env` and API keys following instructions in the [README.md](README.md)
10+
11+
2. Run any example script:
12+
```bash
13+
# Run the Pydantic-AI example
14+
uv run agents_mcp_usage/basic_mcp/basic_mcp_use/pydantic_mcp.py
15+
16+
# Run the OpenAI Agents example
17+
uv run agents_mcp_usage/basic_mcp/basic_mcp_use/oai-agent_mcp.py
18+
19+
# Run the LangGraph example
20+
uv run agents_mcp_usage/basic_mcp/basic_mcp_use/langgraph_mcp.py
21+
22+
# Run the Google ADK example
23+
uv run agents_mcp_usage/basic_mcp/basic_mcp_use/adk_mcp.py
24+
```
25+
26+
4. Check the console output or Logfire for results.
27+
728
### Basic MCP Architecture
829

930
```mermaid
@@ -58,14 +79,78 @@ graph LR
5879
GEM --> LLM_Response
5980
OTHER --> LLM_Response
6081
61-
style MCP fill:#f9f,stroke:#333,stroke-width:2px
62-
style User fill:#bbf,stroke:#338,stroke-width:2px
63-
style Logfire fill:#bfb,stroke:#383,stroke-width:2px
64-
style LLM_Response fill:#fbb,stroke:#833,stroke-width:2px
82+
%% Node styling for better dark/light mode readability
83+
classDef userNode fill:#b3e0ff,stroke:#0066cc,stroke-width:2px,color:#000000;
84+
classDef agentNode fill:#d1c4e9,stroke:#673ab7,stroke-width:1px,color:#000000;
85+
classDef mcpNode fill:#ffccbc,stroke:#ff5722,stroke-width:2px,color:#000000;
86+
classDef toolNode fill:#ffe0b2,stroke:#ff9800,stroke-width:1px,color:#000000;
87+
classDef llmNode fill:#c8e6c9,stroke:#4caf50,stroke-width:1px,color:#000000;
88+
classDef outputNode fill:#ffcdd2,stroke:#e53935,stroke-width:2px,color:#000000;
89+
classDef logNode fill:#e1bee7,stroke:#8e24aa,stroke-width:2px,color:#000000;
90+
91+
%% Apply styles to nodes
92+
class User,LLM_Response userNode;
93+
class Agent,ADK,LG,OAI,PYD agentNode;
94+
class MCP mcpNode;
95+
class Tools,Resources toolNode;
96+
class OAI_LLM,GEM,OTHER llmNode;
97+
class LLM_Response outputNode;
98+
class Logfire logNode;
6599
```
66100

67101
The diagram illustrates how MCP serves as a standardised interface between different agent frameworks and LLM providers.The flow shows how users interact with the system by running a specific agent script, which then leverages MCP to communicate with LLM providers, while Logfire provides tracing and observability.
68102

103+
### Basic MCP Sequence Flow
104+
105+
```mermaid
106+
sequenceDiagram
107+
participant User
108+
participant Agent as Agent Framework
109+
participant MCP as Python MCP Server
110+
participant LLM as LLM Provider
111+
participant Tools as MCP Tools
112+
participant Logfire as Logfire Tracing
113+
114+
Note over User,Logfire: Basic MCP Interaction Flow
115+
116+
User->>Agent: Run agent script with query
117+
118+
activate Agent
119+
Agent->>Logfire: Start tracing
120+
121+
Agent->>MCP: Initialise connection
122+
activate MCP
123+
MCP-->>Agent: Connection established
124+
125+
Agent->>MCP: Send user query
126+
127+
MCP->>LLM: Generate response/action
128+
activate LLM
129+
130+
loop Tool Use Cycle
131+
LLM-->>MCP: Request tool execution
132+
MCP->>Tools: Execute tool (e.g., add, get_time)
133+
activate Tools
134+
Tools-->>MCP: Return tool result
135+
deactivate Tools
136+
MCP->>LLM: Continue with tool result
137+
end
138+
139+
LLM-->>MCP: Final response
140+
deactivate LLM
141+
142+
MCP-->>Agent: Return response
143+
deactivate MCP
144+
145+
Agent->>Logfire: Log completion
146+
Agent->>User: Display final answer
147+
deactivate Agent
148+
149+
Note over User,Logfire: End of interaction
150+
```
151+
152+
The sequence diagram illustrates the temporal flow of interactions between the user, agent framework, MCP server, LLM provider, and tools. It highlights how the tool execution cycle operates within the MCP architecture.
153+
69154
### Google Agent Development Kit (ADK)
70155

71156
**File:** `adk_mcp.py`

‎agents_mcp_usage/multi_mcp/README.md‎

Lines changed: 124 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,28 @@
1-
21
# Multi-MCP Usage Examples
32

43
This directory contains advanced examples demonstrating the integration of multiple Model Context Protocol (MCP) servers with agent frameworks.
54

6-
Unlike the basic examples that use a single MCP server, these examples show how to connect to and coordinate between multiple specialized MCP servers simultaneously.
5+
Unlike the basic examples that use a single MCP server, these examples show how to connect to and coordinate between multiple specialised MCP servers simultaneously.
6+
7+
8+
## Quickstart
9+
10+
1. Configure `.env` and API keys following instructions in the [README.md](README.md)
11+
12+
3. Ensure the Node.js MCP server can be used:
13+
- Install the Node.js MCP server (mermaid-validator) locally, run `make install` if you haven't already
14+
15+
4. Run an example script:
16+
```bash
17+
# Run the Pydantic-AI multi-MCP example
18+
uv run agents_mcp_usage/multi_mcp/multi_mcp_use/pydantic_mcp.py
19+
20+
# Run the multi-MCP evaluation
21+
uv run agents_mcp_usage/multi_mcp/eval_multi_mcp/evals_pydantic_mcp.py
22+
```
23+
24+
5. Check the console output or Logfire for results.
25+
726

827
### Multi-MCP Architecture
928

@@ -44,9 +63,105 @@ graph LR
4463
4564
LLM_Response[("Response")] --> User
4665
LLMs --> LLM_Response
66+
67+
%% Node styling for better dark/light mode readability
68+
classDef userNode fill:#b3e0ff,stroke:#0066cc,stroke-width:2px,color:#000000;
69+
classDef agentNode fill:#d1c4e9,stroke:#673ab7,stroke-width:2px,color:#000000;
70+
classDef mcpNode fill:#ffccbc,stroke:#ff5722,stroke-width:2px,color:#000000;
71+
classDef pythonMcpNode fill:#ffccbc,stroke:#ff5722,stroke-width:2px,color:#000000;
72+
classDef nodeMcpNode fill:#ffe0b2,stroke:#ff9800,stroke-width:2px,color:#000000;
73+
classDef toolNode fill:#dcedc8,stroke:#8bc34a,stroke-width:1px,color:#000000;
74+
classDef llmNode fill:#c8e6c9,stroke:#4caf50,stroke-width:1px,color:#000000;
75+
classDef outputNode fill:#ffcdd2,stroke:#e53935,stroke-width:2px,color:#000000;
76+
classDef logNode fill:#e1bee7,stroke:#8e24aa,stroke-width:2px,color:#000000;
77+
78+
%% Apply styles to nodes
79+
class User userNode;
80+
class Agent agentNode;
81+
class PythonMCP pythonMcpNode;
82+
class NodeMCP nodeMcpNode;
83+
class Tools,Resources,MermaidValidator toolNode;
84+
class LLMs llmNode;
85+
class LLM_Response outputNode;
86+
class Logfire logNode;
4787
```
4888

49-
This diagram illustrates how an agent can leverage multiple specialized MCP servers simultaneously, each providing distinct tools and resources.
89+
This diagram illustrates how an agent can leverage multiple specialised MCP servers simultaneously, each providing distinct tools and resources.
90+
91+
### Multi-MCP Sequence Flow
92+
93+
```mermaid
94+
sequenceDiagram
95+
participant User
96+
participant Agent as Pydantic-AI Agent
97+
participant PyMCP as Python MCP Server
98+
participant NodeMCP as Node.js MCP Server
99+
participant LLM as LLM Provider
100+
participant PyTools as Python Tools
101+
participant NodeTools as Mermaid Validator
102+
participant Logfire as Logfire Tracing
103+
104+
Note over User,Logfire: Multi-MCP Interaction Flow
105+
106+
User->>Agent: Run script with query
107+
108+
activate Agent
109+
Agent->>Logfire: Start tracing session
110+
111+
par Connect to multiple MCP servers
112+
Agent->>PyMCP: Initialise connection
113+
activate PyMCP
114+
PyMCP-->>Agent: Connection established
115+
116+
Agent->>NodeMCP: Initialise connection
117+
activate NodeMCP
118+
NodeMCP-->>Agent: Connection established
119+
end
120+
121+
Agent->>LLM: Process user query
122+
activate LLM
123+
124+
loop Tool Selection & Execution
125+
alt Python MCP Tools Needed
126+
LLM-->>Agent: Need Python tool
127+
Agent->>PyMCP: Execute tool (e.g., add, get_time)
128+
PyMCP->>PyTools: Call tool function
129+
activate PyTools
130+
PyTools-->>PyMCP: Return result
131+
deactivate PyTools
132+
PyMCP-->>Agent: Tool result
133+
Agent->>LLM: Continue with tool result
134+
else Node.js MCP Tools Needed
135+
LLM-->>Agent: Need Mermaid validation
136+
Agent->>NodeMCP: Validate Mermaid diagram
137+
NodeMCP->>NodeTools: Process diagram
138+
activate NodeTools
139+
NodeTools-->>NodeMCP: Validation result
140+
deactivate NodeTools
141+
NodeMCP-->>Agent: Tool result
142+
Agent->>LLM: Continue with tool result
143+
end
144+
end
145+
146+
LLM-->>Agent: Final response
147+
deactivate LLM
148+
149+
Agent->>Logfire: Log completion
150+
151+
par Close MCP connections
152+
Agent->>PyMCP: Close connection
153+
deactivate PyMCP
154+
Agent->>NodeMCP: Close connection
155+
deactivate NodeMCP
156+
end
157+
158+
Agent->>User: Display final answer
159+
deactivate Agent
160+
161+
Note over User,Logfire: End of interaction
162+
```
163+
164+
The sequence diagram shows how the agent coordinates between multiple specialised MCP servers. It highlights the parallel connection establishment, selective tool usage based on need, and proper connection management.
50165

51166
## Example Files
52167

@@ -61,8 +176,8 @@ uv run agents_mcp_usage/multi_mcp/multi_mcp_use/pydantic_mcp.py
61176
```
62177

63178
Key features:
64-
- Connects to multiple specialized MCP servers simultaneously
65-
- Organizes tools and resources by domain
179+
- Connects to multiple specialised MCP servers simultaneously
180+
- Organises tools and resources by domain
66181
- Shows how to coordinate between different MCP servers
67182
- Includes Logfire instrumentation for comprehensive tracing
68183

@@ -77,34 +192,18 @@ uv run agents_mcp_usage/multi_mcp/eval_multi_mcp/evals_pydantic_mcp.py
77192
```
78193

79194
Key features:
80-
- Evaluates agent performance when using multiple specialized MCP servers
81-
- Uses PydanticAI evaluation tools to measure outcomes
82-
- Compares results with single-MCP approaches
195+
- Evaluates agent performance when using multiple specialised MCP servers
196+
- Uses PydanticAI Agent evaluation to measure success of outcomes
83197
- Generates performance metrics viewable in Logfire
84198

85-
### Mermaid Diagrams Generator
86-
87-
**File:** `mermaid_diagrams.py`
88-
89-
A utility for generating Mermaid diagrams to visualize MCP architecture.
90-
91-
```bash
92-
uv run agents_mcp_usage/multi_mcp/mermaid_diagrams.py
93-
```
94-
95-
Key features:
96-
- Creates visualization of MCP architectures
97-
- Helps understand the flow between agents, MCP servers, and LLMs
98-
- Customizable to represent different configurations
99-
100199
## Benefits of Multi-MCP Architecture
101200

102-
Using multiple specialized MCP servers offers several advantages:
201+
Using multiple specialised MCP servers offers several advantages:
103202

104203
1. **Domain Separation**: Each MCP server can focus on a specific domain or set of capabilities.
105204
2. **Modularity**: Add, remove, or update capabilities without disrupting the entire system.
106205
3. **Scalability**: Distribute load across multiple servers for better performance.
107-
4. **Specialization**: Optimize each MCP server for its specific use case.
206+
4. **Specialisation**: Optimise each MCP server for its specific use case.
108207
5. **Security**: Control access to sensitive tools or data through separate servers.
109208

110209
This approach provides a more flexible and maintainable architecture for complex agent systems.

0 commit comments

Comments
 (0)