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 dadosget-product-by-id: Busca um produto específico pelo UUIDsearch-products-by-name: Busca produtos por nome (busca parcial)create-product: Cria um novo produto no banco de dadosupdate-product: Atualiza um produto existentedelete-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
- Adicionar mais entidades: Categories, Users, etc.
- Implementar relacionamentos: Entre entidades
- Adicionar validações: Validações customizadas
- Implementar cache: Cache com Redis
- 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.