@aiconnect/agentjobs-mcp 1.0.9 → 1.2.0

package/.env.example

@@ -9,3 +9,10 @@ AICONNECT_API_KEY=your-api-key-here
 
 # Optional: Default organization ID (defaults to 'aiconnect' if not set)
 # DEFAULT_ORG_ID=your-organization-id
+
+# Debug Settings
+MCP_DEBUG=false
+NODE_ENV=development
+
+# HTTP Debug (opcional - para ver requisições HTTP detalhadas)
+DEBUG=axios

package/README.md

@@ -185,8 +185,39 @@ To use this MCP server with Claude Desktop, add the following configuration to y
 }
 ```
 
+### Local Development with Claude Code
+
+For development and testing, you can add this MCP server directly to your Claude Code project:
+
+```bash
+# Prerequisites: build the project first
+npm install
+npm run build
+
+# Configure your .env file
+cp .env.example .env
+# Edit .env with your API credentials
+
+# Add MCP server to Claude Code (project scope)
+claude mcp add --scope project agentjobs -- ./mcp-agentjobs.sh
+```
+
+This allows you to test and use the AgentJobs tools directly within Claude Code during development, providing immediate feedback and easier debugging.
+
 ## Available Tools
 
+### 📊 `get_jobs_stats`
+Get aggregated statistics for agent jobs without retrieving individual job data. Optimized for dashboards and monitoring with minimal network overhead.
+
+**Parameters:**
+- `scheduled_at_gte`: Start of period (ISO 8601)
+- `scheduled_at_lte`: End of period (ISO 8601)
+- `org_id`: Organization filter
+- `job_type_id`: Job type filter
+- `tags`: Tags filter (comma-separated)
+- `status`: Status filter
+- `channel_code`: Channel filter
+
 ### 🔧 `list_jobs`
 Lists all jobs with filtering and pagination options.
 
@@ -263,6 +294,7 @@ agentjobs-mcp/
 │   ├── index.ts           # Main MCP server entry point
 │   ├── config.ts          # Configuration loader
 │   └── tools/             # Directory for all MCP tools
+│       ├── get_jobs_stats.ts # Tool for getting job statistics
 │       ├── list_jobs.ts   # Tool for listing jobs
 │       ├── get_job.ts     # Tool for getting a job
 │       ├── create_job.ts  # Tool for creating a job
@@ -282,6 +314,40 @@ agentjobs-mcp/
 
 - `npm run build`: Compiles TypeScript
 - `npm start`: Runs the compiled server
+- `npm run debug`: Runs server in debug mode with detailed logging
+- `npm run test:tools`: Tests tool loading without starting server
+- `npm run cli:config`: Shows current configuration
+- `npm run cli:version`: Shows version information
+- `npm run cli:help`: Shows help information
+
+### Debugging
+
+For detailed debugging information, see [Debug Guide](docs/debug-guide.md).
+
+**Quick Debug Commands:**
+```bash
+# Test configuration
+npm run cli:config
+
+# Test tool loading
+npm run test:tools
+
+# Run in debug mode
+MCP_DEBUG=true npm run debug
+
+# Use debug helper script (Fish shell)
+./debug.fish help
+./debug.fish quick
+```
+
+**Debug Environment:**
+```bash
+# Copy debug environment template
+cp .env.debug .env
+# Edit .env with your API credentials
+# Run with debug environment
+./debug.fish debug-with-env
+```
 
 ### Adding new tools
 
@@ -290,6 +356,7 @@ Adding a new tool is simple:
 1. Create a new TypeScript file inside the `src/tools/` directory (e.g., `my_new_tool.ts`).
 2. Implement your tool logic following the existing pattern. The server will automatically detect and register it on startup.
 3. Recompile the project with `npm run build`.
+4. Test with `npm run test:tools` to verify loading.
 
 ## Contributing
 

package/build/config.js

@@ -1,6 +1,13 @@
-// Configuration with fallback to .env.example defaults
+// Configuration for the MCP server
 export const config = {
-    DEFAULT_ORG_ID: process.env.DEFAULT_ORG_ID || 'aiconnect',
+    apiUrl: process.env.AICONNECT_API_URL || 'https://api.aiconnect.cloud/api/v0',
+    apiKey: process.env.AICONNECT_API_KEY || '',
+    defaultOrgId: process.env.DEFAULT_ORG_ID || 'aiconnect',
+    defaultTimezone: process.env.DEFAULT_TIMEZONE || 'UTC',
+    debugMode: process.env.DEBUG === 'true',
+    // Legacy compatibility
+    AICONNECT_API_URL: process.env.AICONNECT_API_URL || 'https://api.aiconnect.cloud/api/v0',
     AICONNECT_API_KEY: process.env.AICONNECT_API_KEY || '',
-    AICONNECT_API_URL: process.env.AICONNECT_API_URL || 'https://api.aiconnect.cloud/api/v0'
+    DEFAULT_ORG_ID: process.env.DEFAULT_ORG_ID || 'aiconnect',
+    DEFAULT_TIMEZONE: process.env.DEFAULT_TIMEZONE || 'UTC'
 };

package/build/config.test.js

@@ -0,0 +1,22 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+describe('config.defaultTimezone', () => {
+    beforeEach(() => {
+        vi.resetModules();
+    });
+    afterEach(() => {
+        vi.unstubAllEnvs();
+        vi.resetModules();
+    });
+    it('reflects DEFAULT_TIMEZONE when set', async () => {
+        vi.stubEnv('DEFAULT_TIMEZONE', 'America/Sao_Paulo');
+        const { config } = await import('./config.js');
+        expect(config.defaultTimezone).toBe('America/Sao_Paulo');
+        expect(config.DEFAULT_TIMEZONE).toBe('America/Sao_Paulo');
+    });
+    it('falls back to UTC when DEFAULT_TIMEZONE is unset', async () => {
+        vi.stubEnv('DEFAULT_TIMEZONE', '');
+        const { config } = await import('./config.js');
+        expect(config.defaultTimezone).toBe('UTC');
+        expect(config.DEFAULT_TIMEZONE).toBe('UTC');
+    });
+});

package/build/debug.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import * as dotenv from 'dotenv';
+dotenv.config();
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import fs from "fs/promises";
+import path from "path";
+import { fileURLToPath } from "url";
+import { config } from './config.js';
+// Enable debug mode
+const DEBUG = true;
+function debugLog(message, data) {
+    if (DEBUG) {
+        const timestamp = new Date().toISOString();
+        console.error(`[DEBUG ${timestamp}] ${message}`);
+        if (data) {
+            console.error('[DEBUG DATA]', JSON.stringify(data, null, 2));
+        }
+    }
+}
+// Get package version
+const packageJson = JSON.parse(await import('fs').then(fs => fs.readFileSync(new URL('../package.json', import.meta.url), 'utf-8')));
+debugLog('Starting MCP Server in DEBUG mode');
+debugLog('Configuration loaded', {
+    DEFAULT_ORG_ID: config.DEFAULT_ORG_ID,
+    AICONNECT_API_URL: config.AICONNECT_API_URL,
+    AICONNECT_API_KEY: config.AICONNECT_API_KEY ? '[SET]' : '[NOT SET]',
+    NODE_ENV: process.env.NODE_ENV,
+    version: packageJson.version
+});
+// Initialize server with debug logging
+const server = new McpServer({
+    name: "agentjobs-mcp-debug",
+    version: packageJson.version
+});
+debugLog('MCP Server initialized');
+// Dynamically load and register tools with debug info
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const toolsDir = path.join(__dirname, 'tools');
+try {
+    debugLog(`Loading tools from: ${toolsDir}`);
+    const toolFiles = await fs.readdir(toolsDir);
+    debugLog(`Found tool files:`, toolFiles);
+    for (const file of toolFiles) {
+        if (file.endsWith('.js')) {
+            debugLog(`Loading tool: ${file}`);
+            try {
+                const toolModule = await import(`./tools/${file}`);
+                if (typeof toolModule.default === 'function') {
+                    toolModule.default(server);
+                    debugLog(`✅ Successfully registered tool: ${file}`);
+                }
+                else {
+                    debugLog(`❌ Tool ${file} does not export a default function`);
+                }
+            }
+            catch (error) {
+                debugLog(`❌ Error loading tool ${file}:`, error);
+            }
+        }
+    }
+}
+catch (error) {
+    debugLog("❌ Error loading tools directory:", error);
+    process.exit(1);
+}
+// Start server with debug transport
+const transport = new StdioServerTransport();
+debugLog('Starting transport connection...');
+// Add connection event handling
+transport.onclose = () => {
+    debugLog('Transport connection closed');
+};
+transport.onerror = (error) => {
+    debugLog('Transport error:', error);
+};
+console.error(`🔍 AI Connect Agent Jobs MCP Server v${packageJson.version} (DEBUG MODE)`);
+console.error('🚀 Server ready and listening for MCP connections');
+try {
+    await server.connect(transport);
+    debugLog('✅ Server connected successfully');
+}
+catch (error) {
+    debugLog('❌ Error connecting MCP server:', error);
+    process.exit(1);
+}

package/build/index.js

@@ -3,11 +3,15 @@ import * as dotenv from 'dotenv';
 dotenv.config();
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { InitializeRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import fs from "fs/promises";
 import path from "path";
 import { fileURLToPath } from "url";
-// Get package version
+import { mcpServerVersion } from "./utils/version.js";
+// Get package metadata (description/homepage/author come from package.json directly;
+// version comes from the shared helper to avoid duplication).
 const packageJson = JSON.parse(await import('fs').then(fs => fs.readFileSync(new URL('../package.json', import.meta.url), 'utf-8')));
+packageJson.version = mcpServerVersion;
 // CLI argument parsing
 const args = process.argv.slice(2);
 // Help text
@@ -50,14 +54,56 @@ if (args.includes('--config') || args.includes('-c')) {
     console.log('Current Configuration:');
     console.log(`  API URL: ${process.env.AICONNECT_API_URL || 'Not set'}`);
     console.log(`  API Key: ${process.env.AICONNECT_API_KEY ? '[SET]' : 'Not set'}`);
+    console.log(`  Default Org: ${process.env.DEFAULT_ORG_ID || 'aiconnect'}`);
+    console.log(`  Default Timezone: ${process.env.DEFAULT_TIMEZONE || 'UTC'}`);
     console.log(`  Node Version: ${process.version}`);
     console.log(`  MCP Server Version: ${packageJson.version}`);
     process.exit(0);
 }
-// Initialize server
+// Protocol version tracking
+let clientProtocolVersion = "2024-11-05"; // Default fallback
+let serverCapabilities = {
+    tools: { listChanged: true },
+    resources: {},
+    prompts: {}
+};
+// Initialize server with dynamic capabilities based on protocol version
 const server = new McpServer({
     name: "agentjobs-mcp",
     version: packageJson.version
+}, {
+    capabilities: serverCapabilities
+});
+console.error(`[DEBUG] MCP Server initialized with name: agentjobs-mcp`);
+console.error(`[DEBUG] Server version: ${packageJson.version}`);
+console.error(`[DEBUG] Default capabilities: tools, resources, prompts`);
+// Intercept initialization to detect protocol version
+const originalSetRequestHandler = server.server.setRequestHandler.bind(server.server);
+// Override initialization handler to capture protocol version.
+// The schema is cast to `any` to short-circuit a TS2589 ("excessively deep") error
+// from generic Zod inference in @modelcontextprotocol/sdk's setRequestHandler signature.
+server.server.setRequestHandler(InitializeRequestSchema, async (request) => {
+    const initParams = request.params;
+    clientProtocolVersion = initParams.protocolVersion || "2024-11-05";
+    console.error(`[VERSION-NEGOTIATION] Client requested protocol: ${clientProtocolVersion}`);
+    // Always use minimal capabilities to prevent loops
+    console.error(`[VERSION-NEGOTIATION] Client requested: ${clientProtocolVersion}`);
+    console.error(`[VERSION-NEGOTIATION] Using minimal capabilities to prevent infinite loops`);
+    // Use only tools capability - no resources/prompts to avoid repeated calls
+    serverCapabilities = {
+        tools: {}
+    };
+    console.error(`[VERSION-NEGOTIATION] Responding with our supported version: 2025-03-26`);
+    console.error(`[VERSION-NEGOTIATION] Updated capabilities:`, JSON.stringify(serverCapabilities, null, 2));
+    // Return initialization response with our supported version
+    return {
+        protocolVersion: "2025-03-26", // Our SDK version
+        capabilities: serverCapabilities,
+        serverInfo: {
+            name: "agentjobs-mcp",
+            version: packageJson.version
+        }
+    };
 });
 // Dynamically load and register tools
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -66,10 +112,16 @@ try {
     const toolFiles = await fs.readdir(toolsDir);
     for (const file of toolFiles) {
         if (file.endsWith('.js')) { // In production, files will be .js
-            const toolModule = await import(`./tools/${file}`);
-            if (typeof toolModule.default === 'function') {
-                toolModule.default(server);
-                console.error(`-> Registered tool: ${file}`);
+            try {
+                const toolModule = await import(`./tools/${file}`);
+                if (typeof toolModule.default === 'function') {
+                    toolModule.default(server);
+                    console.error(`-> Registered tool: ${file}`);
+                }
+            }
+            catch (error) {
+                console.error(`-> Failed to register tool ${file}:`, error);
+                // Continue loading other tools
             }
         }
     }
@@ -78,8 +130,20 @@ catch (error) {
     console.error("Error loading tools:", error);
     process.exit(1);
 }
+console.error(`[DEBUG] Only tools capability enabled - no resources/prompts handlers needed`);
 // Start server with stdio transport
 const transport = new StdioServerTransport();
 console.error(`Starting AI Connect Agent Jobs MCP Server v${packageJson.version}...`);
+console.error('Configuration:');
+console.error(`  API URL: ${process.env.AICONNECT_API_URL || 'Using default'}`);
+console.error(`  API Key: ${process.env.AICONNECT_API_KEY ? '[SET]' : '[NOT SET]'}`);
+console.error(`  Default Org: ${process.env.DEFAULT_ORG_ID || 'aiconnect'}`);
 console.error('Server ready and listening for MCP connections');
-await server.connect(transport);
+// Add error handling for the server connection
+try {
+    await server.connect(transport);
+}
+catch (error) {
+    console.error('Error connecting MCP server:', error);
+    process.exit(1);
+}

package/build/lib/agentJobsClient.js

@@ -0,0 +1,90 @@
+import axios from 'axios';
+import { config } from '../config.js';
+class AgentJobsClient {
+    client = null;
+    getClient() {
+        if (!this.client) {
+            const { AICONNECT_API_URL, AICONNECT_API_KEY } = config;
+            if (!AICONNECT_API_URL || !AICONNECT_API_KEY) {
+                throw new Error('API URL or Key is not configured. Please set AICONNECT_API_URL and AICONNECT_API_KEY environment variables.');
+            }
+            this.client = axios.create({
+                baseURL: AICONNECT_API_URL,
+                headers: {
+                    'Authorization': `Bearer ${AICONNECT_API_KEY}`,
+                    'X-Client-Type': 'mcp',
+                    'Content-Type': 'application/json'
+                }
+            });
+        }
+        return this.client;
+    }
+    async get(endpoint, params) {
+        return this.request(() => this.getClient().get(endpoint, { params }), params);
+    }
+    async getWithMeta(endpoint, params) {
+        try {
+            const response = await this.getClient().get(endpoint, { params });
+            return response.data; // Return the full API response including data and meta
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+    async listJobTypes(orgId, options = {}) {
+        const params = {
+            enrich: 'emoji',
+            limit: options.limit ?? 100,
+            sort: options.sort ?? 'name:asc'
+        };
+        if (options.offset !== undefined) {
+            params.offset = options.offset;
+        }
+        return (await this.getWithMeta(`/organizations/${orgId}/agent-jobs-type`, params));
+    }
+    async getStats(filters = {}) {
+        const params = {
+            ...filters,
+            include: 'stats',
+            limit: 1
+        };
+        return this.get('/services/agent-jobs', params);
+    }
+    async post(endpoint, data) {
+        return this.request(() => this.getClient().post(endpoint, data));
+    }
+    async patch(endpoint, data) {
+        return this.request(() => this.getClient().patch(endpoint, data));
+    }
+    async delete(endpoint, data) {
+        return this.request(() => this.getClient().delete(endpoint, { data }));
+    }
+    async request(requestFn, params) {
+        try {
+            const response = await requestFn();
+            if (params?.include === 'stats') {
+                // @ts-expect-error axios response typing varies per call in this client
+                return response.data;
+            }
+            // @ts-expect-error axios response typing varies per call in this client
+            return response.data?.data || response.data;
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+    handleError(error) {
+        if (axios.isAxiosError(error)) {
+            const axiosError = error;
+            const apiError = axiosError.response?.data?.message || axiosError.response?.data?.error || JSON.stringify(axiosError.response?.data);
+            throw new Error(`API Error (${axiosError.response?.status}): ${apiError || axiosError.message}`);
+        }
+        else if (error instanceof Error) {
+            throw new Error(`Error: ${error.message}`);
+        }
+        else {
+            throw new Error('An unknown error occurred.');
+        }
+    }
+}
+export default new AgentJobsClient();

package/build/test-tools.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import * as dotenv from 'dotenv';
+// Load debug environment
+dotenv.config({ path: '.env.debug' });
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+// Test specific tools
+async function testTools() {
+    console.log('🧪 Testing MCP Tools...\n');
+    // Initialize server
+    const server = new McpServer({
+        name: 'agentjobs-mcp-test',
+        version: 'test'
+    });
+    // Load tools
+    const __dirname = path.dirname(fileURLToPath(import.meta.url));
+    const toolsDir = path.join(__dirname, 'tools');
+    try {
+        const toolFiles = await fs.readdir(toolsDir);
+        console.log(`📁 Found ${toolFiles.length} tool files`);
+        for (const file of toolFiles) {
+            if (file.endsWith('.js')) {
+                try {
+                    console.log(`⚙️  Loading tool: ${file}`);
+                    const toolModule = await import(`./tools/${file}`);
+                    if (typeof toolModule.default === 'function') {
+                        toolModule.default(server);
+                        console.log(`✅ Successfully registered: ${file}`);
+                    }
+                    else {
+                        console.log(`❌ Invalid tool format: ${file}`);
+                    }
+                }
+                catch (error) {
+                    console.log(`❌ Error loading ${file}:`, error?.message || error);
+                }
+            }
+        }
+        // Show success message
+        console.log('\n✅ Tool testing completed!');
+        console.log('💡 To run in debug mode: MCP_DEBUG=true npm run debug');
+    }
+    catch (error) {
+        console.error('❌ Error during tool testing:', error);
+    }
+}
+// Run if this script is executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+    testTools().catch(console.error);
+}
+export { testTools };

package/build/tools/cancel_job.js

@@ -1,74 +1,59 @@
 import { z } from "zod";
-import axios from 'axios';
-import { config } from '../config.js';
+import agentJobsClient from "../lib/agentJobsClient.js";
 import { formatJobSummary } from '../utils/formatters.js';
+import { mcpDebugger, withTiming } from '../utils/debugger.js';
 export default (server) => {
-    server.tool("cancel_job", "Cancels an agent job by its ID.", {
-        job_id: z.string({
-            description: "The unique identifier of the job to be canceled. Example: 'job-12345'.",
-        }),
-        reason: z.string().optional().describe("An optional reason explaining why the job is being canceled."),
+    // @ts-expect-error TS2589: registerTool generic Zod inference exceeds TS depth limit with this schema.
+    server.registerTool("cancel_job", {
+        description: "Cancels an agent job by its ID.",
+        annotations: {
+            title: "Cancel Agent Job"
+        },
+        inputSchema: {
+            job_id: z.string({
+                description: "The unique identifier of the job to be canceled. Example: 'job-12345'."
+            }),
+            reason: z.string({
+                description: "An optional reason explaining why the job is being canceled."
+            }).optional()
+        }
     }, async (params) => {
+        mcpDebugger.toolCall("cancel_job", params);
         const { job_id, reason } = params;
-        const apiUrl = config.AICONNECT_API_URL;
-        const apiKey = config.AICONNECT_API_KEY;
-        if (!apiUrl) {
-            return {
-                content: [{
-                        type: "text",
-                        text: "Error: API URL is not configured. Please set AICONNECT_API_URL environment variable."
-                    }]
-            };
-        }
-        if (!apiKey) {
-            return {
-                content: [{
-                        type: "text",
-                        text: "Error: API Key is not configured. Please set AICONNECT_API_KEY environment variable."
-                    }]
-            };
-        }
-        const endpoint = `${apiUrl}/services/agent-jobs/${job_id}`;
-        const headers = {
-            "Authorization": `Bearer ${apiKey}`,
-        };
+        const endpoint = `/services/agent-jobs/${job_id}`;
         let requestBody;
         if (reason) {
-            headers["Content-Type"] = "application/json";
             requestBody = { reason };
         }
+        mcpDebugger.debug("Job cancellation request", {
+            endpoint,
+            job_id,
+            reason,
+            hasRequestBody: !!requestBody
+        });
         try {
-            const response = await axios.delete(endpoint, {
-                headers,
-                data: requestBody, // axios uses 'data' for DELETE request body
-            });
-            const canceledJob = response.data?.data || { job_id, job_status: 'canceled' };
+            const canceledJob = await withTiming(() => agentJobsClient.delete(endpoint, requestBody), "cancel_job API call");
+            mcpDebugger.debug("Job cancellation response", { canceledJob });
             const summary = formatJobSummary(canceledJob);
-            return {
+            const result = {
                 content: [{
                         type: "text",
                         text: `Successfully canceled job:\n\n${summary}`,
                     }]
             };
+            mcpDebugger.toolResponse("cancel_job", {
+                jobId: job_id,
+                reason,
+                resultLength: result.content[0].text.length
+            });
+            return result;
         }
         catch (error) {
-            let errorMessage = `Failed to cancel job ${job_id}.`;
-            let errorDetails = {};
-            if (axios.isAxiosError(error) && error.response) {
-                const apiError = error.response.data?.message || error.response.data?.error || JSON.stringify(error.response.data);
-                errorMessage = `API Error (${error.response.status}): ${apiError || error.message}`;
-                errorDetails = {
-                    status: error.response.status,
-                    data: error.response.data
-                };
-            }
-            else if (error instanceof Error) {
-                errorMessage = `Error: ${error.message}`;
-            }
+            mcpDebugger.toolError("cancel_job", error);
             return {
                 content: [{
                         type: "text",
-                        text: errorMessage,
+                        text: `Error canceling job: ${error.message}`,
                     }],
             };
         }