MCP-Mem0

Integre memória de longo prazo em agentes de IA usando Mem0.

Documentação

SFCore TH Dev: Integração CumulusCI para Agentes de IA

Uma implementação do servidor Model Context Protocol (MCP) integrado ao CumulusCI para fornecer capacidades de desenvolvimento Salesforce para agentes de IA.

Este servidor permite que agentes de IA interajam com comandos CumulusCI sem que os desenvolvedores precisem lembrar de sintaxe CLI complexa.

Visão Geral

Este projeto demonstra como construir um servidor MCP que permite que agentes de IA executem operações CumulusCI para fluxos de trabalho de desenvolvimento Salesforce. Ele serve como base para criar integrações CCI mais abrangentes.

A implementação segue as melhores práticas estabelecidas pela Anthropic para construir servidores MCP, permitindo integração perfeita com qualquer cliente compatível com MCP.

Recursos

O servidor atualmente fornece uma operação CCI essencial:

create_scratch_org: Cria uma nova scratch org usando o fluxo dev_org do CCI

Pré-requisitos

Python 3.12+
Acesso a uma org Salesforce (Dev Hub para scratch orgs)
Docker se estiver executando o servidor MCP como contêiner (recomendado)

Configuração do Ambiente

O servidor MCP fornece verificação de instalação do CCI e instruções de configuração. Quando você encontrar erros de comando CCI não encontrado, use a ferramenta check_cci_installation que irá guiá-lo através de:

# Check if CCI is installed
cci version

# Install CCI if not present
pipx install cumulusci-plus-azure-devops

# Upgrade CCI if needed
pipx install cumulusci-plus-azure-devops --force

Instalação

Usando uv

Instale o uv se você não o tiver:
```
pip install uv
```

Clone este repositório:

git clone <your-repo-url>
cd sfcore-th-dev

Instale as dependências:
```
uv pip install -e .
```
Certifique-se de que o CumulusCI está instalado e configurado:
```
pip install cumulusci
cci org connect <your-dev-hub>
```

Usando Docker (Recomendado)

Construa a imagem Docker:

docker build -t ghcr.io/jorgesolebur/mcp-sfcore-th-dev:latest --build-arg PORT=8050 .

Envie para o GitHub Container Registry:

docker push ghcr.io/jorgesolebur/mcp-sfcore-th-dev:latest

Nota: Você precisará autenticar com o GitHub Container Registry primeiro:

echo $GITHUB_TOKEN | docker login ghcr.io -u jorgesolebur --password-stdin

Configuração

As seguintes variáveis de ambiente podem ser configuradas no seu arquivo .env:

Variável	Descrição	Padrão
`TRANSPORT`	Protocolo de transporte (sse ou stdio)	`sse`
`HOST`	Host para vincular ao usar transporte SSE	`0.0.0.0`
`PORT`	Porta para escutar ao usar transporte SSE	`8050`

O servidor depende do CumulusCI estar devidamente configurado no sistema onde é executado.

Executando o Servidor

Usando uv

Transporte SSE

# Set TRANSPORT=sse in .env then:
uv run src/main.py

O servidor MCP será executado como um endpoint de API ao qual você pode se conectar com a configuração mostrada abaixo.

Transporte Stdio

Com stdio, o próprio cliente MCP pode iniciar o servidor MCP, então não há nada para executar neste momento.

Usando Docker

Transporte SSE

docker run -d -p 8050:8050 ghcr.io/jorgesolebur/mcp-sfcore-th-dev:latest

O servidor MCP será executado como um endpoint de API dentro do contêiner.

Transporte Stdio

Com stdio, o próprio cliente MCP pode iniciar o contêiner do servidor MCP, então não há nada para executar neste momento.

Integração com Clientes MCP

Configuração SSE

Uma vez que você tenha o servidor executando com transporte SSE, você pode se conectar a ele usando esta configuração:

{
  "mcpServers": {
    "sfcore-th-dev": {
      "transport": "sse",
      "url": "http://localhost:8050/sse"
    }
  }
}

Nota para usuários do Windsurf: Use serverUrl em vez de url na sua configuração:
{
  "mcpServers": {
    "sfcore-th-dev": {
      "transport": "sse",
      "serverUrl": "http://localhost:8050/sse"
    }
  }
}

Nota para usuários do n8n: Use host.docker.internal em vez de localhost, pois o n8n precisa alcançar fora do seu próprio contêiner até a máquina host:

Portanto, a URL completa no nó MCP seria: http://host.docker.internal:8050/sse

Certifique-se de atualizar a porta se estiver usando um valor diferente do padrão 8050.

Python com Configuração Stdio

Adicione este servidor à sua configuração MCP para Claude Desktop, Windsurf ou qualquer outro cliente MCP:

{
  "mcpServers": {
    "sfcore-th-dev": {
      "command": "your/path/to/sfcore-th-dev/.venv/Scripts/python.exe",
      "args": ["your/path/to/sfcore-th-dev/src/main.py"],
      "env": {
        "TRANSPORT": "stdio"
      }
    }
  }
}

Docker com Configuração Stdio

{
  "mcpServers": {
    "sfcore-th-dev": {
      "command": "docker",
      "args": ["run", "--rm", "-i", 
               "-e", "TRANSPORT", 
               "ghcr.io/jorgesolebur/mcp-sfcore-th-dev:latest"],
      "env": {
        "TRANSPORT": "stdio"
      }
    }
  }
}

Estendendo o Servidor

Este modelo fornece uma base para construir integrações CCI mais abrangentes. Para adicionar novas ferramentas CCI:

Crie um novo método @mcp.tool()
Use a função utilitária get_cci_command_instructions() para comportamento consistente

Exemplo:

@mcp.tool()
async def deploy_to_org(org_name: str = "dev") -> str:
    command = f"cci flow run deploy --org {org_name}"
    purpose = f"Deploy to org '{org_name}'"
    return get_cci_command_instructions(command, purpose)

Isso garante que todas as ferramentas tenham execução de comandos e tratamento de erros consistentes.

Ferramentas Disponíveis

Configuração do Ambiente

check_cci_installation: Verifica se o CumulusCI está instalado e fornece instruções de instalação/atualização

Gerenciamento de Scratch Orgs

create_dev_scratch_org: Cria uma scratch org de desenvolvimento usando cci flow run dev_org --org <org_name>
create_feature_scratch_org: Cria uma scratch org de feature/QA usando cci flow run ci_feature_2gp --org <org_name>
create_beta_scratch_org: Cria uma scratch org de beta/regressão usando cci flow run regression_org --org <org_name>
list_orgs: Lista todas as orgs CumulusCI conectadas usando cci org list
open_org: Abre a org especificada em um navegador usando cci org browser --org <org_name>

Operações de Desenvolvimento

run_tests: Executa testes Apex em uma org especificada usando cci task run run_all_tests_locally --org <org_name>
retrieve_changes: Recupera alterações de metadados da org especificada usando cci task run retrieve_changes --org <org_name>
deploy: Implanta metadados locais na org especificada usando cci task run deploy --org <org_name>

Manipulador Genérico de Tarefas CCI

run_generic_cci_task: Manipula qualquer tarefa CCI que não tenha uma ferramenta dedicada seguindo uma abordagem de 3 etapas:
1. Verifica se a tarefa existe usando cci task list
2. Obtém informações e parâmetros da tarefa usando cci task info ou cci task run --help
3. Executa a tarefa com parâmetros apropriados após coletar valores necessários do usuário

Todas as ferramentas CCI fornecem orientação de configuração, se necessário, e seguem padrões consistentes de tratamento de erros.

Recursos MCP

O servidor fornece documentação específica do framework através de recursos MCP. Esses recursos dão aos agentes informações contextuais sobre práticas e padrões de desenvolvimento.

Recursos Disponíveis

Acesse os recursos usando o padrão de URI: framework://<framework-name>

framework://salesforce-triggers: Diretrizes abrangentes para desenvolver triggers Apex
- Arquitetura do framework de triggers
- Implementação do padrão de handler
- Melhores práticas e anti-padrões
- Estratégias de teste
- Considerações de desempenho
framework://salesforce-logging: Padrões e melhores práticas de logging
- Implementação de logger personalizado
- Níveis de log e diretrizes de uso
- Considerações de desempenho
- Estratégias de logging em produção
- Considerações de segurança e privacidade
framework://salesforce-cache-manager: Framework de gerenciamento de Platform Cache para otimização de desempenho
- Três tipos de cache: Organização, Sessão e Transação
- Configuração declarativa com metadados personalizados
- Exemplos de uso e melhores práticas
- Monitoramento de desempenho e depuração
- Considerações de segurança para dados em cache

Usando Recursos

Os agentes podem solicitar documentação do framework quando necessário:

{
  "method": "resources/read",
  "params": {
    "uri": "framework://salesforce-triggers"
  }
}

Isso fornece acesso sob demanda a orientações específicas do framework sem poluir as descrições das ferramentas.

Melhorias Futuras

Considere adicionar:

Recursos adicionais do framework (LWC, Aura, Flows)
Mais ferramentas de operação CCI
Integração com pipelines de CI/CD
Fluxos de trabalho avançados de teste