MCP Aurai Server

🚀 Aurai Advisor MCP

An MCP server that enables local AI to receive guidance from remote AI

Version: v2.2.0 (Refactored and File Upload Fixed) Status: [OK] Production Ready Release Date: 2026-01-24 Optimized Model: GLM-4.7 (Zhipu AI)

✨ Features

• [OK] Multi-round Conversation Mechanism - Intelligently follow up on questions to gradually solve problems.
• [OK] Intelligent Conversation Management - Automatically detect new questions and clear history to ensure a clean context.
• [OK] Intelligent Tool Guidance - Include relevant tool recommendations in tool descriptions.
• [OK] File Upload Support ⭐ - Support file upload via sync_context, and large files are automatically sent in batches.
• [OK] GLM-4.7 Optimization - Optimized based on the hard-coded parameters of the GLM-4.7 model (200K context).
• [OK] Conversation History Persistence - Automatically save to the user directory.
• [OK] GUI Configuration Tool - Generate visual configurations.

📦 Installation Guide

1. Installation

# Enter the project directory
cd mcp-aurai-server

# Create a virtual environment
python -m venv venv
venv\Scripts\activate  # Windows
# source venv/bin/activate  # macOS/Linux

# Install dependencies
pip install -e ".[all-dev]"

# Verify the installation
python .ai_temp/test_file_upload_fix.py
# Expected: ✅ All tests passed!

2. Configuration

Important: Use --scope user to ensure it is available in all projects.

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

3. Usage

After restarting Claude Code, directly describe programming problems in the conversation:

I encountered a KeyError issue, and the error message is 'api_key' not found.
The relevant code is as follows:
[Paste the code]

The AI will automatically decide whether to call the consult_aurai tool.

💻 Usage Examples

Basic Usage

# Scenario 1: Upload a code file (to avoid truncation)
shutil.copy('main.py', 'main.txt')  # Convert to .txt
sync_context(
    operation='incremental',
    files=['main.txt'],
    project_info={'language': 'Python'}
)

# Scenario 2: Upload documents for review
sync_context(
    operation='full_sync',
    files=['README.md', 'docs/Design_Document.md'],
    project_info={'task': 'code_review'}
)

📚 Documentation

🔧 Technical Details

v2.2.0 Update Notes

⚠️ Important: Migration Guide for Old Version Users

If you have installed v2.1.x or earlier versions, please note the following migration items:

Case 1: Users using the custom provider (OpenAI-compatible API) ✅

Good news: No need to reinstall or reconfigure!

# Just upgrade the version
cd D:\mcp-aurai-server
git pull origin main
pip install -e ".[all-dev]"

# Restart Claude Code, and it will take effect automatically

• ✅ The new environment variables (AURAI_CONTEXT_WINDOW, AURAI_MAX_MESSAGE_TOKENS, AURAI_MAX_TOKENS) are optional.
• ✅ The default values have been optimized for GLM-4.7 (200K context).
• ✅ The file upload fix is transparent and will take effect automatically.

Case 2: Users using the zhipu, openai, anthropic, gemini providers ❌

Migration required: v2.2.0 has removed these providers, and you need to switch to custom + OpenAI-compatible API. Migration steps (taking Zhipu AI as an example):

# 1. Delete the old configuration
claude mcp remove aurai-advisor -s user

# 2. Re-add (using the custom provider)
claude mcp add --scope user --transport stdio aurai-advisor \
  --env AURAI_API_KEY="your-api-key" \
  --env AURAI_BASE_URL="https://open.bigmodel.cn/api/paas/v4/" \
  --env AURAI_MODEL="glm-4.7" \
  -- "D:\mcp-aurai-server\venv\Scripts\python.exe" "-m" "mcp_aurai.server"

# 3. Restart Claude Code

Migration configurations for each service provider:

Tip: After the upgrade, it is recommended to run python .ai_temp/test_file_upload_fix.py to verify whether the file upload function is working properly.

Major Changes

1. Simplified Service Provider Support
   • ✅ Only the custom provider (OpenAI-compatible API) is retained.
   • ❌ Direct support for zhipu, openai, anthropic, and gemini is removed.
   • ✅ All services compatible with the OpenAI API can be used.
2. File Upload Function Fixed ⭐
   • ✅ Fixed the issue where the sync_context file content was not sent to the superior AI.
   • ✅ Large files are automatically sent in batches (when exceeding max_message_tokens).
   • ✅ Dynamic Token estimation, automatically adjusted according to the configuration.
3. GLM-4.7 Model Optimization 🎯
   • ✅ Default values are set based on the GLM-4.7 model parameters.
   • ✅ Context window: 200,000 tokens (default).
   • ✅ Single message limit: 150,000 tokens (default).
   • ✅ Maximum output: 32,000 tokens (default).
   • ✅ Support for overriding via environment variables (applicable to other models).

GLM-4.7 Token Configuration Instructions

This version uses the GLM-4.7 model parameters as default values and also supports overriding via environment variables (applicable to other models):

Token Allocation Strategy:

200K (Total context)
├── 32K (Output) - Analysis and response from the superior AI
└── 168K (Input)
    ├── ~18K (System + History + Question)
    ├── 150K (Maximum single file)
    └── ~ - Safety margin

Capacity Reference:

• Single file upload limit: ~150,000 - 200,000 Chinese characters.
• Superior AI output limit: ~20,000 - 30,000 Chinese characters.
• Conversation history: Approximately 10 - 15 rounds of complete conversations.

Note: The default values are optimized based on GLM-4.7. When using other models, you can adjust them via environment variables.

MCP Tools

consult_aurai (Main Tool)

Request guidance from the superior AI to solve programming problems.

Parameters:

• problem_type: Problem type (runtime_error/syntax_error/design_issue/other).
• error_message: Error description.
• code_snippet: Code snippet (optional).
• context: Context information (optional).
• is_new_question: Whether it is a new question (optional, default false).

Return: Analysis and suggestions from the superior AI.

🔗 Related Tools:

• sync_context: Upload documents or code files (supports .md and .txt).
• report_progress: Report the execution progress and get the next step of guidance.
• get_status: View the current conversation status and configuration information.

Conversation History Management:

• Automatic Clearing: Automatically clear the conversation history when the superior AI returns resolved=true.
• Manual Clearing: Set is_new_question=true to force clear the history.
• History Limit: Save a maximum of 50 history records.

sync_context ⭐

Synchronize the code context and upload files for the superior AI to read.

Parameters:

• operation: Operation type (full_sync/incremental/clear).
• files: List of file paths (supports .txt and .md).
• project_info: Project information dictionary (optional).

Functional Features:

• 📄 Support uploading Markdown and text files.
• 🔄 Automatically send large files in batches (to avoid exceeding the Token limit).
• 📏 Intelligent Token estimation (1.5 Chinese characters per token, 4 English characters per token).

report_progress

Report the execution progress.

Parameters:

• actions_taken: Actions taken.
• result: Execution result (success/failed/partial).

get_status

Get the current status.

Return:

• Number of conversation histories.
• Model configuration.
• Token limit configuration.

Environment Variables

Required

Optional

Token Configuration Instructions

Default values (based on GLM-4.7):

• context_window: 200,000 tokens.
• max_message_tokens: 150,000 tokens.
• max_tokens: 32,000 tokens.

References for other models:

• Claude 3.5 Sonnet: 200,000 / 140,000 / 64,000.
• GPT-4o: 128,000 / 100,000 / 32,000.
• DeepSeek: 64,000 / 50,000 / 16,000.

Configuration Examples

# Use Zhipu AI GLM-4.7 (recommended, use default values)
AURAI_API_KEY=your-api-key
AURAI_BASE_URL=https://open.bigmodel.cn/api/paas/v4/
AURAI_MODEL=glm-4.7
# Token configuration uses default values, no need to set

# Use Claude 3.5 Sonnet (adjust Token configuration)
AURAI_API_KEY=your-api-key
AURAI_BASE_URL=https://api.anthropic.com
AURAI_MODEL=claude-3-5-sonnet-20241022
AURAI_CONTEXT_WINDOW=200000
AURAI_MAX_MESSAGE_TOKENS=140000
AURAI_MAX_TOKENS=64000

# Use DeepSeek (adjust Token configuration)
AURAI_API_KEY=your-api-key
AURAI_BASE_URL=https://api.deepseek.com/v1
AURAI_MODEL=deepseek-chat
AURAI_CONTEXT_WINDOW=64000
AURAI_MAX_MESSAGE_TOKENS=50000
AURAI_MAX_TOKENS=16000

# Use other compatible APIs
AURAI_API_KEY=your-key
AURAI_BASE_URL=https://your-api.com/v1
AURAI_MODEL=your-model
# Adjust Token configuration according to the model specifications

Project Structure

mcp-aurai-server/
├── src/mcp_aurai/          # MCP Server source code
│   ├── server.py           # Main server (4 tools)
│   ├── config.py           # Configuration management
│   ├── llm.py              # OpenAI-compatible client
│   ├── prompts.py          # Prompt templates
│   └── utils.py            # Utility functions
│
├── tools/
│   └── control_center.py   # GUI configuration tool
│
├── tests/                  # Test cases
│   ├── test_server.py
│   ├── test_llm.py
│   └── test_config.py
│
├── docs/                   # Documentation
│   ├── User_Manual.md
│   ├── CLAUDE_CODE_INSTALL.md
│   └── Development_Documentation.md
│
├── README.md               # This file
├── pyproject.toml          # Project configuration
└── .env.example            # Environment variable example

Troubleshooting

Do I need to reinstall every time I open Claude Code?

Cause: You are using the local scope, which is only available in a specific directory. Solution: Reinstall using --scope user

claude mcp remove aurai-advisor -s local
claude mcp add --scope user ...

The MCP tool does not appear

claude mcp list                          # Check the configuration
claude mcp remove aurai-advisor -s local # Delete the old configuration
claude mcp add --scope user ...          # Re-add

ModuleNotFoundError

cd D:\mcp-aurai-server
python -m venv venv                      # Create a virtual environment
venv\Scripts\activate
pip install -e ".[all-dev]"              # Install the project

401 Unauthorized

• Check if the API key is correct.
• Visit the provider platform to regenerate the key.

404 Model not found

• Check the spelling of the model name.
• Use the provider API to confirm the available models.

File content is not sent to the superior AI

• Ensure that the sync_context call is successful.
• Check the message "The file has been split into X fragments" in the log.
• Check the AURAI_MAX_MESSAGE_TOKENS configuration.

Testing

# Run the file upload function test
python .ai_temp/test_file_upload_fix.py

# Run all tests
pytest tests/ -v

# Run specific tests
pytest tests/test_server.py -v
pytest tests/test_llm.py -v
pytest tests/test_config.py -v

# View test coverage
pytest tests/ --cov=src/mcp_aurai --cov-report=html

Getting Help

• User Manual: docs/User_Manual.md
• Installation Guide: docs/CLAUDE_CODE_INSTALL.md
• Development Documentation: docs/Development_Documentation.md

📄 License

The MCP Aurai Server is under a dual-license agreement.

Project Name: mcp-aurai-server Version: v2.2.0 Status: [OK] Production Ready Release Date: 2026-01-24