项目概述

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

核心价值定位

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

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

技术栈

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

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

资料来源：README.md

项目背景

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

资料来源：README.md:1

核心问题描述

当前工作流的局限性

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

资料来源：README.md:3-10

问题根因分析

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

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 工具，使其能够主动读取并显示图像文件。

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，支持绝对路径和相对路径：

资料来源：index.js:15-26

#### 支持的图片格式

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

资料来源：index.js:35-47

工作流程对比

#### 无 MCP 时的流程

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 后的流程

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

错误处理机制

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

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

资料来源：index.js:57-64

错误响应格式

部署与运行

服务器启动

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

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

资料来源：index.js:67-72

依赖项

总结

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

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

概述

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

架构设计原则

核心组件

1. MCP 服务器

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

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

服务器配置参数：

资料来源：index.js:13-21

2. 传输层

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

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

资料来源：index.js:82-84

3. 工具处理系统

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

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

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"],
        },
      },
    ],
  };
});

工具参数定义：

资料来源：index.js:24-49

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

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

资料来源：index.js:52-80

系统架构图

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

工作流程

图像查看完整流程

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: 显示图像

请求处理流程

资料来源：index.js:52-79

数据流

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

图像格式支持

资料来源：index.js:56-63

响应数据结构

成功响应

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

错误响应

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

资料来源：index.js:65-80

服务器生命周期

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

技术栈

错误处理机制

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

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

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

资料来源：index.js:66-80

架构优势

与传统方案的对比

资料来源：README.md

部署架构

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

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

概述

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

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

资料来源：index.js:1-18

技术架构

系统组件

资料来源：index.js:3-11

架构图

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 类构造函数进行初始化，传入服务元数据和能力配置：

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

参数说明：

资料来源：index.js:13-23

启动机制

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

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 客户端请求可用工具时，服务器返回工具清单：

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"],
        },
      },
    ],
  };
});

工具定义参数：

资料来源：index.js:26-51

工具调用处理

请求处理流程

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 模块读取图像文件：

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

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

资料来源：index.js:54-55

MIME 类型映射

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

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 协议支持返回多种内容类型的响应。服务器返回包含文本和图像的复合响应：

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

响应结构：

资料来源：index.js:72-84

错误处理

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

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）：输出服务器日志和调试信息

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

资料来源：index.js:78

JSON-RPC 消息格式

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

依赖项

导入语句使用 ES Module 语法：

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 收到：完整图像数据

扩展建议

版本信息

资料来源：index.js:18, 22

概述

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

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

工作原理

通信协议

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

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

执行流程

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 模块异步读取文件内容：

const imageData = await readFile(filePath);

第二步：MIME 类型映射

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

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

第三步：Base64 编码

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

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

第四步：响应构建

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

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

工具定义

输入参数

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

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

输出结构

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

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

错误响应格式：

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

服务器架构

组件关系

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

服务器配置

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

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

错误处理机制

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

所有错误均通过 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
• 许可证：MIT
• 作者：Ibrahim Oguntola

概述

图像处理与格式支持模块是 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 生态系统的完全兼容性。

数据流向

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 类型映射实现

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

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 协议中传输二进制内容。

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

响应构建阶段

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

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

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

工具接口规范

view_image 工具定义

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

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

资料来源：index.js:32-47

响应数据结构

成功响应的结构如下：

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

错误响应的结构如下：

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

资料来源：index.js:80-90

错误处理机制

异常捕获策略

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

常见错误场景

技术实现细节

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 存储环境下性能更佳。

扩展建议

潜在的增强方向

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

概述

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

问题背景

传统方式的局限性

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

资料来源：README.md:1-25

核心功能

view_image 工具

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

资料来源：index.js:24-42

支持的图片格式

• PNG
• JPEG/JPG
• GIF
• BMP
• WebP

资料来源：README.md:45-47

工作流程

集成前后对比

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 内联展示图片]

处理流程详解

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: 内联展示图片

技术实现

架构设计

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

响应数据结构

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

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

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

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

资料来源：index.js:69-96

使用方式

前提条件

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

启动服务器

node index.js

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

资料来源：index.js:101-106

使用示例

用户输入：

#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

项目信息

资料来源：index.js:12-14, README.md:56

概述

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

工作原理

核心问题与解决方案

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

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

架构流程

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

支持的图像格式

资料来源：index.js:44-51

工具接口

view_image 工具定义

{
  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

返回内容结构

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

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

资料来源：index.js:54-79

集成配置

Claude Desktop 配置步骤

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

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

配置参数说明

使用示例

基本使用流程

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

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: 渲染内联图像

典型应用场景

错误处理

常见错误类型

技术实现细节

图像处理流程

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]

核心代码逻辑

// 读取图像文件
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 的对比

资料来源：README.md:1-30

许可证

本项目采用 MIT 许可证。

资料来源：README.md:13

前提条件

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

资料来源：README.md:1

安装步骤

步骤一：克隆仓库

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

步骤二：安装依赖

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

npm install

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

资料来源：index.js:3-5

步骤三：构建项目

npm run build

步骤四：配置 MCP 客户端

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

{
  "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

架构概览

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

验证安装

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

`` #image-viewer 分析 C:\test-image.png ``

1. 在支持的 AI 客户端中发送命令：

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

资料来源：README.md:1

支持的图像格式

资料来源：index.js:45-52

常见问题

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

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

Q: 支持相对路径吗？

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

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

概述

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

常见错误与解决方案

文件读取错误

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

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

解决方案：

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

相关源码：

const imageData = await readFile(filePath);
// 资料来源：index.js:48

MIME 类型映射错误

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

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

支持的格式：

解决方案：

• 确保文件扩展名为小写
• 使用支持的图片格式之一
• 检查文件扩展名是否正确

相关源码：

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 工具
• 检查工具名称拼写是否正确
• 确保使用正确的工具调用格式

相关源码：

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

调试流程图

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[服务器正常工作]

错误响应格式

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

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

成功响应格式

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

{
  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 时返回：

{
  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. 确保文件可读：确认进程有读取目标文件的权限

Pitfall Log / 踩坑日志

项目：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