@aiconnect/agentjobs-mcp 1.0.8

package/.env.example

@@ -0,0 +1,11 @@
+# AI Connect MCP Server Configuration
+# Copy this file to .env and fill in your values
+
+# Required: API endpoint URL for AI Connect
+AICONNECT_API_URL=https://api.aiconnect.cloud/api/v0
+
+# Required: Your API authentication key
+AICONNECT_API_KEY=your-api-key-here
+
+# Optional: Default organization ID (defaults to 'aiconnect' if not set)
+# DEFAULT_ORG_ID=your-organization-id

package/README.md

@@ -0,0 +1,311 @@
+# AI Connect MCP Server
+
+An MCP (Model Context Protocol) server that allows AI agents to query and manage jobs in the AI Connect platform.
+
+## About AI Connect Jobs
+
+AI Connect Jobs is a robust asynchronous task management system on the AI Connect platform, enabling the creation, monitoring, and execution of jobs across different platforms like Slack and WhatsApp, with support for scheduled execution, automatic retries, and timeout handling. The API provides endpoints to create, list, query, and cancel jobs, allowing developers and external systems to easily integrate asynchronous processing functionalities into their applications, automating complex workflows without the need to implement the entire task management infrastructure.
+
+## Features
+
+This MCP Server provides tools for AI agents to:
+
+- 📋 **List Jobs**: Query all jobs with advanced filtering
+- 🔍 **Get Specific Job**: Retrieve details of a specific job by ID
+- ✅ **Create Jobs**: Create new jobs for immediate or scheduled execution
+- ❌ **Cancel Jobs**: Cancel running or scheduled jobs
+- 📊 **Monitor Status**: Track job status (WAITING, RUNNING, COMPLETED, FAILED, CANCELED)
+
+## Technologies
+
+- **Node.js** with **TypeScript**
+- **Model Context Protocol (MCP)** by Anthropic
+- **Zod** for schema validation
+- **AI Connect API** for integration with the Agent Jobs system
+
+## Installation
+
+### NPX (Recommended)
+
+You can run the MCP server directly using npx without installation:
+
+```bash
+npx @aiconnect/agentjobs-mcp --help
+```
+
+### Local Installation
+
+1. **Clone the repository:**
+```bash
+git clone <repository-url>
+cd agentjobs-mcp
+```
+
+2. **Install dependencies:**
+```bash
+npm install
+```
+
+3. **Configure environment variables (Optional):**
+
+The MCP server comes with default values from `.env.example`, so you can run it without setting any environment variables. However, you **must** provide an API key for authentication.
+
+```bash
+cp .env.example .env
+```
+
+Edit the `.env` file with your credentials:
+```env
+DEFAULT_ORG_ID=your-organization     # Default: aiconnect
+AICONNECT_API_KEY=your-api-key       # Required: Must be provided
+AICONNECT_API_URL=https://api.aiconnect.cloud/api/v0  # Default
+```
+
+**Important**: If no environment variables are provided, the server will use these defaults:
+- `DEFAULT_ORG_ID`: `aiconnect`
+- `AICONNECT_API_URL`: `https://api.aiconnect.cloud/api/v0`
+- `AICONNECT_API_KEY`: empty (must be provided for API calls to work)
+
+4. **Build the project:**
+```bash
+npm run build
+```
+
+## Usage
+
+### CLI Usage
+
+The MCP server now supports CLI commands for easy management:
+
+```bash
+# Show help and usage information
+npx @aiconnect/agentjobs-mcp --help
+
+# Show version information
+npx @aiconnect/agentjobs-mcp --version
+
+# Show current configuration status
+npx @aiconnect/agentjobs-mcp --config
+
+# Start MCP server (default behavior)
+npx @aiconnect/agentjobs-mcp
+```
+
+**Setting Environment Variables:**
+```bash
+# Using environment variables with npx
+AICONNECT_API_URL=https://api.aiconnect.cloud/api/v0 \
+AICONNECT_API_KEY=your-api-key-here \
+npx @aiconnect/agentjobs-mcp
+
+# Or create a .env file (recommended for development)
+cp .env.example .env
+# Edit .env with your credentials
+npx @aiconnect/agentjobs-mcp
+```
+
+**Required Environment Variables:**
+- `AICONNECT_API_URL`: API endpoint URL (e.g., https://api.aiconnect.cloud/api/v0)
+- `AICONNECT_API_KEY`: Your API authentication key
+
+**CLI Command Examples:**
+```bash
+# Quick help
+npx @aiconnect/agentjobs-mcp -h
+
+# Check version
+npx @aiconnect/agentjobs-mcp -v
+
+# Verify configuration before starting
+npx @aiconnect/agentjobs-mcp -c
+
+# Test with environment variables
+env AICONNECT_API_URL=https://api.aiconnect.cloud/api/v0 \
+    AICONNECT_API_KEY=test-key \
+    npx @aiconnect/agentjobs-mcp --config
+```
+
+### Local Development
+
+For local development, you can use npm scripts:
+
+```bash
+# Build and test CLI commands
+npm run cli:help
+npm run cli:version  
+npm run cli:config
+
+# Run test suite (if available)
+npm run test:cli
+```
+
+### Configuration Options
+
+This MCP server is designed to work out-of-the-box with minimal configuration. It uses a smart fallback system:
+
+1. **With environment variables**: Full control over all settings
+2. **Without environment variables**: Uses defaults from `.env.example`
+3. **Partial configuration**: Mix of environment variables and defaults
+
+**Default Values (when no env vars are set):**
+- `DEFAULT_ORG_ID`: `"aiconnect"`
+- `AICONNECT_API_URL`: `"https://api.aiconnect.cloud/api/v0"`
+- `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"
+
+### Running the MCP server
+
+```bash
+npm start
+```
+
+The server will start and wait for connections via stdio transport.
+
+### Claude Desktop Configuration
+
+To use this MCP server with Claude Desktop, add the following configuration to your `claude_desktop_config.json` file:
+
+```json
+{
+  "mcpServers": {
+    "agentjobs": {
+      "command": "node",
+      "args": ["/path/to/agentjobs-mcp/build/index.js"],
+      "env": {
+        "DEFAULT_ORG_ID": "your-organization",
+        "AICONNECT_API_KEY": "your-api-key",
+        "AICONNECT_API_URL": "https://api.aiconnect.cloud/api/v0"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### 🔧 `list_jobs`
+Lists all jobs with filtering and pagination options.
+
+**Parameters:**
+- `status` (optional): Filter by status (WAITING, RUNNING, COMPLETED, FAILED, CANCELED)
+- `job_type_id` (optional): Filter by job type
+- `channel_code` (optional): Filter by channel code
+- `limit` (optional): Result limit (default: 50)
+- `offset` (optional): Pagination offset
+- `sort` (optional): Field and direction for sorting
+
+### 🔍 `get_job`
+Gets details of a specific job.
+
+**Parameters:**
+- `job_id` (required): ID of the job to query
+
+### ✅ `create_job`
+Creates a new job for execution.
+
+**Parameters:**
+- `target_channel`: Target channel configuration
+- `job_type_id`: Job type ID
+- `config`: Job configuration (timeouts, retries, etc.)
+- `params`: Job-specific parameters
+- `scheduled_at` (optional): Date/time for scheduled execution
+- `delay` (optional): Random delay in minutes
+
+### ❌ `cancel_job`
+Cancels a running or scheduled job.
+
+**Parameters:**
+- `job_id` (required): ID of the job to cancel
+- `reason` (optional): Cancellation reason
+
+## Job Status
+
+Jobs can have the following status values:
+
+- `WAITING`: Job waiting for execution
+- `SCHEDULED`: Job scheduled for future execution
+- `RUNNING`: Job currently running
+- `COMPLETED`: Job completed successfully
+- `FAILED`: Job failed
+- `CANCELED`: Job was canceled
+
+## Usage Examples
+
+### List running jobs
+```
+Agent: "Show me all jobs that are currently running"
+```
+
+### Query specific job
+```
+Agent: "What's the status of job job-123?"
+```
+
+### Create scheduled job
+```
+Agent: "Create a daily report job for Slack channel C123456 to run tomorrow at 9 AM"
+```
+
+### Cancel job
+```
+Agent: "Cancel job job-456 because it's no longer needed"
+```
+
+## Project Structure
+
+```
+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
+├── build/                 # Compiled JavaScript code
+├── docs/                  # Documentation
+│   └── agent-jobs-api.md  # API documentation
+├── package.json           # Dependencies and scripts
+├── tsconfig.json          # TypeScript configuration
+├── .env.example           # Environment variables example
+└── README.md              # This file
+```
+
+## Development
+
+### Available scripts
+
+- `npm run build`: Compiles TypeScript
+- `npm start`: Runs the compiled server
+
+### 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`
+
+## Contributing
+
+1. Fork the project
+2. Create a feature branch (`git checkout -b feature/new-feature`)
+3. Commit your changes (`git commit -am 'Add new feature'`)
+4. Push to the branch (`git push origin feature/new-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).
+
+## Support
+
+For technical support or questions about AI Connect Jobs:
+- Check the [API documentation](docs/agent-jobs-api.md)
+- Contact the AI Connect development team
+
+---
+
+**Note**: This project was developed using the Anthropic mcp-tools scaffold for integration with the AI Connect platform.

package/build/cancel_job.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import axios from 'axios';
+import { config } from './config.js';
+export default (server) => {
+    server.tool("cancel_job", "Cancels an agent job by its ID.", {
+        job_id: z.string({
+            description: "The ID of the job to cancel.",
+        }),
+        reason: z.string().optional().describe("Optional reason for cancellation."),
+    }, async (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}`,
+        };
+        let requestBody;
+        if (reason) {
+            headers["Content-Type"] = "application/json";
+            requestBody = { reason };
+        }
+        try {
+            const response = await axios.delete(endpoint, {
+                headers,
+                data: requestBody, // axios uses 'data' for DELETE request body
+            });
+            // Assuming the API returns a message field on success as per docs/agent-jobs-api.md:229
+            const responseMessage = response.data?.message || `Job with ID '${job_id}' successfully canceled.`;
+            return {
+                content: [{
+                        type: "text",
+                        text: responseMessage,
+                    }]
+            };
+        }
+        catch (error) {
+            let errorMessage = `Failed to cancel job ${job_id}.`;
+            if (axios.isAxiosError(error) && error.response) {
+                // Try to get a more specific error message from the API 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}`;
+            }
+            else if (error instanceof Error) {
+                errorMessage = `Error: ${error.message}`;
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: errorMessage,
+                    }]
+            };
+        }
+    });
+};

package/build/config.js

@@ -0,0 +1,6 @@
+// Configuration with fallback to .env.example defaults
+export const config = {
+    DEFAULT_ORG_ID: process.env.DEFAULT_ORG_ID || 'aiconnect',
+    AICONNECT_API_KEY: process.env.AICONNECT_API_KEY || '',
+    AICONNECT_API_URL: process.env.AICONNECT_API_URL || 'https://api.aiconnect.cloud/api/v0'
+};

package/build/create_job.js

@@ -0,0 +1,151 @@
+import { z } from 'zod';
+import axios from 'axios';
+import { config } from './config.js';
+// Schema for the target_channel object
+const targetChannelSchema = z
+    .object({
+    org_id: z.string().optional().describe('Organization ID for the target channel. If not provided, uses the default organization.'),
+    platform: z
+        .enum(['whatsapp', 'slack', 'web'])
+        .describe('Platform of the target channel.'),
+    type: z.string().describe('Type of the target channel (e.g., channel).'),
+    code: z.string().describe('Code/identifier for the target channel.'),
+    data: z
+        .record(z.any())
+        .optional()
+        .describe('Additional platform-specific data for the channel.')
+})
+    .describe('Defines the target channel for the job.');
+// Schema for the config object
+const configSchema = z
+    .object({
+    max_follow_ups: z
+        .number()
+        .int()
+        .optional()
+        .describe('Maximum number of follow-ups allowed.'),
+    max_task_retries: z
+        .number()
+        .int()
+        .optional()
+        .describe('Maximum number of retries for a task.'),
+    task_retry_interval: z
+        .number()
+        .int()
+        .optional()
+        .describe('Interval in minutes between task retries.'),
+    start_prompt: z.string().describe('The initial prompt to start the job.'),
+    max_time_to_complete: z
+        .number()
+        .int()
+        .optional()
+        .describe('Maximum time in minutes for the job to complete.'),
+    profile_id: z.string().describe('Profile ID to be used for the job.')
+})
+    .describe('Configuration settings for the job.');
+export default (server) => {
+    server.tool('create_job', 'Creates a new agent job.', {
+        target_channel: targetChannelSchema,
+        job_type_id: z.string().describe('The ID of the job type.'),
+        config: configSchema.optional(),
+        params: z
+            .record(z.any())
+            .optional()
+            .describe('Arbitrary parameters for the job.'),
+        scheduled_at: z
+            .string()
+            .datetime({ message: 'Invalid datetime string. Must be ISO 8601' })
+            .optional()
+            .describe('Optional ISO 8601 date string for scheduling the job.'),
+        delay: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe('Optional maximum random delay in minutes to add to the scheduled time (query parameter).')
+    }, async (toolParams) => {
+        const apiUrl = config.AICONNECT_API_URL;
+        const apiKey = config.AICONNECT_API_KEY;
+        const defaultOrgId = config.DEFAULT_ORG_ID;
+        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.'
+                    }
+                ]
+            };
+        }
+        // Use default org_id if not provided
+        if (!toolParams.target_channel.org_id && defaultOrgId) {
+            toolParams.target_channel.org_id = defaultOrgId;
+        }
+        else if (!toolParams.target_channel.org_id && !defaultOrgId) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Error: Organization ID is required. Please provide org_id or set DEFAULT_ORG_ID environment variable.'
+                    }
+                ]
+            };
+        }
+        const endpoint = `${apiUrl}/services/agent-jobs`;
+        const headers = {
+            Authorization: `Bearer ${apiKey}`,
+            'Content-Type': 'application/json'
+        };
+        // Separate delay as it's a query parameter
+        const { delay, ...bodyPayload } = toolParams;
+        const queryParams = {};
+        if (delay !== undefined) {
+            queryParams.delay = delay;
+        }
+        try {
+            const response = await axios.post(endpoint, bodyPayload, {
+                headers,
+                params: queryParams
+            });
+            // API returns job details under 'data' key
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(response.data, null, 2)
+                    }
+                ]
+            };
+        }
+        catch (error) {
+            let errorMessage = `Failed to create job.`;
+            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}`;
+            }
+            else if (error instanceof Error) {
+                errorMessage = `Error: ${error.message}`;
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: errorMessage
+                    }
+                ]
+            };
+        }
+    });
+};

package/build/get_job.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import axios from 'axios';
+import { config } from './config.js';
+export default (server) => {
+    server.tool("get_job", "Retrieves an agent job by its ID.", {
+        job_id: z.string({
+            description: "The ID of the job to retrieve.",
+        }),
+    }, async (params) => {
+        const { job_id } = 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}`,
+        };
+        try {
+            const response = await axios.get(endpoint, {
+                headers,
+            });
+            // Return the data part of the response, stringified as JSON text
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify(response.data?.data || response.data, null, 2),
+                    }]
+            };
+        }
+        catch (error) {
+            let errorMessage = `Failed to retrieve job ${job_id}.`;
+            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}`;
+            }
+            else if (error instanceof Error) {
+                errorMessage = `Error: ${error.message}`;
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: errorMessage,
+                    }]
+            };
+        }
+    });
+};

package/build/index.js

@@ -0,0 +1,83 @@
+#!/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 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";
+// 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
+const args = process.argv.slice(2);
+// Help text
+const helpText = `
+AI Connect Agent Jobs MCP Server v${packageJson.version}
+${packageJson.description}
+
+USAGE:
+  npx @aiconnect/agentjobs-mcp [OPTIONS]
+
+OPTIONS:
+  --help, -h          Show this help message
+  --version, -v       Show version information
+  --config, -c        Show current configuration
+  --stdio             Start MCP server with stdio transport (default)
+
+EXAMPLES:
+  npx @aiconnect/agentjobs-mcp              # Start MCP server
+  npx @aiconnect/agentjobs-mcp --help       # Show help
+  npx @aiconnect/agentjobs-mcp --version    # Show version
+  npx @aiconnect/agentjobs-mcp --config     # Show configuration
+
+ENVIRONMENT VARIABLES:
+  AICONNECT_API_URL    API endpoint URL (required)
+  AICONNECT_API_KEY    API authentication key (required)
+
+For more information, visit: ${packageJson.homepage}
+Author: ${packageJson.author}
+`;
+// Handle CLI arguments
+if (args.includes('--help') || args.includes('-h')) {
+    console.log(helpText);
+    process.exit(0);
+}
+if (args.includes('--version') || args.includes('-v')) {
+    console.log(`v${packageJson.version}`);
+    process.exit(0);
+}
+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(`  Node Version: ${process.version}`);
+    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
+const server = new McpServer({
+    name: "agentjobs-mcp",
+    version: packageJson.version
+});
+// Initialize components
+cancel_job(server);
+get_job(server);
+list_jobs(server);
+create_job(server);
+// Start server with stdio transport
+const transport = new StdioServerTransport();
+console.error(`Starting AI Connect Agent Jobs MCP Server v${packageJson.version}...`);
+console.error('Server ready and listening for MCP connections');
+await server.connect(transport);