Skip to main content
Glama
Aurai Advisor (上级顾问 MCP)

Aurai Advisor (上级顾问 MCP)

by LZMW

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:

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

Variable

Description

AURAI_API_KEY

API Key

AURAI_BASE_URL

OpenAI-compatible API address

AURAI_MODEL

Model name

Common Optional

Variable

Description

Default Value

AURAI_TEMPERATURE

Temperature

0.7

AURAI_MAX_ITERATIONS

Max iteration rounds

10

AURAI_MAX_HISTORY

Max history entries per session

50

AURAI_CONTEXT_WINDOW

Total context window size

200000

AURAI_MAX_MESSAGE_TOKENS

Max tokens for a single large file message

150000

AURAI_MAX_TOKENS

Max output length

32000

AURAI_LOG_LEVEL

Log level

INFO

AURAI_ENABLE_PERSISTENCE

Whether to persist history

true

AURAI_HISTORY_PATH

Default session history file path

~/.mcp-aurai/history.json

AURAI_HISTORY_LOCK_TIMEOUT

History file lock timeout (seconds)

10

AURAI_ENABLE_HISTORY_SUMMARY

Whether to enable history summary

true

AURAI_HISTORY_SUMMARY_KEEP_RECENT

Recent original rounds kept after summary

3

AURAI_HISTORY_SUMMARY_TRIGGER

Threshold of original records to trigger summary

8


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


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.

Available Tools

4 tools
consult_auraiA

请求上级AI的指导(支持交互对齐机制与多轮对话)

这是核心工具,当本地AI遇到编程问题时调用此工具获取上级AI的指导建议。


🔗 相关工具

  • sync_context:需要上传文档或代码时使用

    • 📄 上传文章、说明文档(.md/.txt)

    • 💻 上传代码文件(避免内容被截断) ⭐ 重要

    • 将 .py/.js/.json 等代码文件复制为 .txt 后上传

  • report_progress:执行上级 AI 建议后,使用此工具报告进度并获取下一步指导

  • get_status:查看当前对话状态、迭代次数、配置信息

💡 重要提示:避免内容被截断

如果 code_snippet 或 context 内容过长,请使用 sync_context 上传文件:

# 步骤 1:将代码文件复制为 .txt
shutil.copy('script.py', 'script.txt')

# 步骤 2:上传文件
sync_context(operation='incremental', files=['script.txt'])

# 步骤 3:告诉上级顾问文件已上传
consult_aurai(
    error_message='请审查已上传的 script.txt 文件'
)

优势:

  • ✅ 避免代码在 context 或 answers_to_questions 字段中被截断

  • ✅ 利用文件读取机制,完整传递内容

  • ✅ 支持任意大小的代码文件


[重要] 何时开始新对话?

系统会自动检测,但你也可以手动控制:

  • 自动清空:当上一次对话返回 resolved=true 时,系统会自动清空历史

  • 手动清空:如果你要讨论一个完全不同的新问题,设置 is_new_question=true

何时设置 is_new_question=true?

  • [OK] 切换到完全不相关的项目/文件

  • [OK] 之前的问题已解决,现在遇到全新的问题

  • [OK] 发现上下文混乱,想重新开始

  • 不要在同一个问题的多轮对话中使用

交互协议

1. 多轮对齐机制

  • 不要期待一次成功:上级顾问可能会认为信息不足,返回反问问题

  • 仔细阅读 questions_to_answer 中的每个问题

  • 主动搜集信息(读取文件、检查日志、运行命令)

  • 再次调用 此工具,将答案填入 answers_to_questions 参数

2. 首次调用

必须提供:

  • problem_type:问题类型(runtime_error/syntax_error/design_issue/other)

  • error_message:清晰描述问题或错误

  • context:相关上下文(代码片段、环境信息、已尝试的方案)

  • code_snippet:相关代码(如果有)

3. 后续调用(当返回 status="need_info" 时)

必须提供:

  • answers_to_questions:对上级顾问反问的详细回答

  • 保持其他参数不变(除非有新信息)

4. 诚实原则

  • 禁止瞎编:如果不知道答案,诚实说明"未找到相关信息"

  • 禁止臆测:不要在没有证据的情况下假设解决方案

  • 提供具体证据(文件路径、日志内容、错误堆栈)

响应格式

信息不足时 (status="need_info")

{
  "status": "need_info",
  "questions_to_answer": ["问题1", "问题2"],
  "instruction": "请搜集信息并再次调用"
}

提供指导时 (status="success")

{
  "status": "success",
  "analysis": "问题分析",
  "guidance": "解决建议",
  "action_items": ["步骤1", "步骤2"],
  "resolved": false  // 是否已完全解决
}

问题解决后

当 resolved=true 时,对话历史会自动清空,下次查询将开始新对话。

[自动] 新对话检测

系统会自动检测新问题:

  • 如果上一次对话的 resolved=true,下次调用 consult_aurai 时会自动清空历史

  • 保证每个独立问题都有干净的上下文,避免干扰

[重要] 明确标注新问题(可选参数)

如果你想强制开始一个新对话,可以设置 is_new_question=true:

  • 效果:立即清空所有之前的对话历史

  • 后果:上级AI将无法看到之前的任何上下文

  • 使用场景:

    • 之前的对话已完全无关

    • 想重新开始讨论一个全新的问题

    • 发现上下文混乱,想重置

示例:

# 第一次咨询(问题A)
consult_aurai(problem_type="runtime_error", error_message="...")

# 继续讨论问题A...
consult_aurai(answers_to_questions="...")

# 切换到问题B(标注为新问题,清空历史)
consult_aurai(
    problem_type="design_issue",
    error_message="...",
    is_new_question=True  # [注意] 会清空之前关于问题A的所有对话
)

Inputs: problem_type (required), error_message (required), code_snippet, context, +3 more. Returns: object

get_statusB

获取当前状态

返回当前对话状态、迭代次数、配置信息等。


返回内容:conversation_history_count(对话历史数量)、max_iterations(最大迭代次数)、max_history(最大历史条数)、provider(AI提供商)、model(模型名称)

Inputs: no named parameters. Returns: object

report_progressA

报告执行进度,请求下一步指导

在执行了上级AI的建议后,调用此工具报告结果,获取下一步指导。


使用场景:执行上级 AI 建议后,报告执行结果并获取后续指导 参数:actions_taken(已执行的行动)、result(success/failed/partial)、new_error(新错误)、feedback(反馈)

Inputs: actions_taken (required), result (required), new_error, feedback. Returns: object

sync_contextA

同步代码上下文(支持上传 .md 和 .txt 文件,避免内容被截断)

在第一次调用或上下文发生重大变化时使用,让上级AI了解当前项目的整体情况。


🎯 典型使用场景

场景 1:上传文章供上级顾问评审

sync_context(
    operation='full_sync',
    files=['文章.md'],
    project_info={
        'task': 'article_review',
        'target_platform': 'GLM Coding 知识库'
    }
)
consult_aurai(
    problem_type='other',
    error_message='请评审以下投稿文章...',
    context={'请查看已上传的文章文件': '已通过 sync_context 上传'}
)

场景 2:上传代码文件(避免内容被截断)⭐ 重要

# 问题:代码太长,在 context 字段中可能被截断
# 解决:将代码转换为 .txt 文件后上传

import shutil

# 步骤 1:将代码文件复制为 .txt
shutil.copy('src/main.py', 'src/main.txt')

# 步骤 2:上传文件
sync_context(
    operation='incremental',
    files=['src/main.txt'],
    project_info={
        'description': '需要调试的代码',
        'language': 'Python'
    }
)

# 步骤 3:告诉上级顾问文件已上传
consult_aurai(
    problem_type='runtime_error',
    error_message='请审查已上传的 src/main.txt 文件,帮我找出bug',
    context={
        'file_location': '已通过 sync_context 上传',
        'expected_behavior': '应该输出...',
        'actual_behavior': '实际输出...'
    }
)

优势:

  • ✅ 避免代码在 context 或 answers_to_questions 字段中被截断

  • ✅ 利用 sync_context 的文件读取机制,完整传递内容

  • ✅ 上级顾问可以完整读取代码文件

场景 3:项目首次初始化

sync_context(
    operation='full_sync',
    files=['README.md', 'docs/说明文档.md'],
    project_info={
        'project_name': 'My Project',
        'tech_stack': 'Python + FastAPI'
    }
)

[注意] 文件上传限制

files 参数只支持 .txt 和 .md 文件!

  • [OK] 支持:README.md, docs.txt, notes.md 等文本和Markdown文件

  • 不支持:.py, .js, .json, .yaml 等代码文件

使用场景

  1. full_sync: 完整同步,适合首次调用或项目重大变更

  2. incremental: 增量同步,适合添加新文件或更新

  3. clear: 清空对话历史

Token优化

当 project_info 中的单个字段超过 800 tokens 时,会自动:

  • 缓存到临时文件

  • 在对话历史中记录文件路径

  • 发送给上级AI时仍会读取完整内容

参数说明

  • operation: 操作类型(full_sync/incremental/clear)

  • files: 文件路径列表,只能是 .txt 或 .md 文件

  • project_info: 项目信息字典,可包含任意字段

Inputs: operation (required), files, project_info. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a distinct, non-overlapping purpose: consult_aurai for core advice, sync_context for file uploads, report_progress for progress updates, and get_status for status checks. The descriptions clearly differentiate their roles, with no ambiguity in when to use each tool.

    Naming Consistency5/5

    All tool names follow a consistent snake_case pattern with clear verb_noun structures: consult_aurai, sync_context, report_progress, get_status. This uniformity makes the set predictable and easy to understand for an agent.

    Tool Count5/5

    With 4 tools, this server is well-scoped for its purpose of providing AI-guided problem-solving. Each tool serves a specific function in the workflow (consult, sync, report, status), and there are no extraneous or missing tools for the domain.

    Completeness5/5

    The tool set fully covers the intended workflow: initiating consultations (consult_aurai), providing context (sync_context), reporting progress (report_progress), and checking status (get_status). There are no gaps; agents can handle the entire lifecycle from problem submission to resolution.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers