Typedb-MCP-Server

Servidor Rust de alta performance, seguro e extensível, atuando como gateway MCP (Model Context Protocol) para o banco de dados TypeDB. Expõe endpoints WebSocket (MCP), HTTP REST para métricas Prometheus, integra autenticação OAuth2 opcional, tracing distribuído (OpenTelemetry) e métricas detalhadas.

Este projeto visa fornecer uma ponte robusta e eficiente entre clientes que utilizam o Model Context Protocol e um backend TypeDB, com foco em segurança, observabilidade e extensibilidade, permitindo que aplicações, incluindo Modelos de Linguagem de Grande Escala (LLMs), interajam de forma padronizada com o TypeDB.

Índice

• Typedb-MCP-Server
  • Índice
  • Visão Geral
  • Principais Funcionalidades
  • Status do Projeto
  • Começando
    • Pré-requisitos
    • Instalação
      • Usando Docker (Recomendado para Início Rápido)
      • A partir do Código-Fonte
    • Configuração Essencial
    • Execução
  • Endpoints Principais
  • Segurança
  • Observabilidade
  • Extensibilidade
  • Documentação Completa
  • Contribuição
  • Licença
  • Agradecimentos

Visão Geral

O Typedb-MCP-Server é um componente crucial para arquiteturas que necessitam de interação programática e segura com o TypeDB. Ele implementa o Model Context Protocol, permitindo que diversos tipos de clientes (como LLMs, ferramentas de desenvolvimento ou microsserviços) utilizem um conjunto padronizado de ferramentas para consultar dados, manipular esquemas e administrar o banco de dados.

Construído em Rust, o servidor foi desenvolvido com foco em performance (utilizando Tokio e Axum) e segurança (suporte a TLS e OAuth2).

Principais Funcionalidades

• Gateway MCP para TypeDB: Expõe as funcionalidades do TypeDB através do Model Context Protocol.
• Transporte WebSocket: Comunicação principal via WebSockets (WSS para TLS).
• Segurança Robusta:
  • TLS para o servidor MCP (HTTPS/WSS) e para a conexão com o TypeDB.
  • Autenticação de cliente opcional via OAuth2/JWT, com validação de issuer, audience e escopos.
  • Controle de acesso granular por ferramenta MCP através de escopos OAuth2.
• Observabilidade Abrangente:
  • Métricas detalhadas no formato Prometheus (/metrics).
  • Tracing distribuído com OpenTelemetry (exportação OTLP).
  • Logging JSON estruturado e configurável.
  • Endpoints de Health Check (livez, /readyz).
• Configurabilidade Flexível: Via arquivo TOML e variáveis de ambiente.
• Extensibilidade: Arquitetura modular que facilita a adição de novas ferramentas MCP.
• Suporte a Docker: Dockerfile e exemplos docker-compose para desenvolvimento e implantação.

Status do Projeto

• Versão Atual: 0.1.0 (conforme Cargo.toml)
• Estado: Em desenvolvimento ativo. Funcionalidades principais implementadas, com foco contínuo em estabilidade, segurança e melhorias.
• Consulte as Issues do GitHub para funcionalidades planejadas e problemas conhecidos.

Começando

Pré-requisitos

• Rust: Versão >= 1.87.0 (conforme rust-toolchain.toml).
• TypeDB Server: Instância acessível (v3.2.0 ou compatível).
• Docker & Docker Compose: Recomendado para facilidade de uso.
• Consulte o Guia do Usuário - Pré-requisitos para uma lista detalhada.

Instalação

Usando Docker (Recomendado para Início Rápido)

A forma mais simples de executar o servidor, especialmente para desenvolvimento e testes, é com Docker Compose.

1. Clone o repositório: git clone https://github.com/guilhermeleste/Typedb-MCP-Server.git && cd Typedb-MCP-Server
2. Se o seu TypeDB (serviço typedb-server-dev no docker-compose.yml) exigir senha, crie um arquivo .env na raiz com TYPEDB_PASSWORD=sua_senha_typedb ou exporte a variável.
3. Execute: docker-compose up -d --build

Para mais detalhes, incluindo build multi-plataforma, veja o README.docker.md e a seção de Instalação com Docker.

A partir do Código-Fonte

1. Clone o repositório (se ainda não o fez).
2. Compile: cargo build --release O binário estará em target/release/typedb_mcp_server.

Consulte o Guia de Instalação a partir do Código-Fonte para mais detalhes.

Configuração Essencial

A configuração é feita primariamente via arquivo TOML (padrão: typedb_mcp_server_config.toml) e pode ser sobrescrita ou complementada por variáveis de ambiente.

1. Arquivo de Configuração TOML:

Crie ou utilize o arquivo typedb_mcp_server_config.toml (ou config.dev.toml, config.test.toml dependendo do ambiente).

Exemplo Mínimo (typedb_mcp_server_config.toml):

[typedb]
address = "localhost:1729"  # Endereço do seu TypeDB Server

[server]
bind_address = "0.0.0.0:8787" # Onde o MCP Server escutará

2. Variáveis de Ambiente e Arquivos .env:

Variáveis de ambiente têm precedência sobre as configurações do arquivo TOML. Para facilitar o gerenciamento, especialmente em desenvolvimento local, você pode usar arquivos .env.

• .env.example: Este arquivo serve como um template e documentação para as variáveis de ambiente suportadas. Copie-o para .env.
• .env: Crie este arquivo na raiz do projeto (copiando de .env.example) e preencha com seus valores locais. Este arquivo não deve ser versionado se contiver segredos.

Variáveis de Ambiente Chave:

• TYPEDB_PASSWORD: Obrigatória se o TypeDB usa autenticação.

  export TYPEDB_PASSWORD="sua_senha_typedb"
  # Ou defina em seu arquivo .env:
  # TYPEDB_PASSWORD=sua_senha_typedb
  

  Importante: Nunca coloque TYPEDB_PASSWORD diretamente no arquivo TOML.

• MCP_CONFIG_PATH: Permite especificar um caminho alternativo para o arquivo de configuração TOML.

  export MCP_CONFIG_PATH="config/custom_config.toml"
  # Ou defina em seu arquivo .env:
  # MCP_CONFIG_PATH=config/custom_config.toml
  

• RUST_LOG: Controla o nível de log.

  export RUST_LOG="info,typedb_mcp_server=debug"
  # Ou defina em seu arquivo .env:
  # RUST_LOG=info,typedb_mcp_server=debug
  

Sobrescrevendo Configurações TOML com Variáveis de Ambiente:

Qualquer configuração do arquivo TOML pode ser sobrescrita usando variáveis de ambiente. O formato é MCP_<NOME_DA_SECAO>__<NOME_DO_CAMPO>=<VALOR>.

Exemplos:

• MCP_SERVER__BIND_ADDRESS="127.0.0.1:9000"
• MCP_TYPEDB__ADDRESS="typedb.example.com:1729"
• MCP_AUTH__OAUTH_ENABLED=false

Para todas as opções de configuração e variáveis de ambiente correspondentes, consulte a Referência Completa de Configuração e o arquivo .env.example.

Veja também:

• typedb_mcp_server_config.toml (configuração padrão)
• config.example.toml (template para TOML)
• .env.example (template para variáveis de ambiente)

Execução

Após a instalação e configuração:

• Com Cargo:

  # Exporte TYPEDB_PASSWORD se necessário
  cargo run --release
  

• Binário Compilado:

  # Exporte TYPEDB_PASSWORD se necessário
  ./target/release/typedb_mcp_server
  

• Com Docker Compose: (já mencionado na instalação) docker-compose up

Consulte o Guia do Usuário - Executando o Servidor para mais detalhes.

Endpoints Principais

• WebSocket MCP: ws://<host>:<porta_servidor>/mcp/ws (ou wss:// com TLS). Path configurável via server.mcp_websocket_path.
• Métricas Prometheus: http://<host>:<porta_metricas>/metrics. Path e porta configuráveis.
• Health Checks: livez e /readyz.

Consulte a Referência da API - Endpoints HTTP para detalhes.

Segurança

• TLS: Fortemente recomendado para todas as comunicações em produção (MCP e TypeDB).
• OAuth2/JWT: Autenticação de cliente opcional, com suporte a JWKS, validação de issuer/audience e escopos.
• Gerenciamento de Credenciais: TYPEDB_PASSWORD via variável de ambiente é crucial.
• Limitação de Taxa e CORS: Configuráveis para maior segurança.

Veja mais em Guia do Usuário - Segurança Básica e Referência de Configuração.

Observabilidade

• Métricas: Formato Prometheus, acessível via HTTP. Veja a Lista de Métricas.
• Logging: Logs JSON estruturados e configuráveis via RUST_LOG ou arquivo de configuração.
• Tracing Distribuído: Suporte a OpenTelemetry (OTLP).
• Health Checks: livez para liveness e /readyz para readiness (incluindo dependências).

Detalhes em Guia do Usuário - Observabilidade.

Extensibilidade

Novas ferramentas MCP podem ser adicionadas de forma modular. Consulte o Guia do Desenvolvedor - Adicionando Novas Ferramentas MCP.

Documentação Completa

Para uma exploração aprofundada de todos os aspectos do Typedb-MCP-Server, visite nossa documentação completa:

➡️ Página Inicial da Documentação

Principais seções:

• Guia do Usuário: Para instalação, configuração e uso.
• Guia do Desenvolvedor: Para entender a arquitetura, código e como contribuir.
• Referência de Configuração: Todas as opções de configuração.
• Referência da API: Detalhes das ferramentas MCP e endpoints HTTP.
• Perguntas Frequentes (FAQ)

Contribuição

Suas contribuições são muito bem-vindas! Por favor, leia nosso Guia de Contribuição e nosso Código de Conduta.

Licença

Este projeto é licenciado sob a Licença MIT.

Agradecimentos

• A toda a equipe e comunidade por trás do TypeDB e do Model Context Protocol.
• Aos desenvolvedores das inúmeras bibliotecas Rust de alta qualidade que tornam este projeto possível.

Gerado automaticamente a partir do código-fonte em 16/05/2025. Para detalhes de implementação, consulte os módulos e a documentação interna.