@aiconnect/agentjobs-mcp 1.0.9 → 1.2.0

package/build/utils/schemas.test.js

@@ -0,0 +1,95 @@
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { flexibleDateTimeSchema } from './schemas.js';
+describe('flexibleDateTimeSchema', () => {
+    it('should validate a correct ISO 8601 string with Zulu time', () => {
+        const result = flexibleDateTimeSchema().safeParse('2025-07-23T21:00:00Z');
+        expect(result.success).toBe(true);
+    });
+    it('should validate a correct ISO 8601 string with a positive offset', () => {
+        const result = flexibleDateTimeSchema().safeParse('2025-07-23T22:00:00+01:00');
+        expect(result.success).toBe(true);
+    });
+    it('should validate a correct ISO 8601 string with a negative offset', () => {
+        const result = flexibleDateTimeSchema().safeParse('2025-07-23T16:00:00-05:00');
+        expect(result.success).toBe(true);
+    });
+    it('should not validate an incorrect date format', () => {
+        const result = flexibleDateTimeSchema().safeParse('23/07/2025 21:00:00');
+        expect(result.success).toBe(false);
+    });
+    it('should not validate a gibberish string', () => {
+        const result = flexibleDateTimeSchema().safeParse('not-a-date');
+        expect(result.success).toBe(false);
+    });
+    it('should not validate an empty string', () => {
+        const result = flexibleDateTimeSchema().safeParse('');
+        expect(result.success).toBe(false);
+    });
+    it('should validate a date-only string (no time component)', () => {
+        const result = flexibleDateTimeSchema().safeParse('2024-07-23');
+        expect(result.success).toBe(true);
+    });
+    it('should reject invalid string with the exact ISO 8601 error message', () => {
+        const result = flexibleDateTimeSchema().safeParse('not-a-date');
+        expect(result.success).toBe(false);
+        if (!result.success) {
+            expect(result.error.issues[0].message).toBe('Invalid date-time string. Please use a valid ISO 8601 format.');
+        }
+    });
+    it('should reject null when used with .optional() (string | undefined, not nullable)', () => {
+        const schema = flexibleDateTimeSchema().optional();
+        expect(schema.safeParse(undefined).success).toBe(true);
+        const nullResult = schema.safeParse(null);
+        expect(nullResult.success).toBe(false);
+        if (!nullResult.success) {
+            const issue = nullResult.error.issues[0];
+            expect(issue.code).toBe('invalid_type');
+            // Zod 3: { expected: 'string', received: 'null' }
+            expect(issue.expected).toBe('string');
+            expect(issue.received).toBe('null');
+        }
+    });
+});
+describe('JSON Schema serialization', () => {
+    it('should inline each list_jobs date filter field without $ref', () => {
+        const shape = z.object({
+            scheduled_at: flexibleDateTimeSchema().optional(),
+            scheduled_at_gte: flexibleDateTimeSchema().optional(),
+            scheduled_at_lte: flexibleDateTimeSchema().optional(),
+            created_at_gte: flexibleDateTimeSchema().optional(),
+            created_at_lte: flexibleDateTimeSchema().optional(),
+        });
+        const json = zodToJsonSchema(shape);
+        const expectedFields = [
+            'scheduled_at',
+            'scheduled_at_gte',
+            'scheduled_at_lte',
+            'created_at_gte',
+            'created_at_lte',
+        ];
+        for (const field of expectedFields) {
+            const prop = json.properties[field];
+            expect(prop.$ref, `expected ${field} to be inline, got $ref ${String(prop.$ref)}`).toBeUndefined();
+            expect(prop.type, `expected ${field} to have type 'string', got ${String(prop.type)}`).toBe('string');
+        }
+    });
+    it('should produce $ref-free JSON for both list_jobs and get_jobs_stats shapes', () => {
+        const listJobsShape = z.object({
+            scheduled_at: flexibleDateTimeSchema().optional(),
+            scheduled_at_gte: flexibleDateTimeSchema().optional(),
+            scheduled_at_lte: flexibleDateTimeSchema().optional(),
+            created_at_gte: flexibleDateTimeSchema().optional(),
+            created_at_lte: flexibleDateTimeSchema().optional(),
+        });
+        const statsShape = z.object({
+            scheduled_at_gte: flexibleDateTimeSchema().optional(),
+            scheduled_at_lte: flexibleDateTimeSchema().optional(),
+            created_at_gte: flexibleDateTimeSchema().optional(),
+            created_at_lte: flexibleDateTimeSchema().optional(),
+        });
+        expect(JSON.stringify(zodToJsonSchema(listJobsShape))).not.toContain('$ref');
+        expect(JSON.stringify(zodToJsonSchema(statsShape))).not.toContain('$ref');
+    });
+});

package/build/utils/version.js

@@ -0,0 +1,12 @@
+import fs from 'fs';
+function readVersion() {
+    try {
+        const raw = fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf-8');
+        const pkg = JSON.parse(raw);
+        return pkg.version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+export const mcpServerVersion = readVersion();

package/build/utils/version.test.js

@@ -0,0 +1,9 @@
+import { describe, it, expect } from 'vitest';
+import { mcpServerVersion } from './version.js';
+describe('mcpServerVersion', () => {
+    it('resolves to a non-empty string from package.json in dev tree', () => {
+        expect(typeof mcpServerVersion).toBe('string');
+        expect(mcpServerVersion.length).toBeGreaterThan(0);
+        expect(mcpServerVersion).not.toBe('unknown');
+    });
+});

package/docs/agent-jobs-api.md

@@ -239,6 +239,47 @@ Cancels a job by changing its status to CANCELED.
 - 404: Job not found
 - 409: Conflict (job is already in a terminal state)
 
+### List Job Types (`agent-jobs-type`)
+
+Lists agent job types registered for an organization. Used by `get_job_type` and `get_context` in this MCP.
+
+#### Path em uso pelas tools deste MCP hoje
+
+```http
+GET /organizations/:org_id/agent-jobs-type
+GET /organizations/:org_id/agent-jobs-type/:job_type_id
+```
+
+(Sem prefixo `/services/`.) **Toda tool nova neste repo deve usar este caminho** até a unificação descrita abaixo, para manter consistência com `get_job_type`.
+
+#### Path canônico upstream
+
+```http
+GET /services/organizations/:org_id/agent-jobs-type
+GET /services/organizations/:org_id/agent-jobs-type/:job_type_id
+```
+
+Este é o caminho documentado upstream pelo AI Connect API. O backend serve a mesma controller em ambos os mounts (legacy + atual). Uma migração futura para o caminho canônico deve ser feita em **change separado abrangendo todas as tools afetadas**: `get_job_type`, `list_jobs`, `create_job`, `get_jobs_stats` e `get_context`.
+
+#### Query parameters suportados
+
+- `enrich=emoji` — adiciona o campo `emoji` no payload (cache server-side de 1h por job_type).
+- `include=schema` — inclui `params_schema` completo de cada job type (não usado por `get_context`; pesado).
+- `limit` — número máximo de itens por página. `get_context` fixa em `100`.
+- `offset` — paginação numérica.
+- `sort` — formato `field:direction`, ex: `name:asc` (default usado por `get_context`).
+
+#### Response shape
+
+```json
+{
+  "data": [
+    { "id": "string", "name": "string", "description": "string?", "emoji": "string?" }
+  ],
+  "meta": { "total": 0, "limit": 100, "offset": 0 }
+}
+```
+
 ## Job Status Values
 
 Jobs can have the following status values:

package/docs/debug-guide.md

@@ -0,0 +1,203 @@
+# 🔍 Guia de Debug do MCP Server
+
+Este guia fornece várias maneiras de depurar e diagnosticar problemas no seu MCP Server.
+
+## 🚀 Comandos de Debug Disponíveis
+
+### 1. Debug Básico
+```bash
+# Compilar e rodar em modo debug
+npm run debug
+
+# Debug com variáveis de ambiente específicas
+MCP_DEBUG=true npm run debug
+```
+
+### 2. Testar Tools
+```bash
+# Verificar se todas as tools estão carregando
+npm run test:tools
+
+# Verificar configuração atual
+npm run cli:config
+```
+
+### 3. Debug com Logs Detalhados
+```bash
+# Usar arquivo de ambiente de debug
+cp .env.debug .env
+# Editar .env com suas credenciais
+npm run debug
+```
+
+## 🛠️ Tipos de Debug
+
+### 1. **Debug de Configuração**
+```bash
+npm run cli:config
+```
+Este comando mostra:
+- URL da API
+- Status da chave de API
+- Versão do Node.js
+- Versão do MCP Server
+
+### 2. **Debug de Carregamento de Tools**
+```bash
+npm run test:tools
+```
+Este comando:
+- Lista todas as tools encontradas
+- Testa o carregamento de cada tool
+- Mostra erros de carregamento se houver
+
+### 3. **Debug Completo em Runtime**
+```bash
+MCP_DEBUG=true npm run debug
+```
+Com `MCP_DEBUG=true`, você verá:
+- Logs de inicialização detalhados
+- Configuração carregada
+- Chamadas de tools em tempo real
+- Respostas das APIs
+- Erros detalhados
+
+## 📊 Interpretando os Logs
+
+### Logs de Tool
+```
+[MCP-DEBUG 2025-08-13T...] [INFO] Tool called: get_jobs_stats
+[MCP-DEBUG 2025-08-13T...] [DEBUG] Data: {"org_id":"aiconnect"}
+```
+
+### Logs de API
+```
+[MCP-DEBUG 2025-08-13T...] [DEBUG] HTTP GET https://api.aiconnect.cloud/api/v0/jobs/stats
+[MCP-DEBUG 2025-08-13T...] [DEBUG] HTTP Response GET [200]
+```
+
+### Logs de Erro
+```
+[MCP-DEBUG 2025-08-13T...] [ERROR] Tool error: get_jobs_stats
+[MCP-DEBUG 2025-08-13T...] [ERROR] Data: {"error": "API key not provided"}
+```
+
+## 🔧 Problemas Comuns e Soluções
+
+### 1. **API Key não configurada**
+**Erro:** `API key not provided`
+**Solução:**
+```bash
+# Definir a chave de API
+export AICONNECT_API_KEY="sua-chave-aqui"
+npm run debug
+```
+
+### 2. **URL da API incorreta**
+**Erro:** `Request failed with status 404`
+**Solução:**
+```bash
+# Verificar/definir URL da API
+export AICONNECT_API_URL="https://api.aiconnect.cloud/api/v0"
+npm run debug
+```
+
+### 3. **Tools não carregando**
+**Erro:** `Error loading tools`
+**Solução:**
+```bash
+# Verificar se o build está atualizado
+npm run build
+npm run test:tools
+```
+
+### 4. **Problemas de Conexão MCP**
+**Erro:** `Transport connection closed`
+**Solução:**
+- Verificar se o cliente MCP está conectado corretamente
+- Usar logs de debug para ver detalhes da conexão
+
+## 📝 Configuração para Claude Desktop
+
+Para debug no Claude Desktop, use esta configuração no `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "agentjobs-debug": {
+      "command": "node",
+      "args": ["/caminho/para/agentjobs-mcp/build/debug.js"],
+      "env": {
+        "MCP_DEBUG": "true",
+        "AICONNECT_API_KEY": "sua-chave-aqui",
+        "AICONNECT_API_URL": "https://api.aiconnect.cloud/api/v0",
+        "DEFAULT_ORG_ID": "aiconnect"
+      }
+    }
+  }
+}
+```
+
+## 🧪 Testes de Funcionalidade
+
+### Teste Manual das Tools
+
+1. **Listar Jobs:**
+   - Comando: "List all jobs"
+   - Debug: Verificar se a API é chamada e se os dados são formatados
+
+2. **Buscar Job Específico:**
+   - Comando: "Get job details for job-123"
+   - Debug: Verificar parâmetros enviados e resposta recebida
+
+3. **Criar Job:**
+   - Comando: "Create a new job"
+   - Debug: Verificar payload da criação e resposta
+
+### Teste de Configuração
+
+```bash
+# Verificar todas as configurações
+npm run cli:config
+
+# Verificar carregamento das tools
+npm run test:tools
+
+# Verificar versão
+npm run cli:version
+```
+
+## 🎯 Dicas de Debug
+
+1. **Use logs incrementais:** Comece com debug básico e aumente verbosidade conforme necessário
+
+2. **Teste isoladamente:** Use `npm run test:tools` para verificar carregamento antes de testar funcionalidade
+
+3. **Monitore a API:** Se possível, monitore logs da API AI Connect em paralelo
+
+4. **Verifique configuração:** Sempre rode `npm run cli:config` primeiro
+
+5. **Use ambiente controlado:** Use `.env.debug` para configuração consistente
+
+## 📋 Checklist de Debug
+
+- [ ] Configuração carregada corretamente (`npm run cli:config`)
+- [ ] Tools carregando sem erro (`npm run test:tools`)  
+- [ ] API key configurada
+- [ ] URL da API acessível
+- [ ] Logs de debug habilitados (`MCP_DEBUG=true`)
+- [ ] Conexão MCP funcionando
+- [ ] Tools respondendo conforme esperado
+
+## 🆘 Debugging Avançado
+
+Para problemas complexos, você pode:
+
+1. **Adicionar mais logs** nas tools específicas
+2. **Usar Node.js debugger** com `--inspect`
+3. **Monitorar requisições HTTP** com `DEBUG=axios`
+4. **Verificar memória e performance** com `node --trace-warnings`
+
+---
+
+💡 **Lembre-se:** O debug é mais eficiente quando feito de forma incremental, testando cada componente isoladamente antes de testar o sistema completo.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiconnect/agentjobs-mcp",
-  "version": "1.0.9",
+  "version": "1.2.0",
   "description": "MCP (Model Context Protocol) server for managing Agent Jobs in the AI Connect platform. Developed by AI Connect - Advanced AI automation and integration solutions.",
   "type": "module",
   "main": "build/index.js",
@@ -28,10 +28,14 @@
     "build": "tsc && chmod +x build/index.js",
     "start": "node build/index.js",
     "dev": "tsc && node build/index.js",
+    "debug": "tsc && node build/debug.js",
+    "debug:watch": "tsc --watch & sleep 2 && node build/debug.js",
     "clean": "rm -rf build",
     "typecheck": "tsc --noEmit",
-    "lint": "echo 'Linting not configured yet'",
-    "test": "echo 'Tests not configured yet'",
+    "lint": "eslint . --ext .ts,.js",
+    "lint:fix": "eslint . --ext .ts,.js --fix",
+    "test": "vitest",
+    "test:tools": "npm run build && node build/test-tools.js",
     "prepare": "npm run build",
     "version:patch": "npm version patch",
     "version:minor": "npm version minor",
@@ -53,7 +57,12 @@
   },
   "devDependencies": {
     "@types/node": "^22.10.5",
-    "typescript": "^5.7.2"
+    "@eslint/js": "^9.14.0",
+    "eslint": "^9.14.0",
+    "typescript-eslint": "^8.12.2",
+    "typescript": "^5.7.2",
+    "vitest": "^3.2.4",
+    "zod-to-json-schema": "^3.23.0"
   },
   "engines": {
     "node": ">=18.0.0"