crm_mcp_server

dock-tech/crm_mcp_server

3.2

If you are the rightful owner of crm_mcp_server 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.

The CRM MCP Server is a comprehensive integration solution for connecting CRM Dock with AppSheet via the AppSheet API, implementing advanced primitives of the Model Context Protocol.

Tools
7
Resources
0
Prompts
0

CRM MCP Server - AppSheet Integration

Servidor MCP completo para integração com CRM Dock via AppSheet API. Implementa todos os primitives avançados do Model Context Protocol.

🚀 Transportes Suportados

1. stdio (JSON-RPC)

Para clientes MCP locais:

crm-mcp-server

2. HTTP Streaming

Para acesso via rede:

crm-mcp-server-http
# ou
python -m crm_mcp_server.server http
# ou via FastMCP CLI com path customizado
fastmcp run src/crm_mcp_server/server.py --transport http --host 0.0.0.0 --port 9001 --path /mcp

# Health check HTTP (quando rodando em modo HTTP)
curl http://localhost:9001/health

🔐 Autenticação (Opcional)

O servidor suporta autenticação OAuth 2.0 / OIDC opcional e desabilitada por padrão.

Características

  • ✅ Opcional: Auth desabilitado por padrão, zero configuração necessária para começar
  • ✅ Fácil de habilitar: Apenas configure env vars e reinicie
  • ✅ Graceful Fallback: Servidor continua funcionando se auth falhar
  • ✅ Múltiplos Provedores: Okta, Auth0, Google, Azure AD, Keycloak, etc
  • ✅ Context de Usuário: Tools podem acessar informações do usuário autenticado

Quando Usar

Use autenticação quando:

  • Servidor está exposto na rede (não localhost)
  • Múltiplos usuários acessam o sistema
  • Precisa rastrear quem executou operações (audit trail)
  • Ambiente de produção com dados sensíveis

Não use quando:

  • Desenvolvimento local pessoal
  • Protótipo/POC sem dados sensíveis
  • Ambiente isolado/sandbox

Quick Start

  1. Configure variáveis no .env:
AUTH_ENABLED=true
FASTMCP_SERVER_AUTH_OIDC_CONFIG_URL=https://your-okta-domain.okta.com/.well-known/openid-configuration
FASTMCP_SERVER_AUTH_OIDC_CLIENT_ID=your_client_id
FASTMCP_SERVER_AUTH_OIDC_CLIENT_SECRET=your_client_secret
  1. Reinicie o servidor:
make server-http
  1. Cliente conecta automaticamente com OAuth:
python client.py  # Browser abre para login automaticamente

Guia Completo

📖 Consulte o guia detalhado:

O guia inclui:

  • Setup completo do Okta (passo a passo)
  • Configuração de outras IDPs (Auth0, Google, Azure AD)
  • Troubleshooting
  • Segurança e melhores práticas
  • Exemplos de uso

Novas Tools com Auth

Quando auth está habilitado, duas novas tools ficam disponíveis:

crm_get_auth_status - Verifica status de autenticação do servidor

{
  "authentication_enabled": true,
  "auth_provider": "OIDC",
  "server_mode": "Authenticated"
}

crm_get_user_info - Retorna informações do usuário autenticado

{
  "authenticated": true,
  "user_id": "00u9abc...",
  "email": "user@example.com",
  "name": "John Doe",
  "username": "john.doe",
  "groups": ["Everyone", "Developers"]
}

Testar Configuração

# Verificar variáveis de auth
make test-auth

# Testar com cliente
make client

# Ver status geral (inclui auth)
make status

📦 Instalação

Pré-requisitos

  • Python 3.10+
  • Credenciais AppSheet (APP_ID e API_KEY)

Instalação Local

# 1. Clonar o repositório
cd crm_mcp_server

# 2. Criar ambiente virtual
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate  # Windows

# 3. Instalar dependências
pip install -e .

# 4. Instalar dependências de desenvolvimento (opcional)
pip install -e ".[dev]"

⚙️ Configuração

Escolha Sua Fonte de Dados

O servidor suporta duas fontes de dados:

  1. AppSheet API (produção) - Dados em tempo real
  2. Dados Locais (desenvolvimento/fallback) - Arquivos CSV/JSON

Opção A: Usar AppSheet (Produção)

⚠️ IMPORTANTE: Antes de usar o servidor, você precisa habilitar a API REST no AppSheet.

📖 Consulte o guia completo:

Resumo rápido:

  1. Acesse https://www.appsheet.com/account/apps
  2. Abra seu aplicativo
  3. Vá em Settings > Integrations > IN
  4. Habilite "Enable API for this app"
  5. Copie o Application Access Key e o App ID

Opção B: Usar Dados Locais (Desenvolvimento/Fallback)

✅ Modo recomendado enquanto a API do AppSheet não estiver disponível

📖 Consulte o guia completo:

Configurar arquivo .env na raiz do projeto:

# Copie o arquivo de exemplo
cp env.example .env

# Edite as configurações conforme necessário

Exemplo de .env:

# Fonte de dados: local ou appsheet
DATA_SOURCE=local

# Diretório dos dados (usa CSVs existentes em dados/)
DATA_DIR=dados

Arquivos suportados (já existentes no projeto):

  • dados/lista-de-emissores.csv → Management + Business
  • dados/base-de-contatos.csv → Contacts

Testar:

python test_local_data.py

Opção C: Configurar Ambos (Recomendado)

# Fonte de dados
DATA_SOURCE=local  # Mudar para "appsheet" quando disponível

# AppSheet (para quando estiver disponível)
APPSHEET_APP_ID=seu-app-id-aqui
APPSHEET_API_KEY=V2-xxxxx-sua-api-key-aqui

# Dados locais
DATA_DIR=dados

# Cache (opcional)
CACHE_ENABLED=true
CACHE_TTL_SECONDS=300

# Servidor HTTP (opcional)
HTTP_HOST=0.0.0.0
HTTP_PORT=9001
HTTP_PATH=/mcp

# Retry (opcional)
MAX_RETRIES=3
RETRY_DELAY_SECONDS=1.0

# Log (opcional)
LOG_LEVEL=INFO
ENVIRONMENT=production

Testar Configuração

Se usando dados locais:

python test_local_data.py

Se usando AppSheet:

python diagnose.py
python test_appsheet_connection.py

🎯 MCP Primitives Implementados

Tools (8)

Core Tools:

  1. crm_buscar_cliente - Busca por ID ou nome com progress reporting
  2. crm_listar_contatos - Lista contatos com categorização
  3. crm_health_check - Verifica conectividade com fonte de dados

Authentication Tools: 4. crm_get_auth_status - Retorna status de autenticação do servidor 5. crm_get_user_info - Retorna informações do usuário autenticado (requer auth)

Advanced Tools: 6. crm_classify_client - Classificação inteligente via LLM (Sampling) 7. crm_complex_query - Queries complexas com confirmação (Elicitations)

Resources (4 URIs)

  • crm://clientes - Lista todos os clientes
  • crm://cliente/{id} - Detalhes completos de um cliente
  • crm://contatos - Lista todos os contatos
  • crm://management/{pch_id} - Dados de gestão (KAM, CSM, tier)

Prompts (3)

  • format_client_summary - Template para resumo executivo
  • format_contact_list_prompt - Template para lista de contatos
  • analyze_portfolio - Template para análise de portfólio

Advanced Features

  • Sampling: Classificação AI de clientes via LLM
  • Elicitations: Confirmações interativas para operações complexas
  • Tags & Annotations: Metadados em todas as tools
  • Context Logging: Logs contextuais em tempo real das operações
  • Structured Logging: Logs estruturados com structlog
  • Retry Logic: Retry automático com backoff exponencial

📖 Exemplos de Uso

Buscar Cliente por Nome

{
  "name": "crm_buscar_cliente",
  "arguments": {
    "query": "Stone Pagamentos",
    "search_mode": "name",
    "format": "detailed"
  }
}

Resposta:

📋 Cliente: Stone Pagamentos
ID PCH: PCH001
ID Dockerone: DOCK001
...

Buscar Cliente por ID

{
  "name": "crm_buscar_cliente",
  "arguments": {
    "query": "PCH001",
    "search_mode": "id",
    "format": "summary"
  }
}

Listar Contatos de um Cliente

{
  "name": "crm_listar_contatos",
  "arguments": {
    "query": "Stone",
    "categoria": "executivos",
    "limit": 10
  }
}

Listar Todos os Contatos do CRM

{
  "name": "crm_listar_contatos",
  "arguments": {
    "categoria": "todas",
    "limit": 50
  }
}

Acessar Resource

Para acessar recursos via URI:

crm://cliente/PCH001

Retorna JSON com detalhes completos do cliente.

Classificar Cliente com AI (Sampling)

{
  "name": "crm.classify_client",
  "arguments": {
    "client_data": "{\"nome\": \"Stone\", \"faturamento_anual\": \"1000000\", \"segmento\": \"Financial\"}"
  }
}

Retorna classificação estruturada:

{
  "success": true,
  "tier_suggested": "Diamond",
  "segment": "Financial",
  "priority": "High",
  "recommended_actions": [
    "Agendar revisão trimestral",
    "Oferecer novos produtos",
    "Expandir relacionamento"
  ],
  "reasoning": "Cliente de alto valor com grande potencial de crescimento"
}

Query Complexa com Confirmação (Elicitations)

{
  "name": "crm.complex_query",
  "arguments": {
    "query_type": "filtered_contacts",
    "filters": {
      "client_name": "Stone",
      "limit": 100
    }
  }
}

O sistema solicitará confirmação interativa antes de executar.

Health Check

{
  "name": "crm_health_check",
  "arguments": {}
}

🏗️ Arquitetura

┌─────────────────────────────────────────────┐
│ MCP Client (Cursor, Claude Desktop, etc)  │
└──────────────┬──────────────────────────────┘
               │
               ▼ (stdio ou HTTP streaming)
┌─────────────────────────────────────────────┐
│ CRM MCP Server (server.py)                 │
│  - Tools (6)                                │
│  - Resources (4)                            │
│  - Prompts (3)                              │
│  - Sampling & Elicitations                  │
└──────────────┬──────────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────────┐
│ Data Provider (data_provider.py)          │
│  - Cache management                         │
│  - Error handling                           │
└──────────────┬──────────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────────┐
│ AppSheet Service (appsheet_service.py)    │
│  - HTTP client                              │
│  - Retry logic (tenacity)                   │
│  - Connection pooling                       │
└──────────────┬──────────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────────┐
│ AppSheet API                                │
│  - Tables: Management, Business, Contacts   │
└─────────────────────────────────────────────┘

⚡ Performance

  • AppSheet API: ~200-500ms por request
  • Com cache: ~10-50ms (hit rate esperado >70%)
  • Retry automático: até 3 tentativas com backoff exponencial
  • Timeout: 30s para requests HTTP
  • Connection pooling: máx 10 conexões simultâneas

🧪 Testes e Diagnóstico

Scripts Utilitários

1. Diagnóstico Completo

Valida toda a configuração do sistema:

python diagnose.py
2. Teste de Credenciais e Download de Dados

Testa conexão e baixa dados para análise local:

python test_appsheet_connection.py
3. Análise de Dados

Analisa dados exportados e gera relatórios:

python analyze_data.py

📖 Guia completo:

Suite de Testes Automatizados

# Todos os testes
pytest tests/ -v

# Testes específicos
pytest tests/test_server.py::test_appsheet_connection -v

# Com cobertura
pytest tests/ --cov=src/crm_mcp_server --cov-report=html

Testes Incluem

  • ✅ Validação de configurações
  • ✅ Conexão com AppSheet
  • ✅ Busca por ID
  • ✅ Busca por nome
  • ✅ Listagem de contatos
  • ✅ Performance de cache
  • ✅ Error handling
  • ✅ Categorização de contatos
  • ✅ Retry mechanism
  • ✅ Health check

🔧 Troubleshooting

Erro: "ZodError: Invalid input" no MCP Inspector

Causa: O servidor estava enviando logs para STDOUT, que é usado pelo protocolo MCP.

Solução: ✅ Já corrigido! Todos os logs agora vão para STDERR.

Erro: "validation error for ProgressNotificationParams"

Causa: O ctx.report_progress() estava sendo chamado incorretamente com strings ao invés de números.

Solução: ✅ Já corrigido! Agora usamos apenas ctx.info() para mensagens de status.

Erro: "APPSHEET_APP_ID não configurado"

Causa: Arquivo .env não existe ou está incorreto.

Solução:

# Criar .env com credenciais
echo "APPSHEET_APP_ID=seu-id" > .env
echo "APPSHEET_API_KEY=sua-key" >> .env

Erro: "Connection timeout"

Causa: Problemas de rede ou AppSheet API lenta.

Solução:

  • Verificar conectividade com internet
  • Retry automático está ativo (até 3 tentativas)
  • Aumentar timeout se necessário no appsheet_service.py

Cache não funcionando

Causa: Cache desabilitado ou TTL muito baixo.

Solução:

# No .env
CACHE_ENABLED=true
CACHE_TTL_SECONDS=300

Erro: "No module named 'fastmcp'"

Causa: Dependências não instaladas.

Solução:

pip install -e .

Testes falhando com "No data"

Causa: AppSheet não tem dados ainda ou credenciais incorretas.

Solução:

  1. Verificar credenciais no .env
  2. Adicionar dados no AppSheet
  3. Alguns testes serão pulados (skip) se não houver dados

🛠️ Desenvolvimento

Makefile - Comandos Úteis

O projeto inclui um Makefile completo com comandos organizados por categoria:

# Ver todos os comandos disponíveis
make help

# Setup completo e iniciar servidor
make quick-start

# Ciclo completo de desenvolvimento
make dev

# Comandos por categoria:
make server-http          # Inicia servidor HTTP (mata porta se ocupada)
make kill-9001           # Libera porta 9001
make lint                # Linting com ruff
make test                # Executa testes
make health-check        # Testa health check
make diagnose            # Diagnóstico completo

Principais comandos:

  • make server-http - Inicia servidor HTTP (automatically kills port if in use)
  • make kill-port PORT=9001 - Libera porta específica
  • make quick-start - Setup completo + servidor
  • make dev - Ciclo completo: kill → lint → test → server

Lint e Formatação

# Lint com ruff
ruff check src/ tests/

# Formatar código
ruff format src/ tests/

# Configurações do ruff
ruff check --line-length 120 --max-complexity 8 src/

Estrutura do Projeto

crm_mcp_server/
├── src/
│   └── crm_mcp_server/
│       ├── __init__.py
│       ├── __main__.py
│       ├── config.py              # Configurações centralizadas
│       ├── server.py               # Servidor MCP principal
│       ├── data_provider.py        # Camada de dados
│       ├── formatter.py            # Formatação de respostas
│       ├── models.py               # Modelos Pydantic
│       └── services/
│           ├── __init__.py
│           └── appsheet_service.py # Cliente AppSheet
├── tests/
│   ├── __init__.py
│   └── test_server.py              # Suite de testes
├── pyproject.toml                  # Configuração do projeto
├── requirements.txt                # Dependências pip
├── .env                            # Variáveis de ambiente (não versionado)
├── .gitignore
└── README.md

📊 Métricas de Qualidade

  • Testes: 11 testes (8 passed, 3 skipped sem dados)
  • Cobertura: >80% das funções críticas
  • Lint: 100% conformidade com ruff
  • Type hints: Completo em funções públicas
  • Documentação: Docstrings em todas as funções

🔐 Segurança

  • ✅ Credenciais via variáveis de ambiente (.env)
  • ✅ Não expõe credenciais nos logs
  • ✅ Validação de entrada via Pydantic
  • ✅ Timeout configurado para evitar hanging
  • ⚠️ Sem autenticação no servidor (assumindo rede interna)
  • ⚠️ Sem rate limiting (pode ser adicionado se necessário)

🔐 Segurança

Visão Geral

  • ✅ Autenticação OAuth/OIDC opcional (desabilitada por padrão)
  • ✅ Credenciais via variáveis de ambiente (.env)
  • ✅ Não expõe credenciais nos logs
  • ✅ Validação de entrada via Pydantic
  • ✅ Timeout configurado para evitar hanging
  • ⚠️ Sem rate limiting (pode ser adicionado se necessário)

Modo Desenvolvimento (Padrão)

Por padrão, o servidor roda sem autenticação:

  • ✅ Ideal para desenvolvimento local
  • ✅ Zero configuração necessária
  • ⚠️ NÃO exponha na rede pública sem auth

Modo Produção (Recomendado)

Para produção, SEMPRE habilite autenticação:

# .env para produção
AUTH_ENABLED=true
FASTMCP_SERVER_AUTH_OIDC_CONFIG_URL=https://your-company.okta.com/.well-known/openid-configuration
FASTMCP_SERVER_AUTH_OIDC_CLIENT_ID=prod_client_id
FASTMCP_SERVER_AUTH_OIDC_CLIENT_SECRET=prod_client_secret
FASTMCP_SERVER_AUTH_OIDC_BASE_URL=https://crm-mcp.your-company.com

Checklist de Segurança para Produção

OBRIGATÓRIO:

  • Habilitar autenticação (AUTH_ENABLED=true)
  • Usar HTTPS (não HTTP)
  • Configurar redirect URIs específicos (não wildcards)
  • Usar gerenciador de secrets (Vault, AWS Secrets, etc)
  • Configurar CORS policy restritiva
  • Habilitar logs estruturados para SIEM

RECOMENDADO:

  • Implementar rate limiting
  • Configurar reverse proxy (nginx, Caddy)
  • Monitorar logs de autenticação
  • Configurar alertas de segurança
  • Revisar permissões de usuários periodicamente
  • Usar authorization server customizado

NUNCA:

  • ❌ Commitar .env no Git
  • ❌ Compartilhar Client Secret publicamente
  • ❌ Usar HTTP em produção (sempre HTTPS)
  • ❌ Desabilitar validação de token
  • ❌ Usar credenciais de dev em produção
  • ❌ Expor servidor sem auth na internet

Audit Trail

Com auth habilitado, todas as operações incluem contexto de usuário nos logs:

logger.info(
    "client_search_success",
    query=query,
    client_name=cliente.nome,
    user_id=token.claims.get("sub"),
    user_email=token.claims.get("email"),
    duration_seconds=duration,
)

Configure structlog para exportar para seu SIEM:

structlog.configure(
    processors=[...],
    logger_factory=structlog.PrintLoggerFactory(file=sys.stdout),
)

Mais Informações

📖 Guia completo de segurança:

🚢 Deploy

Recomendações

  1. Desenvolvimento: Usar modo stdio
  2. Produção interna: Usar HTTP streaming com rede privada
  3. Produção externa: Adicionar autenticação JWT (não implementado)

Variáveis de Ambiente Essenciais para Produção

Com Autenticação (Recomendado):

# Data Source
DATA_SOURCE=appsheet  # ou local
APPSHEET_APP_ID=...
APPSHEET_API_KEY=...

# Authentication (OBRIGATÓRIO em produção)
AUTH_ENABLED=true
FASTMCP_SERVER_AUTH_OIDC_CONFIG_URL=https://your-company.okta.com/.well-known/openid-configuration
FASTMCP_SERVER_AUTH_OIDC_CLIENT_ID=prod_client_id
FASTMCP_SERVER_AUTH_OIDC_CLIENT_SECRET=prod_client_secret
FASTMCP_SERVER_AUTH_OIDC_BASE_URL=https://crm-mcp.your-company.com
FASTMCP_SERVER_AUTH_OIDC_AUDIENCE=https://crm-mcp.your-company.com

# Server
HTTP_HOST=0.0.0.0
HTTP_PORT=9001
ENVIRONMENT=production
LOG_LEVEL=WARNING

# Performance
CACHE_ENABLED=true
MAX_RETRIES=5

Sem Autenticação (apenas para rede interna isolada):

# Data Source
DATA_SOURCE=appsheet
APPSHEET_APP_ID=...
APPSHEET_API_KEY=...

# Authentication (desabilitado - USE APENAS EM REDE PRIVADA)
AUTH_ENABLED=false

# Server
HTTP_HOST=0.0.0.0
HTTP_PORT=9001
ENVIRONMENT=production
LOG_LEVEL=WARNING

# Performance
CACHE_ENABLED=true
MAX_RETRIES=5

🗺️ Roadmap (Melhorias Futuras)

  • Cache Redis distribuído
  • Rate limiting por cliente
  • Metrics Prometheus/Grafana
  • Autenticação JWT
  • Webhooks AppSheet
  • Circuit breaker pattern
  • Observability completa (traces, spans)

📝 Licença

Proprietary - Dock Tech

Versão: 1.0.0 Última atualização: 2025-10-12 Suporte: Dock Tech Team