MCP Tess Server

Um servidor MCP (Model Context Protocol) para executar agentes da Tess AI.

Funcionalidades

• Execute Agent: Executa um agente da Tess com uma mensagem
• List Agents: Lista todos os agentes disponíveis
• Get Agent: Obtém informações detalhadas sobre um agente específico
• Create Memory: Cria uma nova memória em uma coleção
• Update Memory: Atualiza uma memória existente
• Delete Memory: Deleta uma memória
• List Memory Collections: Lista todas as coleções de memória
• Create Memory Collection: Cria uma nova coleção de memória
• Update Memory Collection: Atualiza uma coleção de memória
• Delete Memory Collection: Deleta uma coleção de memória

Ref: Documentação da API Tess

Configuração

1. Instalar dependências

npm install

2. Configurar API Key

Configure sua chave da API da Tess através da variável de ambiente TESS_API_KEY:

Para obter uma chave da API:

1. Acesse Tess AI
2. Vá em User Menu → API Tokens
3. Clique em "Add New Token"

3. Compilar o projeto

npm run build

Configuração do MCP Server

O projeto suporta duas configurações diferentes:

Configuração Local (Desenvolvimento)

• Nome: tess-test
• Execução: Código TypeScript direto via tsx
• Ideal para: Desenvolvimento e testes

Configuração de Produção

• Nome: tess
• Execução: Pacote npm publicado
• Ideal para: Uso em produção

Arquivo de Configuração

Crie ou edite o arquivo ~/.cursor/mcp.json:

{
  "mcpServers": {
    "tess-test": {
      "command": "npx",
      "args": ["tsx", "/CAMINHO/ABSOLUTO/PARA/SEU/PROJETO/src/index.ts"],
      "cwd": "/CAMINHO/ABSOLUTO/PARA/SEU/PROJETO",
      "env": {
        "TESS_API_KEY": "sua_chave_api_aqui"
      }
    },
    "tess": {
      "command": "npx",
      "args": ["-y", "mcp-tess"],
      "env": {
        "TESS_API_KEY": "sua_chave_api_aqui"
      }
    }
  }
}

Importante:

• Substitua /CAMINHO/ABSOLUTO/PARA/SEU/PROJETO pelo caminho real do seu projeto
• Substitua sua_chave_api_aqui pela sua chave da API da Tess
• Use tess-test durante desenvolvimento
• Use tess em produção (após publicar o pacote npm)

Como criar uma nova Tool

A arquitetura atual organiza os serviços por domínio dentro de src/services/tess/. Para criar uma nova tool, siga estes passos:

1. Definir tipos (se necessário)

Se sua tool requer novos tipos, adicione-os em src/services/tess/types.ts:

export interface MinhaNovaResponse {
  message: string;
  data: any;
}

2. Criar ou atualizar arquivo de serviço

Dependendo do domínio da sua nova tool, crie um novo arquivo ou atualize um existente:

Para um novo domínio - Criar arquivo src/services/tess/meuDominio.ts:

import { tessApiClient, handleTessApiError } from "./base";
import { MinhaNovaResponse } from "./types";

export const minhaNovaFuncao = async (
  parametro1: string,
  parametro2?: number
): Promise<MinhaNovaResponse> => {
  try {
    const response = await tessApiClient.post<MinhaNovaResponse>(
      "/meu-endpoint",
      {
        param1: parametro1,
        param2: parametro2
      }
    );

    return response.data;
  } catch (error) {
    throw handleTessApiError(error);
  }
};

Para um domínio existente - Atualizar arquivo existente:

Se a funcionalidade se encaixa em um dos domínios existentes, adicione a nova função ao arquivo correspondente seguindo o mesmo padrão.

3. Exportar no index.ts do serviço

Atualize src/services/tess/index.ts para exportar suas novas funções:

// ... existing code ...

// Se criou um novo arquivo de domínio
export * from "./meuDominio";

4. Registrar a tool no servidor principal

Em src/index.ts, importe e registre a nova tool:

// 1. Importe a função
import { minhaNovaFuncao } from "./services/tess/index.js";

// 2. Registre a tool no servidor
server.tool(
  "minha-nova-tool",
  "Descrição clara da funcionalidade da tool",
  {
    parametro1: z.string().describe("Descrição detalhada do parâmetro 1"),
    parametro2: z.number().optional().describe("Descrição do parâmetro 2 (opcional)"),
  },
  async (args) => {
    try {
      const { parametro1, parametro2 } = args;
      const result = await minhaNovaFuncao(parametro1, parametro2);
      
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(result, null, 2)
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error executing minha nova tool: ${error instanceof Error ? error.message : String(error)}`
          }
        ],
        isError: true
      };
    }
  }
);

5. Padrões recomendados

Estrutura de arquivos:

• Organize por domínio funcional (agents, memories, collections, etc.)
• Use o cliente base tessApiClient para chamadas à API
• Use handleTessApiError para tratamento consistente de erros
• Mantenha tipos centralizados em types.ts

Nomenclatura:

• Tools: kebab-case (ex: create-tess-memory)
• Funções: camelCase (ex: createTessMemory)
• Interfaces: PascalCase (ex: CreateMemoryResponse)
• Arquivos: camelCase (ex: agents.ts, myDomain.ts)

Tratamento de erros:

• Sempre use try/catch nos serviços
• Use handleTessApiError para erros da API Tess
• Retorne mensagens de erro claras nas tools

Validação de parâmetros:

• Use Zod para validação nas tools
• Adicione descrições claras para cada parâmetro
• Marque parâmetros opcionais corretamente

Como testar

Método 1: Teste direto com Node.js

# Executar o servidor em desenvolvimento
npm run dev

Método 2: Teste com Claude Desktop/Cursor (Recomendado)

1. Configure o arquivo MCP conforme mostrado na seção "Configuração do MCP Server"

2. Reinicie a IDE

3. Teste o mcp server:

Você pode usar comandos como:

• "Liste todos os agentes da Tess disponíveis"
• "Execute o agente ID 123 com a mensagem 'Olá, como você pode me ajudar?'"
• "Mostre detalhes do agente ID 456"
• "Crie uma nova memória com o conteúdo 'Esta é uma memória de teste'"

Método 3: Teste com MCP Inspector (Para desenvolvimento)

# Instalar o MCP Inspector globalmente
npm install -g @modelcontextprotocol/inspector

# Executar o inspector
mcp-inspector npx tsx src/index.ts

Estrutura do Projeto

mcp-tess/
├── src/
│   ├── index.ts              # Servidor MCP principal - registro das tools
│   └── services/
│       └── tess/             # Serviços da API Tess organizados por domínio
│           ├── index.ts      # Exportações centralizadas
│           ├── types.ts      # Tipos e interfaces compartilhadas
│           ├── config.ts     # Configurações da API
│           ├── base.ts       # Cliente HTTP base e utilitários
│           ├── agents.ts     # Funcionalidades relacionadas aos agentes
│           ├── memories.ts   # Funcionalidades de memórias
│           └── collections.ts # Funcionalidades de coleções
├── dist/                     # Código compilado
├── package.json
├── tsconfig.json
└── README.md

Exemplos de Uso

Executar um agente

{
  "tool": "Execute Agent",
  "arguments": {
    "agentId": 123,
    "message": "Qual é a previsão do tempo para hoje?",
    "temperature": "0.5",
    "model": "tess-5",
    "fileIds": [1, 2],
    "memoryCollections": [10, 15]
  }
}

Listar agentes

{
  "tool": "List Agents",
  "arguments": {
    "search": "assistente",
    "type": "chat",
    "page": 1,
    "perPage": 5
  }
}

Criar uma memória

{
  "tool": "Create Memory",
  "arguments": {
    "memory": "Esta é uma informação importante que deve ser lembrada",
    "collectionId": 1
  }
}

Gerenciar coleções de memória

{
  "tool": "Create Memory Collection",
  "arguments": {
    "name": "Projetos importantes"
  }
}

Parâmetros da API Tess

Execute Agent

• agentId (obrigatório): ID do agente da Tess
• message (obrigatório): Mensagem para enviar ao agente
• rootId (opcional): ID raiz da execução para criar uma conversa
• temperature (opcional): Temperatura do modelo (padrão: "1")
• model (opcional): Modelo a usar (padrão: "tess-5")
• tools (opcional): Configuração de ferramentas (padrão: "no-tools")
• fileIds (opcional): Array de IDs de arquivos para anexar
• memoryCollections (opcional): Array de IDs de coleções de memória para anexar

Memory Tools

• Create Memory: Cria nova memória (max 32.000 caracteres)
• Update Memory: Atualiza memória existente
• Delete Memory: Remove uma memória
• List Memory Collections: Lista coleções com paginação
• Create Memory Collection: Cria nova coleção
• Update Memory Collection: Atualiza nome da coleção
• Delete Memory Collection: Remove coleção inteira

Troubleshooting

Erro: "Tess API error"

• Verifique se sua API key está correta
• Confirme se você tem acesso aos agentes que está tentando usar
• Verifique se o agentId existe

Servidor não aparece no Claude Desktop

1. Verifique se o caminho no arquivo MCP está correto e absoluto
2. Certifique-se de que a API key está configurada
3. Para desenvolvimento, use a configuração tess-test
4. Para produção, publique o pacote e use a configuração tess
5. Reinicie completamente o Claude Desktop
6. Verifique os logs do MCP server

Erro de sintaxe TypeScript

• Execute npm run build para verificar erros de compilação
• Certifique-se de que todas as dependências estão instaladas

Configuração Local vs Produção

• Local (tess-test): Execute npx tsx src/index.ts no diretório do projeto
• Produção (tess): Execute npx -y mcp-tess (requer publicação no npm)

Desenvolvimento

# Executar em modo desenvolvimento (com hot reload)
npm run dev

# Compilar
npm run build

# Executar versão compilada
npm start

Documentação da API Tess

Para mais informações sobre a API da Tess, consulte:

• Documentação da API Tess