# VisionMcpServer

**Repository Path**: long2023/vision-mcp-server

## Basic Information

- **Project Name**: VisionMcpServer
- **Description**: 这是一个使用 .NET 10 和官方 MCP C# SDK (ModelContextProtocol.AspNetCore) 编写的原生 Model Context Protocol (MCP) 服务器。 它的核心功能是将兼容 OpenAI 格式的 Vision API 模型（例如 gpt-4o, qwen-vl 等）封装成一个原生的 analyze_image (图片分析) MCP 工具
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-20
- **Last Updated**: 2026-05-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 视觉大模型 MCP 服务器 (Vision MCP Server)

这是一个使用 .NET 10 和官方 [MCP C# SDK (ModelContextProtocol.AspNetCore)](https://www.nuget.org/packages/ModelContextProtocol.AspNetCore) 编写的原生 Model Context Protocol (MCP) 服务器。
它的核心功能是将兼容 OpenAI 格式的 Vision API 模型（例如 `gpt-4o`, `qwen-vl` 等）封装成一个原生的 `analyze_image` (图片分析) MCP 工具，并且**直接通过 HTTP/SSE 协议暴露远程端点**。

这使得像 Claude Code、Cline 这样纯文本类型的 AI Agent 客户端框架瞬间拥有处理和理解视觉图片的能力。

本应用作为一个原生的独立服务运行（自带 ASP.NET Core 宿主引擎），并内置了 API Key 防护机制防止恶意调用。

## 环境要求
* .NET 10 SDK（仅编译时需要）
* 一台用于部署的 Windows 或 Linux 远程服务器（如果编译选择了“包含自带运行时(Self-Contained)”，则部署机器上完全**不需要**安装 .NET）。

## 配置文件 (appsettings.json)

应用的各项参数通过可执行文件同目录下的 `appsettings.json` 进行控制。你可以随时自定义你的大模型厂商 Base URL、模型名称、API Key 凭证、绑定的端口，甚至是自定义追加的 HTTP 请求头。

```json
{
  "VisionService": {
    "BaseUrl": "https://api.openai.com/v1",
    "ApiKey": "YOUR_OPENAI_API_KEY",
    "ModelName": "gpt-4o",
    "Headers": {
      "X-Custom-Header": "MyValue"
    }
  },
  "Port": "5000"
}
```

## 一键编译说明

本项目内部已经配置好了用于一键自动化发布的 PowerShell 脚本，并且直接集成了 VS Code 任务（Task）。

### 在 VS Code 中编译（快捷键 `Ctrl+Shift+B`）
* **Publish Windows (Framework Dependent)** - 发布为依赖 .NET 10 的 Windows 程序。
* **Publish Windows (Self Contained)** - 将 .NET 运行时全部打包进单一可执行文件（推荐在不装环境的 Windows 服务器使用）。
* **Publish Linux (Framework Dependent)** - 发布为依赖 .NET 10 的 Linux 程序。
* **Publish Linux (Self Contained)** - 将 Linux 环境的 .NET 运行时打包进独立单文件（强烈推荐：用于无环境依赖部署到 Linux）。

或者使用命令行手动编译：
```bash
# 例如：编译Linux单文件版本
pwsh -File ./publish_scripts/publish.ps1 -Runtime linux-x64 -SelfContained $true
```

## 部署与运行

编译完成后，会在 `publish/` 目录下生成对应平台的输出文件夹（例如 `publish/linux-x64-sc/`）。该文件夹里包含了服务器二进制文件、基础配置、以及为你编写好的“傻瓜式一键运行脚本”。

### Windows 快速启动
1. 打开生成的 `win-x64-sc` 文件夹。
2. 双击运行 `run.bat`。
3. 脚本会提示你输入一个“远程访问密钥 (API Key)”，这是用来防止别人随意扫描你服务器上的 MCP 端口来蹭你的 Token 的。
4. 回车后，MCP 服务器会在 5000 端口启动。脚本最后会自动在控制台打印出一段 JSON，教你怎么配置你的 Agent 客户端。

### Linux 远程部署 (Systemd 守护进程守护模式)
1. 将打包好的 `linux-x64-sc` 文件夹上传到你的 Linux 远程服务器。
2. 在该文件夹下，以 Root 权限执行互动安装脚本：
```bash
sudo ./install.sh
```
3. 脚本会向你提出几个问题：
   - 你的视觉大模型服务商 Base URL 是多少？
   - 调用该大模型的 API Key 是什么？
   - 视觉大模型叫什么名字？（默认 gpt-4o）
   - **你希望给这个 MCP 代理设置什么密码保护？(Remote Access Key)**
4. 问答结束后，安装脚本会自动将所有文件拷贝至 `/opt/vision-mcp/` 目录，生成配置，并自动向系统注册一个名为 `vision-mcp.service` 的 systemd 守护进程并设置为开机自启。
5. 服务启动后，脚本会自动抓取你的服务器 IP，并在屏幕上打印出属于你的 Agent MCP 配置 JSON。

## Agent 客户端配置示例

启动你的远程 MCP 服务后，在你的 AI Agent 框架（如 Cline, Claude Code 等）中，找到 MCP 的配置区域（一般在全局配置或者项目配置里的 `mcpServers`），增加以下 HTTP/SSE 配置：

```json
{
  "mcpServers": {
    "remote-vision": {
      "url": "http://<你服务器的公网或内网IP>:5000/mcp",
      "transport": "sse",
      "headers": {
        "X-API-Key": "<你刚才设置的远程访问密码>"
      }
    }
  }
}
```