Analytical MCP Server

分析 MCP サーバー

Claude 向けに12個の分析ツールを提供する Model Context Protocol サーバーです。記述統計、回帰（線形／多項式／ロジスティック／多変量）、仮説検定、データの前処理、データ可視化の仕様、複数基準意思決定分析、ML モデルの評価、論理的な議論や誤謬の分析、Exa を活用した調査検証に対応しています。stdio 経由で動作します。分析コアに API キーは不要です（調査機能には EXA_API_KEY が必要です）。

セットアップ

前提条件

• Node.js >= 20.0.0
• EXA_API_KEY 環境変数（verify_research と perspective_shifter の実行に必須です。どちらも呼び出しごとに Exa 検索 API を呼び出します）

インストール

オプション 1：直接インストール

npm install
npm run build

オプション 2：Docker

イメージをビルドします。このサーバーは stdio 経由で MCP プロトコルを使用します。デタッチされたデーモンとして実行するのではなく、MCP クライアントが起動し、標準入力／標準出力をパイプで接続します。Claude Desktop による起動方法については、設定の Docker の項を参照してください。

docker build -t analytical-mcp .

# Smoke-test the image interactively (Ctrl-C to exit):
docker run --rm -i -e EXA_API_KEY=your_api_key_here analytical-mcp

設定

直接インストールの設定

1. .env.example を .env にコピーします
2. EXA_API_KEY を .env に追加します
3. Claude Desktop の設定に追加します

{
  "mcpServers": {
    "analytical": {
      "command": "node",
      "args": ["/path/to/analytical-mcp/build/index.js"],
      "env": {
        "EXA_API_KEY": "your-exa-api-key-here"
      }
    }
  }
}

Docker の設定

1. .env.example を .env にコピーします
2. EXA_API_KEY を .env に追加します
3. Claude Desktop の設定に追加します

{
  "mcpServers": {
    "analytical": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", ".env",
        "-v", "$(pwd)/cache:/app/cache",
        "analytical-mcp"
      ]
    }
  }
}

利用可能なツール

サーバーは起動時に12個のツールを無条件で登録します（登録は EXA_API_KEY の有無に依存しません。以下の調査機能を備えた2つのツールは、キーがない場合、呼び出し時にエラーになります）。正式な一覧は src/tools/index.ts を参照してください。

統計分析

• analyze_dataset — 数値データセットまたはレコード配列データセットの記述統計（要約／統計）。
• advanced_statistical_analysis — 表形式データ（オブジェクトの配列）の記述統計と、変数間のピアソン相関を提供します。単一の数値系列には analyze_dataset を使用してください。
• advanced_regression_analysis — 専用のプロバイダーモジュールを用いた、線形、多項式、ロジスティック、多変量回帰です。実際の OLS／ロジスティック計算に基づいており、モックではありません。
• hypothesis_testing — 正確な p 値計算を用いた実際の統計的仮説検定です。ウェルチの独立 t 検定、対応のある t 検定、相関、カイ二乗検定、ANOVA に対応しています（src/utils/statistics.ts を参照）。
• advanced_data_preprocessing — 数値データの正規化、標準化、欠損値処理、IQR 外れ値検出です。
• data_visualization_generator — 散布図、折れ線グラフ、棒グラフ、ヒストグラム、箱ひげ図、ヒートマップ、円グラフ、バイオリンプロット、相関図の仕様を生成します。

機械学習

• ml_model_evaluation — モデルの予測を評価します。分類指標（正解率、適合率、再現率、F1）または回帰指標（MSE、MAE、RMSE、R²）に対応しています。

意思決定分析

• decision_analysis — 複数基準による重み付き意思決定ランキングです。options と criteria に加え、scores 行列が必須です（options.length 行 × criteria.length 列で、各値は 0～10）。weights は任意で、省略すると均等な重み付けが適用されます。options／criteria／weights のみを説明していた古いドキュメントからの仕様変更です。

論理的推論

• logical_argument_analyzer — 専用のプロバイダークラスを用いて、議論の構造、誤謬、妥当性、強さを分析します。
• logical_fallacy_detector — テキスト中の論理的誤謬を検出し、信頼度スコアとともに説明します。
• perspective_shifter — 問題に対する別の視点（ステークホルダー、専門分野、反対意見、楽観的、悲観的）を生成します。EXA_API_KEY が必要です。各視点の根拠を得るため、視点の領域ごとに Exa 検索を実行します。

リサーチの検証

• verify_research — 複数の情報源を使ってリサーチの主張を相互検証します。EXA_API_KEY が必要です。confidence.score（実際に計算された一貫性／信頼度の値、0～1）とconfidence.verified（confidence.scoreがminConsistencyThresholdを満たしたかどうかを示すブール値）を返します。しきい値は合否を判定する基準であり、報告されるスコアに適用される下限値ではありません。

可観測性とメトリクス

Analytical MCP Server には、キャッシュのパフォーマンスとシステムの健全性を監視するための Prometheus スタイルのメトリクス HTTP サーバー（src/utils/metrics_server.ts）が組み込まれています。

メトリクスエンドポイント

有効にすると、サーバーは設定可能なポート 9090 で、HTTP 経由でメトリクスを公開します。

• http://localhost:9090/metrics — Prometheus スタイルのメトリクス
• http://localhost:9090/metrics?format=json — JSON 形式のメトリクス
• http://localhost:9090/health — ヘルスチェックエンドポイント
• http://localhost:9090/ — メトリクスサーバーのステータスページ

利用可能なメトリクス

キャッシュメトリクス

• analytical_mcp_cache_hits_total — 名前空間別のキャッシュヒット数
• analytical_mcp_cache_misses_total — 名前空間別のキャッシュミス数
• analytical_mcp_cache_puts_total — 名前空間別のキャッシュ登録数
• analytical_mcp_cache_evictions_total — 名前空間別のキャッシュ削除数
• analytical_mcp_cache_size — 名前空間別の現在のキャッシュサイズ

システムメトリクス

• analytical_mcp_uptime_seconds — サーバーの稼働時間（秒）
• analytical_mcp_memory_usage_bytes — メモリ使用量（RSS、ヒープ、外部メモリ）
• analytical_mcp_cpu_usage_microseconds — CPU 時間の使用量（ユーザー、システム）

設定

環境変数を設定してメトリクスを有効にします。

METRICS_ENABLED=true        # Enable metrics server (default: false; unauthenticated, opt-in)
METRICS_PORT=9090          # Metrics server port (default: 9090)
METRICS_HOST=127.0.0.1     # Metrics server host (default: 127.0.0.1, use 0.0.0.0 to bind to all interfaces)

使用例

# Get Prometheus metrics
curl http://localhost:9090/metrics

# Get JSON metrics
curl http://localhost:9090/metrics?format=json

# Health check
curl http://localhost:9090/health

監査ログ

すべてのツール呼び出しについて、LOG_LEVELに関係なく、構造化された監査レコードが1件stderrに出力されます（MCP プロトコルのチャネルである stdout には出力されません）。

[2026-07-05T22:56:12.629Z] AUDIT: {"event":"tool_call","tool":"verify_research","ok":true,"durationMs":1352,"argBytes":120,"argHash":"31b769fe1f66","exaCalls":2}

各レコードには、ツール名、結果、所要時間、引数のバイトサイズと SHA-256 フィンガープリント（引数の実際の値は記録されないため、内容が漏洩することはありません）、および呼び出しが発行した外部向け Exa リクエストの数であるexaCallsが含まれます。これにより、機密情報を記録することなく、運用担当者はフォレンジック調査に役立つ記録（過大な入力や繰り返される入力、予期しない外部への呼び出しの増加など）を確認できます。監査ログは単一のフラグで制御され、既定で有効になっています。また、LOG_LEVELとは独立しています。

ENABLE_AUDIT_LOG=true   # per-call audit records to stderr (default: true)

使用例

データセット分析

{
  "data": [23, 45, 67, 12, 89, 34, 56, 78],
  "analysisType": "stats"
}

意思決定分析

{
  "options": ["Option A", "Option B", "Option C"],
  "criteria": ["Cost", "Quality", "Speed"],
  "scores": [
    [7, 6, 8],
    [5, 9, 6],
    [9, 4, 7]
  ],
  "weights": [0.4, 0.4, 0.2]
}

仮説検定

{
  "testType": "t_test_independent",
  "data": [[23, 45, 67, 12, 89], [34, 56, 78, 90, 21]],
  "alpha": 0.05
}

論理分析

{
  "argument": "All birds can fly. Penguins are birds. Therefore, penguins can fly.",
  "analysisType": "comprehensive"
}

開発

テスト

# Run the offline unit suite (no API key needed) — same as test:unit
npm test

# Unit tests only (offline, no API key needed)
npm run test:unit

# Integration tests (non-blocking heads-up without EXA_API_KEY; live-Exa cases self-skip)
npm run test:integration

# Integration tests excluding the live-API suite
npm run test:integration:no-api

# Or via the thin wrapper script
./tools/test-runner.sh unit
./tools/test-runner.sh integration
./tools/test-runner.sh integration:no-api

スクリプト

• npm run build — TypeScript を JavaScript にビルドします
• npm run watch — 変更を監視して再ビルドします
• npm run typecheck — src/ の型をチェックします（テストファイルを除く）
• npm run typecheck:src — src/ と統合テストの型をチェックします
• npm run lint / npm run lint:fix — ESLint
• npm run format / npm run format:check — Prettier
• npm test / npm run test:unit / npm run test:integration — Jest（テストを参照）
• npm run smoke — ビルド後、実サーバーを起動し、stdio の JSON-RPC 経由で initialize/tools-list/tools-call を実行します
• npm run cache:stats / cache:clear / cache:preload — ディスク上のリサーチキャッシュを管理します
• npm run inspector — デバッグ用に MCP inspector を起動します

プロジェクト構成

analytical-mcp/
├── src/
│   ├── tools/           # MCP tool implementations (12 registered tools + supporting providers)
│   ├── utils/           # Utility functions, regression/NLP providers, caching, resilience, metrics
│   ├── integration/     # Integration tests (live-Exa cases self-skip without EXA_API_KEY)
│   ├── __tests__/       # Server-level protocol test (InMemoryTransport)
│   └── index.ts         # Main server entry point
├── docs/                # Documentation
├── tools/               # Development and testing scripts
├── scripts/             # Build/smoke-test scripts
└── examples/            # Usage examples

アーキテクチャに関する補足

• プロバイダーアーキテクチャ：複雑なツール（回帰、NLP、可視化、議論分析）は、src/utils/ と src/tools/ の単一責任のプロバイダーモジュール（例：linear_regression_provider.ts、logistic_regression_provider.ts、polynomial_regression_provider.ts、multivariate_regression_provider.ts、regression_metrics_provider.ts）に分割されています。ツールファイルは処理を調整して結果を整形し、プロバイダーがロジックを担います。
• 堅牢性：src/utils/rate_limit_manager.ts は Exa のレート制限（キーのローテーション、エンドポイントごとのスロットリング）を処理し、src/utils/api_helpers.ts は明示的な shouldRetry 述語による再試行を提供します。
• キャッシュ：src/utils/cache_manager.ts、src/utils/enhanced_cache.ts、src/utils/research_cache.ts は、階層化された名前空間対応のキャッシュを提供します（ENABLE_RESEARCH_CACHE=true で有効化）。
• 統計：src/utils/statistics.ts は、正確な p 値の計算に向けて、対数ガンマ関数、不完全ベータ関数／ガンマ関数、t／F／カイ二乗分布の CDF を基本原理から実装しています。統計的な近似やモック結果は使用しません。

ツールのカテゴリ

統計分析

• 記述統計：平均、中央値、標準偏差、四分位数
• 回帰分析：線形、多項式、ロジスティック、多変量
• 仮説検定：Welch の t 検定、対応のある t 検定、相関、カイ二乗検定、ANOVA

意思決定支援

• 明示的な選択肢 × 基準のスコア行列に基づく、多基準の重み付き意思決定ランキング

論理的推論

• 議論の構造、妥当性、強さの分析
• 確信度スコアによる誤謬の検出
• 多様な視点の生成

リサーチ統合

• Exa を介した複数ソースの検証
• 事実の抽出
• 矛盾／整合性の確認
• 確信度スコア

セキュリティとプライバシー

• 分析処理はすべてローカルで行われます
• リサーチ機能では Exa API を使用します（任意。EXA_API_KEY が必要です）
• 任意のローカルディスクキャッシュを除き、データを永続的に保存しません
• API キーは環境変数で管理します

ライセンス

MIT License。詳細は LICENSE file を参照してください。

コントリビューション

コントリビューションのワークフローと規約についてはCONTRIBUTING.mdを、開発に関する詳細なリファレンスについてはdocs/DEVELOPMENT.mdを参照してください。すべての参加者は行動規範に従う必要があります。

要約すると、main からブランチを作成し、npm run typecheck、npm run lint、npm test、npm run smoke がすべて成功することを確認し、新しい動作にはテストを追加して、テンプレートを使用して PR を作成してください。

セキュリティの脆弱性を報告する場合は、SECURITY.mdに従ってください。公開 issue は作成しないでください。

トラブルシューティング

よくある問題

JSON の解析エラー：すべてのログは stdout ではなく stderr に出力する必要があります。MCP プロトコルでは通信に stdout を使用します。console.log ではなく、Logger クラスを使用してください。

ツールが表示されない：Claude Desktop の設定でサーバー構成を確認し、Claude Desktop アプリケーションを再起動してください。

リサーチ機能が呼び出し時に失敗する：環境変数または .env ファイルに EXA_API_KEY を設定してください。verify_research と perspective_shifter は、設定の有無にかかわらず 12 個すべてのツールが登録されますが、どちらもこのキーが必要です。

サーバーが起動しない：Node.js のバージョンが 20 以上であること、および npm install ですべての依存関係がインストールされていることを確認してください。

詳細なトラブルシューティングについては、docs/TROUBLESHOOTING.mdを参照してください。

デバッグモード

MCP inspector を使用してサーバーを起動します：

npm run inspector

リンク

• Model Context Protocol のドキュメント
• Exa API のドキュメント
• Claude Desktop