上級アドバイザー MCP（Aurai Advisor）

ローカルAIが複雑なプログラミング問題に直面した際、リモートの大規模言語モデルに相談を継続するためのMCPサービス。

現在のリポジトリは「長期利用可能」なバージョンに対応しており、以下の重要な機能が実装されています：

• マルチターン相談と進捗報告

• sync_context ファイル同期

• コード/設定ファイルの自動テキスト変換・アップロード

• セッション分離（session_id）

• 履歴の永続化、ファイルロック、アトミック書き込み

• 履歴の自動要約

• コンテキストウィンドウのトリミング

今回の更新内容

今回のメインライン更新では、主に以下の点を強化しました：

• 履歴をクリアした後に再起動すると「復活」してしまう問題を修正

• session_id によるセッション分離を追加し、異なる問題間でコンテキストが混ざるのを防止

• AURAI_TEMPERATURE、AURAI_MAX_ITERATIONS、AURAI_LOG_LEVEL などの設定を実際に反映

• project_info や補足回答などのコンテキストを上級アドバイザーに確実に送信

• 履歴ファイルのロックとアトミック書き込みを追加し、同時書き込みによる履歴破損のリスクを低減

• 履歴の自動要約を追加し、長時間のセッションでも肥大化を防止

• コンテキストウィンドウのトリミングを追加し、AURAI_CONTEXT_WINDOW が実際に機能するように変更

• sync_context がコードや設定などのテキストファイルを自動的に送信可能なテキストに変換する機能をサポート（手動で .txt にコピーする必要は不要）

• README、インストールガイド、ユーザーマニュアルを書き直し、インストール手順をより目立つ位置に配置

初めてこのリポジトリに触れる方は、以下の2点が最も重要です：

1. 下記の「インストール手順」を確認する

2. コードファイルは直接 sync_context に渡すことができる

用途

このMCPは、Claude Codeやstdio方式をサポートする他のMCPクライアントでの使用に適しています。

典型的なシナリオ：

• ローカルAIが試行錯誤したが、問題が解決しない場合

• エラーログ、コード、ドキュメント、設定をまとめて「上級アドバイザー」に渡したい場合

• 複雑な調査を「質問 -> 実行 -> 報告 -> 次のステップ」というマルチターンのプロセスにしたい場合

機能概要

• consult_aurai 主要な相談ツール。問題、コードスニペット、コンテキスト、試行済みの解決策を提出し、上級アドバイザーの分析と次のステップの提案を取得します。

• sync_context コードとドキュメントのコンテキストを同期します。 .txt/.md だけでなく、.py/.js/.ts/.json/.yaml/.toml/.ini などのテキストファイルを自動的に送信可能なテキスト形式に変換します。

• report_progress 実行結果を上級アドバイザーに報告し、次のイテレーションに進みます。

• get_status 現在のセッション状態、履歴数、モデルおよび履歴ファイルのパスを確認します。

インストール手順

詳細なインストール手順は以下を参照してください：

• Claude Code インストールガイド

• ユーザーマニュアル

ここでは、最も一般的なインストールフローを記載します。

1. 環境準備

# 需要 Python 3.10+
python --version

# 进入仓库目录
cd G:\codex\mcp-aurai-server

2. 仮想環境の作成と依存関係のインストール

python -m venv venv
venv\Scripts\activate
pip install -e ".[all-dev]"

3. Claude Code への MCP 登録

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" ^
  -- "G:\codex\mcp-aurai-server\venv\Scripts\python.exe" "-m" "mcp_aurai.server"

説明：

• AURAI_BASE_URL はOpenAI互換のAPIアドレスである必要があります

• 現在のバージョンでは custom 方式のみを保持し、古い AURAI_PROVIDER は使用しません

• --scope user はすべてのプロジェクトで使用可能にすることを意味し、最も手間がかかりません

4. インストールの検証

claude mcp list
pytest

期待される結果：

• claude mcp list で aurai-advisor が表示される

• pytest が通過する

クイックスタート

シナリオ 1：直接質問する

consult_aurai(
    problem_type="runtime_error",
    error_message="启动时报 KeyError: api_key",
    code_snippet="config = load_config()\napi_key = config['api_key']",
    context={
        "file_path": "src/config.py",
        "terminal_output": "Traceback ...",
    }
)

シナリオ 2：先にコードファイルをアップロードしてから質問する

sync_context(
    operation="incremental",
    files=["src/main.py", "config/settings.json", "README.md"],
    project_info={
        "project_name": "My Project",
        "tech_stack": "Python + FastAPI"
    }
)

consult_aurai(
    problem_type="runtime_error",
    error_message="请结合已同步文件帮我排查启动失败"
)

注意：

• main.py を手動で main.txt にコピーする必要はありません

• テキストコードファイルは自動的にテキストとして送信されます

• バイナリファイルはスキップされます

シナリオ 3：複数の問題を並行して扱う（セッション分離）

consult_aurai(
    problem_type="runtime_error",
    error_message="问题 A",
    session_id="issue-a"
)

consult_aurai(
    problem_type="design_issue",
    error_message="问题 B",
    session_id="issue-b"
)

これにより、異なる問題間でコンテキストが混ざるのを防げます。

sync_context ファイルアップロードルール

直接送信されるもの

• .md、.markdown、.mdx

• .txt

• 各種コードおよび設定テキストファイル（例：

  • .py .js .ts .tsx

  • .json .yaml .yml .toml

  • .ini .cfg .env

  • .java .go .rs .cpp .cs

自動変換されるもの

• .txt/.md ではないが、内容がテキストであるファイル

• 自動的に .txt または .md の送信名が生成されます

• 内容の前に「元のファイルパス」と「自動変換後の送信名」が付記されます

スキップされるもの

• 画像

• 圧縮ファイル

• 音声・動画

• 実行ファイル

• 明らかなバイナリコンテンツ

ファイル群の中にコードと画像が混在している場合：

• コードは通常通りアップロードされます

• 画像は skipped_files として記録されます

• 同期プロセス全体は成功します

環境変数

必須

一般的なオプション

現在のバージョンの重要な挙動

1. セッション分離

• 各 session_id は独自の履歴を持ちます

• 指定がない場合は default が使用されます

• 異なるセッションは異なる履歴ファイルに保存され、混ざるのを防ぎます

2. 履歴要約

• 古い履歴は自動的に「履歴要約」として圧縮されます

• 直近の数ラウンドと最新の sync_context は可能な限りそのまま保持されます

• これによりコンテキスト消費を抑え、現在の問題のためのスペースを確保します

3. コンテキストウィンドウのトリミング

• システムプロンプトを優先的に保持します

• 最新の sync_context を優先的に保持します

• 次に、直近の履歴ラウンドを可能な限り保持します

• 必要に応じて今回の出力長を自動的に縮小し、合計ウィンドウサイズを超えないようにします

4. 履歴ファイルの安定性

• 履歴保存時にロックファイルを使用して同時書き込みによる破損を防ぎます

• 一時ファイルに書き込んでから置換する方式を採用し、JSONが途中で切れるのを防ぎます

テスト

pytest

現在のメインラインでカバーしている重点項目：

• 履歴のクリアと永続化

• セッション分離

• 自動テキスト変換アップロード

• 履歴ロックとアトミック書き込み

• 履歴要約

• コンテキストウィンドウのトリミング

ドキュメント

• Claude Code インストールガイド

• ユーザーマニュアル

• 開発ドキュメント

よくある質問

なぜ上級アドバイザーがアップロードしたコードファイルを受け取れないのですか？

旧バージョンでは手動で .txt に変換する必要がありましたが、現在のバージョンではテキストファイルの自動変換をサポートしています。

それでも受け取れない場合は、以下を確認してください：

• ファイルパスが存在するか

• ファイルがバイナリではないか

• sync_context の戻り値にある uploaded_files / skipped_files

なぜ異なる問題が互いに影響するのですか？

完全に分離したい場合は、異なる問題に対して異なる session_id を渡してください。

なぜ履歴ファイルが短くなったように見えるのですか？

これは履歴要約機能が働いているためです。古い履歴は要約として圧縮されており、失われたわけではなく、コンテキストを節約する「会議議事録」に置き換わっています。