MCP-ALBERTO

MCP-ALBERTO: AI向け基本ツールサーバー

このプロジェクトは**、AI アシスタントの機能を拡張するために設計されたモデル コンテキスト プロトコル (MCP) サーバーを実装します。これは、**単独では有用性が限られているものの、 AI モデルによって組み合わせて調整され、複雑なワークフローを実行し、特定の外部サービス (現在は TotalCheck に関連する「ALBERTO」と呼ばれるシステム) と対話するように設計された、基本的なアトミック ツールのセットを提供します。

目標は、あらかじめパッケージ化された複雑なツールを提供することではなく、資格情報の取得、認証、基盤となるサービスの他のエンドポイントとの対話などのタスクを AI が動的に解決するために使用できるビルディング ブロック (プリミティブ) を提供することです。

実行構成（統合例）

次の構成 (例) は、この MCP を、それを使用するツールと統合する方法を示しています。

プロジェクト構造

• main.ts : アプリケーションのエントリ ポイント。 MCP サーバーを初期化し、トランスポート (現在はStdioServerTransport ) を構成し、使用可能なツールを登録します。
• userservice/ :
  • userservice-api-rest.ts : ユーザー サービス REST API と対話するためのロジック (認証チケットの取得など) が含まれています。
  • userservice-tool.ts : ユーザー サービスに関連する MCP ツール (例: get_ticket ) を定義および登録します。
• README.md : このファイル。
• .gitignore : Git によって無視されるファイルとディレクトリを指定します。
• package.json / package-lock.json : Node.js プロジェクトの依存関係を管理します。
• tsconfig.json : TypeScript コンパイラの構成。

利用可能なMCPツール

このサーバーは次のツールを公開します。これらのツールは低レベルのビルディング ブロックであることを理解することが重要です。 AI がそれらを順番に、または組み合わせて使用してより大きな目標を達成すると、それらの真の可能性が解き放たれます。

• get_node_info
  • **説明:**システム内の特定のノードに関する詳細かつ完全な情報を取得します。
  • 実装: nodeservice/nodeservice-tool.ts
  • パラメータ: unique_id (文字列、必須)、 alf_ticket (文字列)。
  • **使用方法:**ノードの正確なunique_idがわかっており、その詳細がすべて必要な場合に最適です。
• search_by_type
  • 説明: ElasticSearch でテナントおよびタイプ別に柔軟な検索を実行し、さまざまな基準に基づいてノードを見つけることができます。
  • 実装: searchservice/by_type/tool.ts
  • エンドポイント API: /searchservice/tenant/{tenant}/type/{type}/...
  • パラメータ:
    • tenant_name (文字列、必須): 検索するテナント。
    • type_name (文字列、必須): 照会する特定のインデックス/タイプ (例: expediente_inscripcion_mt )。
    • query_body (文字列、必須): JSON 文字列形式の ElasticSearch クエリ。
    • alf_ticket (文字列): 認証チケット。
    • from_index (数値、オプション): ページ区切り。
    • page_size (数値、オプション): ページ区切り。
    • sort (文字列、オプション): 並べ替え。
  • **用途:**特定のインデックス (ファイル、ユーザーなど) を対象とした検索に使用します。
• search_workflow
  • 説明: ElasticSearch のWorkflow taskmanagerエイリアスに対して柔軟な検索を実行します。
  • 実装: searchservice/workflow/tool.ts
  • エンドポイント API: /searchservice/workflow/...
  • パラメータ:
    • query_body (文字列、必須): JSON 文字列形式の ElasticSearch クエリ。
    • alf_ticket (文字列): 認証チケット。
    • from_index (数値、オプション): ページ区切り。
    • page_size (数値、オプション): ページ区切り。
  • **用途:**タスクまたはワークフロー情報を検索します。部分的なデータ (特許、操作) のみが利用可能な場合に、ケースのunique_idまたはtype_name検出するための中間ステップとして役立ちます。
• get_ticket
  • **説明:**外部ログイン サービスから認証チケットを取得します。
  • 実装: userservice/userservice-tool.ts
  • パラメータ:
    • usuario (文字列): 認証用のユーザー名。
    • password (文字列): ユーザーのパスワード。
  • **戻り値:**認証チケットをテキストとして返します。
• get_config_credentials
  • **説明:**構成資格情報 (ユーザー、キー、説明) の定義済みリストを取得します。
  • 実装: configuraciones/configuraciones-tool.ts
  • **パラメータ:**なし。
  • **戻り値:**それぞれusername 、 clave 、およびdescriptionを持つ JSON オブジェクトの配列。
  • **注:**システムと対話するために利用可能な ID を AI に提供します。

一般的なワークフロー

• 構成資格情報を使用してチケットを取得します。
  1. 事前設定されたユーザー名とパスワードを取得するには、 get_config_credentialsを呼び出します。
  2. JSON 結果からusuarioとpasswordを抽出します。
  3. 前の手順で取得したusuarioとpasswordを渡してget_ticket呼び出します。

AIオーケストレーション（概念例）

AI アシスタントは、「管理者ユーザーのチケットを取得してください」などのリクエストを受け取る場合があります。 AI は利用可能なツールを使用して、次の手順を実行します。

1. get_config_credentialsを呼び出します: ユーザーのリストとその説明を取得します。
2. ユーザーの識別: 応答を処理して、「管理者ユーザー」の説明に対応するusernameを検索します。
3. get_ticketを呼び出します。識別されたusernameとそのclave (暗黙的または抽出された) を使用して、認証チケットを要求します。
4. 結果の表示: 取得したチケットをユーザーに返します。

この例は、AI の指示の下で単純なツールが組み合わされ、複雑なニーズを満たす様子を示しています。

サービスとElasticsearch間の相互作用

search_by_type 、 search_workflow 、 get_node_info Elasticsearch のデータ構造とどのように相互作用し、関連するかを理解することが重要です。

1. **プライマリ インデックス:**各プライマリ エンティティ タイプ (例: expediente_inscripcion_mt 、 expediente_operacion_leasing 、 user 、 tenant ) は、独自の ElasticSearch インデックスに存在します。 search_by_type 、適切なtype_nameを指定してこれらのインデックスを直接クエリできます。
2. **ワークフロー インデックス ( taskmanager_* ):**ノードがワークフローに入ると、ワークフロー固有のインデックス (例: taskmanager_expediente_inscripcion_mt ) にエントリが生成されます。
3. エイリアスtaskmanager : すべてのワークフロー インデックスをグループ化するtaskmanagerというエイリアスがあります。 search_workflowまたはsearch_by_typeを使用すると、すべてのアクティブなタスクを検索できます。
4. 典型的なフロー:
   • 主なタイプがわかっている場合、AI はsearch_by_type直接使用します。
   • 一般的な情報が求められている場合、または正確なタイプが不明な場合、AI はsearch_workflow (エイリアスtaskmanagerクエリ) を検出手順として使用できます。
   • search_workflowまたはsearch_by_typeの結果には、必要な情報または親ノードのunique_idが含まれる場合があります。
   • unique_idが取得され、すべての詳細が必要な場合、AI はget_node_info使用できます。

AIガイド：最小検索条件

関連性と効率性の高い結果を確保するために、 search_by_typeまたはsearch_workflowのquery_bodyを構築するときに、ユーザーリクエストで明示的に別の指定がない限り、AI は次の最低限のデフォルト条件を適用する必要があります。

• プライマリインデックス (例: expediente_* 、 user 、 tenant ) をクエリする場合:
  • 削除されたレコードを除外します。クエリに含める内容:
    { "query": { "bool": { "must_not": [{ "term": { "deleted": true } }] } } }
    (必要に応じて、 bool内の他のmustやfilter句と組み合わせます。)
• エイリアスtaskmanagerクエリを実行する場合：
  • アクティブなタスクのみを含め、削除されたレコードは除外します。
  • クエリに含める内容:
    { "query": { "bool": { "must": [{ "term": { "status": "active" } }], "must_not": [{ "term": { "deleted": true } }] } } }
    (実際の名前が異なる場合は、 statusフィールドとそのactive値を調整し、他のmustやfilter句と組み合わせます。)

主な技術的詳細

1- package.jsonの追加構成- "type": "module" : ES6 モジュール (インポート/エクスポート) の使用を有効にします。

2-重要なパッケージ ( dependencies ) - @modelcontextprotocol/sdk : MCP サーバーを作成するための SDK。 - zod : スキーマ検証用（ツール定義で使用）。 - axios : REST API を呼び出すための HTTP クライアント。 - tsx : TypeScript ファイルを直接実行します。

3- MCP メイン ファイル- main.ts : メイン オーケストレーター。 - userservice/userservice-api-rest.ts : API 呼び出しロジック。 - userservice/userservice-tool.ts : MCP ツールの定義。

ローカル開発用のコマンド

1. 依存関係をインストールします:
   npm install
2. MCP サーバーを実行します。
   npx tsx main.ts
   サーバーが起動し、stdio 経由の通信を待機します。