mcp-deps-server/README.md

MCP server for deps.com.br API - Smart PJ 005 business intelligence and credit analysis

# MCP Deps Server

Model Context Protocol server for deps.com.br Smart PJ 005 product integration built with Node.js.

## Overview

This MCP server provides access to deps.com.br Smart PJ 005 consultation via DepsMix API v2, enabling AI assistants to perform comprehensive business intelligence and credit analysis operations for companies (CNPJ).

The server handles authentication automatically and implements the correct cache-first consultation flow as specified in the Deps documentation.

## Features

- **Smart PJ 005 consultation** with automatic cache management
- **Cache-first approach**: First checks for existing consultation data, then performs new consultation if needed
- **CNPJ validation**: Validates CNPJ mathematical integrity before API calls (PJ only)
- **Automatic authentication**: Handles login and token refresh transparently
- **Comprehensive error handling**: Clear messages for common issues

## Smart PJ 005 Product Details

Smart PJ 005 provides comprehensive business analysis including:
- Ações judiciais (Legal actions)
- Cadastro pessoa jurídica (Business registration)
- Cheques devolvidos (Returned checks)
- Comportamental resumido (Behavioral summary)
- Consultas detalhadas (Detailed consultations)
- Contatos (Contacts)
- Diagnóstico da análise (Analysis diagnostics)
- Faturamento presumido (Presumed billing)
- Pendências financeiras (Financial pendencies)
- Protestos (Protests)
- Quadro societário (Corporate structure)
- Receita (Revenue)
- Relação empresa participação sócio - Nível 2 de cobertura (Company-partner relations - Level 2)
- Score

## Installation

### Via NPM (Global - Recomendado)
```bash
npm install -g mcp-deps-server
```

### Via NPX (Uso único)
```bash
npx mcp-deps-server
```

### Instalação Local
```bash
git clone https://github.com/rezultz/mcp-deps
cd mcp-deps
npm install
```

## Configuration

### Para instalação via NPM/NPX

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "deps": {
      "command": "npx",
      "args": ["mcp-deps-server"],
      "env": {
        "DEPS_EMAIL": "your_email@example.com",
        "DEPS_PASSWORD": "your_password_here"
      }
    }
  }
}
```

### Para instalação local

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "deps": {
      "command": "/opt/homebrew/bin/node",
      "args": ["index.js"],
      "cwd": "/path/to/mcp-deps",
      "env": {
        "DEPS_EMAIL": "your_email@example.com",
        "DEPS_PASSWORD": "your_password_here"
      }
    }
  }
}
```

### Alternative Node.js Paths

If your Node.js is installed elsewhere, use the appropriate path:

- **System Node.js**: `/usr/bin/node`
- **NVM**: `/Users/username/.nvm/versions/node/vX.X.X/bin/node`
- **Homebrew (Intel)**: `/usr/local/bin/node`
- **Homebrew (Apple Silicon)**: `/opt/homebrew/bin/node`

## Environment Variables

- `DEPS_EMAIL`: Your deps.com.br account email
- `DEPS_PASSWORD`: Your deps.com.br account password

## Authentication

The server automatically handles authentication with the deps.com.br API v2:

1. Uses your email/password to login via `/api/v2/conta/entrar`
2. Obtains an access token from the response
3. Includes the Bearer token in all subsequent API requests
4. Re-authenticates automatically when the token expires

No manual token management is required.

## Available Tools

### `deps_consultation`
- **Purpose**: Smart PJ 005 consultation with automatic cache management
- **Endpoint**: `GET /api/v2/consultas/depsmix`
- **Product**: Smart PJ 005 (ID: 059D4CF4)
- **Input**: 
  - `document` (CNPJ) - required, must be 14-digit CNPJ
- **Use case**: Complete business intelligence and risk assessment for companies
- **Flow**: 
  1. First attempts consultation with `reutilizarDadosExistentes: true` (check cache)
  2. If no cached data (success: false), performs new consultation with `reutilizarDadosExistentes: false`
  3. Returns comprehensive business analysis data
- **Status**: ✅ Fully functional

## Product Configuration

This server is configured to use **Smart PJ 005** exclusively:

- **Product**: Smart PJ 005
- **Identifier**: `059D4CF4`
- **Type**: Pessoa Jurídica (Business/Company)
- **Input**: CNPJ only (14 digits)
- **Coverage**: Level 2 company-partner relations and comprehensive business data

## Usage Example

```javascript
// Simple CNPJ consultation
{
  "document": "11543248000115"
}

// With formatted CNPJ (automatically cleaned)
{
  "document": "11.543.248/0001-15"
}
```

## Common API Responses

- **Success**: Data returned in `value` field with `success: true`
- **Cache miss**: `success: false` - triggers new consultation automatically
- **No data**: `"O documento consultado não possui informações na base de dados"`
- **Invalid CNPJ**: Mathematical validation error before API call
- **Wrong format**: `"Smart PJ 005 requires a CNPJ (14 digits)"`

## Implementation Status

- ✅ **Authentication**: Working perfectly with API v2
- ✅ **API connectivity**: Confirmed and functional  
- ✅ **Document validation**: Mathematical CNPJ/CPF validation implemented
- ✅ **Cache logic**: Fully implemented and working
- ✅ **Product identifiers**: **RESOLVED** - All correct identifiers mapped
- ✅ **Error handling**: Comprehensive error messages for all scenarios

**Status**: **FULLY FUNCTIONAL** 🎉

## Development

```bash
npm install
npm start
```

## Testing

Test the server locally:

```bash
export DEPS_EMAIL="your_email@example.com"
export DEPS_PASSWORD="your_password_here"
node index.js
```

The server will start and listen for MCP requests via stdin/stdout.