Sam Version MCP 是一个基于 Rust 编写的本地 MCP Server。它面向 GLM-5.2、DeepSeek V4 Pro 等不具备多模态图片识别能力的模型,通过 MCP Tool 调用外部视觉模型 API,把图片识别结果以文本形式返回给调用模型。
当前版本:0.0.1
- 本地 stdio MCP Server,适合接入 TRAE、Claude Desktop 等 MCP 客户端
- 支持本地图片路径识别
- 支持 Base64 图片数据识别
- 支持 OpenAI 兼容视觉模型接口
- 支持简单 JSON Body 自定义视觉接口
- 支持通过配置文件、环境变量、命令行参数设置
api_url、api_key、model_id
MCP Client / LLM
│
│ 调用 vision_recognize / vision_recognize_base64
▼
Sam Version MCP
│
│ 读取图片、校验格式、转 Base64
▼
视觉模型 API
│
│ 返回图片理解文本
▼
MCP Client / LLM
.
├── 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
Copy-Item config.example.json config.json编辑 config.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": "请描述这张图片的内容"
}
}cargo build --release构建产物:
target/release/sam-version-mcp.exe
.\target\release\sam-version-mcp.exe --config config.json
也可以用命令行参数覆盖配置:
.\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"
| 字段 | 说明 |
|---|---|
vision.api_url |
视觉模型 API 地址 |
vision.api_key |
视觉模型 API Key |
vision.model_id |
视觉模型 ID |
vision.api_format |
API 请求格式,可选 openai 或 json_body |
vision.timeout_seconds |
请求超时时间 |
vision.default_prompt |
默认图片识别提示词 |
环境变量优先级高于配置文件。
| 环境变量 | 说明 |
|---|---|
VISION_API_URL |
覆盖 vision.api_url |
VISION_API_KEY |
覆盖 vision.api_key |
VISION_MODEL_ID |
覆盖 vision.model_id |
VISION_API_FORMAT |
覆盖 vision.api_format,可选 openai、json、json_body |
VISION_DEFAULT_PROMPT |
覆盖默认提示词 |
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"
{
"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"
}
}
}
}从本地图片路径识别图片。
参数:
| 参数 | 必填 | 说明 |
|---|---|---|
image_path |
是 | 本地图片路径 |
prompt |
否 | 图片识别提示词 |
api_url |
否 | 临时覆盖默认 API URL |
api_key |
否 | 临时覆盖默认 API Key |
示例:
{
"image_path": "E:/images/test.png",
"prompt": "请识别这张图中的文字,并描述主要内容"
}从 Base64 图片数据识别图片。
参数:
| 参数 | 必填 | 说明 |
|---|---|---|
image_base64 |
是 | Base64 编码图片,可以带 data:image/png;base64, 前缀 |
mime_type |
否 | 图片 MIME 类型,例如 image/png、image/jpeg |
prompt |
否 | 图片识别提示词 |
api_url |
否 | 临时覆盖默认 API URL |
api_key |
否 | 临时覆盖默认 API Key |
示例:
{
"image_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
"mime_type": "image/png",
"prompt": "请描述图片内容"
}查看当前视觉模型配置。该工具不会返回 API Key 明文,只会返回是否已配置 API Key。
当 api_format 为 openai 时,请求体格式如下:
{
"model": "gpt-4o",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "请描述这张图片的内容"
},
{
"type": "image_url",
"image_url": {
"url": "data:image/png;base64,..."
}
}
]
}
],
"max_tokens": 4096
}当 api_format 为 json_body 时,请求体格式如下:
{
"model_id": "your-model-id",
"image": "base64...",
"mime_type": "image/png",
"prompt": "请描述这张图片的内容"
}服务会优先从响应中的 text、content、result 字段提取结果。如果都不存在,则返回完整 JSON。
格式化:
cargo fmt
格式检查:
cargo fmt --check编译检查:
cargo check
Release 打包:
cargo build --release- 不要把真实
api_key提交到 Git 仓库 - 推荐通过环境变量或本地未跟踪的
config.json保存密钥 config.example.json只应保留示例密钥
更详细的使用说明见 USAGE.md。