MCP Aurai Server

🚀 上级顧問 MCP (Aurai Advisor)

ローカルAIにリモートAIの指導を提供するMCPサーバーです。

バージョン: v2.2.0 (リファクタリングとファイルアップロードの修正) 状態: [OK] 本番環境での使用可 リリース日: 2026-01-24 最適化モデル: GLM-4.7 (智譜AI)

🚀 クイックスタート

1. インストール

# プロジェクトディレクトリに移動
cd mcp-aurai-server

# 仮想環境を作成
python -m venv venv
venv\Scripts\activate  # Windows
# source venv/bin/activate  # macOS/Linux

# 依存関係をインストール
pip install -e ".[all-dev]"

# インストールを検証
python .ai_temp/test_file_upload_fix.py
# 期待結果: ✅ すべてのテストが通過！

2. 設定

重要: --scope user を使用して、すべてのプロジェクトで利用可能にすることを確認してください。

claude mcp add --scope user --transport stdio aurai-advisor \
  --env AURAI_API_KEY="your-api-key" \
  --env AURAI_BASE_URL="https://api.example.com/v1" \
  --env AURAI_MODEL="gpt-4o" \
  -- "D:\mcp-aurai-server\venv\Scripts\python.exe" "-m" "mcp_aurai.server"

3. 使用方法

Claude Codeを再起動した後、会話でプログラミングの問題を直接記述します。

KeyErrorの問題に遭遇しました。エラーメッセージは 'api_key' not found です。
関連するコードは以下の通りです。
[コードを貼り付ける]

AIは自動的に consult_aurai ツールを呼び出すかどうかを判断します。

✨ 主な機能

• [OK] 多輪対話メカニズム - スマートな追及により、問題を段階的に解決します。
• [OK] スマートな対話管理 - 新しい問題を自動検出し、履歴をクリアして、クリーンなコンテキストを維持します。
• [OK] スマートなツールガイド - ツールの説明に関連するツール推奨事項が含まれています。
• [OK] ファイルアップロードのサポート ⭐ - sync_context を通じてファイルをアップロードでき、大きなファイルは自動的に分割して送信されます。
• [OK] GLM-4.7の最適化 - GLM-4.7モデルのパラメータをハードコードで最適化（200Kのコンテキスト）
• [OK] 対話履歴の永続化 - ユーザーディレクトリに自動保存されます。
• [OK] GUI設定ツール - 視覚的な設定を生成します。

📦 インストール

# プロジェクトディレクトリに移動
cd mcp-aurai-server

# 仮想環境を作成
python -m venv venv
venv\Scripts\activate  # Windows
# source venv/bin/activate  # macOS/Linux

# 依存関係をインストール
pip install -e ".[all-dev]"

# インストールを検証
python .ai_temp/test_file_upload_fix.py
# 期待結果: ✅ すべてのテストが通過！

💻 使用例

基本的な使用法

Claude Codeを再起動した後、会話でプログラミングの問題を直接記述します。

KeyErrorの問題に遭遇しました。エラーメッセージは 'api_key' not found です。
関連するコードは以下の通りです。
[コードを貼り付ける]

AIは自動的に consult_aurai ツールを呼び出すかどうかを判断します。

高度な使用法

# シナリオ 1: コードファイルをアップロードする（切断を避ける）
shutil.copy('main.py', 'main.txt')  # .txtに変換
sync_context(
    operation='incremental',
    files=['main.txt'],
    project_info={'language': 'Python'}
)

# シナリオ 2: レビュー用のドキュメントをアップロードする
sync_context(
    operation='full_sync',
    files=['README.md', 'docs/設計文書.md'],
    project_info={'task': 'code_review'}
)

📚 ドキュメント

🔧 技術詳細

v2.2.0 更新説明

⚠️ 重要：旧バージョンのユーザー移行ガイド

ケース 1: custom プロバイダー（OpenAI互換API）を使用しているユーザー ✅ 良いニュース：再インストールや再設定は必要ありません！

# バージョンをアップグレードするだけです
cd D:\mcp-aurai-server
git pull origin main
pip install -e ".[all-dev]"

# Claude Codeを再起動すると、自動的に有効になります

• ✅ 新しい環境変数（AURAI_CONTEXT_WINDOW、AURAI_MAX_MESSAGE_TOKENS、AURAI_MAX_TOKENS）はオプションです。
• ✅ デフォルト値はGLM-4.7に最適化されています（200Kのコンテキスト）。
• ✅ ファイルアップロードの修正は透過的で、自動的に有効になります。

ケース 2: zhipu、openai、anthropic、gemini プロバイダーを使用しているユーザー ❌ 移行が必要：v2.2.0ではこれらのプロバイダーが削除され、custom + OpenAI互換APIに切り替える必要があります。 移行手順（智譜AIを例に）：

# 1. 古い設定を削除
claude mcp remove aurai-advisor -s user

# 2. 再追加（customプロバイダーを使用）
claude mcp add --scope user --transport stdio aurai-advisor \
  --env AURAI_API_KEY="your-api-key" \
  --env AURAI_BASE_URL="https://open.bigmodel.cn/api/paas/v4/" \
  --env AURAI_MODEL="glm-4.7" \
  -- "D:\mcp-aurai-server\venv\Scripts\python.exe" "-m" "mcp_aurai.server"

# 3. Claude Codeを再起動

各サービスプロバイダーの移行設定：

ヒント：アップグレード後、python .ai_temp/test_file_upload_fix.py を実行して、ファイルアップロード機能が正常に動作することを確認することをお勧めします。

重大な変更

1. サービスプロバイダーのサポートを簡素化
   • ✅ custom プロバイダー（OpenAI互換API）のみを残します。
   • ❌ zhipu、openai、anthropic、geminiの直接サポートを削除します。
   • ✅ すべてのOpenAI API互換サービスを使用できます。
2. ファイルアップロード機能の修正 ⭐
   • ✅ sync_context のファイル内容が上位AIに送信されない問題を修正します。
   • ✅ 大きなファイルは自動的に分割して送信されます（max_message_tokens を超えた場合）。
   • ✅ 動的なToken推定により、設定に応じて自動的に調整されます。
3. GLM-4.7モデルの最適化 🎯
   • ✅ GLM-4.7モデルのパラメータをデフォルト値として設定します。
   • ✅ コンテキストウィンドウ：200,000 tokens（デフォルト）
   • ✅ 単一メッセージの上限：150,000 tokens（デフォルト）
   • ✅ 最大出力：32,000 tokens（デフォルト）
   • ✅ 環境変数を使用して上書きできます（他のモデルにも適用）

GLM-4.7 Token設定説明

このバージョンでは、GLM-4.7 モデルのパラメータをデフォルト値として使用し、環境変数を使用して上書きできます（他のモデルにも適用）。

Token割り当て戦略：

200K (総コンテキスト)
├── 32K (出力) - 上位AIの分析と提案
└── 168K (入力)
    ├── ~18K (システム + 履歴 + 問題)
    ├── 150K (最大単一ファイル)
    └── ~ - 安全マージン

容量参考：

• 単一ファイルのアップロード上限：~15 - 20万中文字
• 上位AIの出力上限：~2 - 3万中文字
• 対話履歴：約10 - 15回の完全な対話

注意：デフォルト値はGLM-4.7に最適化されています。他のモデルを使用する場合は、環境変数で調整できます。

MCPツール

consult_aurai（主要ツール）

上位AIにプログラミングの問題を解決するための指導を依頼します。 パラメータ：

• problem_type: 問題のタイプ（runtime_error/syntax_error/design_issue/other）
• error_message: エラーの説明
• code_snippet: コードスニペット（オプション）
• context: コンテキスト情報（オプション）
• is_new_question: 新しい問題かどうか（オプション、デフォルトはfalse）

戻り値：上位AIの分析と提案

🔗 関連ツール：

• sync_context：ドキュメントまたはコードファイルをアップロードします（.mdと.txtをサポート）
• report_progress：実行状況を報告し、次の手順の指導を取得します
• get_status：現在の対話状態、設定情報を確認します

対話履歴管理：

• 自動クリア：上位AIが resolved=true を返した場合、対話履歴が自動的にクリアされます。
• 手動クリア：is_new_question=true を設定すると、履歴を強制的にクリアします。
• 履歴制限：最大50件の履歴を保存します。

sync_context ⭐

コードのコンテキストを同期し、上位AIが読むためのファイルをアップロードします。 パラメータ：

• operation: 操作のタイプ（full_sync/incremental/clear）
• files: ファイルパスのリスト（.txtと.mdをサポート）
• project_info: プロジェクト情報の辞書（オプション）

機能特性：

• 📄 Markdownとテキストファイルのアップロードをサポートします。
• 🔄 大きなファイルは自動的に分割して送信されます（Token制限を超えないように）。
• 📏 スマートなToken推定（中文1.5文字/token、英文4文字/token）

report_progress

実行状況を報告します。 パラメータ：

• actions_taken: 実行されたアクション
• result: 実行結果（success/failed/partial）

get_status

現在の状態を取得します。 戻り値：

• 対話履歴の件数
• モデル設定
• Token制限設定

環境変数

必須

オプション

Token設定説明

デフォルト値（GLM-4.7に基づく）：

• context_window: 200,000 tokens
• max_message_tokens: 150,000 tokens
• max_tokens: 32,000 tokens

他のモデルの参考値：

• Claude 3.5 Sonnet: 200,000 / 140,000 / 64,000
• GPT-4o: 128,000 / 100,000 / 32,000
• DeepSeek: 64,000 / 50,000 / 16,000

設定例

# 智譜AI GLM-4.7を使用する（推奨、デフォルト値を使用）
AURAI_API_KEY=your-api-key
AURAI_BASE_URL=https://open.bigmodel.cn/api/paas/v4/
AURAI_MODEL=glm-4.7
# Token設定はデフォルト値を使用するため、設定する必要はありません。

# Claude 3.5 Sonnetを使用する（Token設定を調整）
AURAI_API_KEY=your-api-key
AURAI_BASE_URL=https://api.anthropic.com
AURAI_MODEL=claude-3-5-sonnet-20241022
AURAI_CONTEXT_WINDOW=200000
AURAI_MAX_MESSAGE_TOKENS=140000
AURAI_MAX_TOKENS=64000

# DeepSeekを使用する（Token設定を調整）
AURAI_API_KEY=your-api-key
AURAI_BASE_URL=https://api.deepseek.com/v1
AURAI_MODEL=deepseek-chat
AURAI_CONTEXT_WINDOW=64000
AURAI_MAX_MESSAGE_TOKENS=50000
AURAI_MAX_TOKENS=16000

# 他の互換APIを使用する
AURAI_API_KEY=your-key
AURAI_BASE_URL=https://your-api.com/v1
AURAI_MODEL=your-model
# モデルの仕様に応じてToken設定を調整してください。

プロジェクト構造

mcp-aurai-server/
├── src/mcp_aurai/          # MCPサーバーのソースコード
│   ├── server.py           # メインサーバー（4つのツール）
│   ├── config.py           # 設定管理
│   ├── llm.py              # OpenAI互換クライアント
│   ├── prompts.py          # プロンプトテンプレート
│   └── utils.py            # ユーティリティ関数
│
├── tools/
│   └── control_center.py   # GUI設定ツール
│
├── tests/                  # テストケース
│   ├── test_server.py
│   ├── test_llm.py
│   └── test_config.py
│
├── docs/                   # ドキュメント
│   ├── ユーザーマニュアル.md
│   ├── CLAUDE_CODE_INSTALL.md
│   └── 開発ドキュメント.md
│
├── README.md               # このファイル
├── pyproject.toml          # プロジェクト設定
└── .env.example            # 環境変数の例

トラブルシューティング

毎回Claude Codeを開くたびに再インストールする必要がありますか？

原因：ローカルスコープ（local）を使用しているため、特定のディレクトリでのみ使用できます。 解決策：--scope user を使用して再インストールします。

claude mcp remove aurai-advisor -s local
claude mcp add --scope user ...

MCPツールが表示されない場合

claude mcp list                          # 設定を確認
claude mcp remove aurai-advisor -s local # 古い設定を削除
claude mcp add --scope user ...          # 再追加

ModuleNotFoundError

cd D:\mcp-aurai-server
python -m venv venv                      # 仮想環境を作成
venv\Scripts\activate
pip install -e ".[all-dev]"              # プロジェクトをインストール

401 Unauthorized

• APIキーが正しいか確認してください。
• プロバイダーのプラットフォームでキーを再生成してください。

404 Model not found

• モデル名のスペルを確認してください。
• プロバイダーのAPIを使用して、利用可能なモデルを確認してください。

ファイル内容が上位AIに送信されない場合

• sync_context の呼び出しが成功していることを確認してください。
• ログに "ファイルがX個の断片に分割されました" というメッセージが表示されていることを確認してください。
• AURAI_MAX_MESSAGE_TOKENS の設定を確認してください。

テスト

# ファイルアップロード機能のテストを実行
python .ai_temp/test_file_upload_fix.py

# すべてのテストを実行
pytest tests/ -v

# 特定のテストを実行
pytest tests/test_server.py -v
pytest tests/test_llm.py -v
pytest tests/test_config.py -v

# テストのカバレッジを確認
pytest tests/ --cov=src/mcp_aurai --cov-report=html

ヘルプの取得

• ユーザーマニュアル: docs/ユーザーマニュアル.md
• インストールガイド: docs/CLAUDE_CODE_INSTALL.md
• 開発ドキュメント: docs/開発ドキュメント.md

📄 ライセンス

MCP Aurai Serverは二重ライセンス契約です。

プロジェクト名: mcp-aurai-server バージョン: v2.2.0 状態: [OK] 本番環境での使用可 リリース日: 2026-01-24