README.md•5.38 kB
# 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:
```env
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=seu_usuario
DB_PASSWORD=sua_senha
DB_DATABASE=seu_banco
```
### 2. Instalação
```bash
# 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
```bash
# Desenvolvimento (com watch)
npm run dev
# Produção
npm start
```
### 2. Testar com MCP Inspector
O comando mais importante para testar as ferramentas MCP:
```bash
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
```sql
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
```json
{
"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
```json
{
"name": "teste"
}
```
### Atualizar Produto
```json
{
"id": "uuid-do-produto",
"amount": 15,
"description": "Nova descrição"
}
```
## 🧪 Testes
### Teste da Migração TypeORM
```bash
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
```bash
# 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
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [TypeORM Documentation](https://typeorm.io/)
- [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
---
**Desenvolvido para demonstrar o poder do MCP integrado com TypeORM para fornecer acesso estruturado a dados de banco de dados.**