Dual Cycle Reasoner

MCP Dual-Cycle Reasoner

自律型エージェント向けにDual-Cycle Metacognitive Reasoning Frameworkを実装したModel Context Protocol（MCP）サーバーです。このツールは、インテリジェントなループ検出と経験の取得により、エージェントの自己認識と信頼性を高めます。

説明

MCP Dual-Cycle Reasonerは、AI エージェントの自律性と信頼性を高めるために設計された高度なツールです。デュアルサイクルのメタ認知フレームワークを実装することで、エージェントが自身の認知プロセスを監視し、反復的なループに陥ったことを検出し、過去の経験から学んでより適切な判断を下せるようにします。

このフレームワークは、次の2つの主要コンポーネントで構成されます。

• Sentinel：エージェントのアクションを監視し、アクションの反復、状態の不変、進捗の停滞などの異常を検出します。
• Adjudicator：過去の経験を蓄積するケースベースを管理し、以前に遭遇した問題の解決策をエージェントが保存および取得できるようにします。

このサーバーはTypeScriptで構築され、統計分析、自然言語処理、意味的類似性のための高性能ライブラリを活用しています。これにより、エントロピーに基づく異常検出、NLIに基づくテキスト分析、インテリジェントなケース管理などの高度な機能を実現します。

主な機能

• 📊 高度な統計分析：エントロピーに基づく異常検出と時系列分析。
• 🧠 強化されたケースベース推論：NLIに基づくテキスト分析を用いた意味的類似性マッチング。
• 🎯 複数の検出戦略：統計的、パターンベース、ハイブリッドなループ検出。
• 📈 時系列分析：傾向の検出と周期パターンの認識。
• 🔧 設定可能な検出：ドメイン固有のしきい値と進捗インジケーター。
• 🎨 インテリジェントなケース管理：品質スコアリング、重複排除、使用状況に基づく最適化。
• 🚀 高性能ライブラリ：simple-statistics、natural、compromise、HuggingFace Transformersを使用して構築されています。

技術スタック

• 言語：TypeScript
• フレームワーク：Node.js
• サーバー：SSEトランスポート用のFastMCP
• NLPと機械学習：
  • @huggingface/transformers：NLIに基づく意味分析用
  • natural：感情分析とトークン化用
  • compromise：自然言語処理用
• 統計：
  • simple-statistics：統計計算用
  • ml-matrix：行列演算用
• 開発ツール：
  • jest：テスト用
  • eslint：リンティング用
  • prettier：コード整形用
  • zod：スキーマ検証用

インストール

プロジェクトをローカルで実行するには、次の手順に従ってください。

1. リポジトリをクローンする：

   git clone https://github.com/cyqlelabs/mcp-dual-cycle-reasoner.git
   cd mcp-dual-cycle-reasoner
   

2. 依存関係をインストールする：

   npm install
   

3. プロジェクトをビルドする：

   npm run build
   

使用方法

サーバーの実行

サーバーは次の2つのモードで実行できます。

1. HTTP Stream（デフォルト）：

   npm start
   

   サーバーはポート8080で起動します。

2. Stdio：

   npm start -- --stdio
   

Claude Desktopでの使用

以下をClaude DesktopのMCP設定に追加してください。

{
  "mcpServers": {
    "dual-cycle-reasoner": {
      "command": "npx",
      "args": ["@cyqlelabs/mcp-dual-cycle-reasoner"]
    }
  }
}

stdioトランスポートを使用するには、args配列に--stdioフラグを追加してください。

利用可能なツール

コア監視ツール

start_monitoring

エージェントの認知プロセスのメタ認知モニタリングを初期化します。

入力スキーマ：

{
  goal: string; // Current goal being pursued
  initial_beliefs?: string[]; // Initial beliefs about the task
}

process_trace_update

メインの監視機能です。エージェントからの認知トレースの更新を処理します。

入力スキーマ：

{
  last_action: string; // Latest action name
  current_context?: string; // Current environment context
  goal: string; // Current goal being pursued
  window_size?: number; // Monitoring window size (default: 10)
}

返却ペイロード：

介入が必要かどうかと、検出されたループに関する詳細を示す JSON オブジェクトを返します。

{
  "intervention_required": true,
  "loop_detected": {
    "detected": true,
    "type": "action_repetition",
    "confidence": 0.85,
    "details": "Loop detected via parameter_repetition: 57% anomaly score...",
    "actions_involved": ["click_submit_button"]
  }
}

stop_monitoring

メタ認知モニタリングを停止し、セッションの概要を取得します。

入力スキーマ：{}

ループ検出ツール

detect_loop

さまざまな戦略を用いて、エージェントがループに陥っているかどうかを検出します。

入力スキーマ：

{
  current_context?: string; // Current environment context
  goal: string; // Current goal being pursued
  detection_method?: "statistical" | "pattern" | "hybrid"; // Detection method (default: "hybrid")
}

返却ペイロード：

LoopDetectionResult オブジェクトを JSON 文字列として返します。

{
  "detected": true,
  "type": "action_repetition",
  "confidence": 0.85,
  "details": {
    "dominant_method": "parameter_repetition",
    "anomaly_score": 0.57,
    "actions_involved_count": 1,
    "recent_actions_count": 10,
    "metrics": {
      "semantic_repetition": 0.6,
      "parameter_repetition": 0.8
    }
  },
  "actions_involved": ["click_submit_button"]
}

configure_detection

ループ検出のパラメーターと、ドメイン固有の進捗指標を設定します。

入力スキーマ：

{
  progress_indicators?: string[]; // default: []
  min_actions_for_detection?: number; // default: 5
  alternating_threshold?: number; // default: 0.5
  repetition_threshold?: number; // default: 0.4
  progress_threshold_adjustment?: number; // default: 0.2
  semantic_intents?: string[]; // default: []
}

強化されたエクスペリエンス管理

store_experience

強化されたメタデータと品質スコアを付与して、将来の事例ベース推論に使用する事例を保存します。

入力スキーマ：

{
  problem_description: string;
  solution: string;
  outcome: boolean;
  context?: string;
  difficulty_level?: "low" | "medium" | "high";
}

retrieve_similar_cases

高度なセマンティックマッチングとフィルタリングを用いて、類似する事例を取得します。

入力スキーマ：

{
  problem_description: string;
  max_results?: number; // default: 5
  context_filter?: string;
  difficulty_filter?: "low" | "medium" | "high";
  outcome_filter?: boolean;
  min_similarity?: number; // default: 0.6
}

返却ペイロード：

Case オブジェクトの配列を JSON 文字列として返します。

[
  {
    "id": "case-123",
    "problem_description": "Form submission button not responding to clicks",
    "solution": "Ensure all required fields are filled correctly.",
    "outcome": true,
    "context": "registration_form",
    "difficulty_level": "medium",
    "similarity_metrics": {
      "combined_similarity": 0.92
    }
  }
]

システムツール

get_monitoring_status

現在の監視ステータスと統計情報を取得します。

入力スキーマ：{}

返却ペイロード：

is_monitoring、current_goal、trace_length、intervention_count を含む、現在の監視ステータスを示す JSON 文字列を返します。

{
  "is_monitoring": true,
  "current_goal": "Complete user registration process on website",
  "trace_length": 15,
  "intervention_count": 2,
  "recent_actions": [
    { "type": "click_submit_button", "timestamp": 1678886400000 },
    { "type": "click_submit_button", "timestamp": 1678886401000 }
  ]
}

reset_engine

デュアルサイクルエンジンの状態をリセットします。

入力スキーマ：{}

使用例のシナリオ

以下は、デュアルサイクル推論エンジンを使って自律エージェントを監視し、時間とともに経験を蓄積する方法を示す完全な例です。

1. 初期設定と構成

// Configure detection parameters for your domain
await configure_detection({
  progress_indicators: ['page_loaded', 'form_submitted', 'data_extracted'],
  min_actions_for_detection: 3,
  alternating_threshold: 0.6,
  repetition_threshold: 0.3,
  semantic_intents: [
    'navigating to page',
    'clicking element',
    'filling form field',
    'submitting form',
    'validating input',
    'handling popup',
    'extracting data',
    'waiting for response',
  ],
});

// Start monitoring the agent's goal
await start_monitoring({
  goal: 'Complete user registration process on website',
});

2. エージェントのアクションの監視

// Monitor each action the agent takes
await process_trace_update({
  last_action: 'click_signup_button',
  current_context: 'homepage',
  goal: 'Complete user registration process on website',
});

// ... agent continues actions ...

// Agent gets stuck clicking submit repeatedly
await process_trace_update({
  last_action: 'click_submit_button',
  current_context: 'registration_form',
  goal: 'Complete user registration process on website',
});
// Returns: {
//   "intervention_required": true,
//   "loop_detected": {
//     "detected": true,
//     "type": "action_repetition",
//     "confidence": 0.85,
//     "details": {
//       "dominant_method": "parameter_repetition",
//       "anomaly_score": 0.57,
//       "actions_involved_count": 1,
//       "recent_actions_count": 10,
//       "metrics": {
//         "semantic_repetition": 0.6,
//         "parameter_repetition": 0.8
//       }
//     },
//     "actions_involved": ["click_submit_button"]
//   }
// }

3. 経験の保存と取得

// Store a successful experience
await store_experience({
  problem_description: 'Email validation error blocking form submission',
  solution: 'Check email format and retry with valid email address',
  outcome: true,
  context: 'registration_form',
  difficulty_level: 'medium',
});

// When a loop is detected, retrieve similar cases for recovery
const similarCases = await retrieve_similar_cases({
  problem_description: 'Form submission button not responding to clicks',
  max_results: 3,
  context_filter: 'registration_form',
  outcome_filter: true,
});

ループ検出について

process_trace_update ツールがループの可能性を検出すると、詳細な loop_detected オブジェクトを返します。このオブジェクトの各要素を理解すると、エージェントの動作の診断やデバッグに役立ちます。

details オブジェクトの主な指標について、簡単に説明します。

• dominant_method：ループ検出のきっかけとなった主要な手法（例：semantic_repetition、state_invariance）。
• anomaly_score：エージェントの直近のアクションがループの一部であるという確信度を示す全体スコア（0～1）です。複数の検出手法の加重平均です。
• actions_involved_count：検出されたループの一部であると特定された直近のアクション数です。
• recent_actions_count：分析対象となった直近のアクションの合計数です。
• metrics：各種検出手法の生スコアを含むオブジェクトです。例：
  • semantic_repetition：直近のアクションのうち、互いに意味的に類似しているものの割合です。
  • parameter_repetition：意味的に類似したアクション間における、パラメーターの類似度の割合です。
  • exact_repetition：直近のアクションのうち、文字単位で完全に重複しているものの割合です。
  • cyclical_pattern：アクションの反復シーケンスの有無を示すスコア（0～1）です。
  • oscillation_pattern：揺れ動く（行ったり来たりする）アクションの有無を示すスコア（0～1）です。
  • alternating_pattern：アクションパターンの交互反復の有無を示すスコア（0～1）です。

コントリビューション

コントリビューションを歓迎します。プルリクエストを送信する前に、コントリビューションガイドラインを読み、すべてのテストが通ることを確認してください。

ライセンス

このプロジェクトは MIT ライセンスのもとでライセンスされています。詳細については、LICENSE ファイルをご覧ください。