内容
<p align="center">
<a href="https://three.ws"><img src="https://three.ws/three-ws-mcp-icon.svg" alt="three.ws" width="88" height="88"></a>
</p>
<h1 align="center">@three-ws/vision-mcp</h1>
<p align="center"><strong>让任何 AI 代理都能看到 — 通过 three.ws 视觉处理管道分析和描述图像，无需密钥，免费优先。</strong></p>
<p align="center">
<a href="https://www.npmjs.com/package/@three-ws/vision-mcp"><img alt="npm" src="https://img.shields.io/npm/v/@three-ws/vision-mcp?logo=npm&color=cb3837"></a>
<img alt="license" src="https://img.shields.io/npm/l/@three-ws/vision-mcp?color=3b82f6">
<img alt="node" src="https://img.shields.io/node/v/@three-ws/vision-mcp?color=339933&logo=node.js">
<a href="https://registry.modelcontextprotocol.io/?q=io.github.nirholas"><img alt="MCP Registry" src="https://img.shields.io/badge/MCP%20Registry-io.github.nirholas-0ea5e9"></a>
<a href="https://three.ws"><img alt="three.ws" src="https://img.shields.io/badge/built%20by-three.ws-000"></a>
</p>
---
> 一个 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，通过 stdio 为任何 AI 助手提供 **图像理解**。传递一个图像的公开 URL 或 base64 编码，代理可以读取截图中的文本，识别场景中的内容，评论 3D/头像渲染，或编写替代文本 — 所有操作均为实时，只读，无需密钥。
每个答案都来自 three.ws 视觉处理管道：**免费的 NVIDIA NIM 视觉模型引导每个请求**，并在它们后面自动使用服务器端的付费备份。调用者无需支付费用，也无需提供者密钥 — 只需将 `THREE_WS_BASE` 指向部署即可。
## 安装
```bash
npm install @three-ws/vision-mcp
```
或使用 `npx`（无需安装）：
```bash
npx @three-ws/vision-mcp
```
## 快速开始
**Claude Code**，一行命令：
```bash
claude mcp add vision -- npx -y @three-ws/vision-mcp
```
**Claude Desktop / Cursor**（`claude_desktop_config.json` 或 `mcp.json`）：
```json
{
"mcpServers": {
"vision": {
"command": "npx",
"args": ["-y", "@three-ws/vision-mcp"]
}
}
}
```
使用 MCP Inspector 检查表面：
```bash
npx -y @modelcontextprotocol/inspector npx @three-ws/vision-mcp
```
## 工具
| 工具 | 类型 | 功能 |
| ------------------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
| `analyze_image` | 只读 | 回答关于图像的提示 — 视觉 Q&A，OCR（读取截图），分类或评论渲染。 |
| `describe_image` | 只读 | 自然语言描述，用于替代文本或标题，可通过详细程度和焦点控制。 |
| `get_vision_status` | 只读 | 报告视觉提供者是否在线以及接受哪些图像格式。无需图像，无需成本。 |
所有三个工具都是只读的 — 它们查看图像，但从不存储或修改任何内容。VLM 是非确定性的，且实时提供者链会移动，因此都不是幂等的。
### 输入参数
**`analyze_image`** — `prompt`（必填），以及 `imageUrl`（公开的 https）或 `image`（base64 / 数据 URI）之一。可选 `imageType`（用于原始 base64），`maxTokens`（16–2048，默认为 512）。
**`describe_image`** — `imageUrl` 或 `image` 之一。可选 `imageType`，`detail`（`brief` | `standard` | `detailed`，默认为 `standard`），`focus`（强调的方面）。
**`get_vision_status`** — 无参数。
## 示例
```jsonc
// analyze_image — 读取截图中的文本
> { "imageUrl": "https://three.ws/render.png", "prompt": "横幅文本是什么？" }
{
"ok": true,
"text": "横幅显示 \"three.ws — 3D AI 代理\"。",
"provider": "nvidia",
"model": "nvidia/nemotron-nano-12b-v2-vl",
"prompt": "横幅文本是什么？",
"image_source": "url"
}
```
```jsonc
// describe_image — base64 图像的替代文本
> { "image": "data:image/png;base64,iVBORw0KG...", "detail": "brief" }
{
"ok": true,
"description": "一只海鸥在模糊的海岸背景下侧面图。",
"detail": "brief",
"provider": "nvidia",
"model": "nvidia/nemotron-nano-12b-v2-vl",
"image_source": "base64"
}
```
```jsonc
// get_vision_status — 门控 "描述此内容" 功能
> {}
{
"ok": true,
"configured": true,
"image_types": ["image/jpeg", "image/png", "image/webp", "image/gif"],
"max_image_mb": 12
}
```
图像可以是 JPEG、PNG、WebP 或 GIF，最高 **12 MB**。Base64 输入在上传前会在本地检查大小；`imageUrl` 必须是公开的 **https** URL（视觉服务器会获取它，因此私有/环回主机会被拒绝）。
## 定价和身份验证
**调用者无需支付费用，也无需密钥**。该平台首先在免费的 NVIDIA NIM 视觉通道上运行每个请求，并在其自己的基础设施上仅在付费模型上进行备份 — 该成本是平台的，对您透明。
端点按 IP 限制速率。要将您的限制提高到每个用户层，请设置可选的 `THREE_WS_API_KEY`（一个 three.ws API 密钥）；它作为承载令牌发送。永远不需要它来使用免费模型。
## 要求
- **Node.js >= 20.**
- 可以访问 `https://three.ws`（或您自己的 `THREE_WS_BASE`）。
### 环境变量
| 变量 | 必需 | 默认 | 目的 |
| --------------------- | -------- | ------------------ | ------------------------------------------------------------- |
| `THREE_WS_BASE` | 否 | `https://three.ws` | 调用哪个部署。 |
| `THREE_WS_TIMEOUT_MS` | 否 | `30000` | 每个请求的超时时间（调用可能跨免费通道）。 |
| `THREE_WS_API_KEY` | 否 | — | 可选的承载令牌，以将速率限制提高到每个用户。 |
## 链接
- 首页：https://three.ws
- 更新日志：https://three.ws/changelog
- 问题：https://github.com/nirholas/three.ws/issues
- 许可证：Apache-2.0 — 见 [LICENSE](./LICENSE)
---
<p align="center">
<sub>
three.ws SDK 套件的一部分 — 3D AI 代理、链上身份和代理支付。<br/>
<a href="https://three.ws">网站</a> · <a href="https://three.ws/changelog">更新日志</a> · <a href="https://github.com/nirholas/three.ws">GitHub</a>
</sub>
</p>
## 许可证
Copyright © 2026 nirholas. All rights reserved.
本软件是专有的 — 见 [LICENSE](./LICENSE)。未经版权所有者明确书面许可，不得授予任何权利。
