mcp-tess/README.md

MCP server for executing Tess AI api

# 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](https://docs.tess.pareto.io/api/introduction/)

## Configuração

### 1. Instalar dependências

```bash
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](https://tess.pareto.io)
2. Vá em User Menu → API Tokens
3. Clique em "Add New Token"

### 3. Compilar o projeto

```bash
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`:

```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`:

```typescript
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`:

```typescript
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:

```typescript
// ... 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:

```typescript
// 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

```bash
# 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)

```bash
# 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

```json
{
  "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

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

### Criar uma memória

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

### Gerenciar coleções de memória

```json
{
  "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

```bash
# 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](https://docs.tess.pareto.io/api/introduction/)