Skip to content
Snippets Groups Projects
Unverified Commit 08740a62 authored by Logan's avatar Logan Committed by GitHub
Browse files

improve MCP README (#18080)

parent b0f1342d
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
llama-index-integrations/tools/llama-index-tools-mcp/README.md
+ 45
− 0
View file @ 08740a62
......@@ -4,8 +4,53 @@ This tool connects to MCP Servers and allows an Agent to call the tools provided
This idea is migrated from [Integrate MCP Tools into LlamaIndex](https://psiace.me/posts/integrate-mcp-tools-into-llamaindex/).
## Installation
```bash
pip install llama-index-tools-mcp
```
## Usage
Usage is as simple as connecting to an MCP Server and getting the tools.
```python
from llama_index.tools.mcp import BasicMCPClient, McpToolSpec
# We consider there is a mcp server running on 127.0.0.1:8000, or you can use the mcp client to connect to your own mcp server.
mcp_client = BasicMCPClient("http://127.0.0.1:8000/sse")
mcp_tool_spec = McpToolSpec(
client=mcp_client,
# Optional: Filter the tools by name
# allowed_tools=["tool1", "tool2"],
)
# sync
tools = mcp_tool_spec.to_tool_list()
# async
tools = await mcp_tool_spec.to_tool_list_async()
```
Then you can use the tools in your agent!
```python
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
agent = FunctionAgent(
name="Agent",
description="Some description",
llm=OpenAI(model="gpt-4o"),
tools=tools,
system_prompt="You are a helpful assistant.",
)
resp = await agent.run("What is the weather in Tokyo?")
```
## Notebook Example
This tool has a more extensive example usage documented in a Jupyter notebook [here](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/tools/llama-index-tools-mcp/examples/mcp.ipynb).
This tool is designed to be used as a way to call the tools provided by MCP Servers.
llama-index-integrations/tools/llama-index-tools-mcp/examples/mcp.ipynb
+ 6
− 4
View file @ 08740a62
%% Cell type:markdown id:99eee7a2 tags:
# MCP ToolSpec
This tool connects to MCP Servers and allows an Agent to call the tools provided by MCP Servers.
This idea is migrated from [Integrate MCP tools into LlamaIndex](https://psiace.me/posts/integrate-mcp-tools-into-llamaindex/).
To run this example, you need to edit the .env file to set the correct values for the [IPInfo API Token](https://ipinfo.io/signup) and a [OpenAI API key](https://platform.openai.com/api-keys).
```bash
# get the code
git clone https://github.com/run-llama/llama_index
cd llama_index/llama-index-integrations/tools/llama-index-tools-mcp/examples
# install dependencies
pip install ipinfo
cp .env.example .env
# NOTE: edit the .env file to have the correct values!
# run the server
python mcp_server.py --server_type=sse
```
%% Cell type:markdown id:d8f6ef6b tags:
In this example, we will create a toy example with an agent that can query the ip info of the user.
It's built using the `AgentWorkflow` class from LlamaIndex. If that's new to you, you can [read more about it](https://docs.llamaindex.ai/en/stable/examples/agent/agent_workflow_basic/)!
%% Cell type:code id:30e6088f tags:
``` python
from llama_index.llms.openai import OpenAI
import dotenv
dotenv.load_dotenv()
llm = OpenAI(model="gpt-4o")
```
%% Cell type:code id:f519717e-c620-4e32-9729-99740b648556 tags:
``` python
from llama_index.tools.mcp import McpToolSpec
from llama_index.core.agent.workflow import AgentWorkflow, ToolCallResult, ToolCall
from llama_index.core.agent.workflow import FunctionAgent, ToolCallResult, ToolCall
from llama_index.core.workflow import Context
SYSTEM_PROMPT = """\
You are an AI assistant.
Before you help a user, you need to fetch the ip info first, to help you follow the laws of the country.
"""
async def get_agent(tools: McpToolSpec):
tools = await tools.to_tool_list_async()
agent = AgentWorkflow.from_tools_or_functions(
list(tools),
agent = FunctionAgent(
name="Agent",
description="An agent that can fetch the ip info of the user.",
tools=tools,
llm=llm,
system_prompt=SYSTEM_PROMPT,
)
return agent
async def handle_user_message(
message_content: str,
agent: AgentWorkflow,
agent: FunctionAgent,
agent_context: Context,
verbose: bool = False,
):
handler = agent.run(message_content, ctx=agent_context)
async for event in handler.stream_events():
if verbose and type(event) == ToolCall:
print(f"Calling tool {event.tool_name} with kwargs {event.tool_kwargs}")
elif verbose and type(event) == ToolCallResult:
print(f"Tool {event.tool_name} returned {event.tool_output}")
response = await handler
return str(response)
```
%% Cell type:code id:9a69bdec tags:
``` python
from llama_index.tools.mcp import BasicMCPClient, McpToolSpec
# We consider there is a mcp server running on 127.0.0.1:8000, or you can use the mcp client to connect to your own mcp server.
mcp_client = BasicMCPClient("http://127.0.0.1:8000/sse")
mcp_tool = McpToolSpec(client=mcp_client)
# get the agent
agent = await get_agent(mcp_tool)
# create the agent context
agent_context = Context(agent)
```
%% Cell type:code id:db33a67f tags:
``` python
# Run the agent!
while True:
user_input = input("Enter your message: ")
if user_input == "exit":
break
print("User: ", user_input)
response = await handle_user_message(user_input, agent, agent_context, verbose=True)
print("Agent: ", response)
```
%% Output
User: Hello! I need some help with my homework
Calling tool fetch_ipinfo with kwargs {'kwargs': ''}
Tool fetch_ipinfo returned meta=None content=[TextContent(type='text', text='{"ip": "71.17.163.153", "hostname": "71-17-163-153.regn.hsdb.sasknet.sk.ca", "city": "Regina", "region": "Saskatchewan", "country": "CA", "loc": "50.4501,-104.6178", "timezone": "America/Regina"}')] isError=False
Agent: Hello! How can I assist you with your homework?
%% Cell type:markdown id:79c44895 tags:
Here, we can see the agent is calling the `fetch_ipinfo` tool to get the ip info! This tool is running remotely on the mcp server.
The `MCPToolSpec` is connecting to the MCP server and creating `FunctionTool`s for each tool that is registered on the MCP server.
%% Cell type:code id:7a84adf7 tags:
``` python
tools = await mcp_tool.to_tool_list_async()
for tool in tools:
print(tool.metadata.name, tool.metadata.description)
```
%% Output
fetch_ipinfo Get the detailed information of a specified IP address
Args:
ip(str or None): The IP address to get information for. Follow the format like 192.168.1.1 .
**kwargs: Additional keyword arguments to pass to the IPInfo handler.
Returns:
IPDetails: The detailed information of the specified IP address.
%% Cell type:markdown id:33e7be78 tags:
You can also limit the tools that the `MCPToolSpec` will create by passing a list of tool names to the `MCPToolSpec` constructor.
%% Cell type:code id:4929af70 tags:
``` python
mcp_tool = McpToolSpec(client=mcp_client, allowed_tools=["some fake tool"])
tools = await mcp_tool.to_tool_list_async()
for tool in tools:
print(tool.metadata.name, tool.metadata.description)
```
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment

:feet::heart: Strive to be the person your dogs believe you are :heart::feet: