Aurai Advisor (上级顾问 MCP)
The Aurai Advisor MCP server acts as a bridge that lets a local AI escalate complex programming problems to a more powerful remote model through multi-round consultations and guided problem-solving.
Core Tools:
consult_aurai— Submit programming problems (runtime errors, syntax issues, design concerns, etc.) with code snippets, error messages, and context to a senior AI advisor, supporting interactive multi-round dialogue with clarifying questionssync_context— Upload code (.py,.js,.ts,.json), configuration (.yaml,.toml,.ini), and documentation (.md,.txt) files to give the advisor full project context; binary files are automatically skippedreport_progress— Report back the results of executed suggestions (success/failed/partial) and any new errors, continuing the iterative "ask → execute → report → next step" cycleget_status— Retrieve current session metadata: conversation history count, max iterations, model in use, and history file path
Additional Features:
Session isolation via
session_idto keep multiple independent problems separateAutomatic history summarization and context window trimming to manage long sessions within token limits
New question detection — automatically clears history when a problem is marked resolved, or manually via
is_new_question=truePersistent storage with file locking and atomic writes for reliability
Configurable via environment variables (API key, model, temperature, max iterations, context window size, log level)
Enables integration with Google Gemini's API to leverage their models for remote technical advice and debugging support.
Integrates with OpenAI's API to use models like GPT-4o for providing expert guidance and problem-solving assistance during development.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Aurai Advisor (上级顾问 MCP) Help me fix this KeyError: 'api_key' not found in my python code"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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_contextfile synchronizationAutomated 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_idfor session isolation to prevent context leakage between different problemsEnabled real configuration support for
AURAI_TEMPERATURE,AURAI_MAX_ITERATIONS,AURAI_LOG_LEVEL, etc.Ensured
project_infoand follow-up answers are properly sent to the senior advisorAdded 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_WINDOWis now fully effectivesync_contextnow supports automatic conversion of code/config text files, no longer requiring manual conversion to.txtRewrote 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:
Read the "Installation Instructions" below first
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_auraiThe primary consultation tool. Submit problems, code snippets, context, and attempted solutions to get analysis and next-step suggestions from the senior advisor.sync_contextSynchronize code and documentation context. It now supports not only.txt/.mdbut also automatically converts text files like.py/.js/.ts/.json/.yaml/.toml/.iniinto a format suitable for transmission.report_progressReport execution results to the senior advisor to continue the next iteration.get_statusView 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-server2. 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_URLmust be an OpenAI-compatible API addressThe current version only supports the
custommethod; the oldAURAI_PROVIDERis no longer used--scope usermeans it will be available in all projects, which is the most convenient
4. Verify Installation
claude mcp list
pytestExpected:
claude mcp listshowsaurai-advisorpytestpasses
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.pytomain.txtanymoreText-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.txtVarious 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/.mdbut contain text contentAn automatic
.txtor.mdfilename will be generated for transmissionThe 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_filesThe overall synchronization is still considered successful
Environment Variables
Required
Variable | Description |
| API Key |
| OpenAI-compatible API address |
| Model name |
Common Optional
Variable | Description | Default Value |
| Temperature |
|
| Max iteration rounds |
|
| Max history entries per session |
|
| Total context window size |
|
| Max tokens for a single large file message |
|
| Max output length |
|
| Log level |
|
| Whether to persist history |
|
| Default session history file path |
|
| History file lock timeout (seconds) |
|
| Whether to enable history summary |
|
| Recent original rounds kept after summary |
|
| Threshold of original records to trigger summary |
|
Key Behaviors in Current Version
1. Session Isolation
Each
session_idhas its own historyUses
defaultif not specifiedDifferent 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_contextare kept in their original form as much as possibleThis reduces context usage, freeing up space for the current problem
3. Context Window Trimming
System prompts are prioritized
The latest
sync_contextis prioritizedRecent 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
pytestKey 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_filesin thesync_contextresponse
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 toolsconsult_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等代码文件
使用场景
full_sync: 完整同步,适合首次调用或项目重大变更
incremental: 增量同步,适合添加新文件或更新
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
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for AI dialogue using various LLM models via AceDataCloud
An MCP server that gives your AI access to the source code and docs of all public github repos
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Driflyte MCP server which lets AI assistants query topic-specific knowledge from web and GitHub.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceAn MCP server that orchestrates AI coding assistants (Claude Code CLI and Gemini CLI) to perform complex programming tasks autonomously, allowing remote control of your local development environment from anywhere.140MIT
- AlicenseNot gradedqualityDmaintenanceA local-first MCP server for coordinating parallel AI coding sessions with tools like Claude Code and Codex in a single repository.2MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that turns multiple AI coding agents into a coordinated team that chats, debates, remembers, audits security, and works in parallel on the same project.MIT
- FlicenseNot gradedqualityBmaintenanceA local MCP server that connects AI coding agents like Claude, Codex, and Gemini, enabling task routing, cross-model debates, and token-efficient context sharing without external APIs.19-