Skip to content

REST API接口

Jump to bottom
nixi-agent edited this page Aug 10, 2026 · 1 revision

REST API接口

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细端点说明
  6. 依赖关系分析
  7. 性能与限流
  8. 故障排查指南
  9. 结论
  10. 附录：测试与调试

简介

本服务提供两类对外能力：

  • 健康检查 HTTP 端点，用于快速探测服务状态与认证状态。
  • JSON-RPC over HTTP（SSE）的 MCP 工具调用接口，暴露一组“工具”供客户端通过 tools/list 发现、tools/call 调用，实现 VRChat 好友监控、群组管理、世界查询、资源上传下载等能力。

服务监听本地端口 8799，仅绑定 127.0.0.1，默认不对外开放。所有对 VRChat 的写操作均受内置限流器保护，避免触发远端限流。

项目结构

  • start-monitor.js：HTTP 服务器、MCP 协议处理、工具路由、SSE 响应封装、启动流程。
  • vrchat-api.js：VRChat 官方 API 客户端，负责认证（Cookie/Basic Auth/OTP）、请求封装、文件上传下载。
  • core/rate-limiter.js：请求级限流器，保证对 VRChat API 的请求间隔安全。
  • test-apis.mjs：VRChat 官方 API 的全面测试脚本（可作为参考）。
  • archive/*：历史或桥接实现，展示 MCP over stdio 与 HTTP 的交互方式，有助于理解会话与鉴权头。
graph TB
Client["客户端"] --> HTTP["HTTP 服务器<br/>:8799"]
HTTP --> |/health| Health["健康检查"]
HTTP --> |POST /mcp| MCP["MCP 处理器"]
MCP --> Tools["工具路由<br/>tools/list, tools/call"]
Tools --> RL["限流器"]
Tools --> VRC["VRChat API 客户端"]
VRC --> API["https://api.vrchat.cloud/api/1"]
Loading

图表来源

  • start-monitor.js:2185-2248
  • vrchat-api.js:50-87

核心组件

  • HTTP 服务器与路由：
    • GET /health：返回服务运行时间、认证状态、数据库统计、限流器统计、WebSocket 状态等。
    • GET /mcp：探针，返回空 SSE 流以探测服务端支持。
    • POST /mcp：接收 JSON-RPC 消息，按 method 分发到 initialize、notifications/initialized、tools/list、tools/call。
  • MCP 会话：
    • 使用内存 Map 维护会话，支持可选 Mcp-Session-Id 头进行会话关联。
    • 初始化后 capabilities 声明为 { tools: {} }，协议版本固定为 2025-03-26。
  • 工具系统：
    • tools/list 返回全部可用工具定义（名称、描述、输入参数 Schema）。
    • tools/call 根据 name 路由到具体处理器，部分处理器经 RateLimiter 执行。
  • VRChat 认证：
    • Cookie 持久化 + Basic Auth 登录 + OTP 验证；自动续期 Cookie。
    • ensureAuthWithAutoOtp 支持在需要时自动拉取邮箱验证码完成登录。
  • 限流器：
    • 最小间隔 2600ms，队列最大长度 50，串行执行并等待必要间隔。

架构总览

sequenceDiagram
participant C as "客户端"
participant S as "HTTP 服务器"
participant M as "MCP 处理器"
participant T as "工具路由"
participant R as "限流器"
participant A as "VRChat API 客户端"
participant V as "VRChat 官方API"
C->>S : POST /mcp (JSON-RPC)
S->>M : 解析 body, 提取 sessionId
M->>T : tools/call(name, args)
alt 需要访问外部API
T->>R : execute(fn)
R->>A : 调用封装方法(ensureAuth/_request)
A->>V : HTTPS 请求
V-->>A : JSON 响应
A-->>R : 结果
R-->>T : 结果
else 本地数据
T-->>M : 结果
end
M-->>C : SSE data : {jsonrpc, result/error}
Loading

图表来源

  • start-monitor.js:2215-2263
  • start-monitor.js:1947-2181
  • vrchat-api.js:50-87

详细端点说明

通用约定

  • 传输协议：HTTP + JSON-RPC 2.0，响应采用 Server-Sent Events（SSE），每行 data: 。
  • 内容类型：请求 Content-Type: application/json；响应 Content-Type: text/event-stream。
  • 会话：可选请求头 Mcp-Session-Id，服务端回显相同头以便客户端关联会话。
  • 错误：当 JSON 解析失败或工具抛出异常时，返回 jsonrpc 错误对象，常见代码：
    • -32700：Parse error（请求体非合法 JSON）
    • -32603：内部错误（工具执行异常）
    • -32601：方法不存在（当前仅支持 initialize、notifications/initialized、tools/list、tools/call）
  • 成功：result.content[0].text 为 JSON 字符串，需客户端二次解析。

GET /health

  • 作用：健康检查，返回服务运行时长、认证状态、数据库统计、限流器统计、WebSocket 状态、好友状态统计、事件管道统计。
  • 请求：无参数。
  • 响应：application/json，字段包括 ok、auth、db、rateLimiter、ws、friendState、eventPipeline、uptime。
  • 示例（成功）：
    • 请求：GET http://127.0.0.1:8799/health
    • 响应：{ ok: true, auth: { authenticated: true/false, user?: {...}, needsOtp?: boolean }, db: {...}, rateLimiter: {...}, ws: {...}, friendState: {...}, eventPipeline: {...}, uptime: number }
  • 示例（未认证）：
    • auth.authenticated=false，若需要 OTP，则包含 needsOtp=true。

POST /mcp（JSON-RPC over HTTP）

  • 作用：MCP 协议入口，支持以下 method：
    • initialize：建立会话，返回协议版本与能力。
    • notifications/initialized：通知已初始化（可忽略）。
    • tools/list：列出所有可用工具及其输入 Schema。
    • tools/call：调用指定工具。
  • 请求头：
    • Content-Type: application/json
    • Accept: application/json, text/event-stream
    • Mcp-Session-Id: 可选，用于会话关联
  • 请求体（JSON-RPC）：
    • jsonrpc: "2.0"
    • id: 任意标识（建议递增数字）
    • method: 见上
    • params: 依 method 而定
  • 响应：SSE 流，每行 data: <JSON-RPC 消息>。
  • 示例（initialize）：
    • 请求：
      • POST /mcp
      • Body: { jsonrpc:"2.0", id:1, method:"initialize", params:{ protocolVersion:"2025-03-26", capabilities:{}, clientInfo:{ name:"...", version:"..." } } }
    • 响应（SSE）：data: { jsonrpc:"2.0", id:1, result:{ protocolVersion:"2025-03-26", capabilities:{ tools:{} }, serverInfo:{ name:"vrc-monitor", version:"1.0.0" } } }
  • 示例（tools/list）：
    • 请求：{ jsonrpc:"2.0", id:2, method:"tools/list" }
    • 响应：data: { jsonrpc:"2.0", id:2, result:{ tools:[...] } }
  • 示例（tools/call）：
    • 请求：{ jsonrpc:"2.0", id:3, method:"tools/call", params:{ name:"get_server_status", arguments:{} } }
    • 响应：data: { jsonrpc:"2.0", id:3, result:{ content:[{ type:"text", text:"{...}" }] } }
  • 错误示例（未知工具）：
    • 响应：data: { jsonrpc:"2.0", id:3, error:{ code:-32601, message:"Unknown tool: xxx" } }

工具列表与调用（tools/list 与 tools/call）

  • tools/list 返回全部工具定义，每个工具包含：
    • name：工具名
    • description：功能描述
    • inputSchema：输入参数 JSON Schema（type/object，properties，required 等）
  • tools/call 的 params：
    • name：工具名
    • arguments：对象，字段与 inputSchema 对应
  • 返回值统一包装为 result.content[0].text，值为 JSON 字符串，客户端需自行解析。
  • 错误：
    • 参数缺失或类型不符：由工具处理器抛错，返回 -32603。
    • 外部 API 错误：如 VRChat 返回 4xx/5xx，工具会转换为错误信息。

关键工具说明（节选）

以下为常用工具与其行为摘要（完整列表请通过 tools/list 获取）：

  • get_server_status：返回服务健康与认证状态。
  • get_database_stats：返回本地数据库统计。
  • get_online_friends：返回在线好友列表（含昵称、位置解析等）。
  • search_users：按显示名搜索用户。
  • send_boop：向用户发送“拍一拍”，需 userId，可选 emojiId。
  • upload_print / upload_gallery_image：上传照片至相册或画廊（需 VRChat Plus）。
  • remove_print / remove_gallery_image：删除资源，需 confirm:true 确认。
  • download_print / download_gallery_image：下载资源到本地 downloads 目录。
  • create_instance / invite_myself：创建实例并邀请自己进入。
  • send_friend_request / remove_friend：添加/移除好友。
  • get_world_name / set_world_note / get_world_history：世界信息查询与备注管理。
  • scan_new_worlds / get_new_worlds：扫描新发布世界与查询跟踪结果。
  • get_watchlist / add_to_watchlist / remove_from_watchlist：关注名单管理。
  • get_companions / get_online_pattern：同屏好友分析与上线规律。
  • get_nicknames / set_nickname：昵称映射管理。
  • get_user_groups / get_group_info / get_group_instances / get_group_announcement / search_groups：群组相关查询。
  • join_group / leave_group / peek_group_announcement：加入/离开群组及预览公告。
  • backup_database：立即备份本地数据库。

注意：

  • 涉及外部 VRChat API 的工具大多经 RateLimiter 保护，确保最小间隔。
  • 部分写操作要求 confirm:true 才真正执行，否则返回预览。

依赖关系分析

  • HTTP 层：
    • Node.js http.createServer 提供 /health 与 /mcp。
    • /mcp 解析 JSON-RPC 并分派到 handleRpc。
  • 工具层：
    • 工具处理器调用 Storage、FriendStateManager、EventPipeline、WsManager 等模块读取本地数据或状态。
  • 外部依赖：
  • 限流：
    • RateLimiter 保证相邻请求的最小间隔，防止触发远端限流。
classDiagram
class HttpServer {
+handleRequest(req,res)
+createServer()
}
class McpHandler {
+handleRpc(rpc,session,res)
+sendSSE(res,events,sessionId)
}
class ToolRouter {
+dispatch(name,args)
}
class RateLimiter {
+execute(fn)
+getStats()
}
class VrchatApiClient {
+ensureAuth()
+_request(method,path,body)
+uploadPrint(...)
+downloadFile(url)
}
HttpServer --> McpHandler : "POST /mcp"
McpHandler --> ToolRouter : "tools/call"
ToolRouter --> RateLimiter : "wraps external calls"
ToolRouter --> VrchatApiClient : "calls VRChat API"
Loading

图表来源

  • start-monitor.js:2185-2263
  • start-monitor.js:1947-2181
  • core/rate-limiter.js:1-82
  • vrchat-api.js:50-87

性能与限流

  • 限流策略：
    • 最小间隔 2600ms，队列最大长度 50，串行执行。
    • 适用于调用 VRChat API 的工具，避免触发 30次/分钟限制。
  • 并发控制：
    • 同一时刻仅一个任务在处理，其他任务排队等待。
  • 统计：
    • 可通过 /health 的 rateLimiter 字段查看 totalCalls、totalWaitedMs、queueLength、isProcessing、minInterval。
  • 建议：
    • 批量操作应拆分多次调用，避免单次请求过大。
    • 合理设置 limit/offset 分页参数，减少单次负载。

故障排查指南

  • 常见问题：
    • 认证失败：/health 中 auth.authenticated=false，可能需要 OTP。
    • 需要 OTP：调用工具时可能抛出 needsOtp 信号，需先完成 OTP 验证流程。
    • 限流：若频繁调用外部 API，可能被限流；观察 rateLimiter 统计与日志。
    • 端口占用：启动时报 EADDRINUSE，检查是否有旧进程残留。
  • 定位步骤：
    • 使用 /health 检查服务状态。
    • 通过 tools/list 确认工具是否可用。
    • 逐步缩小问题范围：先调用只读工具，再尝试写工具。
    • 检查本地 credentials.json 与 auth_cookie.txt 是否存在且有效。
  • 日志：
    • 控制台输出包含关键节点日志（登录、WS 连接、事件处理、错误等）。

结论

本服务通过简洁的 HTTP 端点与 JSON-RPC over HTTP（SSE）暴露了丰富的 VRChat 管理能力。健康检查便于运维监控，MCP 工具体系提供了可扩展的能力集合。内置限流与认证机制保障了稳定性与安全性。建议在生产环境中仅允许可信来源访问本地端口，并结合反向代理与访问控制策略加固。

附录：测试与调试

使用 curl 测试

  • 健康检查：
  • MCP 探针：
  • 初始化：
    • curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' http://127.0.0.1:8799/mcp
  • 列出工具：
    • curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' http://127.0.0.1:8799/mcp
  • 调用工具（示例：get_server_status）：
    • curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_server_status","arguments":{}}}' http://127.0.0.1:8799/mcp

使用 Node 测试脚本

  • 运行全面测试：
    • node test-apis.mjs
  • 该脚本演示了对 VRChat 官方 API 的多阶段调用，可作为参考了解各端点的预期行为与错误场景。

调试技巧

  • 启用更详细的日志：在服务端控制台查看关键节点输出。
  • 使用浏览器或 Postman 订阅 SSE 流，观察 data: 行。
  • 对于需要 OTP 的场景，确保 credentials.json 配置正确，并具备邮箱 IMAP 授权码。
  • archive/stdio-bridge.js:1-60

📚 vrc-monitor Wiki

入门

核心架构

API 参考手册

工具与交互

WebSocket 通信

实时监控功能

部署与运维

开发指南

Clone this wiki locally