@aiconnect/agentjobs-mcp 1.0.8

package/build/list_jobs.js

@@ -0,0 +1,88 @@
+import { z } from "zod";
+import axios from 'axios';
+import { config } from './config.js';
+// Define the schema for job status based on docs/agent-jobs-api.md:246-251
+const jobStatusSchema = z.enum([
+    "waiting",
+    "scheduled",
+    "running",
+    "completed",
+    "failed",
+    "canceled"
+]);
+export default (server) => {
+    server.tool("list_jobs", "Retrieves a list of agent jobs, with optional filters and pagination.", {
+        org_id: z.string().optional().describe("Filter by organization ID. If not provided, uses the default organization."),
+        status: jobStatusSchema.optional().describe("Filter by job status."),
+        scheduled_at: z.string().datetime().optional().describe("Filter by exact scheduled time (ISO 8601)."),
+        scheduled_at_gte: z.string().datetime().optional().describe("Filter by scheduled time greater than or equal to (ISO 8601)."),
+        scheduled_at_lte: z.string().datetime().optional().describe("Filter by scheduled time less than or equal to (ISO 8601)."),
+        created_at_gte: z.string().datetime().optional().describe("Filter by creation time greater than or equal to (ISO 8601)."),
+        created_at_lte: z.string().datetime().optional().describe("Filter by creation time less than or equal to (ISO 8601)."),
+        job_type_id: z.string().optional().describe("Filter by job type ID."),
+        channel_code: z.string().optional().describe("Filter by channel code."),
+        limit: z.number().int().positive().optional().describe("Maximum number of jobs to return."),
+        offset: z.number().int().nonnegative().optional().describe("Number of jobs to skip (for pagination)."),
+        sort: z.string().optional().describe("Sorting field and direction (e.g., created_at:desc)."),
+    }, async (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`;
+        const headers = {
+            "Authorization": `Bearer ${apiKey}`,
+        };
+        // Build query parameters object from provided params
+        const queryParams = {};
+        for (const [key, value] of Object.entries(params)) {
+            if (value !== undefined) {
+                queryParams[key] = value;
+            }
+        }
+        try {
+            const response = await axios.get(endpoint, {
+                headers,
+                params: queryParams, // Axios uses 'params' for query parameters in GET requests
+            });
+            // Return the data part of the response, stringified as JSON text
+            // API docs show jobs under 'data' key, and meta for pagination
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify(response.data, null, 2),
+                    }]
+            };
+        }
+        catch (error) {
+            let errorMessage = `Failed to list jobs.`;
+            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/docs/agent-jobs-api.md

@@ -0,0 +1,336 @@
+# Agent Jobs API Endpoints
+
+This document describes the REST API endpoints available for the Agent Jobs module. These endpoints allow you to create, retrieve, and manage agent jobs programmatically.
+
+## Base URL
+
+All endpoints are prefixed with `/services/agent-jobs`.
+
+## Authentication
+
+All endpoints require authentication using a valid app token with the appropriate access level:
+
+- READ access to the SERVICES scope is required for GET operations
+- WRITE access to the SERVICES scope is required for POST and DELETE operations
+
+## Endpoints
+
+### Create a Job
+
+Creates a new agent job.
+
+**Endpoint:** `POST /services/agent-jobs`
+
+**Access Level Required:** WRITE access to SERVICES scope
+
+**Request Body:**
+
+```json
+{
+  "target_channel": {
+    "org_id": "string",
+    "platform": "string",
+    "type": "string",
+    "code": "string",
+    "data": {}
+  },
+  "job_type_id": "string",
+  "config": {
+    "max_follow_ups": "number",
+    "max_task_retries": "number",
+    "task_retry_interval": "number",
+    "start_prompt": "string",
+    "max_time_to_complete": "number",
+    "profile_id": "string"
+  },
+  "params": {},
+  "scheduled_at": "string" // Optional ISO 8601 date string
+}
+```
+
+**Query Parameters:**
+
+- `delay` (optional): A non-negative integer representing the maximum random delay in minutes to add to the scheduled time
+
+**Response:**
+
+```json
+{
+  "data": {
+    "job_id": "string",
+    "org_id": "string",
+    "channel_code": "string",
+    "job_type_id": "string",
+    "job_status": "string",
+    "created_at": "string",
+    "updated_at": "string",
+    "scheduled_at": "string",
+    "tasks": [],
+    "result": null,
+    "params": {},
+    "config": {}
+  },
+  "meta": {
+    "org_id": "string",
+    "id": "string"
+  }
+}
+```
+
+**Status Codes:**
+
+- 201: Job created successfully
+- 400: Bad request (missing required fields or invalid format)
+- 401: Authentication required
+- 404: Job type or organization not found
+
+### Get Jobs
+
+Retrieves a list of jobs for the authenticated organization.
+
+**Endpoint:** `GET /services/agent-jobs`
+
+**Access Level Required:** READ access to SERVICES scope
+
+**Query Parameters:**
+
+- `status`: Filter by job status (WAITING, RUNNING, COMPLETED, FAILED, CANCELED)
+- `scheduled_at`: Filter by scheduled time
+- `scheduled_at_gte`: Filter by scheduled time greater than or equal to
+- `scheduled_at_lte`: Filter by scheduled time less than or equal to
+- `created_at_gte`: Filter by creation time greater than or equal to
+- `created_at_lte`: Filter by creation time less than or equal to
+- `job_type_id`: Filter by job type ID
+- `channel_code`: Filter by channel code
+- `limit`: Maximum number of jobs to return (pagination)
+- `offset`: Number of jobs to skip (pagination)
+- `sort`: Sorting field and direction (e.g., `created_at:desc`)
+
+**Response:**
+
+```json
+{
+  "data": [
+    {
+      "job_id": "string",
+      "org_id": "string",
+      "channel_code": "string",
+      "job_type_id": "string",
+      "job_status": "string",
+      "created_at": "string",
+      "updated_at": "string",
+      "scheduled_at": "string",
+      "tasks": [],
+      "result": null,
+      "params": {},
+      "config": {}
+    }
+  ],
+  "meta": {
+    "org_id": "string",
+    "limit": "number",
+    "offset": "number",
+    "total": "number",
+    "sort": [
+      {
+        "field": "string",
+        "direction": "string"
+      }
+    ]
+  }
+}
+```
+
+**Status Codes:**
+
+- 200: Success
+- 401: Authentication required
+
+### Get Job by ID
+
+Retrieves a specific job by its ID.
+
+**Endpoint:** `GET /services/agent-jobs/:id`
+
+**Access Level Required:** READ access to SERVICES scope
+
+**URL Parameters:**
+
+- `id`: The ID of the job to retrieve
+
+**Response:**
+
+```json
+{
+  "data": {
+    "job_id": "string",
+    "org_id": "string",
+    "channel_code": "string",
+    "job_type_id": "string",
+    "job_status": "string",
+    "created_at": "string",
+    "updated_at": "string",
+    "scheduled_at": "string",
+    "tasks": [
+      {
+        "task_id": "string",
+        "created_at": "string",
+        "status": "string",
+        "result": "string"
+      }
+    ],
+    "result": "string",
+    "params": {},
+    "config": {}
+  },
+  "meta": {
+    "org_id": "string",
+    "id": "string"
+  }
+}
+```
+
+**Status Codes:**
+
+- 200: Success
+- 400: Bad request (missing job ID)
+- 401: Authentication required
+- 403: Forbidden (job belongs to a different organization)
+- 404: Job not found
+
+### Cancel Job
+
+Cancels a job by changing its status to CANCELED.
+
+**Endpoint:** `DELETE /services/agent-jobs/:id`
+
+**Access Level Required:** WRITE access to SERVICES scope
+
+**URL Parameters:**
+
+- `id`: The ID of the job to cancel
+
+**Request Body (optional):**
+
+```json
+{
+  "reason": "string" // Optional reason for cancellation
+}
+```
+
+**Response:**
+
+```json
+{
+  "meta": {
+    "org_id": "string",
+    "job_id": "string"
+  },
+  "message": "Job with ID '{job_id}' successfully canceled"
+}
+```
+
+**Status Codes:**
+
+- 200: Job successfully canceled
+- 400: Bad request (missing job ID)
+- 401: Authentication required
+- 403: Forbidden (job belongs to a different organization)
+- 404: Job not found
+- 409: Conflict (job is already in a terminal state)
+
+## Job Status Values
+
+Jobs can have the following status values:
+
+- `WAITING`: Job is waiting to be executed
+- `SCHEDULED`: Job is scheduled for future execution
+- `RUNNING`: Job is currently running
+- `COMPLETED`: Job has completed successfully
+- `FAILED`: Job has failed
+- `CANCELED`: Job was canceled
+
+## Examples
+
+### Creating a Job for Immediate Execution
+
+```bash
+curl -X POST https://api.example.com/services/agent-jobs \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "target_channel": {
+      "org_id": "org123",
+      "platform": "slack",
+      "type": "channel",
+      "code": "C123456",
+      "data": {
+        "channel_id": "C123456",
+        "team_id": "T123456"
+      }
+    },
+    "job_type_id": "daily-report",
+    "config": {
+      "max_follow_ups": 3,
+      "max_task_retries": 2,
+      "task_retry_interval": 5,
+      "max_time_to_complete": 60,
+      "profile_id": "profile123"
+    },
+    "params": {
+      "report_type": "daily",
+      "include_metrics": true
+    }
+  }'
+```
+
+### Creating a Scheduled Job
+
+```bash
+curl -X POST https://api.example.com/services/agent-jobs \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "target_channel": {
+      "org_id": "org123",
+      "platform": "slack",
+      "type": "channel",
+      "code": "C123456",
+      "data": {
+        "channel_id": "C123456",
+        "team_id": "T123456"
+      }
+    },
+    "job_type_id": "daily-report",
+    "config": {
+      "max_follow_ups": 3,
+      "max_task_retries": 2,
+      "task_retry_interval": 5,
+      "max_time_to_complete": 60,
+      "profile_id": "profile123"
+    },
+    "params": {
+      "report_type": "daily",
+      "include_metrics": true
+    },
+    "scheduled_at": "2023-12-31T09:00:00Z"
+  }'
+```
+
+### Retrieving Jobs with Filtering
+
+```bash
+curl -X GET "https://api.example.com/services/agent-jobs?status=RUNNING&job_type_id=daily-report&limit=10&offset=0&sort=created_at:desc" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+### Canceling a Job
+
+```bash
+curl -X DELETE https://api.example.com/services/agent-jobs/job123 \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "reason": "No longer needed"
+  }'
+```

package/docs/guidelines.md

@@ -0,0 +1,267 @@
+# AI Connect MCP Server - Development Guidelines
+
+This document outlines the development guidelines, standards, and best practices for the AI Connect MCP Server project.
+
+This project is an MCP (Model Context Protocol) server that provides AI agents with the ability to interact with the AI Connect Jobs system from the AI Connect platform. It's built using Node.js, TypeScript, and follows the MCP specification from Anthropic.
+
+## Environment Variables
+
+Use the following environment variables for configuration:
+
+- `AICONNECT_API_URL`: API endpoint URL (e.g., https://api.aiconnect.cloud/api/v0)
+- `AICONNECT_API_KEY`: Your API authentication key
+
+## Development Standards
+
+### Code Style
+
+- **Language**: TypeScript with strict mode enabled
+- **Module System**: ES modules (ESM)
+- **Code Formatting**: Use consistent indentation (2 spaces)
+- **Naming Conventions**:
+  - Files: `snake_case.ts` for tools, `camelCase.ts` for utilities
+  - Functions: `camelCase`
+  - Constants: `UPPER_SNAKE_CASE`
+  - Types/Interfaces: `PascalCase`
+
+### File Organization
+
+```
+src/
+├── index.ts              # Main server entry point
+├── tools/                # MCP tools directory
+│   ├── list_jobs.ts     # Individual tool files
+│   ├── get_job.ts
+│   ├── create_job.ts
+│   └── cancel_job.ts
+├── types/               # Type definitions
+├── utils/               # Utility functions
+└── config/              # Configuration files
+```
+
+### Tool Development
+
+#### Tool Structure
+
+Each MCP tool should follow this pattern:
+
+```typescript
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+export default (server: McpServer) => {
+  server.tool(
+    "tool_name",
+    "Clear description of what the tool does",
+    {
+      // Zod schema for parameters
+      param1: z.string({
+        description: "Description of parameter"
+      }),
+      param2: z.number().optional({
+        description: "Optional parameter description"
+      })
+    },
+    async (params) => {
+      try {
+        // Tool implementation
+        
+        return {
+          content: [{
+            type: "text",
+            text: "Response content"
+          }]
+        };
+      } catch (error) {
+        // Error handling
+        return {
+          content: [{
+            type: "text",
+            text: `Error: ${error.message}`
+          }],
+          isError: true
+        };
+      }
+    }
+  );
+};
+```
+
+#### Tool Guidelines
+
+1. **Single Responsibility**: Each tool should have one clear purpose
+2. **Error Handling**: Always wrap tool logic in try-catch blocks
+3. **Validation**: Use Zod schemas for parameter validation
+4. **Documentation**: Provide clear descriptions for tools and parameters
+5. **Response Format**: Return consistent response structures
+
+### API Integration
+
+#### HTTP Client Standards
+
+- Use native `fetch` for HTTP requests
+- Implement proper error handling for API calls
+- Include appropriate headers (Authorization, Content-Type)
+- Handle rate limiting and timeouts
+
+#### Environment Variables
+
+Required environment variables:
+
+```env
+DEFAULT_ORG_ID=<organization-id>
+AICONNECT_API_KEY=<api-key>
+AICONNECT_API_URL=<api-base-url>
+```
+
+### Error Handling
+
+#### Error Types
+
+1. **Validation Errors**: Invalid parameters or missing required fields
+2. **API Errors**: HTTP errors from AI Connect API
+3. **Authentication Errors**: Invalid or expired API keys
+4. **Network Errors**: Connection issues
+
+#### Error Response Format
+
+```typescript
+{
+  content: [{
+    type: "text",
+    text: "Error: [Category] - [Description]"
+  }],
+  isError: true
+}
+```
+
+### Testing Guidelines
+
+#### Test Structure
+
+- Unit tests for individual tools
+- Integration tests for API interactions
+- Mock external dependencies
+
+#### Test Files
+
+- Place tests in `tests/` directory
+- Name test files with `.test.ts` suffix
+- Use descriptive test names
+
+### Documentation
+
+#### Code Documentation
+
+- Use JSDoc comments for functions and classes
+- Document complex logic with inline comments
+- Keep documentation up to date with code changes
+
+#### API Documentation
+
+- Maintain API documentation in `docs/agent-jobs-api.md`
+- Update tool documentation when adding new features
+- Include usage examples
+
+### Git Workflow
+
+#### Branch Naming
+
+- Feature branches: `feature/description`
+- Bug fixes: `fix/description`
+- Documentation: `docs/description`
+
+#### Commit Messages
+
+Follow conventional commit format:
+
+```
+type(scope): description
+
+feat(tools): add list_jobs filtering capability
+fix(api): handle timeout errors properly
+docs(readme): update installation instructions
+```
+
+#### Pull Request Process
+
+1. Create feature branch from `main`
+2. Make changes with appropriate tests
+3. Update documentation if needed
+4. Submit PR with clear description
+5. Address review feedback
+6. Merge after approval
+
+### Security
+
+#### API Key Management
+
+- Never commit API keys to version control
+- Use environment variables for sensitive data
+- Rotate API keys regularly
+
+#### Input Validation
+
+- Validate all user inputs using Zod schemas
+- Sanitize data before API calls
+- Implement proper authorization checks
+
+### Performance
+
+#### Best Practices
+
+- Implement request caching where appropriate
+- Use connection pooling for API calls
+- Handle large datasets with pagination
+- Optimize for minimal memory usage
+
+### Deployment
+
+#### Build Process
+
+```bash
+npm run build  # Compile TypeScript
+npm start      # Run compiled server
+```
+
+#### Environment Setup
+
+- Development: Use `.env` file
+- Production: Set environment variables in deployment system
+
+### Troubleshooting
+
+#### Common Issues
+
+1. **Connection Errors**: Check API URL and network connectivity
+2. **Authentication Failures**: Verify API key and organization ID
+3. **Tool Not Found**: Ensure tool is registered in `index.ts`
+4. **Parameter Validation**: Check Zod schema definitions
+
+#### Debugging
+
+- Use console logging for development
+- Implement structured logging for production
+- Monitor API response times and error rates
+
+## Contributing
+
+### Code Review Checklist
+
+- [ ] Code follows style guidelines
+- [ ] All tests pass
+- [ ] Documentation is updated
+- [ ] Error handling is implemented
+- [ ] Security considerations addressed
+- [ ] Performance impact assessed
+
+### Release Process
+
+1. Update version in `package.json`
+2. Update CHANGELOG.md
+3. Create release tag
+4. Deploy to production environment
+
+---
+
+For questions about these guidelines, please contact the development team or open an issue in the project repository.