AI Connect MCP Server

AI Connect MCP 服务器

一个 MCP（Model Context Protocol）服务器，允许 AI Agent 在 AI Connect 平台中查询和管理任务。

关于 AI Connect 任务

AI Connect Jobs 是 AI Connect 平台上强大的异步任务管理系统，可在 Slack 和 WhatsApp 等不同平台创建、监控和执行任务，并支持计划执行、自动重试和超时处理。该 API 提供用于创建、列出、查询和取消任务的端点，让开发者和外部系统能够轻松将异步处理功能集成到应用程序中，无需实现整套任务管理基础设施，即可自动化复杂工作流。

功能

此 MCP 服务器为 AI Agent 提供以下工具：

• 📋 列出任务：通过高级筛选查询所有任务
• 🔍 获取指定任务：按 ID 获取指定任务的详细信息
• ✅ 创建任务：创建立即执行或计划执行的新任务
• ❌ 取消任务：取消正在运行或已计划的任务
• 📊 监控状态：跟踪任务状态（WAITING、RUNNING、COMPLETED、FAILED、CANCELED）

技术

• Node.js 和 TypeScript
• Anthropic 的 Model Context Protocol (MCP)
• 用于架构验证的 Zod
• 用于与 Agent Jobs 系统集成的 AI Connect API

安装

NPX（推荐）

无需安装，即可使用 npx 直接运行 MCP 服务器：

npx @aiconnect/agentjobs-mcp --help

本地安装

1. 克隆代码库：

git clone <repository-url>
cd agentjobs-mcp

2. 安装依赖项：

npm install

3. 配置环境变量（可选）：

MCP 服务器使用 .env.example 中的默认值，因此无需设置任何环境变量即可运行。不过，必须提供 API 密钥才能进行身份验证。

cp .env.example .env

使用你的凭据编辑 .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
DEFAULT_TIMEZONE=America/Sao_Paulo   # Default: UTC (informational only, surfaced via get_context)

重要：如果未提供环境变量，服务器将使用以下默认值：

• DEFAULT_ORG_ID：aiconnect
• AICONNECT_API_URL：https://api.aiconnect.cloud/api/v0
• AICONNECT_API_KEY：空（必须提供才能调用 API）
• DEFAULT_TIMEZONE：UTC

4. 构建项目：

npm run build

使用方法

CLI 用法

MCP 服务器现已支持 CLI 命令，方便管理：

# 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

设置环境变量：

# 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

必需的环境变量：

• AICONNECT_API_URL：API 端点 URL（例如 https://api.aiconnect.cloud/api/v0）
• AICONNECT_API_KEY：你的 API 身份验证密钥

可选的环境变量：

• DEFAULT_ORG_ID：省略工具的 org_id 参数时使用的备用组织 ID（默认值：aiconnect）
• DEFAULT_TIMEZONE：get_context 工具提供的首选时区，供大模型客户端格式化时间戳。仅供参考，不会改变其他工具的行为；其他工具仍会以 UTC 格式输出时间戳（默认值：UTC）

CLI 命令示例：

# 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

本地开发

进行本地开发时，可以使用 npm 脚本：

# 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

配置选项

此 MCP 服务开箱即用，所需配置极少。它采用智能回退机制：

1. 设置环境变量时：可完全控制所有设置
2. 未设置环境变量时：使用 .env.example 中的默认值
3. 部分配置时：混合使用环境变量和默认值

默认值（未设置环境变量时）：

• DEFAULT_ORG_ID："aiconnect"
• AICONNECT_API_URL："https://api.aiconnect.cloud/api/v0"
• AICONNECT_API_KEY：""（空值——必须提供）
• DEFAULT_TIMEZONE："UTC"

错误处理：

• 即使缺少环境变量，服务也始终会启动。
• 如果未提供 AICONNECT_API_KEY 或 AICONNECT_API_URL，每个工具在执行时都会返回清晰的错误消息，引导用户正确配置环境。
• 如果未设置 DEFAULT_ORG_ID，则默认为 "aiconnect"。
• 如果未设置 DEFAULT_TIMEZONE，则默认为 "UTC"。此值仅供参考（由 get_context 工具返回），不会影响其他工具的时间戳解析或格式化。

运行 MCP 服务

npm start

服务将启动，并通过 stdio 传输等待连接。

Claude Desktop 配置

要在 Claude Desktop 中使用此 MCP 服务，请将以下配置添加到 claude_desktop_config.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",
        "DEFAULT_TIMEZONE": "America/Sao_Paulo"
      }
    }
  }
}

使用 Claude Code 进行本地开发

在开发和测试时，可以将此 MCP 服务直接添加到 Claude Code 项目中：

# 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

这样，你就可以在开发期间直接在 Claude Code 中测试和使用 AgentJobs 工具，获得即时反馈并更轻松地调试。

可用工具

📊 get_jobs_stats

获取 Agent 作业的汇总统计数据，而不检索单个作业数据。针对仪表盘和监控场景进行了优化，可最大限度减少网络开销。

参数：

• scheduled_at_gte：时段开始时间（ISO 8601）
• scheduled_at_lte：时段结束时间（ISO 8601）
• org_id：组织筛选条件
• job_type_id：作业类型筛选条件
• tags：标签筛选条件（逗号分隔）
• status：状态筛选条件
• channel_code：渠道筛选条件

🔧 list_jobs

列出所有作业，并支持筛选和分页选项。

参数：

• status（可选）：按状态筛选（WAITING、RUNNING、COMPLETED、FAILED、CANCELED）
• job_type_id（可选）：按作业类型筛选
• channel_code（可选）：按渠道代码筛选
• limit（可选）：结果数量上限（默认：50）
• offset（可选）：分页偏移量
• sort（可选）：排序字段和方向
• include_activities（可选）：为每个作业附加近期活动（默认：false）
• activities_limit_per_job（可选）：每个作业的活动数量上限（1–100，默认 15）
• activities_total_limit（可选）：整个响应中的活动总数上限（1–3000，默认 500）
• activities_sort（可选）：created_at 或 -created_at（默认 -created_at）

🔍 get_job

获取特定作业的详细信息。

参数：

• job_id（必填）：要查询的作业 ID
• include_activities（可选）：以内联覆盖层的形式附加近期活动（默认：false）
• include_limit（可选）：要附加的活动数量上限（1–100，默认 50）
• include_sort（可选）：created_at 或 -created_at（默认 -created_at）

🧾 get_job_activities

通过专用的 /services/activities 端点，检索特定 Agent 作业的审计活动记录。支持真正的分页（不会截断）和服务器端筛选。若要针对性地调查作业活动日志，请使用此工具；若要快速查看近期活动概览，请使用 get_job 并设置 include_activities=true。

参数：

• job_id（必需）：Agent 作业的 ID
• org_id（可选）：组织范围
• status（可选）：submitted、completed 或 canceled
• activity_type_code（可选）：开放字符串代码（例如，ai_completion）
• source_type（可选）：dispatch、process_module 或 direct
• limit（可选）：页面大小（默认值为 50）
• offset（可选）：分页偏移量（默认值为 0）
• sort（可选）：排序字段／方向（默认值为 -created_at）

✅ create_job

创建新的作业以供执行。

参数：

• target_channel：目标通道配置
• job_type_id：作业类型 ID
• config：作业配置（超时、重试等）
• params：特定于作业的参数
• scheduled_at（可选）：计划执行的日期／时间
• delay（可选）：随机延迟分钟数

❌ cancel_job

取消正在运行或已计划的作业。

参数：

• job_id（必需）：要取消的作业 ID
• reason（可选）：取消原因

作业状态

作业可能具有以下状态值：

• WAITING：作业等待执行
• SCHEDULED：作业已计划在将来执行
• RUNNING：作业正在运行
• COMPLETED：作业已成功完成
• FAILED：作业失败
• CANCELED：作业已取消

使用示例

列出正在运行的作业

Agent: "Show me all jobs that are currently running"

查询特定作业

Agent: "What's the status of job job-123?"

创建计划作业

Agent: "Create a daily report job for Slack channel C123456 to run tomorrow at 9 AM"

取消作业

Agent: "Cancel job job-456 because it's no longer needed"

项目结构

agentjobs-mcp/
├── src/                    # TypeScript source code
│   ├── 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
│       ├── get_job_activities.ts # Tool for getting a job's activity trail
│       ├── 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
├── package.json           # Dependencies and scripts
├── tsconfig.json          # TypeScript configuration
├── .env.example           # Environment variables example
└── README.md              # This file

开发

可用脚本

• npm run build：编译 TypeScript
• npm start：运行编译后的服务
• npm run debug：以调试模式运行服务并启用详细日志记录
• npm run test:tools：测试工具加载，不启动服务
• npm run cli:config：显示当前配置
• npm run cli:version：显示版本信息
• npm run cli:help：显示帮助信息

调试

如需详细的调试信息，请参阅调试指南。

快速调试命令：

# 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

调试环境：

# Copy debug environment template
cp .env.debug .env
# Edit .env with your API credentials
# Run with debug environment
./debug.fish debug-with-env

添加新工具

添加新工具很简单：

1. 在 src/tools/ 目录中创建一个新的 TypeScript 文件（例如，my_new_tool.ts）。
2. 按照现有模式实现工具逻辑。服务会在启动时自动检测并注册该工具。
3. 使用 npm run build 重新编译项目。
4. 使用 npm run test:tools 进行测试，验证工具是否已加载。

贡献

1. Fork 项目
2. 创建功能分支（git checkout -b feature/new-feature）
3. 提交更改（git commit -am 'Add new feature'）
4. 推送到该分支（git push origin feature/new-feature）
5. 发起 Pull Request

许可证

本项目采用 MIT 许可证。

支持

如需 AI Connect Jobs 的技术支持或有相关问题：

• 查阅 API 文档
• 联系 AI Connect 开发团队

---

注意：本项目使用 Anthropic mcp-tools 脚手架开发，用于与 AI Connect 平台集成。