Projeto Typedb-MCP-Server

Este projeto implementa um servidor Model Context Protocol (MCP) de alta performance em Rust, projetado para atuar como uma ponte segura e eficiente entre clientes MCP (incluindo Grandes Modelos de Linguagem - LLMs) e um backend de banco de dados TypeDB. Ele permite que clientes interajam com o TypeDB de forma padronizada, acessando dados, manipulando esquemas e administrando bancos de dados através do protocolo MCP baseado em JSON-RPC sobre WebSocket.

Principais Funcionalidades

• Gateway MCP para TypeDB: Traduz requisições do protocolo MCP para operações nativas no TypeDB.
• Comunicação via WebSocket: Utiliza WebSocket como transporte principal para sessões interativas.
• Segurança: Suporta TLS (HTTPS/WSS) e autenticação de cliente opcional via OAuth2/JWT com validação de escopos.
• Observabilidade: Expõe métricas no formato Prometheus e suporta tracing distribuído com OpenTelemetry.
• Gerenciamento de Bancos de Dados: Ferramentas MCP para criar, listar, verificar a existência e deletar bancos TypeDB.
• Operações de Esquema: Ferramentas MCP para definir, remover definições e obter o esquema TypeDB.
• Consultas de Dados: Ferramentas MCP para executar queries TypeQL de leitura, inserção, deleção e atualização.
• Recursos e Templates: Expõe recursos informativos estáticos (como guias de TypeQL) e templates para recursos dinâmicos (como o esquema de um banco de dados).
• Configurabilidade Flexível: Configuração via arquivo TOML e variáveis de ambiente.

Instalação

A forma mais recomendada para iniciar rapidamente é utilizando Docker Compose:

1. Clone o repositório do GitHub.
2. Navegue até o diretório do projeto clonado.
3. Certifique-se de ter o Docker e Docker Compose instalados e em execução.
4. Configure a senha do seu TypeDB (se aplicável) através de uma variável de ambiente 'TYPEDB_PASSWORD' em um arquivo '.env' na raiz do projeto (consulte '.env.example').
5. Execute 'docker-compose up -d --build' para construir e iniciar o servidor MCP e uma instância TypeDB de teste.

Alternativamente, você pode compilar e executar a partir do código-fonte Rust (requer Rust 1.87+ e um TypeDB Server acessível):

1. Clone o repositório.
2. Navegue até o diretório do projeto.
3. Exporte a variável de ambiente 'TYPEDB_PASSWORD' se o seu TypeDB exigir autenticação.
4. Compile o projeto com 'cargo build --release'.
5. Execute o binário gerado em 'target/release/typedb_mcp_server'.

Configuração do Servidor (para Clientes MCP)

Um cliente MCP precisa saber como se conectar a este servidor. A configuração para o cliente dependerá do transporte e se a segurança está habilitada.

Assumindo que o servidor está rodando localmente (via Docker Compose padrão ou binário com config padrão):

• Protocolo: WebSocket
• URL do Endpoint MCP: 'ws://localhost:8788/mcp/ws'
  • Se TLS (HTTPS/WSS) estiver habilitado no servidor MCP: 'wss://localhost:8444/mcp/ws'
• Autenticação (Opcional): Se OAuth2 estiver habilitado no servidor, o cliente precisará enviar um token JWT válido no cabeçalho 'Authorization: Bearer <token>'.

Um exemplo conceitual de como um cliente MCP (como um framework LLM) poderia configurar a conexão JSON (sem mostrar código):

{
  // Nome amigável para o servidor (para exibição no cliente)
  "name": "TypeDB MCP Server Local",

  // Tipo de transporte utilizado
  "transport": {
    // O transporte é WebSocket
    "type": "websocket",
    // A URL completa para se conectar ao endpoint MCP no servidor
    "url": "ws://localhost:8788/mcp/ws" 
    // Se o servidor MCP usar TLS (WSS), a URL seria: "wss://localhost:8444/mcp/ws"
  },

  // Configuração de autenticação (Opcional - incluir apenas se o servidor MCP exigir OAuth2)
  "auth": {
    // Tipo de autenticação
    "type": "bearer_token",
    // O token Bearer a ser usado. O cliente LLM/aplicação deve obter este token
    // do provedor de identidade configurado no servidor MCP (via oauth.jwks_uri).
    // ESTE CAMPO DEVE SER GERADO DINAMICAMENTE PELO CLIENTE COM UM TOKEN VÁLIDO.
    "token": "<SEU_TOKEN_JWT_VALIDO_AQUI>" 
  },

  // Informações adicionais sobre as capacidades ou provedor do servidor (Opcional)
  // O cliente tipicamente obtém isso via requisição 'initialize' após a conexão.
  "serverInfo": {
     "name": "Typedb-MCP-Server",
     "version": "X.Y.Z" // Versão do servidor
  }
}

Nota: A URL exata e a porta dependem da configuração 'server.bind_address', 'server.mcp_websocket_path' e 'server.tls_enabled' no arquivo de configuração TOML do servidor.

Uso Básico

Uma vez que o servidor esteja rodando e o cliente MCP (como um framework de ferramentas para LLMs) esteja configurado para conectar-se a ele:

1. Inicialização: O cliente estabelece a conexão WebSocket e envia a requisição MCP 'initialize' para obter as capacidades do servidor.
2. Listagem de Ferramentas/Recursos: O cliente pode chamar 'tools/list' para descobrir as ferramentas disponíveis (query_read, define_schema, etc.) e 'resources/list' / 'resources/templates/list' para descobrir recursos informativos.
3. Chamada de Ferramentas: O cliente envia requisições 'tools/call' especificando o 'name' da ferramenta desejada e os 'arguments' necessários (ex: 'database_name', 'query'). O servidor executa a operação no TypeDB e retorna o resultado ou erro via JSON-RPC.
4. Leitura de Recursos: O cliente envia requisições 'resources/read' com a 'uri' do recurso desejado (estático ou dinâmico) para obter seu conteúdo.