Deephaven MCP

Servidores MCP para Deephaven orquestrarem workers de dados e alimentarem Q&A de documentação com LLMs, permitindo fluxos de trabalho de dados orientados por IA.

GitHub
5
Experimente este MCPPatrocinado

Documentação

deephaven-mcp

PyPI License Build Status

A ferramenta de linha de comando dhcli está em desenvolvimento rápido. Nomes de comandos, flags e formatos de saída podem mudar sem aviso, então uma atualização pode quebrar scripts escritos para eles — fixe uma versão se você precisar de estabilidade. Agentes de IA não precisam desse cuidado: dhcli se descreve em tempo de execução por meio de dhcli agents tree e --agents, então um agente que lê esse manifesto se adapta às mudanças por conta própria.

Sumário

Visão Geral

Potencialize seus fluxos de trabalho de IA com dados em tempo real. O Deephaven MCP traz o poder dos dataframes ao vivo diretamente para suas ferramentas de IA favoritas — Claude Desktop, Cursor, VS Code (GitHub Copilot), Windsurf e muito mais.

Por que o Deephaven MCP?

Trabalhar com dados em tempo real geralmente significa abrir mão do fluxo de trabalho simples e interativo que você obtém com tabelas estáticas. Os dataframes ao vivo do Deephaven eliminam essa troca: escreva consultas como se seus dados fossem estáticos e elas continuam atualizando automaticamente conforme novos dados chegam, tudo por meio de linguagem natural.

O que torna isso diferente:

  • Dados ao Vivo, Resultados ao Vivo: Consulte Kafka em streaming, feeds em tempo real e dados em lote com a mesma facilidade de arquivos CSV estáticos
  • Integração Nativa com IA: Seu assistente de IA entende seu pipeline de dados e pode ajudar a otimizar, depurar e estender
  • Pronto para Empresas: Testado em batalha em Wall Street por mais de uma década, agora disponível para sua equipe
  • Zero Curva de Aprendizado: Escreva consultas como se estivesse trabalhando com tabelas estáticas — atualizações em tempo real acontecem automaticamente

O Deephaven MCP implementa o padrão Model Context Protocol (MCP) usando FastMCP, conectando Deephaven Community Core e Deephaven Enterprise ao seu fluxo de trabalho de desenvolvimento de IA.

Ele é construído para cientistas de dados, engenheiros, analistas e usuários de negócios — independentemente da sua experiência em programação. Deixe a IA gerar o código enquanto você foca nos insights.

Casos de Uso Principais

  • Desenvolvimento Assistido por IA: Integre o Deephaven com ferramentas de desenvolvimento baseadas em LLM (por exemplo, Claude Desktop, GitHub Copilot) para exploração de dados assistida por IA, geração de código e análise.
  • Gerenciamento Multi-Ambiente: Gerencie e consulte programaticamente várias implantações do Deephaven Community Core e Enterprise a partir de uma única interface.
  • Documentação Interativa: Encontre rapidamente informações e exemplos da documentação do Deephaven usando consultas em linguagem natural.
  • Automação de Scripts: Execute scripts Python ou Groovy em várias sessões do Deephaven para fluxos de trabalho de processamento de dados.
  • Descoberta de Esquemas: Recupere e analise automaticamente esquemas de tabelas de instâncias do Deephaven conectadas.
  • Monitoramento de Ambiente: Monitore a saúde das sessões, versões de pacotes e status do sistema em sua infraestrutura do Deephaven.

Início Rápido

O Deephaven MCP é distribuído como um único pacote, e um dh-mcp-systems-server lê uma árvore de diretórios de configuração. Essa árvore pode conter uma seção community/, uma seção enterprise/ ou ambas ao mesmo tempo — o servidor único hospeda tudo o que encontrar, simultaneamente. Cada seção é opcional; você nunca fica preso a um único tipo de implantação.

O caminho mais rápido é o início rápido do Community Core abaixo. Depois que funcionar, adicione o Enterprise com mais um comando na mesma árvore de configuração — sem segunda instalação, sem segundo servidor. (Se você só precisa do Enterprise, comece por lá; os passos são independentes.)

Instale uma vez (abaixo) e configure as seções que precisar.

Instalar Deephaven MCP

Instale com uv (veja Pré-requisitos se você ainda não o tem):

uv tool install --python-preference managed "deephaven-mcp"

Isso coloca dhcli, dh-mcp-systems-server e dh-mcp-docs-server no seu PATH sem venv para gerenciar. Para a alternativa baseada em venv, veja Instalação e Configuração Inicial.

Sobre --python-preference managed: diz ao uv para baixar e usar seu próprio Python gerenciado (sob ~/.local/share/uv/python/) em vez de qualquer Python do seu sistema. Você não precisa instalar o Python por conta própria.

Para ferramentas de IA somente stdio (por exemplo, Claude Desktop), instale também mcp-proxy — ele faz a ponte entre um cliente somente stdio e servidores MCP HTTP, como o servidor de documentação hospedado:

uv tool install --python-preference managed mcp-proxy

Início Rápido do Community Core

Comece a usar em 5 minutos! Tudo o que você precisa é deephaven-mcp instalado — você não precisa de um servidor Deephaven em execução, porque dhcli pode iniciar um para você. Já está executando o Deephaven Community Core? Você pode apontar para ele.

1. Crie Sua Configuração

Um comando escreve uma configuração funcional:

dhcli config init

Sem prompts, nada para editar manualmente. Agora você pode iniciar um worker do Deephaven sempre que quiser — sem Docker, nada mais para instalar:

dhcli session create dev

Veja Deephaven CLI (dhcli) para saber o que mais dhcli pode fazer.

Opcional — para usar um servidor Deephaven que você já executa, adicione-o:

dhcli config session add local --host localhost --port 10000 \
  --auth psk --token '${env:DH_LOCAL_PSK}'

O formato ${env:...} mantém seu token fora do arquivo, então defina-o no seu shell: export DH_LOCAL_PSK='your-token'. Use --auth anonymous se o seu servidor não precisar de token.

Para verificar sua configuração a qualquer momento:

dhcli config validate

O código de saída 0 significa que você está pronto. dhcli config files mostra onde os arquivos foram parar.

Onde os arquivos ficam: ~/.deephaven/ai/config/ no POSIX, %APPDATA%/Deephaven/ai/config/ no Windows. dhcli config define as permissões de arquivo que o servidor exige; se você editar manualmente, aplique chmod 700 ao diretório e chmod 600 a cada arquivo. Para cada configuração que você pode alterar, veja docs/CONFIGURATION.md e a árvore de exemplo em config-samples/ai/config/.

2. Verifique se Funciona

Confirme que a configuração está boa antes de envolver uma ferramenta de IA. dhcli inicia seu próprio servidor em segundo plano, então não há nada para você iniciar:

dhcli config validate    # is the configuration itself well-formed?
dhcli session list       # can the server load it and see your session?

config validate verifica apenas os arquivos. session list vai além: ele carrega a árvore e lista as sessões que o servidor conhece. Se sua sessão aparecer, tanto a configuração quanto o servidor estão funcionando, e qualquer coisa que der errado a partir daqui está na conexão da sua ferramenta de IA. Uma configuração ruim falha imediatamente com um erro nomeando o arquivo e o campo.

3. Conecte Sua Ferramenta de IA

Sua ferramenta de IA inicia o servidor de sistemas para você e o encerra quando sai. Não há porta para escolher, nenhum segredo compartilhado e nenhum processo em segundo plano para gerenciar.

Para Claude Desktop, abra Claude Desktop → Configurações → Desenvolvedor → Editar Config e adicione:

{
  "mcpServers": {
    "deephaven-systems": {
      "command": "dh-mcp-systems-server",
      "args": ["--transport", "stdio"]
    },
    "deephaven-docs": {
      "command": "mcp-proxy",
      "args": [
        "--transport=streamablehttp",
        "https://deephaven-mcp-docs-prod.dhc-demo.deephaven.io/mcp"
      ]
    }
  }
}

A segunda entrada, deephaven-docs, conecta-se ao servidor de documentação hospedado do Deephaven para que você possa fazer perguntas sobre o próprio Deephaven. O Claude Desktop o acessa por meio de mcp-proxy, que você instalou em Instalar Deephaven MCP.

O diretório de configuração padrão é ~/.deephaven/ai/config/ (criado na Etapa 1), então nenhum DH_AI_DATA_DIR é necessário. Para usar um local diferente, adicione um bloco env definindo DH_AI_DATA_DIR para uma raiz de dados que contenha um subdiretório config/.

Usando outra coisa? Veja Instruções de Configuração por Ferramenta para Cursor, VS Code e Windsurf.

4. Experimente

Reinicie sua ferramenta de IA (ou IDE) para que ela reconheça a nova configuração.

Confirme que a configuração está funcionando perguntando:

"Liste minhas sessões do Deephaven e mostre-me as tabelas na sessão local"

"Quais pacotes Python estão instalados no meu ambiente Deephaven?"

"Execute este código Python na minha sessão do Deephaven: t = empty_table(100).update('x=i', 'y=i*2')"

Precisa de ajuda? Consulte a seção Solução de Problemas, pergunte ao servidor de documentação hospedado sobre recursos do Deephaven ou entre no Slack da Comunidade Deephaven!

Início Rápido do Enterprise

Comece a usar em 5 minutos! Você precisa deephaven-mcp instalado e de um sistema Deephaven Enterprise que você possa acessar. Pergunte ao seu administrador do Deephaven pela URL connection.json e suas credenciais.

Adicionando a uma configuração existente? Isso é aditivo — não é uma instalação separada nem um servidor separado. Se você já executou o início rápido do Community Core, você está adicionando ao mesmo diretório de configuração, e um dh-mcp-systems-server hospeda suas sessões da Comunidade e sistemas Enterprise juntos. Se você pulou a Comunidade, esta seção é independente.

1. Crie Sua Configuração

Um comando declara seu sistema. Cada sistema Enterprise se torna um arquivo sob enterprise/systems/.

Autenticação por senha (com o segredo lido de uma variável de ambiente):

dhcli config system add prod \
  --url https://dhe.example.com/iris/connection.json \
  --auth password --username iris --password '${env:DH_PROD_PASSWORD}'

Autenticação por chave privada — a chave está em um arquivo, então faça referência a ela. Esta é a sua chave privada do Deephaven:

dhcli config system add prod \
  --url https://dhe.example.com/iris/connection.json \
  --auth private_key --key '${file:/etc/deephaven/priv-prod.base64.txt}'

Omita qualquer flag para ser solicitado em um terminal. Em seguida, verifique:

export DH_PROD_PASSWORD='your-password'    # for the password-auth variant
dhcli config validate

Exporte o segredo antes de executar validate — ele resolve referências ${env:...} no seu shell atual. O nome que você passar se torna o nome do arquivo, então prod acima cria enterprise/systems/prod.json. community é reservado e não pode ser usado como nome de sistema.

Vários sistemas: execute dhcli config system add <name> ... uma vez por sistema. Liste o que você declarou com dhcli config system list, e remova um com dhcli config system remove <name>.

Comunidade e Enterprise coexistem na mesma árvore — o único servidor hospeda ambos:

~/.deephaven/ai/config/
├── community/
│   └── sessions/
│       └── local.json      # Community Core sessions
└── enterprise/
    └── systems/
        └── prod.json       # Enterprise systems — same tree, one server

Um exemplo completo combinado é fornecido em config-samples/ai/config/ (ambas as seções preenchidas); a seção Configuração abaixo e docs/CONFIGURATION.md cobrem a árvore completa.

2. Verifique se Funciona

Confirme que a configuração está boa antes de envolver uma ferramenta de IA. dhcli inicia seu próprio servidor em segundo plano, então não há nada para você iniciar:

dhcli config validate    # is the configuration itself well-formed?
dhcli system list        # which systems does the server serve?

system list retorna cada sistema configurado como pares {name, type} — o guarda-chuva community ao lado de cada sistema Enterprise. Sua entrada prod aparecendo lá confirma que tanto a configuração quanto o servidor estão funcionando. Uma configuração ruim falha imediatamente com um erro nomeando o arquivo e o campo.

Para verificar se o sistema está realmente acessível, não apenas configurado:

dhcli system status --system prod --connect

3. Conecte Sua Ferramenta de IA

Sua ferramenta de IA inicia o servidor de sistemas para você e o encerra quando sai. Não há porta para escolher, nenhum segredo compartilhado e nenhum processo em segundo plano para gerenciar.

Para Claude Desktop, abra Claude Desktop → Configurações → Desenvolvedor → Editar Config e adicione:

{
  "mcpServers": {
    "deephaven-systems": {
      "command": "dh-mcp-systems-server",
      "args": ["--transport", "stdio"]
    },
    "deephaven-docs": {
      "command": "mcp-proxy",
      "args": [
        "--transport=streamablehttp",
        "https://deephaven-mcp-docs-prod.dhc-demo.deephaven.io/mcp"
      ]
    }
  }
}

A segunda entrada, deephaven-docs, conecta-se ao servidor de documentação hospedado do Deephaven para que você possa fazer perguntas sobre o próprio Deephaven. O Claude Desktop o acessa por meio de mcp-proxy, que você instalou em Instalar Deephaven MCP.

O diretório de configuração padrão é ~/.deephaven/ai/config/ (criado na Etapa 1), portanto nenhum DH_AI_DATA_DIR é necessário. Para usar um local diferente, adicione um bloco env definindo DH_AI_DATA_DIR para uma raiz de dados que contenha um subdiretório config/.

Usando outra ferramenta? Consulte Instruções de Configuração por Ferramenta para Cursor, VS Code e Windsurf.

4. Experimente

Reinicie sua ferramenta de IA (ou IDE) para que ela reconheça a nova configuração.

Confirme que a configuração está funcionando perguntando:

"Qual é o status do meu sistema Deephaven Enterprise?"

"Liste todas as consultas persistentes no meu sistema empresarial"

"Mostre-me as tabelas disponíveis na minha sessão empresarial"

Precisa de ajuda? Consulte a seção Solução de Problemas, pergunte ao servidor de documentação hospedado sobre os recursos do Deephaven, ou entre no Deephaven Community Slack!

Atualização Rápida

Já tem o deephaven-mcp instalado? Veja como atualizar:

Usando uv tool (recomendado):

uv tool upgrade deephaven-mcp

Usando uv pip (instalação baseada em venv):

uv pip install --upgrade "deephaven-mcp"

Usando pip padrão (instalação baseada em venv):

.venv/bin/pip install --upgrade "deephaven-mcp"

Após a atualização, reinicie sua ferramenta de IA para que as alterações tenham efeito.

Atualizando uma configuração v1 para v2

A v2 substituiu o único arquivo de configuração v1 (nomeado pela variável DH_MCP_CONFIG_FILE removida) por uma árvore de diretórios de configuração. Se você está atualizando da v1, um conversor integrado reescreve seu arquivo antigo na nova árvore — siga o guia de migração.

Componentes do Deephaven MCP

Deephaven CLI (dhcli)

A ferramenta de linha de comando do Deephaven, projetada para humanos e especialmente agentes de IA. Ela inspeciona e opera sistemas Deephaven a partir do shell com comandos substantivo-verbo, flags tipadas e saída estruturada voltada para máquinas.

  • Configurar: dhcli config init, config session add, config system add, config validate — crie e verifique a árvore de configuração sem editar JSON manualmente.
  • Operar: verbos session, system, table, catalog e pq, por exemplo, dhcli session list ou dhcli session open <id>.
  • Perguntar à documentação: dhcli docs ask consulta o assistente de documentação do Deephaven.
  • Modos de saída: -o human|json|json-pretty|yaml, com padrão para json compacto.
  • Para agentes: dhcli agents tree emite a árvore de comandos com resumos de uma linha como JSON, e --full o manifesto completo com parâmetros, esquemas de saída e códigos de erro — preferível a extrair dados de --help.
  • Saída de emergência: dhcli tool call invoca qualquer ferramenta MCP diretamente.

Ela gerencia seu próprio servidor em segundo plano, portanto não há ciclo de vida para executar você mesmo. Consulte docs/CLI.md para a referência completa.

Servidor de Sistemas (dh-mcp-systems-server)

Um binário multiplexado único que hospeda cada sessão Community configurada e cada sistema Enterprise em um único processo. Ferramentas que operam em um sistema Enterprise específico recebem um argumento system; ferramentas de PQ codificam o sistema no id do PQ (formato enterprise:<system>:<serial>).

Principais Capacidades (lado Community):

  • Gerenciamento de Sessões: Liste, monitore e obtenha status detalhado de todas as sessões DHC configuradas
  • Criação de Sessões Community: Inicie dinamicamente novas sessões Community Core via Docker ou python com recursos configuráveis
  • Descoberta de Tabelas: Listagem leve de nomes de tabelas e recuperação abrangente de esquemas
  • Operações de Tabelas: Recupere esquemas de tabelas, metadados e dados reais com formatação flexível
  • Execução de Scripts: Execute scripts Python ou Groovy diretamente em sessões Deephaven
  • Gerenciamento de Pacotes: Consulte pacotes Python instalados nos ambientes das sessões

Principais Capacidades (lado Enterprise):

  • Descoberta de Sistemas: Liste cada sessão Community e sistema Enterprise configurado (list_systems)
  • Status do Sistema Enterprise: Verifique o status de qualquer sistema DHE configurado (enterprise_systems_status(system))
  • Recuperação de Controlador: Force uma reconexão imediata do controlador para um sistema (enterprise_controller_reconnect(system))
  • Gerenciamento de Sessões Enterprise: Crie e exclua sessões de trabalho enterprise por sistema
  • Gerenciamento de Consultas Persistentes: Gerenciamento completo do ciclo de vida de PQs enterprise entre sistemas — criar, iniciar, parar, reiniciar, modificar, excluir
  • Descoberta de Catálogo: Navegue pelo catálogo enterprise nos níveis de tabela e namespace

Alterações de configuração exigem reinicialização do servidor — a ferramenta mcp_reload anterior foi removida.

Servidor de Documentação (dh-mcp-docs-server)

Conecta-se à base de conhecimento de documentação do Deephaven via Inkeep AI para responder perguntas sobre recursos, APIs e padrões de uso do Deephaven. Faça perguntas em linguagem natural e obtenha respostas específicas com exemplos de código e explicações.

O Deephaven hospeda uma instância pública — você não executa este servidor. Aponte sua ferramenta de IA para o endpoint hospedado:

https://deephaven-mcp-docs-prod.dhc-demo.deephaven.io/mcp

Ele fala apenas streamable-HTTP; clientes somente stdio (por exemplo, Claude Desktop) fazem a ponte através de mcp-proxy. Consulte Configuração de Ferramenta de IA para a configuração deephaven-docs por cliente. (O binário dh-mcp-docs-server é o mesmo servidor, disponível se você quiser auto-hospedar.)

Ferramentas MCP Disponíveis

Todas as ferramentas abaixo são expostas pelo único dh-mcp-systems-server multiplexado. Ferramentas que operam em um sistema Enterprise específico recebem um argumento system obrigatório; ferramentas de PQ codificam o sistema no id do PQ (formato enterprise:<system>:<serial>).

Descoberta de sistemas:

  • list_systems - Liste cada sessão Community e sistema Enterprise configurado como pares (name, type)
  • enterprise_systems_status(system) - Relate a saúde (liveness) de um sistema DHE configurado e quaisquer erros de descoberta
  • enterprise_controller_reconnect(system) - Force uma tentativa de reconexão imediata para a assinatura de controlador travada de um sistema DHE; retorna instantaneamente sem esperar pela tentativa

Sessões Community:

  • session_community_create - Inicie dinamicamente sessões Community Core
  • session_community_delete(id) - Exclua uma sessão criada dinamicamente
  • session_community_credentials(id) - Recupere credenciais de sessão (sujeito a security.credential_retrieval_mode)

Sessões Enterprise:

  • session_enterprise_create(system, ...) - Crie uma sessão de trabalho no sistema DHE nomeado
  • session_enterprise_delete(id) - Exclua uma sessão enterprise criada dinamicamente e o PQ que a sustenta

Gerenciamento de Consultas Persistentes (PQ):

  • pq_name_to_id(system, name) - Converta um nome de PQ em seu id canônico
  • pq_list(system) - Liste todas as consultas persistentes em um sistema
  • pq_details(id) - Obtenha informações detalhadas do PQ (id = enterprise:<system>:<serial>)
  • pq_create(system, ...) - Crie uma nova consulta persistente
  • pq_modify(id, ...) - Modifique a configuração de um PQ existente
  • pq_start(ids) - Inicie PQs (execução paralela com concorrência configurável)
  • pq_stop(ids) - Pare PQs em execução (execução paralela com concorrência configurável)
  • pq_restart(ids) - Reinicie PQs (execução paralela com concorrência configurável)
  • pq_delete(ids) - Exclua PQs (execução paralela com concorrência configurável)

Operações em Lote Paralelas: pq_start, pq_stop, pq_restart e pq_delete aceitam uma lista de ids e operam neles em paralelo, relatando sucesso ou falha por item em vez de falhar todo o lote. O limite de concorrência é configurável pelo operador via pq_tools.default_max_concurrent em enterprise/settings.json — consulte docs/CONFIGURATION.md.

Descoberta de catálogo:

  • catalog_tables_list(system, ...) - Liste tabelas do catálogo
  • catalog_namespaces_list(system, ...) - Navegue pelos namespaces do catálogo

Operações de sessão e tabela (qualquer sessão, community ou enterprise):

  • sessions_list - Liste todas as sessões
  • session_details(id) - Obtenha informações detalhadas da sessão
  • session_tables_list(id) - Liste tabelas disponíveis
  • session_table_schema(id, ...) - Obtenha o esquema de uma tabela
  • session_table_data(id, ...) - Recupere dados de tabela com opções de formatação
  • session_script_run(id, ...) - Execute scripts Python/Groovy
  • session_pip_list(id) - Consulte pacotes instalados

Para os parâmetros completos de cada ferramenta, formato de retorno e exemplos, execute dhcli tool show <name> (ou dhcli tool list para enumerá-los) — consulte docs/CLI.md. O detalhe autoritativo é o docstring de origem de cada ferramenta, que também é o que o comando exibe ao vivo.

Diagramas de Arquitetura

Arquitetura do Servidor de Sistemas

graph TD
    A["MCP Clients (Claude Desktop, Cursor, Copilot, ...)"] --"stdio (default) or HTTP"--> S("dh-mcp-systems-server")
    S --> R{{"MultiSystemRegistry"}}
    R --> C("Community session registry")
    R --> E1("Enterprise system 'prod'")
    R --> E2("Enterprise system 'staging'")
    C --> CW1("Community Core Worker 1")
    C --> CW2("Community Core Worker N")
    E1 --> EP("PQ workers (prod)")
    E2 --> ES("PQ workers (staging)")

Um único processo dh-mcp-systems-server compõe um registro filho community (quando community/sessions/ não está vazio) e um registro filho enterprise por arquivo sob enterprise/systems/. As ferramentas roteiam para o filho correto com base em um argumento system ou no prefixo analisado de um id de sessão/PQ.

Arquitetura do Servidor de Documentação

graph TD
    A["MCP Clients with HTTP support"] --"streamable-http (direct)"--> B("MCP Docs Server")
    C["stdio-only MCP Clients (e.g. Claude Desktop)"] --"stdio"--> D["mcp-proxy"]
    D --"streamable-http"--> B
    B --"Accesses"--> E["Deephaven Documentation Corpus via Inkeep API"]

O Servidor de Documentação hospedado fala streamable-HTTP. Clientes com suporte nativo a HTTP MCP conectam diretamente; clientes somente stdio (por exemplo, Claude Desktop) fazem a ponte através de mcp-proxy.

Pré-requisitos

  • uv (Recomendado): Usado para uv tool install, que coloca os comandos do servidor no seu PATH sem venv para gerenciar.
    • Instale-o com pip install uv, ou consulte o guia de instalação do uv.
    • Se os comandos não forem encontrados depois, execute uv tool update-shell e abra um novo terminal. O diretório de binários da ferramenta uv — tipicamente ~/.local/bin no macOS/Linux, %LOCALAPPDATA%\uv\bin\ no Windows — não está no PATH padrão em todos os lugares.
  • Python: Versão 3.12 ou superior. O uv baixa seu próprio Python gerenciado automaticamente via --python-preference managed — nenhuma instalação separada de Python é necessária. (Baixar Python só é necessário para fluxos de trabalho sem uv)
  • Docker (Opcional): Necessário para criação de sessões community baseadas em Docker. (Baixar Docker)
  • Acesso a sistemas Deephaven: Para usar os servidores MCP, você precisará de um ou mais dos seguintes:
  • Arquivos de Configuração: Cada integração requer arquivos de configuração adequados (locais específicos detalhados em cada seção de integração)

Instalação e Configuração Inicial

Caminho Rápido: Para uma experiência rápida de início, consulte o guia Início Rápido acima. Esta seção fornece detalhes adicionais de instalação e métodos alternativos.

A maneira recomendada de instalar o deephaven-mcp é a partir do PyPI, que fornece a versão estável mais recente.

Métodos de Instalação

Usando uv tool install (Recomendado)

uv é um gerenciador de pacotes Python de alto desempenho. uv tool install coloca os comandos do servidor diretamente no seu PATH em um ambiente isolado e gerenciado — sem venv para criar ou ativar.

Instale o uv (se você não o tiver):

pip install uv

Ou consulte o guia de instalação do uv para outras opções.

Instale o deephaven-mcp como uma ferramenta:

uv tool install --python-preference managed "deephaven-mcp"

Após este comando, dhcli, dh-mcp-systems-server e dh-mcp-docs-server estão disponíveis no seu PATH. O suporte tanto para Community Core quanto para Enterprise (Core+) está sempre incluído.

Sobre o --python-preference managed: uv baixa e usa seu próprio Python (sob ~/.local/share/uv/python/) em vez de qualquer Python no seu sistema, portanto atualizar ou remover seu Python do sistema não pode quebrar a instalação. Recomendado para todos — você não precisa instalar Python você mesmo.

Onde as ferramentas são instaladas:

PlataformaScripts (no PATH)Ambiente da ferramenta
macOS/Linux~/.local/bin/~/.local/share/uv/tools/deephaven-mcp/
Windows%LOCALAPPDATA%\uv\bin\%APPDATA%\uv\tools\deephaven-mcp\

Execute uv tool dir para encontrar a raiz do ambiente da ferramenta no seu sistema. A criação de sessões Community Core e a conectividade Enterprise (Core+) fazem parte da instalação base — nenhum extra é necessário para qualquer uma delas. Os extras opcionais cobrem apenas ferramentas de desenvolvimento:

ExtraFornece
[test]Framework de testes e utilitários
[lint]Ferramentas de qualidade de código (linting, formatação, verificação de tipos)
[dev]Ambiente de desenvolvimento completo (tudo acima)

Novo no uv? Veja o curso intensivo de uv para uma orientação rápida.

Alternativa: Usando uv pip ou pip padrão com um venv

Se você preferir um venv manual (por exemplo, ao desenvolver ou testar):

# Create virtual environment with Python 3.12+
uv venv .venv -p 3.12

Opcional: ative-o em cada novo terminal se quiser usar python ou pip diretamente sem uv run.

Unix / macOS:

source .venv/bin/activate

Windows (PowerShell ou Prompt de Comando):

.venv\Scripts\activate

# Install deephaven-mcp
uv pip install "deephaven-mcp"

Ou com pip padrão:

python3.12 -m venv .venv

Unix / macOS:

source .venv/bin/activate

Windows (PowerShell ou Prompt de Comando):

.venv\Scripts\activate

pip install "deephaven-mcp"

Ao conectar sua ferramenta de IA a uma instalação via venv, use o caminho completo para os executáveis (por exemplo, .venv/bin/dh-mcp-systems-server), pois sua ferramenta de IA não ativa o ambiente para você.

Alternativa: Binários autônomos (sem necessidade de Python)

Se você não tiver Python (ou uv), baixe um binário autônomo pré-compilado — um único executável que incorpora seu próprio interpretador Python e todas as dependências, e executa totalmente offline.

Obtenha o arquivo para sua plataforma na página de Releases do GitHub, e então siga docs/STANDALONE_BINARIES.md para os passos de instalação.

Configuração

dh-mcp-systems-server lê uma árvore de diretórios de pequenos arquivos JSON / JSON5. Ordem de resolução: flag --config-dir, depois $DH_AI_DATA_DIR/config/, e então o subdiretório config/ da raiz de dados do usuário padrão da plataforma (~/.deephaven/ai/config/ no POSIX ou %APPDATA%/Deephaven/ai/config/ no Windows). As seções de Início Rápido acima mostram exemplos mínimos de Community e Enterprise; esta seção orienta você sobre o restante da árvore.

config_dir/
├── server.json                      # transport / host / port / PSK (HTTP only)
├── community/
│   ├── settings.json                # community-wide globals (optional)
│   └── sessions/
│       └── <name>.json              # one file per static session
└── enterprise/
    ├── settings.json                # enterprise-wide globals (optional)
    └── systems/
        └── <name>.json              # one file per enterprise system

Cada nome de arquivo é o nome da sessão ou sistema — local.json declara a sessão local. Os nomes podem usar letras, dígitos, _ e -, mas sem pontos.

Referência completa: docs/CONFIGURATION.md é a fonte única de verdade para o esquema — cada campo suportado, cada tipo de autenticação, a sintaxe de templating ${env:VAR} / ${file:/path}, o bloco session_creation para sessões Community sob demanda, e as opções de transporte server.json / PSK.

Criação e inspeção: os verbos dhcli config leem e escrevem esta árvore para você — init (escreve uma linha de base funcional), session add / system add, set / unset / get / keys, edit, files, show e validate. Cada alteração é validada pelo esquema antes de uma gravação atômica, então um arquivo inválido nunca chega ao disco. Veja docs/CLI.md.

Exemplos funcionais: config-samples/ai/config/ contém uma árvore de exemplo completa e copiável para Community e Enterprise.

Segurança: o servidor exige que o diretório de configuração esteja protegido, o que os verbos dhcli config tratam para você. docs/SECURITY.md cobre essas permissões, o manuseio de PSK e o templating de credenciais em detalhes.

Configuração da Ferramenta de IA

Esta seção explica como conectar o Deephaven ao seu assistente de IA ou IDE.

Como Funciona

Você adiciona duas entradas à configuração MCP da sua ferramenta de IA:

  • deephaven-systems — suas próprias sessões e sistemas Deephaven. Sua ferramenta de IA executa dh-mcp-systems-server para você e o interrompe ao sair, então você nunca inicia, interrompe ou monitora isso manualmente.
  • deephaven-docs — o servidor de documentação hospedado do Deephaven, para perguntas sobre o próprio Deephaven. Este é remoto, então ferramentas que falam HTTP conectam-se diretamente a ele e ferramentas que não falam (Claude Desktop) passam por mcp-proxy.

Em seguida, reinicie sua ferramenta de IA para que ela leia a nova configuração. Encontre sua ferramenta abaixo para o arquivo e formato exatos.

Instruções de Configuração por Ferramenta

Claude Desktop

O Claude Desktop inicia o dh-mcp-systems-server por conta própria. Ele não fala HTTP, então alcança o servidor de documentação hospedado por meio do mcp-proxy.

Abra Claude Desktop → Configurações → Desenvolvedor → Editar Config e adicione:

{
  "mcpServers": {
    "deephaven-systems": {
      "command": "dh-mcp-systems-server",
      "args": ["--transport", "stdio"]
    },
    "deephaven-docs": {
      "command": "mcp-proxy",
      "args": [
        "--transport=streamablehttp",
        "https://deephaven-mcp-docs-prod.dhc-demo.deephaven.io/mcp"
      ]
    }
  }
}

O servidor de sistemas lê o diretório de configuração padrão ~/.deephaven/ai/config/; adicione um bloco env definindo DH_AI_DATA_DIR apenas para apontar para uma raiz de dados não padrão (que deve conter um subdiretório config/).

Se sua ferramenta de IA relatar que mcp-proxy ou dh-mcp-systems-server não foi encontrado, localize-o com which <name> (macOS/Linux) ou where <name> / Get-Command <name> (cmd.exe / PowerShell do Windows) e use o caminho completo como o valor de command.

Recursos adicionais:

Cursor

Crie ou edite um arquivo de configuração MCP:

  • Específico do projeto: .cursor/mcp.json na raiz do seu projeto
  • Global: ~/.cursor/mcp.json para todos os projetos
{
  "mcpServers": {
    "deephaven-systems": {
      "type": "stdio",
      "command": "dh-mcp-systems-server",
      "args": ["--transport", "stdio"]
    },
    "deephaven-docs": {
      "url": "https://deephaven-mcp-docs-prod.dhc-demo.deephaven.io/mcp"
    }
  }
}

Recursos adicionais:

VS Code (GitHub Copilot)

Execute o comando MCP: Adicionar Servidor na Paleta de Comandos (Cmd-Shift-P) e selecione Configurações do Workspace para criar .vscode/mcp.json, ou crie esse arquivo manualmente na raiz do seu projeto.

Configure seus servidores:

{
  "servers": {
    "deephaven-systems": {
      "command": "dh-mcp-systems-server",
      "args": ["--transport", "stdio"]
    },
    "deephaven-docs": {
      "type": "http",
      "url": "https://deephaven-mcp-docs-prod.dhc-demo.deephaven.io/mcp"
    }
  }
}

Você verá os servidores MCP listados na barra lateral de Extensões sob "Servidores MCP".

Recursos adicionais:

Windsurf

Vá para Configurações do Windsurf > Cascade > Servidores MCP > Gerenciar MCPs > Ver Config Raw para abrir ~/.codeium/windsurf/mcp_config.json para edição.

{
  "mcpServers": {
    "deephaven-systems": {
      "command": "dh-mcp-systems-server",
      "args": ["--transport", "stdio"]
    },
    "deephaven-docs": {
      "serverUrl": "https://deephaven-mcp-docs-prod.dhc-demo.deephaven.io/mcp"
    }
  }
}

Recursos adicionais:

Avançado: Compartilhar um Servidor via HTTP

A maioria das pessoas deve pular esta seção. As configurações acima são mais simples e são o que recomendamos. Use HTTP apenas quando quiser que várias ferramentas de IA em uma máquina compartilhem um único processo de servidor.

O transporte HTTP exige um segredo compartilhado (um PSK) e aceita conexões apenas da sua própria máquina. O PSK deve vir de server.json, então adicione esse arquivo, lendo o valor de uma variável de ambiente para manter o segredo fora dele:

// ~/.deephaven/ai/config/server.json
{
  "psk": "${env:DH_MCP_PSK}"
}

Em seguida, exporte essa variável e inicie o servidor:

export DH_MCP_PSK='your-shared-secret'
dh-mcp-systems-server --transport http --port 8000

Aponte sua ferramenta de IA para o servidor em execução, enviando o PSK em cada solicitação. Cursor e Windsurf ambos resolvem ${env:NAME} dentro de headers:

{
  "mcpServers": {
    "deephaven-systems": {
      "url": "http://127.0.0.1:8000/mcp",
      "headers": { "X-Deephaven-PSK": "${env:DH_MCP_PSK}" }
    }
  }
}

Como você iniciou este servidor, você gerencia seu ciclo de vida — ao contrário das configurações stdio acima, onde sua ferramenta de IA faz isso por você.

O valor de psk deve corresponder em ambos os lados, e o servidor deve ser reiniciado após alterá-lo. O endereço de bind é sempre loopback; veja docs/CONFIGURATION.md para cada campo de server.json e docs/SECURITY.md para o limite de confiança.

Solução de Problemas

Esta seção fornece orientação abrangente para diagnosticar e resolver problemas comuns com a configuração e operação do Deephaven MCP. Os problemas são organizados por categoria, começando com os problemas mais frequentemente encontrados.

Comece Aqui: Diagnostique com dhcli

A CLI responde à maioria das perguntas "é meu config ou minha ferramenta de IA?" sem envolver seu cliente de IA:

dhcli config validate    # is the configuration valid? exit 0 = yes
dhcli config files       # which files exist, and which one is broken?
dhcli daemon status      # is the background server running?
dhcli daemon logs -n 50  # what did it say?

config files funciona mesmo quando a configuração está quebrada ou vazia, então é o primeiro comando certo quando validate falha — ele nomeia o arquivo ofensor e seu primeiro erro de validação. Se validate passar, mas sua ferramenta de IA ainda não conseguir conectar, o problema está na conexão da ferramenta de IA, não na configuração.

Para testar se algo está realmente acessível em vez de meramente configurado:

dhcli session list                 # can the server see your sessions?
dhcli system status --connect      # are your Enterprise systems live?
dhcli docs status                  # is the hosted docs server reachable?

Correções Rápidas

Antes de mergulhar na solução de problemas detalhada, tente estas soluções comuns:

  1. Reinicie seu IDE/assistente de IA após qualquer alteração de configuração
  2. Valide sua configuração do Deephaven com dhcli config validate — ele relata o arquivo e o campo exatos com defeito
  3. Verifique se os caminhos de arquivo estão corretos em suas configurações JSON (use caminhos absolutos para instalações baseadas em venv)
  4. Verifique se seu ambiente virtual está ativado ao executar comandos (apenas instalações baseadas em venv — não necessário com uv tool install)
  5. Valide o próprio JSON da sua ferramenta de IA usando https://jsonlint.com ou o validador JSON do seu IDE

Mensagens de Erro Comuns

ErroOnde Você Verá IssoSolução
spawn mcp-proxy ENOENTLogs da ferramenta de IAExecute uv tool install --python-preference managed mcp-proxy primeiro; se a ferramenta ainda não conseguir encontrá-lo, localize-o com which mcp-proxy (macOS/Linux) ou where mcp-proxy / Get-Command mcp-proxy (Windows) e use o caminho completo como o command
Connection failedLogs do servidor MCPVerifique a conexão com a internet e as URLs do servidor
Config directory not found / falha na auditoria de permissõesInicialização do servidor MCPVerifique se o diretório passado via --config-dir (ou derivado de DH_AI_DATA_DIR) existe e se cada arquivo é chmod 600 e o diretório é chmod 700 (POSIX).
Permission deniedExecução de comandoGaranta que o executável tenha permissões adequadas; execute chmod +x no caminho mcp-proxy
Python version errorInstalação da ferramenta uvO Deephaven MCP requer Python 3.12+; use uv tool install --python-preference managed ...
JSON parse errorLogs do IDE/assistente de IACorrija erros de sintaxe JSON nos arquivos de configuração
Module not found: deephaven_mcpLogs do servidor MCPExecute novamente uv tool install --python-preference managed "deephaven-mcp"
Invalid id formatRespostas da ferramenta MCPCommunity: community:community:{name}; Enterprise: enterprise:{system_name}:{name}
Invalid idRespostas da ferramenta MCPIDs PQ são enterprise:<system>:<serial> onde <serial> é um inteiro não negativo.
Enterprise system 'foo' is not configuredRespostas da ferramenta MCPO argumento system não corresponde a nenhum arquivo sob enterprise/systems/. O erro lista os sistemas configurados.
HTTP 401/403 do servidorConfiguração HTTP avançada apenasO cabeçalho X-Deephaven-PSK está ausente ou não corresponde a server.json. Reinicie o servidor após editar o PSK.
Servidor HTTP recusa iniciar com erro de loopbackConfiguração HTTP avançada apenas--host foi definido para um endereço não loopback. O transporte HTTP vincula apenas a 127.0.0.1 / ::1 / localhost; encerre o TLS em um proxy reverso no mesmo host.
config_invalidComandos dhcliUm arquivo sob o diretório de configuração falhou na validação. Execute dhcli config files para encontrar qual; a mensagem nomeia o arquivo e o campo. Uma referência ${env:VAR} não resolvida conta — exporte a variável no shell em que você está executando.

Para scripts e agentes de IA: falhas de dhcli imprimem um objeto {error, error_code, exit_code, command} estruturado nos modos de saída JSON. Ramifique no error_code estável, não no texto da mensagem; execute dhcli agents errors para o registro completo de códigos e seus significados.

Problemas de Configuração JSON

A maioria dos problemas de configuração decorre de erros de sintaxe JSON ou caminhos incorretos:

  • Sintaxe JSON inválida:

    • Vírgulas, colchetes ou aspas ausentes ou extras
    • Use validador JSON para verificar a sintaxe
    • Erro comum: vírgula final na última propriedade do objeto

  • Caminhos de arquivo incorretos:

    • Use caminhos absolutos para instalações baseadas em venv; com uv tool install, o command é apenas o nome do executável (por exemplo, dh-mcp-systems-server)
    • Use barras normais / mesmo no Windows em JSON
    • Verifique se os arquivos existem nos caminhos especificados

  • Problemas com variáveis de ambiente:

    • DH_AI_DATA_DIR deve apontar para um diretório raiz de dados do usuário válido diretório (sob o qual config/ e runtime/ residem), ou ser desdefinido para usar o padrão da plataforma
    • Variáveis de ambiente no bloco env devem usar nomes corretos
    • Valores sensíveis devem usar variáveis de ambiente, não strings codificadas

Problemas de conexão de ferramentas LLM

  • Ferramenta LLM não consegue conectar / servidor não encontrado:
    • Confirme que dh-mcp-systems-server está no seu PATH — sua ferramenta de IA o executa pelo nome, então se which dh-mcp-systems-server não encontrar nada, a ferramenta também não conseguirá. Use o caminho completo como o valor de command.
    • Verifique o log MCP da sua ferramenta de IA para a falha; o servidor escreve seus erros de inicialização lá.
    • Garanta que DH_AI_DATA_DIR ou --config-dir aponte para uma fonte de configuração válida (ou desdefina ambos para usar o padrão da plataforma)
    • Garanta que qualquer sessão Deephaven Community Core que você pretende usar esteja em execução e acessível pela rede
    • Defina PYTHONLOGLEVEL=DEBUG para obter logs mais detalhados do servidor MCP
  • Somente se você configurou o caminho HTTP avançado:
    • Verifique se o servidor está em execução e ouvindo na porta esperada
    • Verifique se a URL na configuração do seu cliente MCP corresponde ao host e porta do servidor
    • Garanta que seu cliente envie o cabeçalho X-Deephaven-PSK com o valor declarado em server.json

Problemas de rede e firewall

  • Problemas de firewall ou rede:
    • Garanta que não haja regras de firewall (locais ou de rede) impedindo:
      • O servidor MCP de conectar às suas instâncias Deephaven nos hosts e portas especificados.
      • Seu cliente MCP de alcançar o endpoint HTTP do servidor de sistemas (por exemplo, http://127.0.0.1:8000/mcp) — somente se você configurou o caminho HTTP avançado.
      • Seu cliente MCP de alcançar o servidor de documentação em https://deephaven-mcp-docs-prod.dhc-demo.deephaven.io.
    • Teste a conectividade básica de rede (por exemplo, usando ping ou curl da máquina relevante) se as conexões estiverem falhando.

Problemas de comando e caminho

  • command not found para uv (nos logs da ferramenta LLM):
    • Garanta que uv esteja instalado e seu diretório de instalação esteja na variável de ambiente PATH do seu sistema, acessível pela ferramenta LLM.
  • command not found para dhcli, dh-mcp-systems-server ou dh-mcp-docs-server:
    • Se você usou uv tool install (recomendado):
      • Reinstale ou atualize: uv tool install --python-preference managed "deephaven-mcp" (ou uv tool upgrade deephaven-mcp).
      • Coloque o diretório bin da ferramenta uv no seu PATH: execute uv tool update-shell, depois abra um novo shell.
      • Ainda ausente? Localize o binário com which dh-mcp-systems-server (macOS/Linux) ou where dh-mcp-systems-server / Get-Command dh-mcp-systems-server (Windows).
    • Se você usou um ambiente virtual (instalação alternativa): Garanta que o pacote esteja instalado no venv com uv pip install "deephaven-mcp", e ative o venv ou use o caminho completo para o executável (por exemplo, .venv/bin/dh-mcp-systems-server).

Problemas de instalação e dependências

  • Module not found: deephaven_mcp / comandos ausentes após a instalação:

    • Usuários de uv tool install: Reinstale com uv tool install --python-preference managed "deephaven-mcp". A instalação da ferramenta é autocontida — não há venv gerenciado pelo usuário para ativar.
    • Usuários de ambiente virtual: Certifique-se de que o venv esteja ativado (seu prompt de shell deve mostrar seu nome) antes de executar comandos, ou invoque comandos via uv run ... / o caminho completo de .venv/bin/....

  • Problemas de instalação de dependências:

    • Dependências ausentes (usuários de uv tool install): Execute novamente uv tool install --python-preference managed "deephaven-mcp" para atualizar o ambiente de ferramenta isolado, ou uv tool upgrade deephaven-mcp para obter uma versão mais recente.
    • Dependências ausentes (usuários de venv): Reinstale com uv pip install "deephaven-mcp".
    • Conflitos de versão: uv tool install é executado em um ambiente isolado, então conflitos entre pacotes são raros; para instalações venv, verifique versões de pacotes conflitantes no seu ambiente.
    • Problemas específicos de plataforma: Alguns pacotes podem exigir compilação específica da plataforma.

  • Compatibilidade de versão do Python:

    • Deephaven MCP requer Python 3.12 ou superior.
    • Verifique sua versão do Python: python --version.
    • Usuários de uv tool install: Passe --python-preference managed (como os comandos documentados fazem) para deixar o uv gerenciar um interpretador compatível automaticamente; se você instalou anteriormente com um Python diferente, reinstale a ferramenta.
    • Usuários de ambiente virtual: Garanta que seu venv use Python 3.12+ (por exemplo, uv venv .venv -p 3.12).

Problemas de servidor e ambiente

  • Falhas de inicialização do servidor:

    • Erros de Python: Verifique os logs do servidor para tracebacks de Python e garanta que as dependências estejam instaladas corretamente
    • Problemas de permissão: Garanta que o processo do servidor MCP tenha as permissões de arquivo e rede necessárias
    • Problemas de caminho: Verifique se todos os caminhos de executáveis na configuração estão corretos e acessíveis

  • Problemas de tempo de execução:

    • Erros de corrotina: Reinicie o servidor MCP após fazer alterações no código

    • Problemas de memória: Monitore o uso de recursos do servidor, especialmente com grandes conjuntos de dados

    • Problemas de cache: Limpe os arquivos de cache do Python se estiver enfrentando problemas persistentes:

      find . -name "*.pyc" -delete

  • Problemas específicos do uv:

    • Falhas de comando: Garanta que uv esteja instalado e pyproject.toml esteja configurado corretamente
    • Problemas de caminho: Verifique se uv está na variável de ambiente PATH do seu sistema
    • Detecção de projeto: Execute comandos uv a partir do diretório raiz do projeto

Problemas de configuração de sessão Deephaven

  • Falhas de conexão de sessão:

    • Verifique a sintaxe e o conteúdo do seu arquivo de configuração — veja docs/CONFIGURATION.md
    • Verifique docs/CONFIGURATION.md para quaisquer variáveis de ambiente necessárias referenciadas via template ${env:VAR}
    • Garanta que as instâncias Deephaven de destino estejam em execução e acessíveis pela rede
    • Verifique se o processo do servidor MCP tem permissões de leitura para todos os arquivos sob o diretório de configuração

  • Problemas de formato de ID:

    • Use o formato correto: {type}:{system}:{name}
    • Comunidade: community:community:<session_name> (o SessionId é o próprio nome da sessão, por exemplo, community:community:my_session)
    • Empresa: enterprise:<system_name>:<pq_serial> (o SessionId é o serial PQ como uma string decimal, por exemplo, enterprise:prod:42); use pq_name_to_id para resolver um nome PQ para seu serial
    • Evite caracteres especiais ou espaços em nomes de sessão (o nome da sessão da comunidade deve corresponder a [A-Za-z0-9][A-Za-z0-9_-]* já que ele serve como o SessionId). Pontos não são permitidos — um nome se torna um segmento de um caminho de configuração separado por pontos, então renomeie usando - ou _

  • Problemas de autenticação:

    • Sessões da comunidade: Verifique URLs de conexão e o bloco auth.credentials — veja docs/CONFIGURATION.md
    • Sessões empresariais: Verifique o bloco auth.credentials por sistema (discriminado por type: password ou private_key) — veja docs/CONFIGURATION.md
    • Templating: Garanta que quaisquer referências ${env:VAR} / ${file:/path} sejam resolvidas na inicialização — veja docs/CONFIGURATION.md
    • Segurança: Veja docs/SECURITY.md para tratamento de credenciais e permissões de diretório

Notas específicas da plataforma

  • Windows: use barras normais / em caminhos de arquivo JSON; executáveis venv residem sob .venv\Scripts\ em vez de .venv/bin/.
  • macOS: O Gatekeeper pode bloquear executáveis não assinados na primeira execução; permita-os via Configurações do Sistema ou xattr -d com.apple.quarantine <path>.

Análise de logs e depuração

Locais de arquivos de log:

  • Daemon dhcli: execute dhcli daemon logs para lê-lo, ou dhcli daemon logs --path para imprimir sua localização.
  • Claude Desktop: macOS ~/Library/Logs/Claude/, Windows %APPDATA%\Claude\logs\ — mcp.log contém o registro geral de conexão MCP; mcp-server-<name>.log contém o stderr de cada servidor.
  • VS Code/Copilot: Verifique o painel de saída do VS Code e o console do desenvolvedor
  • Cursor IDE: Verifique o painel de log do IDE e as ferramentas do desenvolvedor
  • Windsurf IDE: Verifique o terminal integrado do IDE e as saídas de log

O que procurar nos logs:

  • Erros de inicialização: tracebacks de Python, módulos ausentes, permissão negada
  • Erros de conexão: timeouts de rede, conexões recusadas, falhas de resolução de DNS
  • Erros de configuração: erros de análise JSON, caminhos inválidos, variáveis de ambiente ausentes
  • Erros de tempo de execução: exceções inesperadas, esgotamento de recursos, erros de timeout

Habilitando registro de depuração:

Defina PYTHONLOGLEVEL=DEBUG para registro detalhado. Para o daemon dhcli, defina-o no seu shell e reinicie o daemon, depois leia o log:

export PYTHONLOGLEVEL=DEBUG
dhcli daemon restart
dhcli daemon logs -n 100

Quando sua ferramenta de IA inicia o servidor, adicione a variável ao bloco env da sua estrofe deephaven-systems em vez disso, depois verifique o log MCP da sua ferramenta de IA.

Quando buscar ajuda

Se você tentou as soluções acima e ainda está enfrentando problemas:

  1. Reúna informações:

    • Mensagens de erro dos logs
    • Seus arquivos de configuração (remova informações sensíveis)
    • Informações do sistema (SO, versão do Python, versões de pacotes)
    • Passos para reproduzir o problema

  2. Verifique a documentação:

  3. Suporte da comunidade:

Solução de problemas de IDE e assistente de IA

Para solução de problemas de IDE e assistente de IA, consulte a documentação oficial de cada ferramenta:

Contribuindo

Acolhemos calorosamente contribuições para o Deephaven MCP! Seja relatórios de bugs, sugestões de recursos, melhorias de documentação ou contribuições de código, sua ajuda é valorizada.

Por onde começar:

Comunidade e Suporte

Recursos adicionais:

Licença

Este projeto é licenciado sob a Licença Apache 2.0. Veja o arquivo LICENSE para detalhes.