Content
# Multi-Helper MCP
Enable pure text master models (e.g., GLM-5.2) to gain **visual understanding, world knowledge, internet search, web reading, and open-source repository access** through MCP tool calls.
## Why Do We Need It?
Many powerful programming models (e.g., GLM-5.2, DeepSeek-Coder) are **pure text models** without visual capabilities. When image content enters the conversation context, it can cause the session to be permanently damaged (`Model only support text input` error).
This MCP server allows pure text master models to indirectly use multimodal models and external capabilities through "tool calls": **images, knowledge queries, searches, web scraping, and repository reading are passed as tool parameters to the MCP server, which calls specialized models or local implementations and returns pure text results to the master**.
## Architecture
```
┌─────────────────────────────────────────────────────┐
│ Master Model (pure text, e.g., GLM-5.2) │
│ encounters image → vision_describe │
│ encounters objective fact → deepseek_knowledge │
│ encounters complex analysis → deepseek_knowledge_deep │
│ encounters latest information → web_search │
│ encounters web reading → web_reader │
│ encounters repository reading → github_repo │
└────────────────────┬────────────────────────────────┘
↓ MCP (stdio)
┌────┬────┬────┬────┬────┐
▼ ▼ ▼ ▼ ▼
Visual Knowledge Knowledge Web Search Local
Model (fast) (deep) Search httpx
```
The core idea is: **the master model is always the main brain, and external helpers are just "tools"**. The master model maintains stability and context continuity, while external helpers are pluggable.
## Provided Tools
| Tool | Function | Implementation |
|------|----------|---------------|
| `vision_describe(image_path, question)` | Analyze local images and return text descriptions | Visual model (e.g., doubao-seed-2.0-lite) |
| `deepseek_knowledge(query)` | Quickly query objective facts (e.g., names, dates, definitions) | Fast knowledge model (e.g., deepseek-v4-flash) |
| `deepseek_knowledge_deep(query)` | Deeply reason complex knowledge questions | Deep knowledge model (e.g., deepseek-v4-pro) |
| `web_search(query, count, freshness)` | Search for real-time information online, supporting time range filtering | Bocha API (independent of cloud vendors, currently free) |
| `web_reader(url, max_chars)` | Fetch web page content, preserving original text | Local httpx + selectolax |
| `github_repo(action, repo, ...)` | Read GitHub repository structure and files | GitHub REST API (public repositories do not require tokens) |
`vision_describe` supports `image_path="latest"` to automatically locate the latest screenshot, and `"latest:2"` to retrieve the second newest screenshot, eliminating the need to manually copy file paths.
### Why Use Bocha for Internet Search Instead of Volcano Cloud?
Practical conclusions: Volcano Cloud's coding plan package **does not include any search/browsing models** — `doubao-search`, `bot-res-search`, and `doubao-pro-32k-browsing` all return `UnsupportedModel: does not support the coding plan feature`, and the `enable_search=True` parameter is also ineffective. Therefore, internet search uses the third-party Bocha API (currently completely free, independent of cloud vendors).
## Prerequisites
- **Python 3.11+**
- **[uv](https://docs.astral.sh/uv/)** (Python package manager, no need to manually manage virtual environments)
- **Any OpenAI-compatible gateway API key**:
- Volcano Cloud coding plan (recommended, free within package)
- Zhipu official BigModel
- OpenRouter
- Local Ollama / vLLM, etc.
## Quick Start
### 1. Clone Repository
```bash
git clone <your-repo-url> multi-helper-mcp
cd multi-helper-mcp
```
### 2. Install Dependencies
```bash
uv sync
```
uv will automatically create an isolated environment and install `mcp[cli]`, `openai`, and `pillow`.
### 3. Verify and Start
```bash
# Windows
set ARK_API_KEY=your-key-here
uv run server.py
# Linux/Mac
export ARK_API_KEY=your-key-here
uv run server.py
```
Output similar to the following indicates successful startup:
```
[multi-helper] vision=doubao-seed-2.0-lite, knowledge=deepseek-v4-flash(fast), ...
Running stdio MCP server
```
## Client Integration
This MCP server is compatible with any client that supports the MCP protocol. The following provides configuration examples for ZCode and Claude Code.
### ZCode
Edit `~/.zcode/cli/config.json` and add:
```json
{
"mcp": {
"servers": {
"glm-router": {
"type": "stdio",
"command": "uv",
"args": ["run", "--directory", "/path/to/multi-helper-mcp", "server.py"],
"env": {
"ARK_API_KEY": "<your-api-key>",
"ARK_BASE_URL": "https://ark.cn-beijing.volces.com/api/coding/v3",
"VISION_MODEL_ID": "doubao-seed-2.0-lite",
"KNOWLEDGE_MODEL_ID": "deepseek-v4-flash",
"KNOWLEDGE_MODEL_DEEP_ID": "deepseek-v4-pro"
}
}
}
}
}
```
> ZCode also supports global instruction files `~/.zcode/AGENTS.md`, which can write rules to constrain the master model to correctly call this tool (e.g., "When the user mentions a screenshot, directly call `vision_describe('latest')` without using Read to read images").
### Claude Code
Claude Code supports two configuration methods:
**Method A: Global Configuration** (available for all projects)
Edit `~/.claude.json` and add:
```json
{
"mcpServers": {
"glm-router": {
"command": "uv",
"args": ["run", "--directory", "/path/to/multi-helper-mcp", "server.py"],
"env": {
"ARK_API_KEY": "<your-api-key>",
"ARK_BASE_URL": "https://ark.cn-beijing.volces.com/api/coding/v3",
"VISION_MODEL_ID": "doubao-seed-2.0-lite",
"KNOWLEDGE_MODEL_ID": "deepseek-v4-flash",
"KNOWLEDGE_MODEL_DEEP_ID": "deepseek-v4-pro"
}
}
}
}
```
**Method B: Project-Level Configuration** (only available for the current project)
Create `.mcp.json` in the project root directory with the same content.
**Using CLAUDE.md**: Claude Code reads `~/.claude/CLAUDE.md` (global) or project `CLAUDE.md`, and you can write rules to constrain the master model to correctly call this tool.
### General MCP Configuration
Any MCP client that supports stdio transport can use the following configuration to connect:
```
command: uv
args: ["run", "--directory", "<path-to-this-repo>", "server.py"]
env:
ARK_API_KEY: <your-api-key>
ARK_BASE_URL: <your-gateway-url>
VISION_MODEL_ID: <vision-model-id>
KNOWLEDGE_MODEL_ID: <fast-knowledge-model-id>
KNOWLEDGE_MODEL_DEEP_ID: <deep-knowledge-model-id>
```
## Configuration Details
All configurations are passed through environment variables, with no hardcoded default keys. The complete template is in `.env.example`.
### Required
| Environment Variable | Description | Example |
|----------|------|------|
| `ARK_API_KEY` | Gateway API key | `ark-xxxxx` / `sk-xxxxx` |
### Model Configuration
| Environment Variable | Description | Default (Volcano Cloud) | Requirements |
|----------|------|-----------------|------|
| `ARK_BASE_URL` | Gateway address | `https://ark.cn-beijing.volces.com/api/coding/v3` | OpenAI compatible |
| `VISION_MODEL_ID` | Visual model ID | `doubao-seed-2.0-lite` | Must support image input |
| `KNOWLEDGE_MODEL_ID` | Fast knowledge model ID | `deepseek-v4-flash` | Text model sufficient |
| `KNOWLEDGE_MODEL_DEEP_ID` | Deep knowledge model ID | `deepseek-v4-pro` | With reasoning better |
> **How to fill in other gateways**: Zhipu official uses `glm-4v-flash` for visual; OpenRouter uses `openai/gpt-4o-mini` for visual; local Ollama uses `llava:7b` for visual. Knowledge models are similar, filled according to your gateway-supported model IDs.
### Optional Tuning
| Environment Variable | Description | Default |
|----------|------|--------|
| `MAX_IMAGE_SIDE` | Image compression maximum side pixels | `1024` |
| `JPEG_QUALITY` | JPEG compression quality (0-100) | `85` |
| `MAX_OUTPUT_TOKENS` | Visual model single return maximum tokens | `800` |
| `SCREENSHOT_DIR` | Screenshot directory (`latest` keyword scan range) | System default (`~/Pictures/Screenshots`) |
### Internet Search (Bocha)
| Environment Variable | Description | Default |
|----------|------|--------|
| `BOCHA_API_KEY` | Bocha API Key, leaving blank returns an unconfigured prompt | Empty (not configured) |
| `BOCHA_API_URL` | Bocha search interface address | `https://api.bochaai.com/v1/web-search` |
**Get Bocha API Key**: Visit https://open.bochaai.com to register, currently completely free (no credit card required), Individual plan includes web searches and long text summarization. Independent of cloud vendors.
### Web Reading (web_reader)
| Environment Variable | Description | Default |
|----------|------|--------|
| `WEB_READER_TIMEOUT` | Web page fetch timeout (seconds) | `20` |
| `WEB_READER_MAX_CHARS` | Returned text maximum characters, truncated if exceeded | `8000` |
| `WEB_READER_USER_AGENT` | Request UA, some sites reject UA requests | Built-in reasonable UA |
### GitHub Repository Reading (github_repo)
| Environment Variable | Description | Default |
|----------|------|--------|
| `GITHUB_TOKEN` | GitHub Personal Access Token, leaving blank uses anonymous mode | Empty (anonymous, 60 times/hour) |
**Anonymous Mode**: Public repositories do not require tokens, rate-limited to 60 times/hour/IP, occasionally sufficient.
**Configure Token**: Apply for https://github.com/settings/tokens (classic token check `public_repo`), mentions 5000 times/hour, and supports private repositories.
## Usage
After connecting to the client, normally dialogue with the master model. The master model will automatically determine when to call tools:
- **Sending images/screenshots/asking image questions**: Master model calls `vision_describe`, images are analyzed by the visual model in the MCP server, and text results are returned to the master.
- **Asking objective facts** (names, dates, definitions): Master model calls `deepseek_knowledge`.
- **Asking complex analysis** (multi-step reasoning, comparison): Master model calls `deepseek_knowledge_deep`.
- **Asking for latest information** ("recent", "today", "search"): Master model calls `web_search` (requires Bocha Key configuration).
- **Reading web page content** ("read this URL"): Master model calls `web_reader`, directly fetches content without AI processing.
- **Reading open-source repository** ("look at project structure", "read repository file"): Master model calls `github_repo`.
- **Writing code/project-related**: Master model handles itself, without detouring through tools.
### `latest` Keyword Usage
`vision_describe`'s `image_path` parameter supports:
- Absolute path: `C:\Users\xxx\screenshot.png`
- `"latest"`: Automatically retrieve the latest screenshot from the screenshot directory.
- `"latest:N"`: Retrieve the Nth newest screenshot (`latest:2` = second newest, `latest:3` = third newest).
When the user says "view the latest screenshot", the master model should directly call `vision_describe("latest")` without manually copying the path.
## Frequently Asked Questions
### Q: Tool call timeout, what to do?
MCP clients usually have a 30-second tool execution timeout. server.py internally sets a 28-second timeout to actively give up and avoid being externally capped. If frequent timeouts occur:
- Visual timeout: Check if `VISION_MODEL_ID` has selected a fast model (e.g., `doubao-seed-2.0-lite` closes thinking mode).
- Knowledge timeout: `deepseek_knowledge_deep`'s reasoning budget defaults to 3000, complex questions take about 16 seconds, leaving sufficient margin.
### Q: Prompt "Model only support text input"?
Indicates that the master model directly encountered image bytes, and the session has been damaged. This usually occurs because the master model used the Read tool to read images instead of calling `vision_describe`. Solution:
- Write rules in the client's global instruction file to prohibit Read from reading images (ZCode: `~/.zcode/AGENTS.md`, Claude Code: `~/.claude/CLAUDE.md`).
- Current session can only be discarded, and a new session opened.
### Q: Where is the screenshot directory?
Configured by the `SCREENSHOT_DIR` environment variable. Default:
- Windows: `C:\Users\<username>\Pictures\Screenshots`
- macOS: `~/Pictures/Screenshots`
- Linux: `~/Pictures`
If your screenshots are saved elsewhere (e.g., OneDrive synchronization directory), specify using environment variables.
### Q: Don't want to use three models, can use one?
Yes. Fill `KNOWLEDGE_MODEL_ID` and `KNOWLEDGE_MODEL_DEEP_ID` with the same model, and the effect will differ but the function will be normal. If only visual and no knowledge are used, the knowledge tool will still be registered, but you can ignore it.
## Limitations
- **Visual description is text, not "view"**: Sufficient for tasks like screenshot error reporting, chart data, OCR, and layout structure; limited for aesthetic tasks like color matching/spacing/fine-tuning (description process loses visual information).
- **Knowledge tools have context isolation**: Knowledge models cannot see the master model's dialogue history, only the `query` parameter. Suitable for independent objective fact queries, not for analysis relying on dialogue context.
- **Knowledge replies are relayed by the master**: After the knowledge model's answer returns to the master, the master may refine or process it. If you need to preserve it as is, you can require the master to "relay the knowledge tool's reply as is" in the client's instructions.
## File Description
```
multi-helper-mcp/
├── server.py # MCP server main program (three tools)
├── start.bat # Windows startup script (need to set ARK_API_KEY yourself)
├── pyproject.toml # Dependency declaration and entry point
├── uv.lock # Dependency version lock
├── .env.example # Configuration template (copy to .env or fill in client's env)
├── .gitignore
├── LICENSE # MIT
└── README.md # This file
```
## License
MIT
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available