使用说明
Aurai Advisor MCP
让本地 AI（Claude Code）在遇到复杂编程问题时，向远程大模型继续请教的 MCP 服务。
工作原理: 本地 AI 通过 sync_context 上传代码文件 → consult_aurai 提交问题 → 远程顾问返回分析 + 可执行步骤 → 本地 AI 用 report_progress 汇报进展 → 循环直到解决。
关键约束: 远程顾问无法直接访问你的文件系统。它只能看到你通过 sync_context 上传的文件内容和 consult_aurai 描述的信息。
安装
1. 环境要求
- Python 3.10+
- Claude Code（或其他支持 MCP stdio 的客户端）
2. 下载并安装依赖
git clone https://github.com/LZMW/mcp-aurai-server.git
cd mcp-aurai-server
python -m venv venv
venv\Scripts\activate # Windows
# source venv/bin/activate # macOS / Linux
pip install -e .
3. 在 Claude Code 中注册
claude mcp add --scope user --transport stdio aurai-advisor \
--env AURAI_API_KEY="你的API密钥" \
--env AURAI_BASE_URL="https://你的API地址/v1" \
--env AURAI_MODEL="模型名称" \
-- "完整路径\venv\Scripts\python.exe" "-m" "mcp_aurai.server"
Windows 实际示例:
claude mcp add --scope user --transport stdio aurai-advisor \
--env AURAI_API_KEY="sk-xxxxxxxxxxxxxxxx" \
--env AURAI_BASE_URL="https://api.openai.com/v1" \
--env AURAI_MODEL="gpt-4o" \
-- "D:\mcp-aurai-server\venv\Scripts\python.exe" "-m" "mcp_aurai.server"
--scope user 表示在所有项目中可用。
4. 验证
claude mcp list
看到 aurai-advisor: ✓ Connected 即成功。
5. 卸载
claude mcp remove "aurai-advisor" -s user
配置参数
所有参数通过环境变量设置，在 claude mcp add 时用 --env 传入。
必填
| 环境变量 | 说明 | 示例 |
|---|---|---|
AURAI_API_KEY |
API 密钥 | sk-xxxxxxxx |
AURAI_BASE_URL |
OpenAI 兼容接口地址 | https://api.openai.com/v1 |
AURAI_MODEL |
模型名称 | gpt-4o / claude-opus-4-1-20250805-thinking |
AI 调用控制
| 环境变量 | 默认值 | 范围 | 说明 |
|---|---|---|---|
AURAI_TEMPERATURE |
0.7 |
0.0–2.0 | 生成温度。越低越确定，越高越随机 |
AURAI_MAX_TOKENS |
32000 |
≥1 | 远程顾问单次回复的最大输出长度（tokens） |
AURAI_CONTEXT_WINDOW |
200000 |
≥1 | 模型上下文窗口大小（tokens）。输入 + 输出的总上限 |
AURAI_MAX_MESSAGE_TOKENS |
150000 |
≥1 | 单个文件超过此值会自动拆分成多段发送 |
AURAI_MAX_ITERATIONS |
50 |
1–200 | 单个问题最多对话轮数。50 轮内解决 → 自动清空历史；超限 → 清空历史并返回 requires_human_intervention |
上下文预算 & Token 监控:
| 环境变量 | 默认值 | 范围 | 说明 |
|---|---|---|---|
AURAI_CONTEXT_HIGH_WATERMARK |
0.85 |
0.5–1.0 | 上下文高水位线。输入 tokens 超过此比例时返回预警并主动压缩历史 |
每次 consult_aurai / report_progress 响应中均包含 token_usage 字段，实时展示输入 tokens、使用率、是否触发预警。当超过高水位线时，会主动压缩历史为输出腾空间。本地 AI 可根据 warning=true 提示调用 sync_context(operation='clear') 清空历史。
上下文预算分配策略: 优先保证 AURAI_MAX_TOKENS 的输出预算。输入过大时裁剪历史消息，不压缩输出。仅当基础消息（系统提示词 + 当前问题）本身就超过窗口时才缩减输出。
对话历史
| 环境变量 | 默认值 | 范围 | 说明 |
|---|---|---|---|
AURAI_MAX_HISTORY |
50 |
1–200 | 每个会话在本地最多保留多少条历史记录 |
AURAI_PROMPT_HISTORY_TURNS |
10 |
1–50 | 每次发送给远程顾问时附带最近多少轮原始对话（摘要不受此限制） |
AURAI_ENABLE_PERSISTENCE |
true |
bool | 是否将历史保存到磁盘。关闭后重启 Claude Code 历史丢失 |
AURAI_HISTORY_PATH |
~/.mcp-aurai/history.json |
— | 历史文件存储路径 |
AURAI_HISTORY_LOCK_TIMEOUT |
10 |
1–120s | 跨进程文件锁等待超时 |
AURAI_ENABLE_HISTORY_SUMMARY |
true |
bool | 是否启用历史摘要。仅在接近 max_history（80%）时触发，保留 60% 原始记录 |
历史机制说明:
AURAI_MAX_HISTORY（50 条）是本地存储上限——现代 200K 上下文下纯对话远填不满，真正的瓶颈是sync_context上传的大文件- 摘要不再按固定条数触发，而是在接近 max_history 时（40/50 条）才启动
- Token 水位线预警（
AURAI_CONTEXT_HIGH_WATERMARK）是实时防线，在每次请求前检查 - 不同
session_id的历史互相隔离
进程管理
| 环境变量 | 默认值 | 范围 | 说明 |
|---|---|---|---|
AURAI_STDIO_IDLE_TIMEOUT_SECONDS |
600 |
0–86400 | 空闲多久后自动退出。0 = 永不退出（推荐） |
AURAI_STDIO_IDLE_CHECK_INTERVAL_SECONDS |
30 |
1–3600 | 空闲检查间隔 |
推荐设置 AURAI_STDIO_IDLE_TIMEOUT_SECONDS=0，避免 Claude Code 还在运行但 MCP 因空闲被误杀。空闲退出前会检查父进程是否存活，但如果不在意残留进程，直接禁用最省心。
其他
| 环境变量 | 默认值 | 说明 |
|---|---|---|
AURAI_LOG_LEVEL |
INFO |
日志级别：DEBUG / INFO / WARNING / ERROR。调试时建议 DEBUG |
使用指南
MCP 注册后，Claude Code 中自动出现 4 个工具：
典型调用流程
1. sync_context(operation='sync', files=['src/bug.py'], project_info={...})
↑ 让顾问看到你的代码
2. consult_aurai(problem_type='runtime_error', error_message='...')
↑ 提交问题，获取分析
3. 如返回 status='need_info' → 搜集顾问反问的信息 → 再次 consult_aurai(answers_to_questions='...')
↑ 多轮对齐
4. 如返回 status='success' → 按 action_items 执行修改
5. report_progress(actions_taken='改了X', result='success')
↑ 汇报进展，获取下一步指导
6. 重复 4-5，直到 resolved=true
工具速查
| 工具 | 用途 |
|---|---|
sync_context |
上传文件和项目背景。operation='sync' 追加，'clear' 清空 |
consult_aurai |
提交问题。支持多轮：收到反问→搜集信息→answers_to_questions 继续 |
report_progress |
按顾问指导执行后汇报结果，获取下一步 |
get_status |
查看会话状态（历史条数、模型、空闲时间） |
会话隔离
不同任务传不同的 session_id，避免上下文串扰：
consult_aurai(session_id='bug-123', ...) # 修 Bug A
consult_aurai(session_id='feature-456', ...) # 写功能 B
常见问题
上级顾问收不到我上传的代码？
检查 sync_context 返回的 uploaded_files 和 skipped_files。二进制文件（图片、压缩包）会被自动跳过。代码文件（.py/.js/.ts 等）会自动转换为文本发送。
不同问题互相干扰？
给不同问题传不同的 session_id。或设置 is_new_question=true 清空当前会话历史。
Claude Code 提示 MCP 连不上？
- 检查
claude mcp list确认状态 - 查看
AURAI_STDIO_IDLE_TIMEOUT_SECONDS，推荐设为0禁用空闲退出 - 查看日志：
AURAI_LOG_LEVEL=DEBUG可看到详细日志（输出到 stderr）
历史文件变得很大？
历史摘要在自动工作。旧记录被压缩为纪要而非删除，可设置 AURAI_ENABLE_HISTORY_SUMMARY=false 完全禁用摘要（不推荐）。
怎么切换模型？
claude mcp remove "aurai-advisor" -s user
claude mcp add --scope user --transport stdio aurai-advisor \
--env AURAI_API_KEY="sk-..." \
--env AURAI_BASE_URL="https://api.openai.com/v1" \
--env AURAI_MODEL="新模型名称" \
-- "D:\mcp-aurai-server\venv\Scripts\python.exe" "-m" "mcp_aurai.server"
