【Agent】【tools】6.LlamaIndex + MCP Usage

案例目标本案例展示了如何使用LlamaIndex与MCP(Model Context Protocol)集成实现以下目标从MCP服务器获取工具并集成到LlamaIndex应用中将LlamaIndex工作流转换为MCP应用程序使用MCP客户端与服务器进行交互实现OAuth 2.0认证保护MCP连接管理MCP资源、提示和工具技术栈与核心依赖llama-index-tools-mcpModel Context Protocol (MCP)BasicMCPClientFastMCPOAuth 2.0TokenStorage本案例主要使用llama-index-tools-mcp包它提供了多个工具用于在LlamaIndex中使用MCP包括客户端连接、工具获取、工作流转换等功能。环境配置1安装依赖包%pip install llama-index-tools-mcp2安装MCP CLI可选pip install mcp[cli]如果需要从命令行启动MCP服务器需要安装MCP CLI工具。案例实现1. 从MCP服务器获取工具使用get_tools_from_mcp_url或aget_tools_from_mcp_url函数可以从MCP服务器获取FunctionTool列表。from llama_index.tools.mcp import (get_tools_from_mcp_url,aget_tools_from_mcp_url,)# 异步方式tools await aget_tools_from_mcp_url(http://127.0.0.1:8000/mcp)默认情况下这将使用BasicMCPClient它会运行命令或连接到URL并返回工具。也可以传入自定义的ClientSession来使用不同的客户端。from llama_index.tools.mcp import BasicMCPClientclient BasicMCPClient(http://127.0.0.1:8000/mcp)tools await aget_tools_from_mcp_url(http://127.0.0.1:8000/mcp,clientclient,allowed_tools[tool1, tool2],)2. 将工作流转换为MCP应用如果有自定义的Workflow可以使用workflow_as_mcp函数将其转换为MCP应用。from llama_index.core.workflow import (Context,Workflow,Event,StartEvent,StopEvent,step,)from llama_index.tools.mcp.utils import workflow_as_mcpclass RunEvent(StartEvent):msg: strclass InfoEvent(Event):msg: strclass LoudWorkflow(Workflow):Useful for converting strings to uppercase and making them louder.stepdef step_one(self, ctx: Context, ev: RunEvent) - StopEvent:ctx.write_event_to_stream(InfoEvent(msgHello, world!))return StopEvent(resultev.msg.upper() !)workflow LoudWorkflow()mcp workflow_as_mcp(workflow)这段代码将自动生成一个FastMCP服务器该服务器将使用工作流类名作为工具名称使用自定义的RunEvent作为工具的输入类型自动使用SSE流来传输工作流事件流的JSON转储如果这段代码在一个名为script.py的脚本中可以使用以下命令启动MCP服务器mcp dev script.py可以通过向workflow_as_mcp函数传递额外参数来进一步自定义FastMCP服务器workflow_name: 工作流名称默认为类名workflow_description: 工作流描述默认为类文档字符串start_event_model: 用于开始事件的事件模型**fastmcp_init_kwargs: 传递给FastMCP()服务器构造函数的额外参数3. MCP客户端使用BasicMCPClient提供了对MCP服务器功能的全面访问而不仅仅是工具。基本客户端操作from llama_index.tools.mcp import BasicMCPClient# 使用不同传输方式连接到MCP服务器http_client BasicMCPClient(https://example.com/mcp) # 可流式传输的HTTPsse_client BasicMCPClient(https://example.com/sse) # 服务器发送事件local_client BasicMCPClient(python, args[server.py]) # stdio# 列出可用工具tools await http_client.list_tools()# 调用工具result await http_client.call_tool(calculate, {x: 5, y: 10})# 列出可用资源resources await http_client.list_resources()# 读取资源content, mime_type await http_client.read_resource(config://app)# 列出可用提示prompts await http_client.list_prompts()# 获取提示prompt_result await http_client.get_prompt(greet, {name: World})4. OAuth认证客户端支持OAuth 2.0认证用于连接到受保护的MCP服务器。from llama_index.tools.mcp import BasicMCPClient# 使用内存令牌存储的简单认证client BasicMCPClient.with_oauth(https://api.example.com/mcp,client_nameMy App,redirect_uris[http://localhost:3000/callback],# 处理重定向URL的函数例如打开浏览器redirect_handlerlambda url: print(fPlease visit: {url}),# 从用户获取授权码的函数callback_handlerlambda: (input(Enter the code: ), None),)# 使用已认证的客户端tools await client.list_tools()默认情况下如果没有提供token_storage客户端将使用内存令牌存储。可以传入自定义的TokenStorage实例来使用不同的存储。自定义令牌存储实现from llama_index.tools.mcp import BasicMCPClientfrom mcp.client.auth import TokenStoragefrom mcp.shared.auth import OAuthToken, OAuthClientInformationFullfrom typing import Optionalclass DefaultInMemoryTokenStorage(TokenStorage):Simple in-memory token storage implementation for OAuth authentication.This is the default storage used when none is provided to with_oauth().Not suitable for production use across restarts as tokens are onlystored in memory.def __init__(self):self._tokens: Optional[OAuthToken] Noneself._client_info: Optional[OAuthClientInformationFull] Noneasync def get_tokens(self) - Optional[OAuthToken]:Get the stored OAuth tokens.return self._tokensasync def set_tokens(self, tokens: OAuthToken) - None:Store OAuth tokens.self._tokens tokensasync def get_client_info(self) - Optional[OAuthClientInformationFull]:Get the stored client information.return self._client_infoasync def set_client_info(self, client_info: OAuthClientInformationFull) - None:Store client information.self._client_info client_info# 使用自定义存储client BasicMCPClient.with_oauth(https://api.example.com/mcp,client_nameMy App,redirect_uris[http://localhost:3000/callback],redirect_handlerlambda url: print(fPlease visit: {url}),callback_handlerlambda: (input(Enter the code: ), None),token_storageDefaultInMemoryTokenStorage(),)案例效果本案例实现了LlamaIndex与MCP的全面集成具有以下效果能够从远程MCP服务器获取工具并在本地使用支持将LlamaIndex工作流转换为MCP服务器应用提供多种传输方式连接MCP服务器HTTP、SSE、stdio支持OAuth 2.0认证保护MCP连接能够管理MCP资源、提示和工具支持自定义令牌存储实现提供完整的客户端API用于与MCP服务器交互关键点MCP(Model Context Protocol)是一种标准化协议允许AI应用程序与外部工具和数据源进行交互。通过LlamaIndex与MCP的集成开发者可以轻松地扩展AI应用的功能访问各种外部服务和资源。案例实现思路本案例的实现思路基于以下几个关键概念1协议标准化通过MCP协议标准化AI应用与外部工具的交互方式使不同系统之间可以无缝集成。2客户端-服务器架构采用客户端-服务器架构客户端连接到MCP服务器获取工具、资源和提示服务器提供这些功能。3多种传输方式支持多种传输方式HTTP、SSE、stdio适应不同的部署场景和安全需求。4认证与安全通过OAuth 2.0认证机制保护MCP连接确保只有授权的客户端可以访问服务器资源。5工作流转换提供将LlamaIndex工作流转换为MCP应用的功能使开发者可以轻松地将现有工作流暴露为MCP服务。扩展建议基于本案例可以考虑以下扩展方向持久化令牌存储实现持久化令牌存储如数据库或文件存储提高生产环境中的可用性高级认证机制集成更高级的认证机制如JWT、SAML等满足企业级安全需求工具过滤与分类实现更复杂的工具过滤和分类机制便于管理和使用大量工具缓存机制添加工具和资源缓存机制提高性能和减少网络请求错误处理与重试增强错误处理和重试机制提高系统的健壮性监控与日志添加详细的监控和日志记录功能便于调试和性能优化批量操作支持批量工具调用和资源操作提高效率自定义传输协议实现自定义传输协议适应特定的网络环境和安全要求总结本案例展示了如何使用LlamaIndex与MCP(Model Context Protocol)集成实现AI应用与外部工具和资源的标准化交互。通过llama-index-tools-mcp包开发者可以轻松地从MCP服务器获取工具、将工作流转换为MCP应用并使用OAuth 2.0认证保护连接。MCP协议为AI应用提供了一种标准化的方式来访问外部工具和数据源使不同系统之间可以无缝集成。这种标准化方法大大简化了AI应用的开发提高了代码的可重用性和可维护性。该案例的代码示例全面且实用涵盖了从基本工具获取到高级认证的各种场景为开发者提供了完整的参考实现。