LlamaIndex MCP demos

Expor os serviços LlamaCloud como ferramentas MCP para construir e gerenciar aplicações LLM.

GitHub
225

Documentação

[!CAUTION] Este repositório foi arquivado e não é mais suportado. Consulte nossa documentação para obter as informações mais recentes sobre como conectar seus agentes às APIs da Plataforma LlamaParse.

LlamaIndex MCP demos

llamacloud-mcp é uma ferramenta que permite usar o LlamaCloud como um servidor MCP. Ela pode ser usada para consultar índices do LlamaCloud e extrair dados de arquivos.

Ela permite:

  • especificar um ou mais índices para usar na recuperação de contexto.
  • especificar um ou mais agentes de extração para usar na extração de dados
  • configurar IDs de projeto e organização
  • configurar o transporte a ser usado para o servidor MCP (stdio, sse, streamable-http)

Começando

  1. Instale uv
  2. Execute uvx llamacloud-mcp@latest --help para ver as opções disponíveis.
  3. Configure seu cliente MCP para usar o servidor llamacloud-mcp. Você pode iniciar o servidor diretamente com uvx llamacloud-mcp@latest ou usar um arquivo claude_desktop_config.json para conectar com o claude desktop.

Uso

% uvx llamacloud-mcp@latest --help
Usage: llamacloud-mcp [OPTIONS]

Options:
  --index TEXT                    Index definition in the format
                                  name:description. Can be used multiple
                                  times.
  --extract-agent TEXT            Extract agent definition in the format
                                  name:description. Can be used multiple
                                  times.
  --project-id TEXT               Project ID for LlamaCloud
  --org-id TEXT                   Organization ID for LlamaCloud
  --transport [stdio|sse|streamable-http]
                                  Transport to run the MCP server on. One of
                                  "stdio", "sse", "streamable-http".
  --api-key TEXT                  API key for LlamaCloud
  --help                          Show this message and exit.

Configurar o Claude Desktop

  1. Instale o Claude Desktop
  2. Na barra de menus, escolha Claude -> Settings -> Developer -> Edit Config. Isso exibirá um arquivo de configuração que você pode editar no seu editor de texto preferido.
  3. Crie e adicione os seguintes "mcpServers" ao arquivo de configuração, onde cada --index é uma nova ferramenta de índice que você define, e cada --extract-agent é uma ferramenta de agente de extração.
  4. Você vai querer que sua configuração fique mais ou menos assim (certifique-se de substituir $YOURPATH pelo caminho para o repositório):
{
    "mcpServers": {
        "llama_index_docs_server": {
            "command": "uvx",
            "args": [
                "llamacloud-mcp@latest",
                "--index",
                "your-index-name:Description of your index",
                "--index",
                "your-other-index-name:Description of your other index",
                "--extract-agent",
                "extract-agent-name:Description of your extract agent",
                "--project-name",
                "<Your LlamaCloud Project Name>",
                "--org-id",
                "<Your LlamaCloud Org ID>",
                "--api-key",
                "<Your LlamaCloud API Key>"
            ]
        },
        "filesystem": {
        "command": "npx",
        "args": [
                "-y",
                "@modelcontextprotocol/server-filesystem",
                "<your directory you want filesystem tool to have access to>"
            ]
        }
    }
}

Certifique-se de reiniciar o Claude Desktop após configurar o arquivo.

Agora você está pronto para consultar! Você deve ver um ícone de ferramenta com seu servidor listado abaixo da caixa de consulta no Claude Desktop, assim:

LlamaCloud como servidor MCP do zero

Para fornecer um servidor MCP local que possa ser usado por um cliente como o Claude Desktop, você pode usar mcp-server.py. Você pode usar isso para fornecer uma ferramenta que usará RAG para fornecer ao Claude informações privadas atualizadas ao segundo que ele pode usar para responder perguntas. Você pode fornecer quantas dessas ferramentas quiser.

Configure seu índice LlamaCloud

  1. Obtenha uma conta LlamaCloud
  2. Crie um novo índice com qualquer fonte de dados que desejar. No nosso caso, usamos o Google Drive e fornecemos um subconjunto da documentação do LlamaIndex como fonte. Você também pode enviar documentos diretamente para o índice se quiser apenas testá-lo.
  3. Obtenha uma chave de API na interface do LlamaCloud

Configure seu servidor MCP

  1. Clone este repositório
  2. Crie um arquivo .env e adicione duas variáveis de ambiente:
    • LLAMA_CLOUD_API_KEY - A chave de API que você obteve na etapa anterior
    • OPENAI_API_KEY - Uma chave de API da OpenAI. Ela é usada para alimentar a consulta RAG. Você pode usar qualquer outro LLM se não quiser usar a OpenAI.

Agora vamos olhar o código. Primeiro você instancia um servidor MCP:

mcp = FastMCP('llama-index-server')

Em seguida, você define sua ferramenta usando o decorador @mcp.tool():

@mcp.tool()
def llama_index_documentation(query: str) -> str:
    """Search the llama-index documentation for the given query."""

    index = LlamaCloudIndex(
        name="mcp-demo-2",
        project_name="Rando project",
        organization_id="e793a802-cb91-4e6a-bd49-61d0ba2ac5f9",
        api_key=os.getenv("LLAMA_CLOUD_API_KEY"),
    )

    response = index.as_query_engine().query(query + " Be verbose and include code examples.")

    return str(response)

Aqui nossa ferramenta é chamada de llama_index_documentation; ela instancia um índice LlamaCloud chamado mcp-demo-2 e então o usa como mecanismo de consulta para responder à pergunta, incluindo algumas instruções extras no prompt. Você receberá instruções sobre como configurar seu índice LlamaCloud na próxima seção.

Por fim, você executa o servidor:

if __name__ == "__main__":
    mcp.run(transport="stdio")

Observe o transporte stdio, usado para comunicação com o Claude Desktop.

LlamaIndex como cliente MCP

O LlamaIndex também tem uma integração de cliente MCP, o que significa que você pode transformar qualquer servidor MCP em um conjunto de ferramentas que podem ser usadas por um agente. Você pode ver isso em mcp-client.py, onde usamos o BasicMCPClient para conectar ao nosso servidor MCP local.

Para simplificar a demonstração, estamos usando o mesmo servidor MCP que configuramos acima. Normalmente, você não usaria MCP para conectar o LlamaCloud a um agente LlamaIndex; você usaria QueryEngineTool e o passaria diretamente ao agente.

Configure seu servidor MCP

Para fornecer um servidor MCP local que possa ser usado por um cliente HTTP, precisamos modificar ligeiramente mcp-server.py para usar o método run_sse_async em vez de run. Você pode encontrar isso em mcp-http-server.py.

mcp = FastMCP('llama-index-server',port=8000)

asyncio.run(mcp.run_sse_async())

Obtenha suas ferramentas do servidor MCP

mcp_client = BasicMCPClient("http://localhost:8000/sse")
mcp_tool_spec = McpToolSpec(
    client=mcp_client,
    # Optional: Filter the tools by name
    # allowed_tools=["tool1", "tool2"],
)

tools = mcp_tool_spec.to_tool_list()

Crie um agente e faça uma pergunta

llm = OpenAI(model="gpt-4o-mini")

agent = FunctionAgent(
    tools=tools,
    llm=llm,
    system_prompt="You are an agent that knows how to build agents in LlamaIndex.",
)

async def run_agent():
    response = await agent.run("How do I instantiate an agent in LlamaIndex?")
    print(response)

if __name__ == "__main__":
    asyncio.run(run_agent())

Está tudo pronto! Agora você pode usar o agente para responder perguntas do seu índice LlamaCloud.