Treasure Data MCP Server

Treasure Data MCP Server

Servidor MCP (Model Context Protocol) para Treasure Data, permitindo que assistentes de IA consultem e interajam com o Treasure Data através de uma interface segura e controlada.

🚀 Prévia Pública

Este servidor MCP está atualmente em prévia pública. Estamos animados para que você experimente e agradecemos seu feedback para nos ajudar a melhorar o serviço.

Observação importante: Durante este período de prévia, o uso do servidor é gratuito. No entanto, planejamos introduzir um modelo de preços baseado no uso no futuro, que será baseado no número de consultas emitidas. Forneceremos aviso prévio e informações detalhadas sobre preços antes da implementação de quaisquer cobranças.

Seu feedback durante esta fase é inestimável e nos ajudará a moldar o futuro desta ferramenta. Obrigado por ser um adotante inicial!

Recursos

• 🔍 Consulte bancos de dados, tabelas e esquemas através do information_schema
• 📊 Execute consultas SQL com limitação automática de resultados para contextos de LLM
• 🔒 Design com segurança em primeiro lugar, com modo somente leitura por padrão
• 🌍 Suporte a múltiplas regiões (regiões US, JP, EU, AP)
• 🚀 Execução sem instalação via npx
• 🎯 Integração com CDP (Customer Data Platform) para gerenciamento de segmentos e ativações (Experimental)
• 🔄 Monitoramento e controle de workflows - visualize status de execução, logs e repita workflows com falha
• 📝 Registro de auditoria abrangente para todas as operações

Pré-requisitos

Instalação do Node.js

Este servidor MCP requer Node.js versão 18.0.0 ou superior. Se você não tiver o Node.js instalado:

1. Baixe o Node.js em nodejs.org

   • Escolha a versão LTS (Long Term Support)
   • O instalador inclui npm e npx

2. Verifique a instalação executando:

node --version  # Should show v18.0.0 or higher
npx --version   # Included with npm 5.2+

3. Métodos alternativos de instalação:
   • macOS: brew install node (usando Homebrew)
   • Windows: Use o instalador do nodejs.org ou winget install OpenJS.NodeJS
   • Linux: Use o gerenciador de pacotes da sua distribuição ou os repositórios NodeSource

Instalação

Usando npx (recomendado)

Nenhuma instalação necessária! Configure sua ferramenta MCP para executar @treasuredata/mcp-server diretamente via npx:

npx @treasuredata/mcp-server

O que é npx? npx é um executor de pacotes que vem com npm 5.2+. Ele baixa e executa pacotes sem instalá-los globalmente, garantindo que você sempre use a versão mais recente.

Instalação global

Se você preferir uma instalação tradicional:

npm install -g @treasuredata/mcp-server

Configuração

Adicione à configuração do seu cliente MCP (por exemplo, Claude Desktop):

{
  "mcpServers": {
    "treasuredata": {
      "command": "npx",
      "args": ["@treasuredata/mcp-server"],
      "env": {
        "TD_API_KEY": "your_api_key",
        "TD_SITE": "us01",
        "TD_ENABLE_UPDATES": "false",
        "TD_DATABASE": "sample_datasets"
      }
    }
  }
}

Opções de Configuração

• TD_API_KEY (obrigatório): Sua chave de API do Treasure Data
• TD_SITE (opcional): Endpoint da região - us01 (padrão), jp01, eu01, ap02, ap03, dev
• TD_ENABLE_UPDATES (opcional): Habilita operações de escrita (ferramenta execute) - false (padrão), true
• TD_DATABASE (opcional): Banco de dados padrão para consultas (por exemplo, sample_datasets)

Integração com Claude Code

Claude Code fornece suporte integrado para servidores MCP através do comando claude mcp add. Para usar este servidor MCP com Claude Code:

claude mcp add td -e TD_API_KEY=$TD_API_KEY -- npx @treasuredata/mcp-server

Este comando:

• Adiciona o servidor com o nome "td"
• Define a variável de ambiente TD_API_KEY com o valor da sua chave de API
• Configura o Claude Code para usar npx @treasuredata/mcp-server (sempre usa a versão mais recente)

Configuração Adicional

Você também pode especificar variáveis de ambiente adicionais:

claude mcp add td \
  -e TD_API_KEY=$TD_API_KEY \
  -e TD_SITE=us01 \
  -e TD_DATABASE=sample_datasets \
  -- npx @treasuredata/mcp-server

Uma vez configurado, o Claude Code terá automaticamente acesso a todas as ferramentas descritas abaixo para consultar e analisar seu Treasure Data.

Ferramentas Disponíveis

1. list_databases

Lista todos os bancos de dados na sua conta Treasure Data.

Exemplo:

{
  "name": "list_databases",
  "arguments": {}
}

2. list_tables

Lista todas as tabelas em um banco de dados específico.

Parâmetros:

• database (string, opcional): Nome do banco de dados. Se omitido, usa o contexto atual do banco de dados (TD_DATABASE ou o último banco de dados usado)

Exemplo:

{
  "name": "list_tables",
  "arguments": {
    "database": "sample_datasets"
  }
}

Com banco de dados padrão configurado:

{
  "name": "list_tables",
  "arguments": {}
}

3. describe_table

Obtém informações de esquema para uma tabela específica.

Parâmetros:

• database (string, opcional): Nome do banco de dados. Se omitido, usa o contexto atual do banco de dados (TD_DATABASE ou o último banco de dados usado)
• table (string, obrigatório): Nome da tabela

Exemplo:

{
  "name": "describe_table",
  "arguments": {
    "database": "sample_datasets",
    "table": "www_access"
  }
}

Com banco de dados padrão configurado:

{
  "name": "describe_table",
  "arguments": {
    "table": "www_access"
  }
}

4. query

Executa consultas SQL somente leitura (SELECT, SHOW, DESCRIBE).

Parâmetros:

• sql (string, obrigatório): Consulta SQL a ser executada
• limit (número, opcional): Máximo de linhas (padrão: 40, máximo: 10000)

Dica de desempenho: Para tabelas com uma coluna time, use td_interval() ou td_time_range() para limitar o intervalo de tempo:

• td_interval(time, '-30d/now') - Últimos 30 dias
• td_interval(time, '-7d/now') - Últimos 7 dias
• td_interval(time, '-1d') - Somente ontem
• td_interval(time, '-1h/now') - Última hora
• td_time_range(time, '2024-01-01', '2024-01-31') - Intervalo de datas específico

Exemplo:

{
  "name": "query",
  "arguments": {
    "sql": "SELECT method, COUNT(*) as count FROM www_access GROUP BY method",
    "limit": 10
  }
}

Exemplo com intervalo de tempo:

{
  "name": "query",
  "arguments": {
    "sql": "SELECT method, COUNT(*) as count FROM www_access WHERE td_interval(time, '-7d/now') GROUP BY method",
    "limit": 10
  }
}

5. execute

Executa operações de escrita (UPDATE, INSERT, DELETE, etc.) - requer TD_ENABLE_UPDATES=true.

Parâmetros:

• sql (string, obrigatório): Instrução SQL a ser executada

Exemplo:

{
  "name": "execute",
  "arguments": {
    "sql": "INSERT INTO events (timestamp, event_type) VALUES (NOW(), 'test')"
  }
}

6. use_database

Alterna o contexto atual do banco de dados para consultas subsequentes.

Parâmetros:

• database (string, obrigatório): Banco de dados para o qual alternar

Exemplo:

{
  "name": "use_database",
  "arguments": {
    "database": "production_logs"
  }
}

Após a alternância, todas as consultas usarão o novo banco de dados por padrão, a menos que seja especificado explicitamente.

7. current_database

Obtém o contexto atual do banco de dados usado para consultas.

Parâmetros: Nenhum

Exemplo:

{
  "name": "current_database",
  "arguments": {}
}

Resposta:

{
  "currentDatabase": "sample_datasets",
  "description": "The current database context used for queries"
}

Ferramentas CDP (Customer Data Platform) - EXPERIMENTAL

Observação: As ferramentas CDP estão atualmente experimentais e podem não cobrir todos os casos de uso. Funcionalidades adicionais serão adicionadas com base no feedback dos usuários.

As seguintes ferramentas estão disponíveis para interagir com a Customer Data Platform (CDP) do Treasure Data:

8. list_parent_segments

Lista todos os segmentos pai na sua conta CDP.

Parâmetros: Nenhum

Exemplo:

{
  "name": "list_parent_segments",
  "arguments": {}
}

9. get_parent_segment

Obtém detalhes de um segmento pai específico.

Parâmetros:

• parent_segment_id (inteiro, obrigatório): O ID do segmento pai

Exemplo:

{
  "name": "get_parent_segment",
  "arguments": {
    "parent_segment_id": 12345
  }
}

10. list_segments

Lista todos os segmentos sob um segmento pai específico.

Parâmetros:

• parent_segment_id (inteiro, obrigatório): O ID do segmento pai

Exemplo:

{
  "name": "list_segments",
  "arguments": {
    "parent_segment_id": 12345
  }
}

11. list_activations

Lista todas as ativações (sindicações) para um segmento específico.

Parâmetros:

• parent_segment_id (inteiro, obrigatório): O ID do segmento pai
• segment_id (inteiro, obrigatório): O ID do segmento

Exemplo:

{
  "name": "list_activations",
  "arguments": {
    "parent_segment_id": 12345,
    "segment_id": 67890
  }
}

12. get_segment

Obtém informações detalhadas sobre um segmento específico, incluindo suas regras e metadados.

Parâmetros:

• parent_segment_id (inteiro, obrigatório): O ID do segmento pai
• segment_id (inteiro, obrigatório): O ID do segmento

Exemplo:

{
  "name": "get_segment",
  "arguments": {
    "parent_segment_id": 287197,
    "segment_id": 1536120
  }
}

13. parent_segment_sql

Obtém a instrução SQL para um segmento pai.

Parâmetros:

• parent_segment_id (inteiro, obrigatório): O ID do segmento pai

Exemplo:

{
  "name": "parent_segment_sql",
  "arguments": {
    "parent_segment_id": 287197
  }
}

Exemplo de Resposta:

select
  a.*
from "cdp_audience_287197"."customers" a

14. segment_sql

Obtém a instrução SQL para um segmento com condições de filtragem aplicadas ao segmento pai.

Parâmetros:

• parent_segment_id (inteiro, obrigatório): O ID do segmento pai
• segment_id (inteiro, obrigatório): O ID do segmento

Exemplo:

{
  "name": "segment_sql",
  "arguments": {
    "parent_segment_id": 287197,
    "segment_id": 1536120
  }
}

Exemplo de Resposta:

select
  a.*
from "cdp_audience_287197"."customers" a
where (
  (position('Male' in a."gender") > 0)
)

Ferramentas de Workflow (Experimental) - Monitore e Controle Workflows Digdag

Observação: Estas ferramentas de workflow são experimentais e fornecem acesso detalhado a sessões, tentativas e tarefas de workflow. Elas estão sujeitas a alterações em versões futuras.

As seguintes ferramentas estão disponíveis para monitorar e controlar workflows Digdag. Estas ferramentas se integram ao mecanismo de workflow do Treasure Data baseado em Digdag:

15. list_projects

Lista todos os projetos de workflow.

Parâmetros:

• limit (número, opcional): Máximo de resultados (padrão: 100)
• last_id (string, opcional): Cursor de paginação

Exemplo:

{
  "name": "list_projects",
  "arguments": {
    "limit": 50
  }
}

16. list_workflows

Lista workflows, opcionalmente filtrados por nome de projeto.

Parâmetros:

• project_name (string, opcional): Nome do projeto para filtrar
• limit (número, opcional): Máximo de resultados (padrão: 100)
• last_id (string, opcional): Cursor de paginação

Exemplos:

// List all workflows
{
  "name": "list_workflows",
  "arguments": {
    "limit": 50
  }
}

// List workflows in a specific project
{
  "name": "list_workflows",
  "arguments": {
    "project_name": "my_project",
    "limit": 50
  }
}

17. list_sessions

Lista sessões de execução de workflow com opções de filtragem.

Parâmetros:

• project_name (string, opcional): Filtrar por nome do projeto
• workflow_name (string, opcional): Filtrar por nome do workflow
• status (string, opcional): Filtrar por status (running, success, error, killed, planned)
• from_time (string, opcional): Hora de início (ISO 8601)
• to_time (string, opcional): Hora de término (ISO 8601)
• limit (número, opcional): Máximo de resultados (padrão: 100)
• last_id (string, opcional): Cursor de paginação

Exemplo:

{
  "name": "list_sessions",
  "arguments": {
    "status": "error",
    "from_time": "2024-01-01T00:00:00Z",
    "limit": 20
  }
}

18. get_session_attempts

Obtém todas as tentativas para uma sessão específica.

Parâmetros:

• session_id (string, obrigatório): ID da sessão

Exemplo:

{
  "name": "get_session_attempts",
  "arguments": {
    "session_id": "12345"
  }
}

19. get_attempt_tasks

Lista todas as tarefas dentro de uma tentativa com seu status de execução.

Parâmetros:

• attempt_id (string, obrigatório): ID da tentativa
• include_subtasks (booleano, opcional): Incluir subtarefas (padrão: true)

Exemplo:

{
  "name": "get_attempt_tasks",
  "arguments": {
    "attempt_id": "67890",
    "include_subtasks": false
  }
}

20. get_task_logs

Recupera logs para uma tarefa específica dentro de uma tentativa.

Parâmetros:

• attempt_id (string, obrigatório): ID da tentativa
• task_name (string, obrigatório): Nome da tarefa (por exemplo, "+main+task1")
• offset (número, opcional): Deslocamento do log em bytes
• limit (número, opcional): Máximo de bytes a recuperar (padrão: 1MB)

Exemplo:

{
  "name": "get_task_logs",
  "arguments": {
    "attempt_id": "67890",
    "task_name": "+main+process_data",
    "limit": 5000
  }
}

21. kill_attempt

Solicita o cancelamento de uma tentativa em execução.

Parâmetros:

• attempt_id (string, obrigatório): ID da tentativa
• reason (string, opcional): Motivo do cancelamento

Exemplo:

{
  "name": "kill_attempt",
  "arguments": {
    "attempt_id": "67890",
    "reason": "Stopping for maintenance"
  }
}

22. retry_session

Repete uma sessão desde o início ou de uma tarefa específica.

Parâmetros:

• session_id (string, obrigatório): ID da sessão
• from_task (string, opcional): Nome da tarefa a partir da qual repetir
• retry_params (objeto, opcional): Parâmetros de substituição para a repetição

Exemplo:

{
  "name": "retry_session",
  "arguments": {
    "session_id": "12345",
    "from_task": "+main+failed_task"
  }
}

23. retry_attempt

Repete uma tentativa específica com capacidades de retomada.

Parâmetros:

• attempt_id (string, obrigatório): ID da tentativa a repetir
• resume_from (string, opcional): Nome da tarefa a partir da qual retomar (pular tarefas bem-sucedidas)
• retry_params (objeto, opcional): Parâmetros de substituição para a repetição
• force (booleano, opcional): Forçar repetição mesmo se a tentativa estiver em execução (padrão: false)

Exemplo:

{
  "name": "retry_attempt",
  "arguments": {
    "attempt_id": "67890",
    "resume_from": "+main+failed_task",
    "retry_params": {
      "batch_size": 1000
    }
  }
}

Segurança

• Somente leitura por padrão: Operações de escrita (ferramenta execute) requerem configuração explícita com TD_ENABLE_UPDATES=true
• Validação de consultas: Todas as consultas são validadas antes da execução
• Registro de auditoria: Todas as operações são registradas para monitoramento de segurança
• Limitação de linhas: Injeção automática de LIMIT para consultas SELECT para evitar respostas grandes
• Operações de controle de workflow: kill_attempt, retry_session e retry_attempt são habilitadas por padrão, pois são operações seguras que não modificam dados diretamente

Prompt Básico para Usar td-mcp-server

Ao interagir com um assistente de IA que tem td-mcp-server configurado, você pode usar prompts como estes para trabalhar efetivamente com seu Treasure Data:

Prompt de Configuração Inicial

You have access to Treasure Data through the td-mcp-server. You can:
- List databases and tables
- Describe table schemas
- Execute SQL queries on the data
- Switch between databases using use_database
- Check current database context using current_database
- Work with CDP segments and activations (experimental)
- Generate SQL queries for CDP audiences and segments
- Monitor and control Digdag workflows
- View workflow execution status and logs
- Retry failed workflows and attempts

Start by listing available databases to understand what data is available.

Prompts para Tarefas Comuns

Exploração de Dados:

Please help me explore the data in Treasure Data:
1. First, list all available databases
2. For the database "sample_datasets", show me all tables
3. Describe the schema of the "www_access" table
4. Show me a sample of 5 rows from this table

Análise de Dados:

Analyze the web access logs in the www_access table:
1. What are the top 10 most accessed URLs?
2. Show the distribution of HTTP methods used
3. Find the busiest hours of the day (use td_interval for recent data)
4. Identify any potential anomalies or interesting patterns

Consultas Baseadas em Tempo:

For the www_access table, analyze the last 7 days of data:
- Use td_interval(time, '-7d/now') in your WHERE clause
- Show daily traffic trends
- Compare weekday vs weekend patterns
- Identify peak usage times

Análise de Segmentos CDP:

Help me understand my CDP segments:
1. List all parent segments (audiences) available
2. For parent segment ID 287197, show all child segments
3. Get the SQL query that defines this parent segment
4. For segment 1536120, show the SQL with filtering conditions applied
5. Explain what filtering rules are being applied in this segment

Monitoramento de Workflow:

Help me monitor my Digdag workflows:
1. List all workflow projects available
2. List all workflows in project "my_etl_project"
3. Show me all failed sessions from the last 24 hours
4. For session ID 12345, show all attempts and their status
5. Get the error logs for the failed tasks in attempt 67890
6. Retry the failed session from the task that failed

Solução de Problemas de Workflow:

I have a failed workflow execution. Please help me:
1. List recent error sessions for project "data_pipeline"
2. For the most recent failed session, show me the attempts
3. List all tasks in the failed attempt and identify which ones failed
4. Show me the error logs for the failed tasks
5. Suggest how to retry this workflow

Exemplos de Uso

Com o Claude Desktop

1. Peça ao Claude para analisar seus dados:

Can you show me what databases I have access to in Treasure Data?

2. Consulte dados específicos:

Show me the top 10 most frequent HTTP methods in the www_access table

3. Obtenha esquemas de tabelas:

What columns are in the nasdaq table in sample_datasets?

Exemplos de Conversas

Usuário: "Qual é o número total de registros na tabela www_access?"

Assistente: Vou consultar a tabela www_access para obter o total de registros.

SELECT COUNT(*) as total_records FROM www_access

[Executa a consulta e retorna os resultados]

A tabela www_access contém 5.000 registros no total.

Trabalhando com Múltiplos Bancos de Dados

Usuário: "Preciso trabalhar com o banco de dados production_logs em vez de sample_datasets"

Assistente: Vou alternar para o banco de dados production_logs para você.

[Usa a ferramenta use_database]

Agora alternado para o banco de dados production_logs. Todas as consultas subsequentes usarão este banco de dados por padrão, a menos que você especifique o contrário.

Exemplo de Análise Complexa

Usuário: "Você pode analisar os padrões de comportamento dos usuários nos nossos logs de acesso do último mês?"

Assistente: Vou analisar os padrões de comportamento dos usuários nos seus logs de acesso. Deixe-me dividir isso em várias consultas:

1. Primeiro, deixe-me verificar a estrutura da tabela: [Descreve a tabela para entender as colunas disponíveis]

2. Agora vou analisar o padrão geral de tráfego do último mês:

SELECT
  DATE(time) as date,
  COUNT(*) as daily_requests,
  COUNT(DISTINCT host) as unique_visitors
FROM www_access
WHERE td_interval(time, '-30d/now')
GROUP BY DATE(time)
ORDER BY date

3. Deixe-me identificar as páginas mais populares:

SELECT
  path,
  COUNT(*) as visits,
  COUNT(DISTINCT host) as unique_visitors
FROM www_access
WHERE td_interval(time, '-30d/now')
GROUP BY path
ORDER BY visits DESC
LIMIT 20

[Continua com a análise e insights...]

Desenvolvimento

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run integration tests (requires TD_API_KEY_DEVELOPMENT_AWS)
npm run test:integration

# Development mode
npm run dev

Exemplos de Configurações

Consulte o diretório examples/ para exemplos de configurações:

• claude-desktop-config.json - Configuração básica do Claude Desktop
• development-config.json - Desenvolvimento local com registro de logs
• multi-region-config.json - Configuração multi-região

Notas do Desenvolvedor

Para informações sobre como testar este servidor MCP com o modo de agente do GitHub Copilot Chat, consulte DEVELOPER_NOTES.md.

Licença

Licença Apache 2.0

Contribuições

Contribuições são bem-vindas! Por favor, leia nossas diretrizes de contribuição e envie pull requests para nosso repositório.

Suporte

Para problemas e solicitações de recursos, visite: https://github.com/treasure-data/td-mcp-server/issues