内容
# Sam Version MCP
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`
## 工作流程
```text
MCP Client / LLM
│
│ 调用 vision_recognize / vision_recognize_base64
▼
Sam Version MCP
│
│ 读取图片、校验格式、转 Base64
▼
视觉模型 API
│
│ 返回图片理解文本
▼
MCP Client / LLM
```
## 项目结构
```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
```
## 快速开始
### 1. 准备配置文件
```powershell
Copy-Item config.example.json config.json
```
编辑 `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": "请描述这张图片的内容"
}
}
```
### 2. 构建
```powershell
cargo build --release
```
构建产物：
```text
target/release/sam-version-mcp.exe
```
### 3. 启动
```powershell
.\target\release\sam-version-mcp.exe --config config.json
```
也可以用命令行参数覆盖配置：
```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"
```
## 配置说明
| 字段 | 说明 |
| --- | --- |
| `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 示例：
```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 客户端配置
```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`
从本地图片路径识别图片。
参数：
| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `image_path` | 是 | 本地图片路径 |
| `prompt` | 否 | 图片识别提示词 |
| `api_url` | 否 | 临时覆盖默认 API URL |
| `api_key` | 否 | 临时覆盖默认 API Key |
示例：
```json
{
"image_path": "E:/images/test.png",
"prompt": "请识别这张图中的文字，并描述主要内容"
}
```
### `vision_recognize_base64`
从 Base64 图片数据识别图片。
参数：
| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `image_base64` | 是 | Base64 编码图片，可以带 `data:image/png;base64,` 前缀 |
| `mime_type` | 否 | 图片 MIME 类型，例如 `image/png`、`image/jpeg` |
| `prompt` | 否 | 图片识别提示词 |
| `api_url` | 否 | 临时覆盖默认 API URL |
| `api_key` | 否 | 临时覆盖默认 API Key |
示例：
```json
{
"image_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
"mime_type": "image/png",
"prompt": "请描述图片内容"
}
```
### `vision_config`
查看当前视觉模型配置。该工具不会返回 API Key 明文，只会返回是否已配置 API Key。
## API 格式
### OpenAI 兼容格式
当 `api_format` 为 `openai` 时，请求体格式如下：
```json
{
"model": "gpt-4o",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "请描述这张图片的内容"
},
{
"type": "image_url",
"image_url": {
"url": "data:image/png;base64,..."
}
}
]
}
],
"max_tokens": 4096
}
```
### JSON Body 自定义格式
当 `api_format` 为 `json_body` 时，请求体格式如下：
```json
{
"model_id": "your-model-id",
"image": "base64...",
"mime_type": "image/png",
"prompt": "请描述这张图片的内容"
}
```
服务会优先从响应中的 `text`、`content`、`result` 字段提取结果。如果都不存在，则返回完整 JSON。
## 开发命令
格式化：
```powershell
cargo fmt
```
格式检查：
```powershell
cargo fmt --check
```
编译检查：
```powershell
cargo check
```
Release 打包：
```powershell
cargo build --release
```
## 安全建议
- 不要把真实 `api_key` 提交到 Git 仓库
- 推荐通过环境变量或本地未跟踪的 `config.json` 保存密钥
- `config.example.json` 只应保留示例密钥
## 更多文档
更详细的使用说明见 [USAGE.md](USAGE.md)。
