mcp-server-db

Tiago-Alves-Dev/mcp-server-db

3.1

If you are the rightful owner of mcp-server-db and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

This project demonstrates the integration of Model Context Protocol (MCP) with TypeORM to provide structured database access through MCP tools.

Tools
6
Resources
0
Prompts
0

MCP Server com TypeORM

Este projeto demonstra o poder do Model Context Protocol (MCP) integrado com TypeORM para fornecer acesso estruturado a dados de banco de dados através de ferramentas MCP.

🎯 Propósito

Este projeto foi desenvolvido para demonstrar:

  • Poder do MCP: Como criar ferramentas MCP que se conectam a bancos de dados
  • Integração TypeORM: Uso do TypeORM para operações de banco de dados
  • Dados Tratados: Retorno de dados de forma estruturada e tratada
  • Interface de Teste: Utilização do MCP Inspector para testar as ferramentas

🚀 Funcionalidades

Ferramentas MCP Disponíveis

  • get-products: Retorna todos os produtos do banco de dados
  • get-product-by-id: Busca um produto específico pelo UUID
  • search-products-by-name: Busca produtos por nome (busca parcial)
  • create-product: Cria um novo produto no banco de dados
  • update-product: Atualiza um produto existente
  • delete-product: Remove um produto (soft delete)

🛠️ Tecnologias Utilizadas

  • Node.js: Runtime JavaScript
  • TypeORM: ORM para PostgreSQL
  • PostgreSQL: Banco de dados
  • Model Context Protocol (MCP): Protocolo para comunicação com LLMs
  • @modelcontextprotocol/sdk: SDK oficial do MCP

📋 Pré-requisitos

  • Node.js 18 ou superior
  • PostgreSQL instalado e configurado
  • Variáveis de ambiente configuradas (veja seção Configuração)

⚙️ Configuração

1. Variáveis de Ambiente

Crie um arquivo .env na raiz do projeto:

DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=seu_usuario
DB_PASSWORD=sua_senha
DB_DATABASE=seu_banco

2. Instalação

# Clone o repositório
git clone <url-do-repositorio>
cd MCP-SERVER-BD

# Instale as dependências
npm install

🏃‍♂️ Como Executar

1. Iniciar o Servidor

# Desenvolvimento (com watch)
npm run dev

# Produção
npm start

2. Testar com MCP Inspector

O comando mais importante para testar as ferramentas MCP:

npx @modelcontextprotocol/inspector node index.js

Este comando abre a interface web do MCP Inspector, onde você pode:

  • Visualizar todas as ferramentas disponíveis
  • Testar cada ferramenta individualmente
  • Ver os schemas de entrada e saída
  • Executar operações no banco de dados

🗄️ Estrutura do Banco de Dados

Tabela PRODUCTS

CREATE TABLE "PRODUCTS" (
    "ID" UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
    "CREATED_AT" TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    "UPDATED_AT" TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    "CREATED_BY" VARCHAR(255),
    "UPDATED_BY" VARCHAR(255),
    "NAME" VARCHAR(255) NOT NULL,
    "DESCRIPTION" TEXT,
    "AMOUNT" INTEGER DEFAULT 0,
    "VALIDITY" DATE,
    "ACTIVE" BOOLEAN DEFAULT true,
    "companyId" UUID,
    "AVERAGE_COST" DECIMAL(10,2),
    "UNIT" VARCHAR(50)
);

📁 Estrutura do Projeto

MCP-SERVER-BD/
├── src/
│   └── database/
│       ├── connection.js          # Inicialização do TypeORM
│       ├── ormconfig.js          # Configuração do TypeORM
│       ├── migration-manager.js   # Gerenciador de migrations
│       ├── products.js           # Repository de produtos
│       ├── entities/
│       │   └── Product.js        # Entidade TypeORM
│       └── migrations/
│           └── 001_create_products_table.js
├── index.js                      # Servidor MCP principal
├── test-typeorm.js              # Teste da migração TypeORM
└── package.json

🔧 Exemplos de Uso

Criar um Produto

{
    "name": "Produto Teste",
    "description": "Descrição do produto",
    "amount": 10,
    "averageCost": 25.5,
    "unit": "UN",
    "companyId": "550e8400-e29b-41d4-a716-446655440000"
}

Buscar Produtos por Nome

{
    "name": "teste"
}

Atualizar Produto

{
    "id": "uuid-do-produto",
    "amount": 15,
    "description": "Nova descrição"
}

🧪 Testes

Teste da Migração TypeORM

node test-typeorm.js

Este comando testa:

  • Conexão com o banco de dados
  • Execução de migrations
  • Operações CRUD básicas
  • Validação de UUIDs

🔍 Debugging

Logs do Servidor

O servidor fornece logs detalhados:

  • ✅ Conexão com banco estabelecida
  • 🔄 Execução de migrations
  • 📦 Migrations executadas com sucesso
  • ❌ Erros detalhados quando ocorrem

Verificar Status do Banco

# Conectar ao PostgreSQL
psql -h localhost -U seu_usuario -d seu_banco

# Verificar tabelas
\dt

# Verificar migrations
SELECT * FROM migrations;

🚀 Próximos Passos

  1. Adicionar mais entidades: Categories, Users, etc.
  2. Implementar relacionamentos: Entre entidades
  3. Adicionar validações: Validações customizadas
  4. Implementar cache: Cache com Redis
  5. Adicionar autenticação: Sistema de autenticação

📚 Recursos Adicionais

Desenvolvido para demonstrar o poder do MCP integrado com TypeORM para fornecer acesso estruturado a dados de banco de dados.