@aiconnect/agentjobs-mcp 1.0.8 → 1.1.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

@@ -153,9 +153,9 @@ This MCP server is designed to work out-of-the-box with minimal configuration. I
 - `AICONNECT_API_KEY`: `""` (empty - you must provide this)
 
 **Error Handling:**
-- If `AICONNECT_API_KEY` is not provided, tools will return helpful error messages
-- If `AICONNECT_API_URL` is not set, it defaults to the production API
-- If `DEFAULT_ORG_ID` is not set, it defaults to "aiconnect"
+- The server will always start, even if environment variables are missing.
+- If `AICONNECT_API_KEY` or `AICONNECT_API_URL` are not provided, each tool will return a clear error message upon execution, guiding the user to configure the environment correctly.
+- If `DEFAULT_ORG_ID` is not set, it defaults to "aiconnect".
 
 ### Running the MCP server
 
@@ -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.
 
@@ -260,11 +291,14 @@ Agent: "Cancel job job-456 because it's no longer needed"
 ```
 agentjobs-mcp/
 ├── src/                    # TypeScript source code
-│   ├── index.ts           # Main MCP server
-│   ├── cancel_job.ts      # Tool for canceling jobs
-│   ├── create_job.ts      # Tool for creating jobs
-│   ├── get_job.ts         # Tool for querying job
-│   └── list_jobs.ts       # Tool for listing jobs
+│   ├── 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
+│       └── cancel_job.ts  # Tool for canceling a job
 ├── build/                 # Compiled JavaScript code
 ├── docs/                  # Documentation
 │   └── agent-jobs-api.md  # API documentation
@@ -280,13 +314,49 @@ 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
 
-1. Create a new file in the `src/` folder (e.g., `new_tool.ts`)
-2. Implement the tool following the pattern of existing files
-3. Register the tool in `src/index.ts`
-4. Recompile with `npm run build`
+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,11 @@
-// 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',
+    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'
 };

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,10 +3,10 @@ import * as dotenv from 'dotenv';
 dotenv.config();
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import cancel_job from "./cancel_job.js";
-import get_job from "./get_job.js";
-import list_jobs from "./list_jobs.js";
-import create_job from "./create_job.js";
+import { InitializeRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import fs from "fs/promises";
+import path from "path";
+import { fileURLToPath } from "url";
 // Get package version
 const packageJson = JSON.parse(await import('fs').then(fs => fs.readFileSync(new URL('../package.json', import.meta.url), 'utf-8')));
 // CLI argument parsing
@@ -55,29 +55,88 @@ if (args.includes('--config') || args.includes('-c')) {
     console.log(`  MCP Server Version: ${packageJson.version}`);
     process.exit(0);
 }
-// Validate required environment variables
-if (!process.env.AICONNECT_API_URL) {
-    console.error('Error: AICONNECT_API_URL environment variable is required');
-    console.error('Use --help for more information');
-    process.exit(1);
-}
-if (!process.env.AICONNECT_API_KEY) {
-    console.error('Error: AICONNECT_API_KEY environment variable is required');
-    console.error('Use --help for more information');
-    process.exit(1);
-}
-// 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
+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
+        }
+    };
 });
-// Initialize components
-cancel_job(server);
-get_job(server);
-list_jobs(server);
-create_job(server);
+// Dynamically load and register tools
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const toolsDir = path.join(__dirname, 'tools');
+try {
+    const toolFiles = await fs.readdir(toolsDir);
+    for (const file of toolFiles) {
+        if (file.endsWith('.js')) { // In production, files will be .js
+            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
+            }
+        }
+    }
+}
+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,79 @@
+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 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

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import agentJobsClient from "../lib/agentJobsClient.js";
+import { formatJobSummary } from '../utils/formatters.js';
+import { mcpDebugger, withTiming } from '../utils/debugger.js';
+export default (server) => {
+    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().optional().describe("An optional reason explaining why the job is being canceled."),
+        }
+    }, async (params) => {
+        mcpDebugger.toolCall("cancel_job", params);
+        const { job_id, reason } = params;
+        const endpoint = `/services/agent-jobs/${job_id}`;
+        let requestBody;
+        if (reason) {
+            requestBody = { reason };
+        }
+        mcpDebugger.debug("Job cancellation request", {
+            endpoint,
+            job_id,
+            reason,
+            hasRequestBody: !!requestBody
+        });
+        try {
+            const canceledJob = await withTiming(() => agentJobsClient.delete(endpoint, requestBody), "cancel_job API call");
+            mcpDebugger.debug("Job cancellation response", { canceledJob });
+            const summary = formatJobSummary(canceledJob);
+            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) {
+            mcpDebugger.toolError("cancel_job", error);
+            return {
+                content: [{
+                        type: "text",
+                        text: `Error canceling job: ${error.message}`,
+                    }],
+            };
+        }
+    });
+};

package/build/tools/create_job.js

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+import agentJobsClient from '../lib/agentJobsClient.js';
+import { config } from '../config.js';
+import { flexibleDateTimeSchema } from '../utils/schemas.js';
+import { mcpDebugger, withTiming } from '../utils/debugger.js';
+export default (server) => {
+    server.registerTool('create_job', {
+        description: 'Create a new Agent Job with the minimal set of fields.',
+        annotations: {
+            title: 'Create Agent Job'
+        },
+        inputSchema: {
+            // Required fields
+            job_type_id: z
+                .string()
+                .describe('ID of the job type (e.g. "mood-monitor")'),
+            target_channel: z
+                .object({
+                platform: z
+                    .enum(['whatsapp', 'slack', 'web'])
+                    .describe('Destination platform.'),
+                code: z
+                    .string()
+                    .describe('Channel identifier, phone number, or user ID.'),
+                org_id: z
+                    .string()
+                    .optional()
+                    .describe('Org ID – defaults to config.DEFAULT_ORG_ID')
+            })
+                .describe('Where the agent will communicate.'),
+            params: z
+                .record(z.any())
+                .optional()
+                .describe('Free‑form params passed to the agent'),
+            scheduled_at: flexibleDateTimeSchema
+                .optional()
+                .describe('Schedule the job to run later')
+        }
+    }, async (params) => {
+        mcpDebugger.toolCall("create_job", params);
+        // Fall back to default org if none supplied.
+        params.target_channel.org_id ??= config.DEFAULT_ORG_ID;
+        mcpDebugger.debug("Job creation payload", {
+            job_type_id: params.job_type_id,
+            target_channel: params.target_channel,
+            scheduled_at: params.scheduled_at,
+            paramsCount: params.params ? Object.keys(params.params).length : 0
+        });
+        try {
+            const res = await withTiming(() => agentJobsClient.post('/services/agent-jobs', params), "create_job API call");
+            const jobId = res.id ?? 'unknown';
+            mcpDebugger.debug("Job creation response", { jobId, fullResponse: res });
+            const result = {
+                content: [
+                    {
+                        type: 'text',
+                        text: `✅ Job created (id: ${jobId}).`
+                    }
+                ]
+            };
+            mcpDebugger.toolResponse("create_job", { jobId });
+            return result;
+        }
+        catch (error) {
+            mcpDebugger.toolError("create_job", error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error creating job: ${error.message}`
+                    }
+                ]
+            };
+        }
+    });
+};