# https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp 项目说明书

生成时间：2026-06-01 16:38:20 UTC

## 目录

- [项目介绍](#page-introduction)
- [问题与解决方案](#page-problem-solution)
- [系统架构](#page-architecture)
- [MCP协议集成](#page-mcp-protocol)
- [核心工具：view_image](#page-view-image-tool)
- [图像处理与格式支持](#page-image-formats)
- [VS Code Copilot集成](#page-vscode-integration)
- [Claude Desktop集成](#page-claude-integration)
- [安装指南](#page-installation)
- [故障排除](#page-troubleshooting)

<a id='page-introduction'></a>

## 项目介绍

### 相关页面

相关主题：[问题与解决方案](#page-problem-solution), [系统架构](#page-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/README.md)
- [index.js](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/index.js)
</details>

# 项目介绍

## 项目概述

**InChat Image Viewer MCP** 是一个基于 Model Context Protocol (MCP) 的图像查看服务器，旨在解决 VS Code 中 GitHub Copilot Chat 无法直接查看本地文件路径图片的问题。该项目由 Ibrahim Oguntola 开发，采用 MIT 开源许可证发布。

### 核心价值定位

在日常开发工作中，开发者经常需要向 AI 助手展示截图、错误日志图片或调试信息。然而，传统方式存在以下痛点：

| 传统方式 | 局限性 |
|---------|--------|
| 直接发送文件路径 | AI 无法识别，只能看到纯文本 |
| 使用 `#file:` 引用 | 图片引用不可靠，附件为空 |
| 拖拽上传 | 需要手动操作，打断工作流程 |

本项目通过 MCP 协议让 AI 自动调用 `view_image` 工具，实现图片的内联显示，彻底消除手动操作的需求。

### 技术栈

本项目的技术实现基于以下组件：

- **运行时**：Node.js
- **MCP SDK**：@modelcontextprotocol/sdk
- **传输协议**：Stdio（标准输入输出）

资料来源：[README.md]()

---

## 功能特性

### 支持的图片格式

InChat Image Viewer MCP 支持以下图片格式的查看：

| 格式 | MIME 类型 | 文件扩展名 |
|------|----------|-----------|
| 便携式网络图形 | image/png | .png |
| JPEG 图片 | image/jpeg | .jpg, .jpeg |
| GIF 动画 | image/gif | .gif |
| 位图图片 | image/bmp | .bmp |
| WebP 图片 | image/webp | .webp |

资料来源：[index.js:32-38]()

### 核心工具：view_image

服务器提供一个名为 `view_image` 的 MCP 工具，其功能定义如下：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| file_path | string | 是 | 图片文件的绝对路径或相对路径 |

工具执行后返回包含两种内容的结果：文本描述（文件路径和字节大小）以及 Base64 编码的图片数据。

资料来源：[index.js:17-27]()

---

## 工作原理

### 系统架构

```mermaid
graph TD
    A[用户发送图片路径] --> B[MCP Server 接收请求]
    B --> C[读取本地图片文件]
    C --> D[转换为 Base64 编码]
    D --> E[识别 MIME 类型]
    E --> F[返回图片内容和元数据]
    F --> G[AI 助手内联显示图片]
```

### 工具调用流程

当用户向 Copilot Chat 发送图片路径时，系统执行以下步骤：

1. **请求解析**：服务器接收 `CallToolRequest` 类型的请求
2. **文件读取**：使用 Node.js 的 `fs/promises` 模块读取图片文件
3. **格式转换**：将二进制图片数据转换为 Base64 字符串
4. **类型识别**：根据文件扩展名确定对应的 MIME 类型
5. **结果返回**：构造包含 `text` 和 `image` 类型内容的响应

```mermaid
sequenceDiagram
    participant U as 用户
    participant AI as Copilot Chat
    participant MCP as MCP Server
    participant FS as 文件系统

    U->>AI: 发送图片路径
    AI->>MCP: 调用 view_image 工具
    MCP->>FS: 读取图片文件
    FS-->>MCP: 返回二进制数据
    MCP-->>AI: 返回 Base64 图片和元数据
    AI-->>U: 内联显示图片
```

### 错误处理机制

服务器实现了完善的错误处理流程：

| 场景 | 处理方式 |
|------|---------|
| 文件不存在 | 返回错误文本 `Error: ${error.message}`，isError 标记为 true |
| 未知工具调用 | 抛出 `Unknown tool` 异常 |
| 服务器启动失败 | 输出错误日志并以退出码 1 终止进程 |

资料来源：[index.js:53-62]()

---

## 使用方式

### 交互示例

**使用前（传统方式）**：

```
用户：Show me C:\screenshots\bug.png
AI 收到：<attachments></attachments>  <!-- 空附件 -->
```

**使用后（本工具）**：

```
用户：#image-viewer Show me C:\screenshots\bug.png
AI 自动调用：view_image 工具
结果：图片以内联方式显示
```

### 启动服务器

MCP Server 通过标准输入输出（Stdio）进行通信，启动时输出以下日志：

```javascript
console.error("Image Viewer MCP Server running on stdio");
```

服务器连接过程：

```mermaid
graph LR
    A[创建 Server 实例] --> B[配置 name 和 version]
    B --> C[注册工具处理程序]
    C --> D[创建 StdioServerTransport]
    D --> E[建立连接]
    E --> F[服务运行中]
```

资料来源：[index.js:65-72]()

---

## 文件结构

项目核心文件及功能说明：

| 文件 | 说明 |
|------|------|
| index.js | MCP 服务器主程序，处理所有工具调用和图片读取逻辑 |
| package.json | 项目配置和依赖声明 |

### 关键代码模块

服务器代码包含两个核心请求处理模块：

1. **ListToolsRequestSchema 处理器**：负责声明可用工具列表
2. **CallToolRequestSchema 处理器**：负责执行具体的工具逻辑

资料来源：[index.js:12-14]()

---

## 应用场景

### 适用场景

| 场景 | 描述 |
|------|------|
| 错误截图分析 | 快速分享调试截图给 AI 进行分析 |
| UI 视觉对比 | 向 AI 展示设计稿或界面截图获取反馈 |
| 日志图片解读 | 查看包含图形化日志或图表的信息 |
| 文档配图说明 | 在技术讨论中引用项目截图 |

### 非适用场景

- 远程服务器上的图片（需要先下载到本地）
- 超大图片文件（受限于消息大小限制）
- 受密码保护的图片文件

---

## 总结

InChat Image Viewer MCP 是一个轻量级但极具实用价值的 MCP 服务器，它桥接了本地文件系统与 AI 对话界面之间的鸿沟。通过自动化的工具调用机制，开发者可以在不中断工作流程的情况下，让 AI 助手直接"看到"本地图片内容。

该项目体现了 MCP 协议在扩展 AI 能力方面的灵活性，为类似的需求提供了一个可复用的解决方案。

---

<a id='page-problem-solution'></a>

## 问题与解决方案

### 相关页面

相关主题：[项目介绍](#page-introduction), [核心工具：view_image](#page-view-image-tool)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/README.md)
- [index.js](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/index.js)
</details>

# 问题与解决方案

## 项目背景

`inchat-image-viewer-mcp` 是一个基于 Model Context Protocol (MCP) 的图像查看服务器，旨在解决 VS Code Copilot Chat 中图片查看的工作流中断问题。该项目由 [Ibrahim Oguntola](https://github.com/OguntolaIbrahim) 开发，采用 MIT 许可证。

资料来源：[README.md:1]()

## 核心问题描述

### 当前工作流的局限性

在 VS Code Copilot Chat 环境中，存在多种图片查看方式，但大多数存在明显缺陷：

| 查看方式 | 示例 | 结果 | 可用性 |
|---------|------|------|--------|
| 纯文件路径 | `Show me C:\screenshots\bug.png` | AI 仅看到文本路径，无法显示图片 | ❌ 不可用 |
| `#file:` 引用 | `#file:screenshot.png` | 返回空的 `<attachments>`，AI 看不到任何内容 | ❌ 不可靠 |
| 拖放上传 | 手动拖拽文件到聊天窗口 | AI 以 base64 附件形式看到图片 | ✅ 可用但繁琐 |

资料来源：[README.md:3-10]()

### 问题根因分析

当用户直接提供文件路径时，Copilot Chat 的 `<attachments></attachments>` 标签为空，导致 AI 无法获取图像数据。用户在每次查看图片时都必须停止对话、手动拖拽文件、放下文件，然后重新提问。

```mermaid
graph LR
    A[用户请求分析图片] --> B[提供文件路径]
    B --> C{Copilot Chat处理}
    C --> D[返回空attachments]
    D --> E[AI仅识别文本路径]
    E --> F[用户必须手动拖放]
    F --> G[中断工作流程]
```

资料来源：[README.md:11-14]()

## 解决方案架构

### MCP 服务器设计

本项目通过实现 MCP 协议服务器，为 AI 提供 `view_image` 工具，使其能够主动读取并显示图像文件。

```mermaid
graph TD
    A[用户输入文件路径] --> B[MCP Server接收请求]
    B --> C[读取图像文件]
    C --> D[转换为Base64编码]
    D --> E[识别MIME类型]
    E --> F[返回图像数据给AI]
    F --> G[AI内联显示图片]
```

资料来源：[index.js:1-75]()

### 技术实现要点

#### 工具定义

`view_image` 工具接受单个参数 `file_path`，支持绝对路径和相对路径：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `file_path` | string | 是 | 图像文件的绝对或相对路径 |

资料来源：[index.js:15-26]()

#### 支持的图片格式

服务器通过文件扩展名映射 MIME 类型，支持以下格式：

| 扩展名 | MIME 类型 |
|--------|-----------|
| `.png` | image/png |
| `.jpg` / `.jpeg` | image/jpeg |
| `.gif` | image/gif |
| `.bmp` | image/bmp |
| `.webp` | image/webp |

资料来源：[index.js:35-47]()

### 工作流程对比

#### 无 MCP 时的流程

```mermaid
graph LR
    A1[用户输入] --> B1[分析 C:\test-results\failure.png]
    B1 --> C1[AI收到空attachments]
    C1 --> D1[用户手动拖放图片]
    D1 --> E1[重新请求分析]
    E1 --> F1[AI才能看到图片]
```

资料来源：[README.md:17-24]()

#### 使用 MCP 后的流程

```mermaid
graph LR
    A2[用户输入] --> B2[#image-viewer 分析 C:\screenshots\bug.png]
    B2 --> C2[AI自动调用view_image工具]
    C2 --> D2[服务器读取并转换图片]
    D2 --> E2[返回base64图像数据]
    E2 --> F2[AI内联显示图片]
```

资料来源：[README.md:26-30]()

## 错误处理机制

服务器实现了完善的异常捕获机制，当文件读取失败时返回结构化的错误响应：

```javascript
catch (error) {
  return {
    content: [
      {
        type: "text",
        text: `Error: ${error.message}`,
      },
    ],
    isError: true,
  };
}
```

资料来源：[index.js:57-64]()

### 错误响应格式

| 字段 | 类型 | 说明 |
|------|------|------|
| `content` | array | 包含错误信息的文本对象数组 |
| `content[0].type` | string | 固定值 `"text"` |
| `content[0].text` | string | 错误消息内容 |
| `isError` | boolean | 标识为错误响应 |

## 部署与运行

### 服务器启动

服务器通过标准输入输出（stdio）进行通信，这是 MCP 协议的标准传输方式：

```javascript
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Image Viewer MCP Server running on stdio");
}
```

资料来源：[index.js:67-72]()

### 依赖项

| 依赖包 | 用途 |
|--------|------|
| `@modelcontextprotocol/sdk` | MCP 协议实现，包含服务器和传输层 |
| Node.js 原生模块 | 文件读取（`fs/promises`）、路径处理（`path`） |

## 总结

`inchat-image-viewer-mcp` 通过 MCP 协议桥接了文件系统和 AI 对话系统，将传统的"手动拖放"工作流转变为"AI 自动调用"的智能流程。该方案无需用户中断对话思维，即可实现图片的即时查看与分析。

资料来源：[README.md:1-30](), [index.js:1-75]()

---

<a id='page-architecture'></a>

## 系统架构

### 相关页面

相关主题：[MCP协议集成](#page-mcp-protocol), [核心工具：view_image](#page-view-image-tool)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [index.js](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/index.js)
- [README.md](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/README.md)
</details>

# 系统架构

## 概述

inchat-image-viewer-mcp 是一个基于 Model Context Protocol (MCP) 的图像查看服务器，旨在解决 VS Code Copilot Chat 无法直接通过文件路径查看图像的问题。该项目采用轻量级架构设计，通过标准输入/输出（stdio）传输协议与 AI 助手通信，使用户能够通过提供图像文件路径让 AI 直接"看到"图像内容。

## 架构设计原则

| 原则 | 说明 |
|------|------|
| 零依赖通信 | 使用 stdio 传输层，无需网络配置 |
| 单一职责 | 仅负责图像读取和格式转换 |
| 工具驱动 | 基于 MCP 工具调用机制 |
| 错误隔离 | 独立的错误处理和返回机制 |

## 核心组件

### 1. MCP 服务器

服务器是整个系统的核心入口，基于 `@modelcontextprotocol/sdk` 构建，负责处理来自 AI 客户端的所有请求。

```javascript
const server = new Server(
  {
    name: "image-viewer",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
    },
  }
);
```

**服务器配置参数：**

| 参数 | 值 | 说明 |
|------|-----|------|
| name | "image-viewer" | 服务器标识名称 |
| version | "1.0.0" | 协议版本号 |
| capabilities.tools | {} | 声明工具能力 |

资料来源：[index.js:13-21]()

### 2. 传输层

采用 `StdioServerTransport` 实现标准输入/输出通信，这是一种进程间通信机制，适用于命令行环境下的父子进程交互。

```javascript
const transport = new StdioServerTransport();
await server.connect(transport);
```

资料来源：[index.js:82-84]()

### 3. 工具处理系统

#### 3.1 工具列表处理器

`ListToolsRequestSchema` 处理程序负责向 AI 客户端声明可用的工具及其输入参数模式。

```javascript
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "view_image",
        description: "Display an image from a file path inline in the chat...",
        inputSchema: {
          type: "object",
          properties: {
            file_path: {
              type: "string",
              description: "Absolute or relative path to the image file",
            },
          },
          required: ["file_path"],
        },
      },
    ],
  };
});
```

**工具参数定义：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| file_path | string | 是 | 图像文件的绝对或相对路径 |

资料来源：[index.js:24-49]()

#### 3.2 工具执行处理器

`CallToolRequestSchema` 处理程序负责执行具体的工具逻辑，包括图像读取、格式检测和数据转换。

资料来源：[index.js:52-80]()

## 系统架构图

```mermaid
graph TD
    A[AI 客户端] -->|stdio 通信| B[MCP Server]
    B --> C[ListToolsRequestSchema]
    B --> D[CallToolRequestSchema]
    D --> E[读取图像文件]
    E --> F[base64 编码]
    F --> G[MIME 类型检测]
    G --> H[返回图像数据]
    A -->|"#image-viewer<br>file_path|", I[用户请求]
    I --> D
```

## 工作流程

### 图像查看完整流程

```mermaid
sequenceDiagram
    participant User as 用户
    participant AI as AI 客户端
    participant MCP as MCP Server
    participant FS as 文件系统

    User->>AI: #image-viewer /path/to/image.png
    AI->>MCP: ListToolsRequest
    MCP-->>AI: 返回工具列表
    AI->>MCP: CallToolRequest (view_image)
    MCP->>FS: readFile(file_path)
    FS-->>MCP: 原始图像数据
    MCP->>MCP: 转换为 base64
    MCP->>MCP: 检测 MIME 类型
    MCP-->>AI: {content: [text, image]}
    AI-->>User: 显示图像
```

### 请求处理流程

| 步骤 | 组件 | 操作 |
|------|------|------|
| 1 | ListToolsRequestSchema | 声明 view_image 工具 |
| 2 | CallToolRequestSchema | 接收 file_path 参数 |
| 3 | readFile | 读取磁盘文件 |
| 4 | extname | 提取文件扩展名 |
| 5 | mimeMap | 映射 MIME 类型 |
| 6 | toString("base64") | 编码图像数据 |
| 7 | 返回响应 | 输出 text 和 image 内容 |

资料来源：[index.js:52-79]()

## 数据流

```mermaid
graph LR
    A[file_path<br>字符串] --> B[readFile<br>Buffer]
    B --> C[toString base64<br>base64 字符串]
    D[.png/.jpg/.gif<br>文件扩展名] --> E[mimeMap<br>MIME 类型]
    C --> F[返回内容]
    E --> F
```

## 图像格式支持

| 扩展名 | MIME 类型 | 状态 |
|--------|-----------|------|
| .png | image/png | ✅ 支持 |
| .jpg | image/jpeg | ✅ 支持 |
| .jpeg | image/jpeg | ✅ 支持 |
| .gif | image/gif | ✅ 支持 |
| .bmp | image/bmp | ✅ 支持 |
| .webp | image/webp | ✅ 支持 |

资料来源：[index.js:56-63]()

## 响应数据结构

### 成功响应

```javascript
{
  content: [
    {
      type: "text",
      text: "Image: /path/to/image.png (102400 bytes)"
    },
    {
      type: "image",
      data: "iVBORw0KGgoAAAANSUhEUg...", // base64 数据
      mimeType: "image/png"
    }
  ]
}
```

### 错误响应

```javascript
{
  content: [
    {
      type: "text",
      text: "Error: ENOENT: no such file or directory..."
    }
  ],
  isError: true
}
```

资料来源：[index.js:65-80]()

## 服务器生命周期

```mermaid
graph TD
    A[启动] --> B[创建 StdioServerTransport]
    B --> C[连接服务器到传输层]
    C --> D[输出日志: Image Viewer MCP Server running on stdio]
    D --> E[等待请求]
    E -->|收到请求| F[路由到对应 Handler]
    F --> E
    E -->|发生错误| G[输出错误日志并退出]
```

资料来源：[index.js:82-89]()

## 技术栈

| 层级 | 技术 | 版本 | 用途 |
|------|------|------|------|
| 运行时 | Node.js | - | JavaScript 运行环境 |
| SDK | @modelcontextprotocol/sdk | - | MCP 协议实现 |
| 传输 | @modelcontextprotocol/sdk/server/stdio | - | stdio 传输层 |
| 类型 | @modelcontextprotocol/sdk/types | - | MCP 类型定义 |

## 错误处理机制

系统采用独立的错误捕获机制，确保任何文件读取失败都会返回结构化的错误信息：

1. **文件不存在**：`ENOENT` 错误被捕获并返回友好提示
2. **权限不足**：返回系统错误信息
3. **格式不支持**：使用默认 `image/png` MIME 类型

所有错误响应都包含 `isError: true` 标记，便于 AI 客户端识别并向用户展示错误信息。

资料来源：[index.js:66-80]()

## 架构优势

| 优势 | 说明 |
|------|------|
| 简单性 | 单文件实现，代码量约 90 行 |
| 兼容性 | 通过 stdio 通信，适配任何支持 MCP 的 AI 客户端 |
| 可靠性 | 完善的错误处理和用户反馈 |
| 可扩展性 | 可轻松添加更多工具（如 view_pdf、view_video 等） |

## 与传统方案的对比

| 方案 | 工作流程 | 用户体验 |
|------|----------|----------|
| 传统手动拖拽 | 停止对话 → 拖拽文件 → 继续对话 | 中断感强，效率低 |
| InChat Image Viewer MCP | 直接发送文件路径 → AI 自动调用工具 | 流程顺畅，体验佳 |

资料来源：[README.md]()

## 部署架构

```mermaid
graph LR
    A[VS Code<br>Copilot Chat] --> B[stdio]
    B --> C[image-viewer-mcp<br>进程]
    C --> D[本地文件系统]
```

用户只需在 Copilot Chat 配置中注册该 MCP 服务器，即可在对话中直接使用 `#image-viewer` 指令查看图像。

---

<a id='page-mcp-protocol'></a>

## MCP协议集成

### 相关页面

相关主题：[系统架构](#page-architecture), [核心工具：view_image](#page-view-image-tool)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [index.js](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/index.js)
</details>

# MCP协议集成

## 概述

MCP（Model Context Protocol，模型上下文协议）是一种标准化通信协议，用于在AI助手与外部工具之间建立可靠的连接通道。inchat-image-viewer-mcp 项目通过集成 MCP 协议，使 AI 能够直接通过文件路径访问并展示图像内容，无需用户手动拖拽操作。

该项目实现了一个轻量级的 MCP 服务器，专门用于图像查看功能。服务器通过标准输入/输出（stdio）传输层与 AI 客户端通信，支持 `view_image` 工具调用。

资料来源：[index.js:1-18]()

## 技术架构

### 系统组件

| 组件名称 | 来源/依赖 | 功能描述 |
|---------|----------|---------|
| `@modelcontextprotocol/sdk` | npm 包 | 提供 MCP 服务器核心框架 |
| Server | SDK | 协议通信主控制器 |
| StdioServerTransport | SDK | 标准输入/输出传输层实现 |
| ListToolsRequestSchema | SDK | 工具列表请求处理器 |
| CallToolRequestSchema | SDK | 工具调用请求处理器 |

资料来源：[index.js:3-11]()

### 架构图

```mermaid
graph TD
    A[AI 客户端] <-->|stdio 通信| B[MCP 服务器]
    B --> C[Server 实例]
    C --> D[工具注册]
    C --> E[请求处理]
    D --> F[view_image 工具]
    E --> G[文件读取]
    E --> H[Base64 编码]
    G --> I[文件系统]
    H --> J[MIME 类型检测]
    J --> K[图像响应]
```

## 服务器初始化

### 创建服务器实例

服务器通过 `Server` 类构造函数进行初始化，传入服务元数据和能力配置：

```javascript
const server = new Server(
  {
    name: "image-viewer",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
    },
  }
);
```

**参数说明：**

| 参数 | 类型 | 说明 |
|-----|------|------|
| name | string | 服务器标识名称：`image-viewer` |
| version | string | 协议版本：`1.0.0` |
| capabilities.tools | object | 声明工具调用能力（空对象表示支持工具） |

资料来源：[index.js:13-23]()

### 启动机制

服务器使用异步 `main()` 函数启动，通过 `StdioServerTransport` 建立通信连接：

```javascript
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Image Viewer MCP Server running on stdio");
}
```

启动流程采用标准错误流输出状态信息，确保与标准输出的 JSON-RPC 响应分离。

资料来源：[index.js:73-79]()

## 工具定义与注册

### 工具列表接口

MCP 协议通过 `ListToolsRequestSchema` 定义服务器提供的工具列表。当 AI 客户端请求可用工具时，服务器返回工具清单：

```javascript
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "view_image",
        description: "Display an image from a file path inline in the chat. Supports PNG, JPEG, GIF, BMP, WebP.",
        inputSchema: {
          type: "object",
          properties: {
            file_path: {
              type: "string",
              description: "Absolute or relative path to the image file",
            },
          },
          required: ["file_path"],
        },
      },
    ],
  };
});
```

**工具定义参数：**

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| name | string | 是 | 工具唯一标识符：`view_image` |
| description | string | 是 | 工具功能描述文本 |
| inputSchema.type | string | 是 | JSON Schema 类型：`object` |
| inputSchema.properties.file_path | object | 是 | 文件路径参数定义 |
| inputSchema.required | array | 是 | 必填参数列表 |

资料来源：[index.js:26-51]()

## 工具调用处理

### 请求处理流程

```mermaid
graph TD
    A[CallToolRequest 请求] --> B{工具名称检查}
    B -->|view_image| C[获取 file_path]
    C --> D[读取文件数据]
    D --> E{文件存在?}
    E -->|是| F[Base64 编码]
    E -->|否| G[返回错误信息]
    F --> H[检测 MIME 类型]
    H --> I[构建响应内容]
    I --> J[返回图像 + 文本]
    B -->|未知工具| K[抛出异常]
```

### 图像读取与编码

工具处理器通过 `fs/promises` 模块读取图像文件：

```javascript
const imageData = await readFile(filePath);
const base64Image = imageData.toString("base64");
```

文件读取使用异步 API，确保服务器在处理大文件时不会阻塞通信。

资料来源：[index.js:54-55]()

### MIME 类型映射

根据文件扩展名自动识别图像格式：

| 扩展名 | MIME 类型 |
|-------|----------|
| .png | image/png |
| .jpg | image/jpeg |
| .jpeg | image/jpeg |
| .gif | image/gif |
| .bmp | image/bmp |
| .webp | image/webp |
| 其他 | image/png（默认） |

```javascript
const mimeMap = {
  ".png": "image/png",
  ".jpg": "image/jpeg",
  ".jpeg": "image/jpeg",
  ".gif": "image/gif",
  ".bmp": "image/bmp",
  ".webp": "image/webp",
};
const mimeType = mimeMap[ext] || "image/png";
```

资料来源：[index.js:57-70]()

### 响应格式

MCP 协议支持返回多种内容类型的响应。服务器返回包含文本和图像的复合响应：

```javascript
return {
  content: [
    {
      type: "text",
      text: `Image: ${filePath} (${imageData.length.toLocaleString()} bytes)`,
    },
    {
      type: "image",
      data: base64Image,
      mimeType: mimeType,
    },
  ],
};
```

**响应结构：**

| 字段 | 类型 | 说明 |
|-----|------|------|
| content | array | 内容数组 |
| content[0].type | string | 固定值：`text` |
| content[0].text | string | 文件路径和大小信息 |
| content[1].type | string | 固定值：`image` |
| content[1].data | string | Base64 编码的图像数据 |
| content[1].mimeType | string | 图像 MIME 类型 |

资料来源：[index.js:72-84]()

### 错误处理

文件不存在或其他 IO 错误时，返回错误格式的文本响应：

```javascript
return {
  content: [
    {
      type: "text",
      text: `Error: ${error.message}`,
    },
  ],
  isError: true,
};
```

错误响应通过 `isError: true` 标记，使 AI 客户端能够识别并向用户呈现错误信息。

资料来源：[index.js:86-94]()

## 通信协议

### 标准输入/输出传输

项目采用 `StdioServerTransport` 实现进程间通信：

- **标准输入（stdin）**：接收来自 AI 客户端的 JSON-RPC 请求
- **标准输出（stdout）**：发送 JSON-RPC 响应
- **标准错误（stderr）**：输出服务器日志和调试信息

```javascript
console.error("Image Viewer MCP Server running on stdio");
```

资料来源：[index.js:78]()

### JSON-RPC 消息格式

MCP 协议基于 JSON-RPC 2.0 规范，主要包含两种消息类型：

| 消息类型 | 用途 | 标识 |
|---------|------|------|
| requests/list_tools | 获取可用工具列表 | ListToolsRequestSchema |
| notifications/initialized | 初始化完成通知 | - |
| requests/call_tool | 调用指定工具 | CallToolRequestSchema |

## 依赖项

| 依赖包 | 版本 | 用途 |
|-------|------|------|
| @modelcontextprotocol/sdk | latest | MCP 协议 SDK |
| node | ≥16 | 运行环境 |

导入语句使用 ES Module 语法：

```javascript
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
import { readFile } from "fs/promises";
import { extname } from "path";
```

资料来源：[index.js:3-7]()

## 使用场景

### 集成到 VS Code Copilot Chat

1. 安装并配置 MCP 服务器
2. 在对话中引用图像文件路径
3. AI 自动调用 `view_image` 工具
4. 用户直接在聊天界面查看图像

### 工作流程对比

**无 MCP 集成时：**
```
用户：分析 C:\test\failure.png
AI 收到：<attachments></attachments>  <!-- 空附件 -->
```

**有 MCP 集成时：**
```
用户：分析 C:\test\failure.png
AI 调用：view_image 工具
AI 收到：完整图像数据
```

## 扩展建议

| 扩展方向 | 说明 |
|---------|------|
| 缩略图生成 | 添加 `thumbnail` 参数，支持生成预览图 |
| 批量处理 | 支持 `file_paths` 数组参数 |
| 格式转换 | 添加目标格式参数，动态转换图像编码 |
| 元数据提取 | 返回 EXIF、尺寸等附加信息 |

## 版本信息

| 项目 | 版本 |
|-----|------|
| MCP 服务器 | 1.0.0 |
| 协议版本 | JSON-RPC 2.0 |
| SDK | @modelcontextprotocol/sdk |

资料来源：[index.js:18, 22]()

---

<a id='page-view-image-tool'></a>

## 核心工具：view_image

### 相关页面

相关主题：[系统架构](#page-architecture), [图像处理与格式支持](#page-image-formats)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [index.js](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/index.js)
</details>

# 核心工具：view_image

## 概述

`view_image` 是 **InChat Image Viewer MCP** 项目的核心工具，扮演着桥梁角色，将本地文件系统中的图像路径转换为 AI 聊天界面可识别的内联图像显示。该工具基于 Model Context Protocol (MCP) 实现，通过标准输入/输出（stdio）通信机制与 AI 客户端集成，使用户能够在对话中直接通过文件路径引用图像，而无需手动拖拽操作。

从架构层面而言，`view_image` 解决了 GitHub Copilot Chat 等 AI 助手无法直接读取本地文件路径的痛点。当用户发送图像路径时，该工具自动完成文件读取、格式识别和 base64 编码，最终将图像数据以 MCP 协议规定的结构化格式返回给 AI 客户端，实现图像的即时可视化展示。

## 工作原理

### 通信协议

该工具运行在 **StdioServerTransport** 传输层之上，这是一种通过标准输入输出流进行进程间通信的机制。MCP 协议定义了两种核心请求类型：

| 请求类型 | 用途 |
|---------|------|
| `ListToolsRequestSchema` | 向客户端声明可用工具列表及其元数据 |
| `CallToolRequestSchema` | 处理客户端对特定工具的实际调用请求 |

服务器初始化时注册这两个请求处理器，分别负责工具发现和工具执行两个阶段。

### 执行流程

```mermaid
graph TD
    A[用户发送图像路径] --> B[MCP客户端调用view_image工具]
    B --> C[服务器接收file_path参数]
    C --> D[readFile读取文件数据]
    D --> E{文件是否存在?}
    E -->|是| F[提取文件扩展名]
    E -->|否| G[返回错误信息]
    F --> H[映射MIME类型]
    H --> I[base64编码图像数据]
    I --> J[构建MCP响应结构]
    J --> K[返回text + image内容]
```

### 图像处理机制

工具接收到文件路径后，依次执行以下处理步骤：

**第一步：文件读取**

使用 Node.js 的 `fs/promises` 模块异步读取文件内容：

```javascript
const imageData = await readFile(filePath);
```

**第二步：MIME 类型映射**

通过文件扩展名确定图像的 MIME 类型，支持的格式映射关系如下：

| 扩展名 | MIME 类型 |
|-------|----------|
| `.png` | `image/png` |
| `.jpg` / `.jpeg` | `image/jpeg` |
| `.gif` | `image/gif` |
| `.bmp` | `image/bmp` |
| `.webp` | `image/webp` |

默认值设为 `image/png`，当遇到未知扩展名时使用该默认值。

**第三步：Base64 编码**

将原始二进制图像数据转换为 base64 字符串，便于通过文本协议传输：

```javascript
const base64Image = imageData.toString("base64");
```

**第四步：响应构建**

返回符合 MCP 协议规范的 `CallToolResult` 结构，包含两种内容类型：

- `type: "text"` - 显示文件路径和字节大小
- `type: "image"` - 包含 base64 数据和 MIME 类型

## 工具定义

### 输入参数

`view_image` 工具的输入模式定义为：

```javascript
inputSchema: {
  type: "object",
  properties: {
    file_path: {
      type: "string",
      description: "Absolute or relative path to the image file"
    }
  },
  required: ["file_path"]
}
```

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| `file_path` | string | 是 | 图像文件的绝对路径或相对路径 |

### 输出结构

成功响应包含 `content` 数组，元素定义如下：

```javascript
{
  content: [
    { type: "text", text: "Image: {filePath} ({size} bytes)" },
    { type: "image", data: "{base64String}", mimeType: "{mimeType}" }
  ]
}
```

错误响应格式：

```javascript
{
  content: [{ type: "text", text: "Error: {errorMessage}" }],
  isError: true
}
```

## 服务器架构

### 组件关系

```mermaid
graph LR
    subgraph MCP生态
        A[AI客户端] <-->|Stdio| B[InChat Image Viewer服务器]
    end
    subgraph 服务器内部
        B --> C[Server实例]
        C --> D[ListToolsHandler]
        C --> E[CallToolHandler]
        D --> F[view_image工具定义]
        E --> G[图像处理逻辑]
    end
    subgraph 文件系统
        G --> H[读取图像文件]
    end
```

### 服务器配置

| 配置项 | 值 |
|-------|-----|
| 服务名称 | `image-viewer` |
| 版本号 | `1.0.0` |
| 传输方式 | StdioServerTransport |
| 能力声明 | `tools: {}` |

服务器通过 `main()` 函数异步启动，连接成功后向 stderr 输出启动日志：

```javascript
console.error("Image Viewer MCP Server running on stdio");
```

## 错误处理机制

工具内置完善的异常捕获机制，处理以下常见错误场景：

| 错误类型 | 用户看到的提示 |
|---------|---------------|
| 文件不存在 | `Error: ENOENT: no such file or directory...` |
| 路径权限不足 | `Error: EACCES: permission denied...` |
| 无效路径格式 | `Error: ...`（系统错误信息） |

所有错误均通过 `isError: true` 标记返回，确保 AI 客户端能够正确识别处理失败的情况。

## 使用场景

### 适用场景

- 分析测试失败的截图：`"#image-viewer 查看 D:\projects\test-failures\2026-01-20.png"`
- 审查设计稿：`"#image-viewer 审查这个 UI 截图"`
- 调试可视化数据：`"#image-viewer 分析这张错误页面截图"`

### 不适用场景

- 非图像文件路径（会尝试以图像方式处理，导致显示异常）
- 需要 AI 进行 OCR 识别的文档（应使用专门的 OCR 工具）
- 动态生成的图像（需要先生成再调用本工具）

## 技术约束

1. **文件大小限制**：受限于 MCP 协议的通信机制，超大图像可能导致传输超时
2. **路径格式**：支持 Windows 风格路径和 Unix 风格路径
3. **相对路径解析**：相对路径基于服务器进程的当前工作目录
4. **安全考量**：该工具可读取服务器进程有权限访问的任意文件，应在可信环境中使用

## 相关资源

- 项目仓库：[OguntolaIbrahim/inchat-image-viewer-mcp](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp)
- 许可证：MIT
- 作者：Ibrahim Oguntola

---

<a id='page-image-formats'></a>

## 图像处理与格式支持

### 相关页面

相关主题：[核心工具：view_image](#page-view-image-tool), [故障排除](#page-troubleshooting)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [index.js](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/index.js)
</details>

# 图像处理与格式支持

## 概述

图像处理与格式支持模块是 InChat Image Viewer MCP 的核心功能模块，负责实现从本地文件系统读取图像文件并将其转换为 AI 聊天界面可显示的 base64 数据格式。该模块作为 Model Context Protocol（MCP）服务器的一部分运行，通过 `view_image` 工具为 AI 提供图像内联显示能力，消除了用户在 VS Code Copilot Chat 中必须手动拖拽图像的繁琐操作。

该模块的设计目标明确：接收图像文件的绝对路径或相对路径，读取文件内容，识别文件格式，确定对应的 MIME 类型，最终将图像数据以结构化格式返回给 MCP 协议层。整个处理流程对用户透明，用户只需提供文件路径即可获得图像的内联预览效果。

## 功能架构

### 核心组件

图像处理模块的架构相对简洁，核心逻辑集中在一个 JavaScript 文件中。模块采用 Node.js 原生 API 进行文件 I/O 操作，使用 `fs/promises` 模块提供异步文件读取能力。图像格式识别依赖于 `path` 模块的 `extname` 函数提取文件扩展名，随后通过预定义的 MIME 类型映射表确定正确的 MIME 类型。

模块采用 MCP 协议规范定义工具接口，通过 `ListToolsRequestSchema` 声明可用的工具，通过 `CallToolRequestSchema` 处理工具调用请求。这种设计确保了与 MCP 生态系统的完全兼容性。

### 数据流向

```mermaid
graph TD
    A[用户请求: 文件路径] --> B[view_image 工具调用]
    B --> C[读取文件: readFile]
    C --> D{文件是否存在?}
    D -- 否 --> E[返回错误信息]
    D -- 是 --> F[提取文件扩展名]
    F --> G[映射 MIME 类型]
    G --> H[Base64 编码图像数据]
    H --> I[构建 MCP 响应结构]
    I --> J[返回 content 数组]
```

## 支持的图像格式

### 格式映射表

MCP 服务器支持多种常见的图像格式，每种格式都通过精确的 MIME 类型映射确保在浏览器和 AI 界面中的正确渲染。以下是当前版本支持的完整格式列表：

| 文件扩展名 | MIME 类型 | 支持状态 |
|-----------|-----------|---------|
| `.png` | `image/png` | ✅ 完全支持 |
| `.jpg` | `image/jpeg` | ✅ 完全支持 |
| `.jpeg` | `image/jpeg` | ✅ 完全支持 |
| `.gif` | `image/gif` | ✅ 完全支持 |
| `.bmp` | `image/bmp` | ✅ 完全支持 |
| `.webp` | `image/webp` | ✅ 完全支持 |

### MIME 类型映射实现

映射逻辑通过一个静态对象 `mimeMap` 实现，该对象将文件扩展名（包含点号）作为键，对应的标准 MIME 类型作为值。实现代码如下：

```javascript
const mimeMap = {
  ".png": "image/png",
  ".jpg": "image/jpeg",
  ".jpeg": "image/jpeg",
  ".gif": "image/gif",
  ".bmp": "image/bmp",
  ".webp": "image/webp",
};
const mimeType = mimeMap[ext] || "image/png";
```

资料来源：[index.js:57-64]()

值得注意的是，当遇到未在映射表中定义的格式时，系统默认使用 `image/png` 作为回退值。这种设计提供了基本的容错能力，但可能导致非 PNG 格式的图像无法正确显示，因此建议用户仅使用表中列出的受支持格式。

## 图像处理流程

### 文件读取阶段

图像处理的第一步是读取目标文件。模块使用 Node.js 的 `fs/promises.readFile` 函数以异步方式读取文件内容，避免阻塞事件循环。该函数的调用传入用户提供的 `file_path` 参数，该参数可以是绝对路径或相对路径，相对路径相对于 MCP 服务器的工作目录解析。

文件读取操作包装在 try-catch 块中，以处理可能出现的各类异常情况，包括文件不存在、权限不足或路径格式错误等。异步读取确保了即使处理大型图像文件时，服务器仍能保持响应能力。

### 数据转换阶段

读取完成的原始二进制图像数据需要经过两个关键转换步骤：

1. **Base64 编码转换**：使用 `Buffer` 对象的 `toString('base64')` 方法将二进制数据转换为 Base64 字符串格式。Base64 是一种基于 64 个可打印 ASCII 字符表示二进制数据的编码方式，非常适合在 JSON 协议中传输二进制内容。

2. **MIME 类型识别**：通过 `path.extname` 函数提取文件扩展名，将其转换为小写后查询 MIME 映射表获取对应的 MIME 类型字符串。

### 响应构建阶段

处理完成的图像数据通过 MCP 协议规定的内容结构返回。MCP 响应包含一个 `content` 数组，数组中的每个元素代表一种类型的内容块。当前实现返回两种内容块：

- **文本内容块**：包含文件路径和以本地化格式显示的文件大小（字节数）
- **图像内容块**：包含 Base64 编码的图像数据和对应的 MIME 类型

这种双重内容结构确保即使客户端不支持内联图像显示，也能向用户展示有关图像的基本文本信息。

## 工具接口规范

### view_image 工具定义

`view_image` 是 MCP 服务器暴露的唯一工具，其完整的接口定义如下：

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| `file_path` | string | 是 | 图像文件的绝对路径或相对路径 |

工具描述为：`Display an image from a file path inline in the chat. Supports PNG, JPEG, GIF, BMP, WebP.`

资料来源：[index.js:32-47]()

### 响应数据结构

成功响应的结构如下：

```json
{
  "content": [
    {
      "type": "text",
      "text": "Image: /path/to/image.png (1,234,567 bytes)"
    },
    {
      "type": "image",
      "data": "<base64_encoded_string>",
      "mimeType": "image/png"
    }
  ]
}
```

错误响应的结构如下：

```json
{
  "content": [
    {
      "type": "text",
      "text": "Error: <error_message>"
    }
  ],
  "isError": true
}
```

资料来源：[index.js:80-90]()

## 错误处理机制

### 异常捕获策略

模块采用集中式异常处理策略，所有可能抛出异常的代码路径都包裹在 try-catch 块中。当异常发生时，函数返回一个包含错误信息的文本内容块，并将 `isError` 标志设置为 `true`。这种设计遵循了 MCP 协议的错误报告规范。

### 常见错误场景

| 错误场景 | 错误消息示例 | 处理方式 |
|---------|-------------|---------|
| 文件不存在 | `ENOENT: no such file or directory` | 返回错误内容块 |
| 路径格式错误 | `Invalid path` | 返回错误内容块 |
| 读取权限不足 | `EACCES: permission denied` | 返回错误内容块 |
| 文件被占用 | `EBUSY: resource busy or locked` | 返回错误内容块 |

## 技术实现细节

### Buffer 处理

文件读取操作返回的 `Buffer` 对象是 Node.js 中处理二进制数据的核心类型。转换 Base64 时使用 `toString('base64')` 方法，该方法高效地将整个缓冲区内容编码为单个 Base64 字符串。对于超大图像文件，此操作会占用相应大小的内存，但当前实现未提供流式处理或分块编码的支持。

### 扩展名标准化

文件扩展名的处理包含两个标准化步骤：首先使用 `extname` 提取带点号的扩展名，然后将结果转换为小写以确保大小写不敏感的文件名匹配。这种处理方式确保了 `.PNG`、`.Png` 和 `.png` 等变体都能被正确识别。

## 使用示例

### 基本调用

用户可以通过以下方式调用图像查看工具：

```
#image-viewer Show me C:\screenshots\bug.png
```

服务器接收到请求后，执行完整的处理流程，最终返回包含图像内容和元数据的响应。

### 错误处理示例

当请求的文件不存在时：

```
#image-viewer Show me C:\nonexistent\image.png
```

服务器返回的错误响应如下：

```
Error: ENOENT: no such file or directory, open 'C:\nonexistent\image.png'
```

## 性能考量

### 内存使用

每次图像查看请求都会将整个图像文件加载到内存中，这意味着处理大型图像文件（如高分辨率截图）时需要足够的可用内存。对于日常使用场景（如调试截图），当前实现性能充足。

### 响应延迟

图像处理的延迟主要来自文件 I/O 操作和 Base64 编码转换。对于中小型图像文件（几 MB 以内），总响应时间通常在可接受范围内。千兆网络和 SSD 存储环境下性能更佳。

## 扩展建议

### 潜在的增强方向

| 功能方向 | 说明 |
|---------|------|
| 缓存机制 | 缓存已处理的图像数据以减少重复处理 |
| 流式处理 | 对大文件采用流式读取和分块编码 |
| 格式验证 | 添加魔术字节验证以防止文件扩展名欺骗 |
| 缩略图生成 | 提供可选的缩略图生成功能 |
| 元数据提取 | 返回图像的尺寸、颜色深度等元数据 |

当前版本保持了功能的简洁性，专注于核心的图像查看能力，为未来功能扩展预留了充足的空间。

---

<a id='page-vscode-integration'></a>

## VS Code Copilot集成

### 相关页面

相关主题：[Claude Desktop集成](#page-claude-integration), [安装指南](#page-installation)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/README.md)
- [index.js](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/index.js)
</details>

# VS Code Copilot集成

## 概述

InChat Image Viewer MCP 是一款 Model Context Protocol (MCP) 服务器工具，专门用于解决 GitHub Copilot Chat 无法直接查看本地图片文件的痛点。通过该工具，用户只需提供图片的纯文本路径，AI 助手即可自动识别并以内联方式展示图片内容。

## 问题背景

### 传统方式的局限性

在 VS Code Copilot Chat 环境中，图片文件的处理存在以下问题：

| 方式 | 效果 | 可行性 |
|------|------|--------|
| 纯文件路径 | AI 仅看到文本路径，无法显示图片 | ❌ 不可行 |
| `#file:` 引用 | 对图片支持不可靠，常返回空附件 | ❌ 不稳定 |
| 拖放图片 | 需要手动操作，打断工作流 | ⚠️ 可行但不便捷 |

资料来源：[README.md:1-25](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/README.md)

## 核心功能

### view_image 工具

该 MCP 服务器提供了一个核心工具 `view_image`，具备以下能力：

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `file_path` | string | 是 | 图片文件的绝对路径或相对路径 |

资料来源：[index.js:24-42](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/index.js)

### 支持的图片格式

- PNG
- JPEG/JPG
- GIF
- BMP
- WebP

资料来源：[README.md:45-47](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/README.md)

## 工作流程

### 集成前后对比

```mermaid
graph TD
    A[用户] --> B{是否使用 InChat Image Viewer MCP}
    
    B -->|不使用| C[输入图片路径]
    C --> D[AI 仅接收文本路径]
    D --> E[attachments 为空]
    E --> F[无法显示图片]
    
    B -->|使用| G[输入命令: #image-viewer]
    G --> H[指定图片路径]
    H --> I[MCP 调用 view_image 工具]
    I --> J[读取文件并转为 Base64]
    J --> K[返回图片数据]
    K --> L[AI 内联展示图片]
```

### 处理流程详解

```mermaid
sequenceDiagram
    participant U as 用户
    participant AI as Copilot Chat
    participant MCP as MCP Server
    participant FS as 文件系统

    U->>AI: #image-viewer 分析 C:\screenshots\bug.png
    AI->>MCP: 调用 view_image 工具
    MCP->>FS: readFile(file_path)
    FS-->>MCP: 返回图片二进制数据
    MCP->>MCP: 转换为 Base64 编码
    MCP->>MCP: 根据扩展名确定 MIME 类型
    MCP-->>AI: 返回 {text, image} 内容块
    AI-->>U: 内联展示图片
```

## 技术实现

### 架构设计

```mermaid
graph LR
    subgraph MCP["MCP 协议层"]
        LTI[ListToolsRequestSchema]
        CTI[CallToolRequestSchema]
    end
    
    subgraph Core["核心模块"]
        RF[readFile]
        EX[extname]
        BM[Base64 编码]
    end
    
    LTI -->|定义工具| Core
    CTI -->|执行工具| Core
    RF -->|读取文件| BM
    EX -->|获取类型| BM
```

### MIME 类型映射

资料来源：[index.js:60-67](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/index.js)

| 扩展名 | MIME 类型 |
|--------|-----------|
| .png | image/png |
| .jpg | image/jpeg |
| .jpeg | image/jpeg |
| .gif | image/gif |
| .bmp | image/bmp |
| .webp | image/webp |
| (默认) | image/png |

### 响应数据结构

当工具成功执行时，返回以下结构：

```json
{
  "content": [
    {
      "type": "text",
      "text": "Image: /path/to/image.png (12345 bytes)"
    },
    {
      "type": "image",
      "data": "<base64_encoded_data>",
      "mimeType": "image/png"
    }
  ]
}
```

当工具执行失败时，返回错误信息：

```json
{
  "content": [
    {
      "type": "text",
      "text": "Error: <error_message>"
    }
  ],
  "isError": true
}
```

资料来源：[index.js:69-96](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/index.js)

## 使用方式

### 前提条件

1. 安装 Node.js 环境
2. 配置 MCP 服务器支持

### 启动服务器

```bash
node index.js
```

服务器通过标准输入输出（stdio）与 MCP 客户端通信。

资料来源：[index.js:101-106](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/index.js)

### 使用示例

**用户输入：**
```
#image-viewer 分析这张截图: D:\projects\test-failures\2026-01-20.png
```

**AI 自动调用：**
```
view_image(file_path: "D:\\projects\\test-failures\\2026-01-20.png")
```

资料来源：[README.md:37-40](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/README.md)

## 项目信息

| 属性 | 值 |
|------|------|
| 项目名称 | InChat Image Viewer MCP |
| 版本 | 1.0.0 |
| 服务器名称 | image-viewer |
| 许可证 | MIT |
| 作者 | Ibrahim Oguntola |

资料来源：[index.js:12-14](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/index.js), [README.md:56](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/README.md)

---

<a id='page-claude-integration'></a>

## Claude Desktop集成

### 相关页面

相关主题：[VS Code Copilot集成](#page-vscode-integration), [安装指南](#page-installation)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/README.md)
- [index.js](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/index.js)
</details>

# Claude Desktop集成

## 概述

`inchat-image-viewer-mcp` 是一个基于 Model Context Protocol (MCP) 的图像查看服务器，专为解决 AI 助手无法直接查看本地图像文件的问题而设计。该 MCP 服务器可以与 Claude Desktop 无缝集成，使 Claude 能够通过文件路径直接查看和分析本地图像，无需手动拖放操作。

## 工作原理

### 核心问题与解决方案

Claude Desktop 在处理图像时存在以下限制：

| 方式 | 是否支持 | 说明 |
|------|---------|------|
| 纯文件路径 | ❌ | Claude 只能看到文本路径，无法获取图像数据 |
| `#file:` 引用 | ❌ | 对图像文件不可靠，返回空的 `<attachments>` |
| 拖放上传 | ✅ | 可行，但需要手动操作，破坏工作流 |

通过 MCP 协议集成 `inchat-image-viewer` 后，用户只需提供图像文件的绝对或相对路径，Claude Desktop 即可自动调用 `view_image` 工具，将图像以内联方式显示在对话中。

### 架构流程

```mermaid
graph TD
    A[用户输入图像路径] --> B{Claude Desktop MCP Client}
    B --> C[调用 view_image 工具]
    C --> D[inchat-image-viewer-mcp Server]
    D --> E[readFile 读取图像]
    E --> F[转换为 Base64 编码]
    F --> G[匹配 MIME 类型]
    G --> H[返回图像内容块]
    H --> I[Claude Desktop 渲染图像]
    
    style A fill:#e1f5fe
    style I fill:#c8e6c9
    style D fill:#fff3e0
```

## 支持的图像格式

| 格式 | 文件扩展名 | MIME 类型 |
|------|-----------|-----------|
| PNG | `.png` | `image/png` |
| JPEG | `.jpg` / `.jpeg` | `image/jpeg` |
| GIF | `.gif` | `image/gif` |
| BMP | `.bmp` | `image/bmp` |
| WebP | `.webp` | `image/webp` |

资料来源：[index.js:44-51]()

## 工具接口

### view_image 工具定义

```javascript
{
  name: "view_image",
  description: "Display an image from a file path inline in the chat. Supports PNG, JPEG, GIF, BMP, WebP.",
  inputSchema: {
    type: "object",
    properties: {
      file_path: {
        type: "string",
        description: "Absolute or relative path to the image file"
      }
    },
    required: ["file_path"]
  }
}
```

资料来源：[index.js:25-38]()

### 返回内容结构

工具执行成功后返回包含两种内容块的结果：

| 类型 | 说明 |
|------|------|
| `text` | 显示文件路径和文件大小（字节） |
| `image` | Base64 编码的图像数据及 MIME 类型 |

错误发生时返回以下格式：

| 类型 | 说明 |
|------|------|
| `text` | 错误消息 |
| `isError` | 设为 `true` |

资料来源：[index.js:54-79]()

## 集成配置

### Claude Desktop 配置步骤

在 Claude Desktop 的 MCP 配置文件中添加服务器配置：

```json
{
  "mcpServers": {
    "image-viewer": {
      "command": "node",
      "args": ["/path/to/inchat-image-viewer-mcp/index.js"]
    }
  }
}
```

### 配置参数说明

| 参数 | 类型 | 说明 |
|------|------|------|
| `command` | string | 执行命令，此处为 `node` |
| `args` | array | 包含 MCP 服务器入口文件的绝对路径 |

## 使用示例

### 基本使用流程

```
用户: "请分析这张截图 C:\test-results\failure-screenshot.png"
```

```mermaid
sequenceDiagram
    participant User as 用户
    participant Claude as Claude Desktop
    participant MCP as MCP Server
    participant FS as 文件系统

    User->>Claude: 提供图像文件路径
    Claude->>MCP: 调用 view_image 工具
    MCP->>FS: readFile(filePath)
    FS-->>MCP: 返回图像二进制数据
    MCP->>MCP: 转换为 Base64 + MIME
    MCP-->>Claude: 返回 content 数组
    Claude->>User: 渲染内联图像
```

### 典型应用场景

| 场景 | 示例输入 |
|------|---------|
| 调试截图分析 | `"查看 D:\projects\test-failures\2026-01-20.png 并分析错误"` |
| UI 测试对比 | `"比较 C:\screenshots\before.png 和 after.png 的差异"` |
| 日志图像查看 | `"分析 logs\error-snapshot.webp 中的视觉问题"` |

## 错误处理

### 常见错误类型

| 错误场景 | 返回消息 | 处理建议 |
|---------|---------|---------|
| 文件不存在 | `Error: ENOENT: no such file or directory` | 检查文件路径是否正确 |
| 权限不足 | `Error: EACCES: permission denied` | 确认文件读取权限 |
| 无效路径格式 | `Error: Invalid path` | 使用正确的绝对或相对路径 |
| 不支持的格式 | 使用默认 MIME 类型 | 确保文件扩展名为支持的格式之一 |

## 技术实现细节

### 图像处理流程

```mermaid
graph LR
    A[原始文件] --> B[Buffer 读取]
    B --> C{文件扩展名}
    C -->|匹配 mimeMap | D[确定 MIME 类型]
    C -->|未匹配 | E[使用默认 image/png]
    D --> F[toString base64]
    E --> F
    F --> G[构造 content 数组]
    G --> H[返回给 MCP Client]
```

### 核心代码逻辑

```javascript
// 读取图像文件
const imageData = await readFile(filePath);

// 转换为 Base64
const base64Image = imageData.toString("base64");

// MIME 类型映射
const mimeMap = {
  ".png": "image/png",
  ".jpg": "image/jpeg",
  ".jpeg": "image/jpeg",
  ".gif": "image/gif",
  ".bmp": "image/bmp",
  ".webp": "image/webp",
};
```

资料来源：[index.js:44-56]()

## 与标准 Copilot Chat 的对比

| 功能特性 | 标准 Copilot Chat | Claude Desktop + MCP |
|---------|------------------|---------------------|
| 文件路径识别 | ❌ | ✅ |
| 图像内联显示 | ❌ | ✅ |
| 拖放上传 | ✅ 需手动 | ✅ 自动触发 |
| 工作流连贯性 | ❌ 中断 | ✅ 保持 |
| 多格式支持 | 依赖上传格式 | ✅ PNG/JPEG/GIF/BMP/WebP |

资料来源：[README.md:1-30]()

## 许可证

本项目采用 MIT 许可证。

资料来源：[README.md:13]()

---

**项目维护者**: [Ibrahim Oguntola](https://github.com/OguntolaIbrahim)

---

<a id='page-installation'></a>

## 安装指南

### 相关页面

相关主题：[VS Code Copilot集成](#page-vscode-integration), [Claude Desktop集成](#page-claude-integration), [故障排除](#page-troubleshooting)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/README.md)
- [index.js](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/index.js)
</details>

# 安装指南

本页面详细说明如何安装和配置 **inchat-image-viewer-mcp** 扩展，使 AI 助手能够通过文件路径直接查看本地图像文件。

## 前提条件

在安装此 MCP 服务器之前，请确保满足以下环境要求：

| 要求项 | 最低版本 | 说明 |
|--------|----------|------|
| Node.js | v18.0.0 | 服务器运行时环境 |
| npm/yarn | 最新稳定版 | 包管理工具 |
| MCP 兼容客户端 | - | 支持 MCP 协议的工具（如支持 MCP 的 AI 助手） |

> **资料来源**：[README.md:1]()

## 安装步骤

### 步骤一：克隆仓库

```bash
git clone https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp.git
cd inbox-image-viewer-mcp
```

### 步骤二：安装依赖

项目使用 Node.js 环境，需通过 npm 安装依赖包：

```bash
npm install
```

此命令将自动安装 MCP SDK 及其他必需的 Node.js 模块：

| 包名 | 用途 |
|------|------|
| @modelcontextprotocol/sdk | MCP 协议核心 SDK |
| 其他 Node.js 内置模块 | 文件系统操作、路径处理 |

> **资料来源**：[index.js:3-5]()

### 步骤三：构建项目

```bash
npm run build
```

### 步骤四：配置 MCP 客户端

将服务器配置添加到你的 MCP 客户端配置文件（如 Claude Desktop 或支持 MCP 的编辑器配置）中：

```json
{
  "mcpServers": {
    "image-viewer": {
      "command": "node",
      "args": ["/path/to/inchat-image-viewer-mcp/build/index.js"]
    }
  }
}
```

> **注意**：请将 `/path/to/inchat-image-viewer-mcp` 替换为你实际的安装路径。

## 项目结构

```
inchat-image-viewer-mcp/
├── index.js              # MCP 服务器入口
├── package.json          # 项目配置
├── README.md             # 项目说明文档
└── build/                # 编译输出目录
    └── index.js          # 编译后的可执行文件
```

> **资料来源**：[index.js:1-25]()

## 架构概览

```mermaid
graph TD
    A[用户] -->|提供图像文件路径| B[MCP 客户端]
    B -->|调用 view_image 工具| C[image-viewer MCP 服务器]
    C -->|读取文件| D[本地文件系统]
    D -->|返回图像数据| C
    C -->|Base64 编码图像| B
    B -->|显示图像| A
```

## 验证安装

安装完成后，可通过以下方式验证：

1. 在支持的 AI 客户端中发送命令：
   ```
   #image-viewer 分析 C:\test-image.png
   ```

2. 若服务器正常运行，将返回图像的 Base64 数据并在聊天界面中显示该图像。

> **资料来源**：[README.md:1]()

## 支持的图像格式

| 格式 | 扩展名 | MIME 类型 |
|------|--------|-----------|
| PNG | .png | image/png |
| JPEG | .jpg / .jpeg | image/jpeg |
| GIF | .gif | image/gif |
| BMP | .bmp | image/bmp |
| WebP | .webp | image/webp |

> **资料来源**：[index.js:45-52]()

## 常见问题

### Q: 图像无法显示怎么办？

1. 确认文件路径存在且为支持的格式
2. 检查 MCP 服务器是否正常运行
3. 验证文件读取权限

### Q: 支持相对路径吗？

支持。工具接受绝对路径或相对路径：

```javascript
file_path: "screenshots/bug.png"     // 相对路径
file_path: "C:\\images\\bug.png"     // Windows 绝对路径
file_path: "/home/user/bug.png"      // Linux/macOS 绝对路径
```

> **资料来源**：[index.js:29-30]()

## 许可证

本项目采用 MIT 许可证开源发布。

> **资料来源**：[README.md:1]()

---

<a id='page-troubleshooting'></a>

## 故障排除

### 相关页面

相关主题：[安装指南](#page-installation)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [index.js](https://github.com/OguntolaIbrahim/inchat-image-viewer-mcp/blob/main/index.js)
</details>

# 故障排除

本文档提供 InChat Image Viewer MCP 常见问题的诊断和解决方案。

## 概述

InChat Image Viewer MCP 是一个基于 Model Context Protocol (MCP) 的图像查看工具服务器。它允许 AI 助手通过文件路径直接读取并显示图像，无需手动拖放文件。该服务器通过标准输入/输出 (stdio) 与宿主应用通信，实现图像文件的读取和 Base64 编码返回。

## 常见错误与解决方案

### 文件读取错误

**错误信息**：`Error: ENOENT: no such file or directory`

**原因**：指定的文件路径不存在或路径格式不正确

**解决方案**：
- 确认文件路径是正确的绝对路径或相对路径
- 检查文件是否已被移动、重命名或删除
- 在 Windows 系统中，确保使用正确的路径分隔符（反斜杠 `\` 或正斜杠 `/`）
- 验证文件扩展名是否与实际文件类型匹配

**相关源码**：
```javascript
const imageData = await readFile(filePath);
// 资料来源：index.js:48
```

### MIME 类型映射错误

**错误信息**：`image/png`（默认类型而非预期类型）

**原因**：文件扩展名不在支持的格式列表中

**支持的格式**：

| 扩展名 | MIME 类型 |
|--------|-----------|
| .png | image/png |
| .jpg / .jpeg | image/jpeg |
| .gif | image/gif |
| .bmp | image/bmp |
| .webp | image/webp |

**解决方案**：
- 确保文件扩展名为小写
- 使用支持的图片格式之一
- 检查文件扩展名是否正确

**相关源码**：
```javascript
const mimeMap = {
  ".png": "image/png",
  ".jpg": "image/jpeg",
  ".jpeg": "image/jpeg",
  ".gif": "image/gif",
  ".bmp": "image/bmp",
  ".webp": "image/webp",
};
const mimeType = mimeMap[ext] || "image/png";
// 资料来源：index.js:52-60
```

### 未知工具错误

**错误信息**：`Unknown tool: xxx`

**原因**：调用了服务器未注册的工具

**解决方案**：
- 目前服务器仅支持 `view_image` 工具
- 检查工具名称拼写是否正确
- 确保使用正确的工具调用格式

**相关源码**：
```javascript
throw new Error(`Unknown tool: ${request.params.name}`);
// 资料来源：index.js:74
```

## 调试流程图

```mermaid
graph TD
    A[开始调试] --> B{文件是否存在?}
    B -->|否| C[检查文件路径]
    C --> D[确认文件位置]
    D --> E[重新运行命令]
    B -->|是| F{文件格式是否支持?}
    F -->|否| G[转换为支持的格式]
    G --> E
    F -->|是| H{读取权限正常?}
    H -->|否| I[检查文件权限]
    I --> E
    H -->|是| J{图像数据正确?}
    J -->|否| K[重新保存图像]
    K --> E
    J -->|是| L[服务器正常工作]
```

## 错误响应格式

服务器返回的错误响应格式如下：

```javascript
{
  content: [
    {
      type: "text",
      text: `Error: ${error.message}`
    }
  ],
  isError: true
}
// 资料来源：index.js:67-72
```

## 成功响应格式

正常情况下，服务器返回包含文本和图像内容的响应：

```javascript
{
  content: [
    {
      type: "text",
      text: `Image: ${filePath} (${imageData.length.toLocaleString()} bytes)`
    },
    {
      type: "image",
      data: base64Image,
      mimeType: mimeType
    }
  ]
}
// 资料来源：index.js:61-66
```

## 服务器状态检查

### 检查服务器是否运行

服务器启动时会输出以下消息到标准错误：

```
Image Viewer MCP Server running on stdio
// 资料来源：index.js:79
```

### 验证工具列表

服务器响应 `ListToolsRequestSchema` 时返回：

```javascript
{
  tools: [
    {
      name: "view_image",
      description: "Display an image from a file path inline in the chat. Supports PNG, JPEG, GIF, BMP, WebP.",
      inputSchema: {
        type: "object",
        properties: {
          file_path: {
            type: "string",
            description: "Absolute or relative path to the image file"
          }
        },
        required: ["file_path"]
      }
    }
  ]
}
// 资料来源：index.js:28-44
```

## 最佳实践

1. **始终使用绝对路径**：绝对路径可以避免相对路径解析的歧义
2. **验证文件存在性**：在调用工具前确认文件存在
3. **使用受支持的格式**：优先使用 PNG、JPEG、GIF、BMP 或 WebP 格式
4. **检查文件大小**：大图像文件可能会影响传输性能
5. **确保文件可读**：确认进程有读取目标文件的权限

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：oguntolaibrahim/inchat-image-viewer-mcp

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

## 1. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | mcp_registry:io.github.OguntolaIbrahim/image-viewer:1.0.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.OguntolaIbrahim%2Fimage-viewer/versions/1.0.1 | README/documentation is current enough for a first validation pass.

## 2. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.OguntolaIbrahim/image-viewer:1.0.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.OguntolaIbrahim%2Fimage-viewer/versions/1.0.1 | last_activity_observed missing

## 3. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | mcp_registry:io.github.OguntolaIbrahim/image-viewer:1.0.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.OguntolaIbrahim%2Fimage-viewer/versions/1.0.1 | no_demo; severity=medium

## 4. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | mcp_registry:io.github.OguntolaIbrahim/image-viewer:1.0.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.OguntolaIbrahim%2Fimage-viewer/versions/1.0.1 | no_demo; severity=medium

## 5. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.OguntolaIbrahim/image-viewer:1.0.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.OguntolaIbrahim%2Fimage-viewer/versions/1.0.1 | issue_or_pr_quality=unknown

## 6. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.OguntolaIbrahim/image-viewer:1.0.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.OguntolaIbrahim%2Fimage-viewer/versions/1.0.1 | release_recency=unknown

<!-- canonical_name: oguntolaibrahim/inchat-image-viewer-mcp; human_manual_source: deepwiki_human_wiki -->