AI Connect MCP Server

AI Connect MCP サーバー

AI Connect プラットフォーム上のジョブを AI エージェントが照会、管理できる MCP（Model Context Protocol）サーバーです。

AI Connect Jobs について

AI Connect Jobs は、AI Connect プラットフォーム上の堅牢な非同期タスク管理システムです。Slack や WhatsApp など複数のプラットフォームにまたがるジョブの作成、監視、実行が可能で、スケジュール実行、自動再試行、タイムアウト処理にも対応しています。API にはジョブの作成、一覧表示、照会、キャンセルを行うエンドポイントが用意されており、開発者や外部システムは非同期処理機能をアプリケーションに簡単に統合できます。タスク管理の基盤全体を実装することなく、複雑なワークフローを自動化できます。

機能

この MCP サーバーは、AI エージェント向けに次のツールを提供します。

• 📋 ジョブの一覧表示：高度なフィルタリングを使用してすべてのジョブを照会します
• 🔍 特定のジョブの取得：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：LLM クライアントがタイムスタンプを整形できるよう、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 の設定

この MCP サーバーを Claude Desktop で使用するには、次の設定を 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

個々のジョブデータを取得せずに、エージェントジョブの集計統計を取得します。ネットワーク負荷を最小限に抑え、ダッシュボードやモニタリングに最適化されています。

パラメーター：

• 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 エンドポイントを使用して、特定のエージェントジョブの監査アクティビティ履歴を取得します。実際のページネーション（切り捨てなし）とサーバー側のフィルタリングに対応しています。ジョブのアクティビティログを詳しく調査する場合に使用してください。最近のアクティビティを簡単に重ねて表示する場合は、include_activities=true を指定して get_job を使用してください。

パラメーター：

• job_id（必須）：エージェントジョブの 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. プロジェクトをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/new-feature）
3. 変更をコミットします（git commit -am 'Add new feature'）
4. ブランチにプッシュします（git push origin feature/new-feature）
5. プルリクエストを作成します

ライセンス

このプロジェクトはMIT Licenseの下でライセンスされています。

サポート

AI Connect Jobs に関する技術サポートやご質問については、以下をご確認ください。

• API ドキュメントを確認する
• AI Connect の開発チームに問い合わせる

---

注記：このプロジェクトは、AI Connect プラットフォームとの連携のために Anthropic mcp-tools scaffold を使用して開発されました。