Content
# Tool List
Sam Version MCP is a local MCP Server written in Rust. It is designed for models like GLM-5.2, DeepSeek V4 Pro, and others 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 artifact:
```text
target/release/sam-version-mcp.exe
```
### 3. Start
```powershell
.\target\release\sam-version-mcp.exe --config config.json
```
You can also override configurations with 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 configurations.
| 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": "Recognize 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 current visual model configuration. This tool will not return API Key in plaintext, only whether an API Key is configured.
## API Formats
### 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 prioritize extracting results from the `text`, `content`, and `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 build:
```powershell
cargo build --release
```
## Security Recommendations
- Do not submit real `api_key` to Git repositories
- Recommended to save keys through environment variables or local untracked `config.json`
- `config.example.json` should only retain example keys
## More Documents
See more detailed usage instructions in [USAGE.md](USAGE.md).
