DynamoDB Read-Only MCP

Um servidor somente leitura para consultar bancos de dados AWS DynamoDB usando o Model Context Protocol (MCP).

GitHub
2
Experimente este MCPPatrocinado

Documentação

MseeP.ai Security Assessment Badge

DynamoDB Read-Only MCP

npm version smithery badge

Um servidor que utiliza o Model Context Protocol (MCP) para consultar bancos de dados AWS DynamoDB. Este servidor permite que LLMs como Claude consultem dados do DynamoDB por meio de solicitações em linguagem natural.

DynamoDB Read-Only MCP server

Recursos

Este servidor MCP fornece os seguintes recursos:

  • Ferramentas de Gerenciamento de Tabelas:
    • list-tables: Visualizar uma lista de todas as tabelas do DynamoDB
    • describe-table: Visualizar informações detalhadas sobre uma tabela específica
  • Ferramentas de Consulta de Dados:
    • scan-table: Escanear todos ou parte dos dados de uma tabela
    • query-table: Pesquisar dados que correspondam a condições específicas em uma tabela
    • paginate-query-table: Recuperar dados em várias páginas que correspondam a condições específicas
    • get-item: Recuperar um item com uma chave específica
    • count-items: Calcular o número de itens em uma tabela
  • Recursos:
    • dynamodb-tables-info: Um recurso que fornece metadados para todas as tabelas
    • dynamodb-table-schema: Um recurso que fornece informações de esquema para uma tabela específica
  • Prompts:
    • dynamodb-query-help: Um prompt de ajuda para escrever consultas do DynamoDB

Instalação e Execução

Você pode executá-lo sem instalação usando o método Run with NPX abaixo.

Instalando via Smithery

Para instalar o DynamoDB Read-Only Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @jjikky/dynamo-readonly-mcp --client claude

Instalação

  1. Clone o repositório:

    git clone https://github.com/jjikky/dynamo-readonly-mcp.git
cd dynamo-readonly-mcp

  2. Instale os pacotes necessários:

    npm install

  3. Crie um arquivo .env e configure suas credenciais da AWS:

    AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=your_region

Compilar e Executar

npm run build
npm start

Conectar ao Claude Desktop

Para usar este servidor MCP com o Claude Desktop, você precisa modificar o arquivo de configuração do Claude Desktop.

  1. Abra o arquivo de configuração do Claude Desktop:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  2. Adicione a configuração do servidor da seguinte forma:

    {
  "mcpServers": {
    "dynamodb-readonly": {
      "command": "node",
      "args": ["/absolute-path/dynamo-readonly-mcp/dist/index.js"],
      "env": {
        "AWS_ACCESS_KEY_ID": "your_access_key",
        "AWS_SECRET_ACCESS_KEY": "your_secret_key",
        "AWS_REGION": "your_region"
      }
    }
  }
}

  3. Reinicie o Claude Desktop.

Executar com NPX

Você também pode executar este servidor usando npx sem uma instalação global:

{
  "mcpServers": {
    "dynamodb-readonly": {
      "command": "npx",
      "args": ["-y", "dynamo-readonly-mcp"],
      "env": {
        "AWS_ACCESS_KEY_ID": "your_access_key",
        "AWS_SECRET_ACCESS_KEY": "your_secret_key",
        "AWS_REGION": "your_region"
      }
    }
  }
}

Exemplos de Uso

Você pode fazer perguntas ao Claude como:

  1. "Você pode me dizer quais tabelas existem no DynamoDB?"
  2. "Explique a estrutura da tabela Users"
  3. "Encontre o número de usuários na tabela 'Users' onde groupId é '0lxp4paxk7'"

Arquitetura

Este servidor MCP consiste na seguinte estrutura em camadas:

  1. Interface do Cliente (Claude Desktop) - Interação entre usuário e LLM
  2. Camada de Protocolo MCP - Fornece método padronizado de troca de mensagens
  3. Servidor DynamoDB - Implementa funções que interagem com o DynamoDB
  4. AWS SDK - Comunica-se com o serviço AWS DynamoDB

Mecanismos Chave de Operação

1. Inicialização e Conexão

Quando o servidor inicia, ocorre o seguinte processo:

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error('DynamoDB read-only MCP server is running...');
}
  • StdioServerTransport configura um canal de comunicação por meio de entrada/saída padrão.
  • server.connect(transport) conecta-se ao Claude Desktop por meio do protocolo MCP.
  • Durante a conexão, o servidor envia informações sobre ferramentas, recursos e prompts suportados ao cliente.

2. Processamento de Solicitações de Ferramentas

Quando um usuário pergunta ao Claude algo como "Mostre-me a lista de tabelas do DynamoDB":

  1. Claude analisa esta solicitação e chama a ferramenta list-tables.
  2. Esta solicitação é enviada ao servidor por meio do protocolo MCP.
  3. O servidor executa o manipulador de ferramentas correspondente:
server.tool('list-tables', 'Gets a list of all DynamoDB tables', {}, async () => {
  try {
    const tables = await listTables();
    return {
      content: [{ type: 'text', text: JSON.stringify(tables, null, 2) }],
    };
  } catch (error) {
    return { isError: true, content: [{ type: 'text', text: `Error: ${error.message}` }] };
  }
});
  1. O resultado é retornado ao Claude por meio do protocolo MCP.
  2. Claude processa este resultado em linguagem natural e o apresenta ao usuário.

3. Tratamento de Parâmetros Específicos

Quando um usuário solicita "Diga-me a estrutura da tabela Users":

  1. Claude determina que esta solicitação deve usar a ferramenta describe-table.
  2. Claude configura o parâmetro como { tableName: "Users" }.
  3. Esta informação é enviada ao servidor MCP:
server.tool(
  'describe-table',
  'Gets detailed information about a DynamoDB table',
  {
    tableName: z.string().describe('Name of the table to get detailed information for'),
  },
  async ({ tableName }) => {
    // Query table information using the tableName parameter
    const tableInfo = await describeTable(tableName);
    // Return results
  }
);

Aqui, z.string() usa a biblioteca Zod para validar parâmetros.

4. Tratamento de Recursos

Recursos são outro recurso do MCP que fornece dados somente leitura:

server.resource('dynamodb-tables-info', 'DynamoDB table information', async () => {
  // Create and return resource data
  const tables = await listTables();
  const tablesInfo = await Promise.all(/* Query table information */);

  return {
    contents: [
      {
        uri: 'dynamodb://tables-info',
        text: JSON.stringify(tablesInfo, null, 2),
        mimeType: 'application/json',
      },
    ],
  };
});

Claude acessa recursos e os usa como informações de contexto.

5. Tratamento de Prompts

O servidor MCP pode fornecer modelos de prompt para tarefas específicas:

server.prompt(
  'dynamodb-query-help',
  'A prompt that helps write DynamoDB queries',
  {
    tableName: z.string().describe('Table name to query'),
    queryType: z.enum(['basic', 'advanced']).default('basic'),
  },
  async ({ tableName, queryType }) => {
    // Generate prompt content
    return {
      messages: [
        {
          role: 'user',
          content: { type: 'text', text: helpContent },
        },
      ],
    };
  }
);

Este prompt é usado quando um usuário solicita "Mostre-me como escrever consultas para a tabela Users."

Resumo do Fluxo de Dados

  1. O usuário faz uma solicitação ao Claude em linguagem natural
  2. Claude analisa a solicitação e seleciona a ferramenta/recurso/prompt MCP apropriado
  3. O cliente MCP envia a solicitação ao servidor em formato padronizado
  4. O servidor processa a solicitação e chama a API do AWS DynamoDB
  5. O DynamoDB retorna os resultados
  6. O servidor converte os resultados para o formato MCP e os envia ao cliente
  7. Claude processa os resultados em linguagem natural e os apresenta ao usuário

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.