使用说明

项目简介

本项目 'llamacloud-mcp' 提供了一个基于 LlamaCloud 和 LlamaIndex 的 Model Context Protocol (MCP) 服务器的示例。它展示了如何利用 LlamaCloud 托管的索引作为数据资源，并通过 MCP 协议以工具的形式提供给支持 MCP 协议的 LLM 客户端，例如 Claude Desktop。本示例主要关注如何将 LlamaIndex 的 RAG (Retrieval-Augmented Generation) 能力通过 MCP 服务器暴露出来，供 LLM 客户端调用。

主要功能点

工具注册与执行: 通过 '@mcp.tool()' 装饰器注册工具函数 'llama_index_documentation'，该工具能够查询 LlamaCloud 上的 LlamaIndex 索引，实现 RAG 功能。
资源访问: 工具函数内部集成了 LlamaCloudIndex，实现了对 LlamaCloud 托管索引的数据访问。
MCP 服务器运行: 提供 'mcp-server.py' 和 'mcp-http-server.py' 两个脚本，分别支持 'stdio' 和 'SSE' 两种传输协议，可以根据 LLM 客户端的需求选择合适的服务器运行方式。
客户端集成示例: 提供 'mcp-client.py' 演示了如何使用 LlamaIndex 作为 MCP 客户端，连接到 MCP 服务器并调用工具。
Claude Desktop 集成: 详细介绍了如何配置 Claude Desktop 连接到本地运行的 MCP 服务器，并调用 RAG 工具。

安装步骤

克隆仓库: 将 'llamacloud-mcp' 仓库克隆到本地。
安装依赖: 仓库中没有明确的依赖管理文件，但根据 'README.md' 中的 Claude Desktop 配置，推测可能使用 'poetry' 进行依赖管理。建议先安装 'poetry'，然后在仓库根目录下执行 'poetry install' 安装项目依赖。如果无法使用 'poetry'，可以尝试使用 'pip install -r requirements.txt' （如果仓库中有 'requirements.txt' 文件，但实际仓库中没有，根据代码内容推测可能需要安装 'dotenv', 'mcp-server', 'llama-index' 等相关库）。
配置环境变量: 创建 '.env' 文件，并添加以下环境变量：
- 'LLAMA_CLOUD_API_KEY': 您的 LlamaCloud API 密钥。
- 'OPENAI_API_KEY': 您的 OpenAI API 密钥 (用于驱动 RAG 查询，可以选择其他 LLM)。
- 请确保您已在 LlamaCloud 上创建索引并获取 API 密钥。

服务器配置

针对 Claude Desktop 客户端，需要配置 'stdio' 传输协议的 MCP 服务器。 在 Claude Desktop 的配置文件 ('config.json') 中，'mcpServers' 字段下添加如下配置：

{
    "mcpServers": {
        "llama_index_docs_server": {  // 服务器名称，在 Claude Desktop 中显示
            "command": "poetry",      // 启动服务器的命令，这里假设使用 poetry
            "args": [                 // 命令参数
                "--directory",        // poetry 命令的参数，指定工作目录
                "$YOURPATH/llamacloud-mcp", //  替换为仓库的实际本地路径
                "run",                // poetry 命令的参数，运行脚本
                "python",             // 运行 python 脚本
                "$YOURPATH/llamacloud-mcp/mcp-server.py" // 替换为 mcp-server.py 脚本的实际路径
            ]
        }
    }
}

注意:

请将 '$YOURPATH/llamacloud-mcp' 替换为您克隆仓库的实际本地路径。
如果未使用 'poetry'，'command' 和 'args' 需要相应调整，例如直接使用 'python' 命令启动 'mcp-server.py'。
配置完成后，务必重启 Claude Desktop 使配置生效。

针对 HTTP 客户端 (例如 'mcp-client.py')，可以使用 'SSE' 传输协议的 MCP 服务器。 无需额外配置，直接运行 'mcp-http-server.py' 即可，默认监听 8000 端口。

基本使用方法

启动 MCP 服务器:
- stdio 传输 (Claude Desktop): 在仓库根目录下，根据 Claude Desktop 配置的 'command' 和 'args' 启动 'mcp-server.py'。例如，如果配置使用 'poetry'，则可能无需手动启动，Claude Desktop 会自动启动。如果直接使用 'python' 命令，则在终端中执行 'python mcp-server.py'。
- SSE 传输 (HTTP 客户端): 在仓库根目录下，执行 'poetry run python mcp-http-server.py' 或 'python mcp-http-server.py' (取决于是否使用 poetry)。
配置 MCP 客户端:
- Claude Desktop: 按照 “服务器配置” 章节配置 'config.json' 文件并重启 Claude Desktop。配置成功后，在 Claude Desktop 的输入框下方应该能看到工具图标，并列出配置的服务器名称 "llama_index_docs_server"。
- 'mcp-client.py': 直接运行 'python mcp-client.py'，该脚本会连接到默认地址 'http://localhost:8000/sse' 的 MCP 服务器并调用工具。
使用工具:
- Claude Desktop: 在 Claude Desktop 中，选择配置的工具 "llama_index_docs_server"，然后在输入框中输入问题，Claude Desktop 将会调用 MCP 服务器提供的工具进行查询，并利用 RAG 能力回答问题。
- 'mcp-client.py': 脚本会自动运行一个 Agent，调用 MCP 服务器提供的工具回答问题 "How do I instantiate an agent in LlamaIndex?"，并在终端输出结果。

关键词