Content
# Tool List
Sam Version MCP is a local MCP Server written in Rust. It is designed for models like GLM-5.2 and DeepSeek V4 Pro that lack multimodal image recognition capabilities. It calls external visual model APIs through MCP Tool and returns image recognition results in text form to the calling model.
Current Version: `0.0.1`
## Core Capabilities
- Local stdio MCP Server, suitable for connecting to TRAE, Claude Desktop, and other MCP clients
- Supports local image path recognition
- Supports Base64 image data recognition
- Supports OpenAI-compatible visual model interfaces
- Supports simple JSON Body custom visual interfaces
- Supports setting `api_url`, `api_key`, and `model_id` through configuration files, environment variables, and command-line parameters
## Workflow
```text
MCP Client / LLM
│
│ Calls vision_recognize / vision_recognize_base64
▼
Sam Version MCP
│
│ Reads image, checks format, converts to Base64
▼
Visual Model API
│
│ Returns image understanding text
▼
MCP Client / LLM
```
## Project Structure
```text
.
├── Cargo.toml
├── Cargo.lock
├── README.md
├── USAGE.md
├── config.example.json
├── sam-version-mcp-plan.md
└── src
├── config.rs
├── image.rs
├── main.rs
├── server.rs
└── vision.rs
```
## Quick Start
### 1. Prepare Configuration File
```powershell
Copy-Item config.example.json config.json
```
Edit `config.json`:
```json
{
"server_name": "sam-version-mcp",
"server_version": "0.0.1",
"image_upload_dir": "uploads",
"max_image_bytes": 20971520,
"vision": {
"api_url": "https://api.example.com/v1/chat/completions",
"api_key": "sk-your-api-key-here",
"model_id": "gpt-4o",
"api_format": "openai",
"timeout_seconds": 120,
"default_prompt": "Describe the content of this image"
}
}
```
### 2. Build
```powershell
cargo build --release
```
Build product:
```text
target/release/sam-version-mcp.exe
```
### 3. Start
```powershell
.\target\release\sam-version-mcp.exe --config config.json
```
You can also override the configuration using command-line parameters:
```powershell
.\target\release\sam-version-mcp.exe --config config.json --api-url "https://api.example.com/v1/chat/completions" --model-id "gpt-4o" --api-key "sk-your-api-key-here"
```
## Configuration Description
| Field | Description |
| --- | --- |
| `vision.api_url` | Visual model API URL |
| `vision.api_key` | Visual model API Key |
| `vision.model_id` | Visual model ID |
| `vision.api_format` | API request format, optional `openai` or `json_body` |
| `vision.timeout_seconds` | Request timeout time |
| `vision.default_prompt` | Default image recognition prompt |
## Environment Variables
Environment variables have higher priority than configuration files.
| Environment Variable | Description |
| --- | --- |
| `VISION_API_URL` | Overrides `vision.api_url` |
| `VISION_API_KEY` | Overrides `vision.api_key` |
| `VISION_MODEL_ID` | Overrides `vision.model_id` |
| `VISION_API_FORMAT` | Overrides `vision.api_format`, optional `openai`, `json`, `json_body` |
| `VISION_DEFAULT_PROMPT` | Overrides default prompt |
PowerShell example:
```powershell
$env:VISION_API_URL="https://api.example.com/v1/chat/completions"
$env:VISION_API_KEY="sk-your-api-key-here"
$env:VISION_MODEL_ID="gpt-4o"
$env:VISION_API_FORMAT="openai"
```
## MCP Client Configuration
```json
{
"mcpServers": {
"vision": {
"command": "E:/mywork/samVersionMCP/target/release/sam-version-mcp.exe",
"args": ["--config", "E:/mywork/samVersionMCP/config.json"],
"env": {
"VISION_API_URL": "https://api.example.com/v1/chat/completions",
"VISION_API_KEY": "sk-your-api-key-here",
"VISION_MODEL_ID": "gpt-4o",
"VISION_API_FORMAT": "openai"
}
}
}
}
```
## MCP Tools
### `vision_recognize`
Recognize images from local image paths.
Parameters:
| Parameter | Required | Description |
| --- | --- | --- |
| `image_path` | Yes | Local image path |
| `prompt` | No | Image recognition prompt |
| `api_url` | No | Temporary override default API URL |
| `api_key` | No | Temporary override default API Key |
Example:
```json
{
"image_path": "E:/images/test.png",
"prompt": "Identify the text in this image and describe the main content"
}
```
### `vision_recognize_base64`
Recognize images from Base64 image data.
Parameters:
| Parameter | Required | Description |
| --- | --- | --- |
| `image_base64` | Yes | Base64 encoded image, can include `data:image/png;base64,` prefix |
| `mime_type` | No | Image MIME type, e.g., `image/png`, `image/jpeg` |
| `prompt` | No | Image recognition prompt |
| `api_url` | No | Temporary override default API URL |
| `api_key` | No | Temporary override default API Key |
Example:
```json
{
"image_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
"mime_type": "image/png",
"prompt": "Describe the image content"
}
```
### `vision_config`
View the current visual model configuration. This tool will not return the API Key in plain text, only whether the API Key is configured.
## API Format
### OpenAI Compatible Format
When `api_format` is `openai`, the request body format is:
```json
{
"model": "gpt-4o",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Describe the content of this image"
},
{
"type": "image_url",
"image_url": {
"url": "data:image/png;base64,..."
}
}
]
}
],
"max_tokens": 4096
}
```
### JSON Body Custom Format
When `api_format` is `json_body`, the request body format is:
```json
{
"model_id": "your-model-id",
"image": "base64...",
"mime_type": "image/png",
"prompt": "Describe the content of this image"
}
```
The service will extract the result from the `text`, `content`, or `result` fields in the response. If none exist, it will return the complete JSON.
## Development Commands
Formatting:
```powershell
cargo fmt
```
Format check:
```powershell
cargo fmt --check
```
Compilation check:
```powershell
cargo check
```
Release packaging:
```powershell
cargo build --release
```
## Security Recommendations
- Do not submit the actual `api_key` to the Git repository
- Recommended to save the key through environment variables or local untracked `config.json`
- `config.example.json` should only retain example keys
## More Documents
See [USAGE.md](USAGE.md) for more detailed usage instructions.
