CLI Integradora para Arcee, TESS e MCP

Este projeto implementa uma interface de linha de comando (CLI) que integra APIs de terceiros, incluindo Arcee AI, TESS e o SDK oficial do Model Context Protocol (@sdk-mcp). O projeto segue a estrutura Clean Architecture e os princípios do Domain-Driven Design (DDD).

Visão Geral da Integração

Esta CLI não reimplementa os serviços que integra, mas serve como uma camada de abstração que permite:

1. Acesso unificado a múltiplos serviços (Arcee, TESS, MCP)
2. Padronização de interfaces para facilitar o uso
3. Adição de funcionalidades específicas à CLI sem modificar as APIs subjacentes

Arquitetura de Componentes

MCP (Model Context Protocol)

O MCP é um protocolo padronizado que facilita a comunicação entre modelos de linguagem e ferramentas externas. Este projeto utiliza o SDK oficial do MCP (@sdk-mcp) para implementar essa comunicação, sem modificar ou reimplementar o protocolo.

Servidor TESS-MCP

O servidor TESS-MCP é o componente responsável por implementar a integração entre o TESS (Tool Execution Subsystem) e o MCP. Este servidor:

• Orquestra e gerencia ferramentas que podem ser utilizadas por modelos de IA
• Expõe APIs para listar e executar agentes de IA
• Gerencia upload e organização de arquivos
• Permite interação com modelos de linguagem como o "tess-ai-light"

O TESS trabalha em conjunto com o MCP, permitindo que modelos solicitem e utilizem ferramentas de forma padronizada.

CLI (Interface de Linha de Comando)

A CLI consome as APIs do servidor TESS-MCP, Arcee AI e MCP, fornecendo uma interface unificada para o usuário final. Ela não reimplementa essas funcionalidades, apenas oferece uma forma padronizada de acessá-las.

Arcee AI

O Arcee AI é uma plataforma completa de IA que inclui:

• Arcee Orchestra: plataforma agentic para construir fluxos de trabalho de IA
• Arcee Conductor: roteador inteligente que seleciona o modelo mais adequado e eficiente em custo para cada prompt
• Small Language Models (SLMs): modelos de linguagem otimizados para tarefas específicas

Para mais informações sobre TESS, consulte a documentação oficial da API TESS.

Arquitetura do Projeto

O projeto segue a Clean Architecture com as seguintes camadas:

1. Domínio

• domain/interfaces: Interfaces que definem contratos para integração com APIs externas
• domain/services: Serviços de domínio que orquestram as chamadas para APIs externas
• domain/exceptions: Exceções de domínio para tratamento de erros

2. Aplicação

• application/use_cases: Casos de uso que coordenam a lógica de negócio

3. Infraestrutura

• infrastructure/mcp_client: Cliente que integra o SDK oficial do MCP (@sdk-mcp)
• infrastructure/providers: Adaptadores para as APIs externas (TESS, Arcee)

4. Interface de Usuário

• src/commands: Comandos CLI para interação com os casos de uso
• src/adapters: Adaptadores para compatibilidade entre implementações

Arquitetura de Adaptadores

Papel dos Adaptadores

Os adaptadores no projeto são componentes arquiteturais intencionais que servem a propósitos específicos:

1. Desacoplamento entre sistemas:

   • MCP e TESS são sistemas com responsabilidades distintas que evoluem independentemente
   • Os adaptadores permitem que essas evoluções ocorram sem quebrar a integração

2. Tradução entre interfaces:

   • Convertem chamadas e dados entre o formato esperado por cada sistema
   • Protegem o domínio de mudanças nas APIs externas

3. Implementação do padrão Ports & Adapters:

   • Facilitam testes unitários e simulações
   • Permitem substituir implementações sem afetar o domínio

Tipos de Adaptadores

O projeto utiliza dois tipos principais de adaptadores:

1. Adaptadores de Infraestrutura:

   • Localização: infrastructure/providers
   • Propósito: Conectar as interfaces do domínio com APIs externas
   • Exemplo: TessApiProvider adapta a API do TESS para a interface ITessProvider do domínio

2. Adaptadores de Compatibilidade:

   • Localização: src/adapters
   • Propósito: Manter compatibilidade com código existente enquanto usa as novas implementações
   • Exemplo: MCPRunClient adapta a nova implementação para código que ainda usa a interface antiga

Otimização de Adaptadores

Nosso foco é manter adaptadores eficientes através de:

• Interfaces padronizadas com contratos claros
• Minimização de conversões desnecessárias
• Cobertura adequada de testes
• Documentação das responsabilidades de cada adaptador

Funcionalidades da CLI

A CLI fornece acesso unificado aos seguintes serviços:

MCP e TESS

A CLI consome as APIs do servidor TESS-MCP, permitindo:

• Listar todas as ferramentas disponíveis
• Buscar ferramentas específicas
• Obter detalhes de ferramentas e agentes
• Executar ferramentas e agentes com parâmetros
• Fazer upload de arquivos para uso com agentes

Arcee AI

A CLI permite interagir com a API do Arcee AI:

• Gerar conteúdo com modelos de linguagem
• Interagir através de uma interface de chat
• Selecionar entre diferentes modelos disponíveis
• Utilizar o roteamento inteligente do Arcee Conductor

Uso

# Ferramentas MCP (via SDK @sdk-mcp)
arcee mcp-tools listar
arcee mcp-tools buscar "processamento"
arcee mcp-tools detalhes tool1
arcee mcp-tools executar tool1 '{"param1": "valor1"}'

# Servidor TESS-MCP
arcee tess listar
arcee tess executar agent123 "Como posso otimizar este código?"

# API Arcee AI
arcee chat "Explique o conceito de Clean Architecture"
arcee generate "Escreva um código Python para ordenar uma lista"

Garantindo Compatibilidade e Evolução

O projeto usa adaptadores para permitir evolução contínua enquanto mantém compatibilidade:

# Código existente (continua funcionando)
from src.tools.mcpx_simple import MCPRunClient

client = MCPRunClient(session_id="abc123")
tools = client.get_tools()

# Código novo (implementação atual)
from infrastructure.mcp_client import MCPClient

client = MCPClient()
tools = client.list_tools()

Este modelo de adaptadores permite:

• Evolução gradual sem quebrar código existente
• Melhoria contínua da implementação interna
• Facilidade de migração para novos clientes

Desenvolvimento

Para desenvolver novos recursos de integração:

1. Defina interfaces no domínio (domain/interfaces) que espelhem as APIs externas
2. Implemente serviços no domínio (domain/services) que orquestrem chamadas às APIs
3. Crie casos de uso na aplicação (application/use_cases) para funcionalidades específicas
4. Implemente clientes/adaptadores na infraestrutura (infrastructure) para comunicação com APIs externas
5. Exponha funcionalidades via CLI (src/commands)

Este fluxo de desenvolvimento garante uma separação clara entre o código do projeto e as APIs externas integradas.

Novidades

25/03/2024

• Novo script para interação direta com API TESS: Implementado o script tess_api_cli.py que permite listar, consultar e executar agentes TESS diretamente, sem depender do comando test_api_tess.
• Suporte a múltiplos modelos de linguagem: O script suporta diversos modelos de linguagem, incluindo GPT-4o e Claude 3.5 Sonnet.
• Exemplos práticos para geração de anúncios: Adicionados exemplos para cafeteria, agência de marketing digital e corretora de seguros.
• Documentação detalhada: Criados guias de integração e dicas avançadas para otimização de anúncios Google Ads usando a API TESS.

20/03/2024

• Interface Streamlit simplificada: Removidas as abas superiores desnecessárias, mantendo apenas "Arcee CLI" e "Ajuda".
• Correção de bugs no adaptador TESS: Resolvidos problemas na comunicação com a API TESS.