Aurai Advisor (MCP)

An MCP service that allows local AI to consult remote large models when encountering complex programming problems.

This repository corresponds to the "long-term stable" version, which has implemented these key capabilities:

• Multi-turn consultation and progress reporting

• sync_context file synchronization

• Automated conversion of code/config files to text for upload

• Session isolation (session_id)

• History persistence, file locking, and atomic writes

• Automated history summarization

• Context window trimming

What's New

This main update focuses on the following improvements:

• Fixed the issue where history would "resurrect" after being cleared and restarted

• Added session_id for session isolation to prevent context leakage between different problems

• Enabled real configuration support for AURAI_TEMPERATURE, AURAI_MAX_ITERATIONS, AURAI_LOG_LEVEL, etc.

• Ensured project_info and follow-up answers are properly sent to the senior advisor

• Added history file locking and atomic writes to reduce the risk of concurrent writes corrupting history files

• Added automated history summarization to prevent long sessions from becoming bloated

• Added context window trimming; AURAI_CONTEXT_WINDOW is now fully effective

• sync_context now supports automatic conversion of code/config text files, no longer requiring manual conversion to .txt

• Rewrote README, installation guides, and user manuals, with installation steps now placed more prominently

If you are new to this repository, the two most important things are:

1. Read the "Installation Instructions" below first

2. Code files can now be passed directly to sync_context

Related MCP server: session-coord-mcp

Use Cases

This MCP is suitable for use within Claude Code or other MCP clients that support stdio.

Typical scenarios:

• The local AI has already tried to solve the problem but failed

• You need to provide errors, code, documentation, and configurations to a "senior advisor"

• You want to turn complex troubleshooting into a multi-turn process of "Ask -> Execute -> Report -> Next Step"

Feature Overview

• consult_aurai The primary consultation tool. Submit problems, code snippets, context, and attempted solutions to get analysis and next-step suggestions from the senior advisor.

• sync_context Synchronize code and documentation context. It now supports not only .txt/.md but also automatically converts text files like .py/.js/.ts/.json/.yaml/.toml/.ini into a format suitable for transmission.

• report_progress Report execution results to the senior advisor to continue the next iteration.

• get_status View current session status, history count, and model/history file paths.

Installation Instructions

For more detailed installation steps, see:

• Claude Code Installation Guide

• User Manual

Here is the most common installation process:

1. Prepare Environment

# 需要 Python 3.10+
python --version

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

2. Create Virtual Environment and Install Dependencies

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

3. Register MCP in Claude Code

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"

Notes:

• AURAI_BASE_URL must be an OpenAI-compatible API address

• The current version only supports the custom method; the old AURAI_PROVIDER is no longer used

• --scope user means it will be available in all projects, which is the most convenient

4. Verify Installation

claude mcp list
pytest

Expected:

• claude mcp list shows aurai-advisor

• pytest passes

Quick Start

Scenario 1: Direct Consultation

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 ...",
    }
)

Scenario 2: Upload Code Files First, Then Consult

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="请结合已同步文件帮我排查启动失败"
)

Note:

• No need to manually copy main.py to main.txt anymore

• Text-based code files will be automatically converted to text for sending

• Binary files will be skipped

Scenario 3: Parallel Problems with Session Isolation

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"
)

This prevents different problems from interfering with each other.

sync_context File Upload Rules

Files Sent Directly

• .md, .markdown, .mdx

• .txt

• Various code and configuration text files, e.g.:

  • .py .js .ts .tsx

  • .json .yaml .yml .toml

  • .ini .cfg .env

  • .java .go .rs .cpp .cs

Files Automatically Converted

• Files that are not .txt/.md but contain text content

• An automatic .txt or .md filename will be generated for transmission

• The content will be prefixed with the "original file path" and the "automatically converted filename"

Files Skipped

• Images

• Archives

• Audio/Video

• Executables

• Obvious binary content

If a batch of files contains both code and images:

• Code is uploaded as usual

• Images are recorded as skipped_files

• The overall synchronization is still considered successful

Environment Variables

Required

Common Optional

Key Behaviors in Current Version

1. Session Isolation

• Each session_id has its own history

• Uses default if not specified

• Different sessions are saved to different history files to avoid cross-talk

2. History Summarization

• Older history is automatically compressed into a "history summary"

• Recent rounds and the latest sync_context are kept in their original form as much as possible

• This reduces context usage, freeing up space for the current problem

3. Context Window Trimming

• System prompts are prioritized

• The latest sync_context is prioritized

• Recent history rounds are kept as much as possible

• Output length is automatically reduced when necessary to prevent exceeding the total window size

4. Robust History Files

• Uses lock files when saving history to prevent concurrent write corruption

• Writes to a temporary file before replacing the original to avoid partial JSON files

Testing

pytest

Key areas covered by the current main branch include:

• History clearing and persistence

• Session isolation

• Automatic text conversion and upload

• History locking and atomic writes

• History summarization

• Context window trimming

Documentation

• Claude Code Installation Guide

• User Manual

• Development Documentation

FAQ

Why didn't the senior advisor receive the code file I uploaded?

Older versions required manual conversion to .txt. The current version supports automatic conversion of text files.

If it is still not received, check:

• If the file path exists

• If the file is binary

• The uploaded_files / skipped_files in the sync_context response

Why do different problems affect each other?

If you want complete isolation, pass a different session_id for different problems.

Why does the history file look shorter?

This is the history summarization at work. Old history is compressed into a summary; it is not lost, but replaced with "meeting minutes" that consume less context.