内容
<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>
---
> 一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，通过标准输入/输出为任何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 代码**，一行：
```bash
claude mcp add vision -- npx -y @three-ws/vision-mcp
```
**Claude 桌面版 / Cursor**（`claude_desktop_config.json` 或 `mcp.json`）：
```json
{
"mcpServers": {
"vision": {
"command": "npx",
"args": ["-y", "@three-ws/vision-mcp"]
}
}
}
```
使用MCP检查器检查界面：
```bash
npx -y @modelcontextprotocol/inspector npx @three-ws/vision-mcp
```
## 工具
| 工具 | 类型 | 功能 |
| ------------------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
| `analyze_image` | 只读 | 回答关于图像的提示 - 视觉问答，OCR（读取截图），分类或评论渲染。 |
| `describe_image` | 只读 | 用于替代文本或标题的自然语言描述，可通过详细程度和焦点进行控制。 |
| `get_vision_status` | 只读 | 报告视觉提供商是否在线以及接受哪些图像格式。无需图像，无需成本。 |
这三个工具都是只读的 - 它们查看图像，但永远不会存储或修改任何内容。VLM是非确定性的，并且实时提供商链会移动，因此没有一个是幂等的。
### 输入参数
**`analyze_image`** - `prompt`（必需），以及 `imageUrl`（公开的https）或 `image`（base64 / data 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 agents\"。",
"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 - 门控 "describe this" 功能
> {}
{
"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)。未经版权所有者明确书面许可，不得授予任何权利。
