Chatvolt MCP

🚀 Chatvolt MCPサーバー: 概要

このドキュメントでは、Chatvoltモデルコンテキストプロトコル（MCP）サーバーの概要を説明します。これは、AIエージェントにChatvoltプラットフォームとやり取りするためのツールセットを提供し、その機能を拡張するためのTypeScriptベースのアプリケーションです。

🚀 クイックスタート

このMCPサーバーは、クライアントからのコマンドで起動されます。接続するには、クライアントを設定して chatvolt-mcp コマンドを起動し、必要な環境変数を渡す必要があります。

以下は、クライアントの mcpServers 設定を構成する例です。

{
  "mcpServers": {
    "chatvolt-mcp": {
      "command": "npx",
      "args": [
        "chatvolt-mcp"
      ],
      "env": {
        "CHATVOLT_API_KEY": "{your_token}"
      }
    }
  }
}

⚠️ 重要提示

"{your_token}" を実際のChatvolt APIキーに置き換える必要があります。

✨ 主な機能

このプロジェクトの主な目的は、AIモデルとChatvolt APIの間の架け橋として機能することです。AIエージェントがエージェントの管理、データストアのクエリ、CRMシナリオの処理などのアクションを実行するために呼び出すことができる一連のツールを公開します。これにより、複雑なワークフローの自動化が可能になり、Chatvoltプラットフォームに自然言語インターフェースが提供されます。

📦 インストール

ドキュメントに具体的なインストール手順は記載されていません。

🔧 技術詳細

主要技術

• Node.js：サーバーのランタイム環境です。
• TypeScript：静的型付けと最新のJavaScript機能を提供する主要なプログラミング言語です。
• @modelcontextprotocol/sdk：MCPサーバーを構築するためのコアSDKで、ツール、リソースの定義とAIモデルからのリクエストの処理を簡素化します。

主要コンポーネント

1. MCPサーバー (src/server.ts)

アプリケーションの核心はMCPサーバーで、以下の役割を担っています。

• サーバーの初期化：サーバーの名前、バージョン、機能を設定します。
• リクエストの処理：ListTools、CallTool、ListResources、GetPrompt などのさまざまなMCPリクエストタイプのハンドラーを実装します。
• ツールのディスパッチ：CallTool リクエストを受け取り、適切なツールハンドラーにディスパッチします。

2. ツール (src/tools/)

ツールは、AIエージェントが実行できるアクションです。src/tools/ ディレクトリに定義されており、大まかに以下のカテゴリに分類されます。

• エージェント管理：Chatvoltエージェントの作成、更新、削除、一覧表示のためのツールです。
• CRM管理：CRMシナリオとステップを管理するためのツールです。
• データストア管理：データストアとデータソースとやり取りするためのツールです。

3. リソースとプロンプト

サーバーは、リソースとプロンプトを通じてAIモデルに追加のコンテキストを提供します。

• TOOL_DESCRIPTIONS.md：利用可能なすべてのツールとそのパラメータの詳細な説明を提供するMarkdownファイルです。
• MODELS.md：エージェントとともに使用できるAIモデルのリストです。
• SYSTEM_PROMPTS.md：AIエージェントをガイドするシステムレベルの指示が含まれています。

詳細なアーキテクチャ

1. リクエストのライフサイクル: CallTool

CallTool リクエストは、AIエージェントがアクションを実行する主要なメカニズムです。このリクエストのライフサイクルは以下の通りです。

sequenceDiagram
    participant AI Agent
    participant MCP Server
    participant Tool Handler
    participant Chatvolt API

    AI Agent->>+MCP Server: Sends CallToolRequest (e.g., 'delete_agent', {id: '123'})
    MCP Server->>MCP Server: Receives request in CallTool handler
    Note over MCP Server: Finds handler for 'delete_agent' in `toolHandlers` map
    MCP Server->>+Tool Handler: Invokes handleDeleteAgent(request)
    Tool Handler->>Tool Handler: Validates arguments (e.g., checks for 'id')
    Tool Handler->>+Chatvolt API: Calls `deleteAgent('123')`
    Chatvolt API-->>-Tool Handler: Returns result (e.g., {success: true})
    Tool Handler-->>-MCP Server: Returns formatted content
    MCP Server-->>-AI Agent: Sends response with tool output

フローの説明：

1. リクエストの受信：MCPサーバーが CallToolRequest を受け取ります。このリクエストは、src/server.ts で定義された汎用の CallToolRequestSchema ハンドラーによって処理されます。
2. ハンドラーのディスパッチ：サーバーは toolHandlers オブジェクトから特定のツールハンドラーを検索します。このオブジェクトは、ツール名（例："delete_agent"）を対応するハンドラー関数（例：handleDeleteAgent）にマッピングします。このオブジェクトは、中央の src/tools/ インデックスファイルからインポートされます。
3. ツールの実行：一致するハンドラー関数が実行されます。例えば、src/tools/deleteAgent.ts の handleDeleteAgent が呼び出されます。
4. ビジネスロジック：ツールハンドラーはリクエストから必要な引数を抽出し、それらを検証してから、src/services/ レイヤーの関連する関数（例：deleteAgent(id)）を呼び出します。
5. APIの相互作用：サービス関数は、Chatvoltプラットフォームへの実際のAPI呼び出しを担当します。
6. レスポンスの整形：ツールハンドラーはサービスからデータを受け取り、それを文字列化（この場合はJSONとして）し、MCP SDKが期待する形式でラップします。
7. レスポンスの送信：サーバーは最終的な整形されたコンテンツを、呼び出しを開始したAIエージェントに送信します。

2. ディレクトリ構造

プロジェクトは、関心事を分離するように組織されており、モジュール性と保守性が高くなっています。

• src/：すべてのアプリケーションソースコードのルートディレクトリです。
• src/tools/：サーバーが公開する各ツールの実装が含まれています。
  • 構造：各ツールは通常、独自のファイル（例：deleteAgent.ts）を持っています。
  • 内容：各ファイルは2つの主要な構成要素をエクスポートします。
    1. MCP SDKが必要とする name、description、inputSchema を含む Tool 定義オブジェクト（例：deleteAgentTool）。
    2. ツールを実行するためのロジックを含むハンドラー関数（例：handleDeleteAgent）。
  • 集約：このディレクトリ内の中央の index.js ファイルは、すべての個々のツールとハンドラーをインポートし、2つの集約オブジェクトとしてエクスポートします。tools（すべてのツール定義の配列）と toolHandlers（ツール名をそのハンドラーにマッピングするマップ）。
• src/services/：このディレクトリは、主にChatvolt APIなどの外部サービスとやり取りするビジネスロジックとAPIクライアントコードを収容することを目的としています。
  • 目的：ツールハンドラーと基盤となるプラットフォームの間の架け橋として機能します。この分離により、ツールハンドラーはリクエスト/レスポンスの処理と引数の検証のみに責任を持ち、サービスレイヤーはAPI通信の詳細を管理します。
  • 例：src/tools/deleteAgent.ts からインポートされる deleteAgent 関数は、Chatvoltの /agents/:id エンドポイントに DELETE リクエストを送信するために必要な fetch 呼び出しとロジックを含みます。

3. ツールの定義と登録

ツールは、サーバーの機能を定義する核心的なコンポーネントです。それらの定義と登録は明確なパターンに従っています。

1. ツールの定義：各ツールは、@modelcontextprotocol/sdk/types.js ライブラリの Tool 型の定数オブジェクトとして定義されます。このオブジェクトには以下が含まれます。
   • name：ツールの一意の機械可読名（例："delete_agent"）。
   • description：ツールが何をするかとそのパラメータの人間可読な説明です。TOOL_DESCRIPTIONS.md のようなリソースファイルがAIモデルに詳細なドキュメントを提供するために存在しますが、ツール定義自体の description プロパティは簡潔な要約として機能します。
   • inputSchema：ツールが受け入れる引数を正式に定義するJSONスキーマオブジェクトで、それらの型と必須かどうかが含まれます。
2. ツールの登録：サーバーは以下のプロセスを通じてツールを検出して登録します。
   • tools 配列と toolHandlers マップは、src/tools/index.js から src/server.ts にインポートされます。
   • src/server.ts の ListToolsRequestSchema ハンドラーは、インポートされた tools 配列を使用して、利用可能なツールのリストに対するリクエストに応答します。
   • CallToolRequestSchema ハンドラーは、toolHandlers マップを使用して、受信したリクエストの name パラメータに基づいて正しい関数を見つけて実行します。

このアーキテクチャにより、新しいツールは src/tools/ ディレクトリに新しいファイルを作成し、中央の index.js ファイルを更新することで簡単に追加でき、src/server.ts のコアサーバーロジックを変更する必要はありません。

システムプロンプトのドキュメント

このドキュメントでは、Chatvolt MCP（モデルコンテキストプロトコル）とやり取りする際にAIエージェントの動作をガイドするために使用されるシステムプロンプトの役割と内容について説明します。これらのプロンプトは、SYSTEM_PROMPTS.md ファイルで定義されており、AIに基本的な一連の指示を提供します。

システムプロンプトの目的

システムプロンプトは、AIのペルソナ、目的、操作制約を定義する高レベルの指示です。これらは、ユーザーのリクエストをどのように解釈し、ツールをどのように利用し、レスポンスをどのように構成するかについて明確なフレームワークを確立することで、AIが予測可能かつ効果的に動作することを保証します。

主要な指示とシナリオ

SYSTEM_PROMPTS.md ファイルには、AIの動作をガイドするための3つの主要なシナリオとそれぞれに対応するシステムプロンプトが概説されています。

1. シンプルなツール操作

• 目的：単一のツール呼び出しで満たすことができる単純なユーザーリクエストを処理することです。
• AIのペルソナ：ChatvoltプラットフォームのエキスパートAIアシスタントです。
• 核心的な指示：
  1. ユーザーの意図を特定します。
  2. 最も適切な単一のツール（例：list_agents）を選択します。
  3. 正しいパラメータでツールを実行します。
  4. 結果をユーザーに報告します。

2. 複雑な多段階ワークフロー

• 目的：大きな目標を達成するために一連のツール呼び出しを必要とする複雑なタスクを管理することです。
• AIのペルソナ：ワークフローを調整する責任を持つ上級AI自動化エンジニアです。
• 核心的な指示：
  1. 分解：ユーザーのリクエストを小さな逐次的なステップに分解します。
  2. 計画：ステップごとに適切なツールを特定して、段階的な計画を作成します。
  3. 実行：ツールを順次呼び出し、各ツールの成功を待ってから次のツールに進みます。あるツールの出力は別のツールの入力として使用できます。
  4. 合成：実行されたすべてのアクションと結果の最終的な要約を提供します。

3. 自己発見と学習

• 目的：タスクを実行する前に、AIが自らの機能を活用し、学習できるようにすることです。
• AIのペルソナ：高度に自律的で積極的なAIエージェントです。
• 核心的な指示：
  1. 最初に自己発見：複雑なタスクを試みる前に、AIは必ず getDocumentation ツールを呼び出して、利用可能なすべてのツールに関する情報を取得する必要があります。
  2. 分析：ドキュメントをレビューして、その機能を理解します。
  3. 計画：新たに取得したツールの知識に基づいて計画を立案します。
  4. 実行：計画を実行し、結果を報告します。

📚 ドキュメント

APIとツールのリファレンス

このドキュメントでは、サーバーとやり取りするために使用できる利用可能なツールの詳細なリファレンスを提供します。

create_agent

新しいChatvoltエージェントを作成します。

update_agent

IDに基づいて既存のエージェントを部分的に更新します。特定のエージェントの1つ以上のフィールドを更新できます。リクエストボディで提供されたフィールドのみが更新されます。

delete_agent

指定されたエージェントを削除します。

list_agents

利用可能なすべてのエージェントのリストを取得します。

このツールにはパラメータはありません。

get_agent

単一のエージェントに関する詳細情報を取得します。

agent_query

エージェントにクエリまたはメッセージを送信して処理させます。

enable_disable_agent_integration

エージェントの特定の統合を有効または無効にします。

create_crm_scenario

CRM内に新しいシナリオを作成します。

update_crm_scenario

既存のCRMシナリオを更新します。

delete_crm_scenario

CRMシナリオを削除します。

list_crm_scenarios

すべてのCRMシナリオのリストを表示します。

create_crm_step

CRMシナリオ内に新しいステップを作成します。

update_crm_step

CRMシナリオ内の既存のステップを更新します。

delete_crm_step

CRMシナリオからステップを削除します。

list_crm_steps

指定されたCRMシナリオのすべてのステップのリストを表示します。

create_datastore

新しいデータストアを作成します。

get_datastore

特定のデータストアに関する情報を取得します。

list_datastores

すべてのデータストアのリストを取得します。

このツールにはパラメータはありません。

create_datasource

データストア内に新しいデータソースを作成します。