hono-opencode-mock

基于 Hono 的 Mock 服务器，用于模拟 OpenAI 兼容 API 和 MCP 工具调用。

功能

• Chat Completions API — POST /v1/chat/completions，支持流式（SSE）和非流式响应，兼容 OpenAI API 格式
• Image Upload API — POST /v1/image/upload，支持 multipart 文件上传
• MCP Server — 基于 HTTP 传输的 MCP 服务，提供 image_upload 工具（支持 URL 下载和 Base64 数据上传）

快速开始

npm install
npm run dev

open http://localhost:8787

MCP HTTP 端点

MCP 服务已集成到 HTTP 服务器中，通过 POST /mcp 端点对外提供，使用 JSON-RPC 2.0 协议。

端点信息

项目	说明
URL	http://localhost:8787/mcp
Method	POST
Content-Type	application/json

支持的 MCP 方法

方法	说明
initialize	初始化 MCP 会话
notifications/initialized	通知初始化完成（返回 202）
tools/list	列出可用工具
tools/call	调用工具

可用工具

工具	说明
image_upload	上传图片文件，支持 URL 下载或 Base64 数据

测试示例

初始化会话：

curl -X POST http://localhost:8787/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

列出工具：

curl -X POST http://localhost:8787/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

调用工具（URL 方式）：

curl -X POST http://localhost:8787/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"image_upload","arguments":{"url":"https://example.com/image.jpg"}}}'

调用工具（Base64 方式）：

# 先获取图片的 Base64 编码
BASE64=$(curl -s https://example.com/image.jpg | base64 -w0)

curl -X POST http://localhost:8787/mcp \
  -H "Content-Type: application/json" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":4,\"method\":\"tools/call\",\"params\":{\"name\":\"image_upload\",\"arguments\":{\"base64\":\"$BASE64\",\"filename\":\"photo.jpg\"}}}"

在 Coding Agent 中配置 MCP Server

本项目通过 HTTP 协议提供 MCP 服务。部分 coding agent 支持直接配置 HTTP URL 作为 MCP 服务端。

通用配置

{
  "mcpServers": {
    "hono-mcp-upload": {
      "url": "http://localhost:8787/mcp"
    }
  }
}

需要先运行 npm run dev 启动 HTTP 服务，MCP 端点才会可用。

各 Agent 配置方式

opencode — 编辑项目根目录下的 .opencode.json：

{
  "mcpServers": {
    "hono-mcp-upload": {
      "url": "http://localhost:8787/mcp"
    }
  }
}

Cursor — 在 Cursor 设置的 MCP 配置中添加：

{
  "mcpServers": {
    "hono-mcp-upload": {
      "url": "http://localhost:8787/mcp"
    }
  }
}

目前 opencode、Cursor 等 agent 对 HTTP/URL 类型的 MCP 服务有不同程度的支持。如果你的 agent 只支持 stdio 传输，请参考项目历史版本或使用 npx tsx src/index.ts 配合 stdio 代理工具。

MCP HTTP 传输说明

MCP（Model Context Protocol）支持多种传输方式：

传输方式	说明
stdio	通过标准输入/输出通信，需将 MCP 服务作为子进程启动
HTTP	通过 HTTP POST 请求通信，MCP 服务作为独立 HTTP 端点运行
SSE	基于 Server-Sent Events 的流式传输（MCP Streamable HTTP）

本项目采用 HTTP 传输方式，MCP 服务与 HTTP API 服务运行在同一进程中。客户端通过 POST /mcp 发送 JSON-RPC 2.0 请求，服务端返回 JSON-RPC 2.0 响应。

相比 stdio 模式，HTTP 传输的优势：

• 无需为每个 agent 启动子进程
• 可以在多个服务/客户端间共享
• 便于调试和测试（可用 curl 直接调用）
• 支持标准 HTTP 认证和中间件

脚本

命令	说明
npm run dev	启动开发服务器（热重载），包含 HTTP API 和 MCP HTTP 端点
npm run build	TypeScript 编译
npm start	运行编译后的服务