Skip to main content
Glama

简体中文 | 繁體中文 | English | 日本語 | Русский

ErisPulse-ApiMCP

把 ErisPulse 机器人运行时能力经 MCP(Model Context Protocol) 开放给 AI 客户端(Claude Desktop 等):收消息、发消息、调用模块 API、管理模块/适配器、观测事件流、检索框架文档。

架构

┌─────────────────────────┐  MCP (stdio)  ┌──────────────────────────────────┐
│  AI 客户端               │◄─────────────►│  erispulse-apimcp(stdio server) │
│  (Claude Desktop ...)   │   17 个 tools  │  官方 mcp SDK · HTTP 转发         │
└─────────────────────────┘               └──────────────┬───────────────────┘
                                                         │ HTTP POST /apimcp/*
                                                         │ 头: X-ApiMCP-Token
                                                         ▼
┌────────────────────────────────────────────────────────────────────────────┐
│  ErisPulse 机器人进程                                                       │
│  ┌──────────────────────────────────────────────────────────────────────┐  │
│  │ ApiMCP 模块(REST 桥,挂框架内置 HTTP server,默认 :8000)             │  │
│  │  · token 鉴权(必须显式配置;未配置则除 health 探活外全部 503)        │  │
│  │  · 事件通配处理器 → 订阅过滤 → 环形缓冲(默认 1000 条,超限淘汰最旧)   │  │
│  └───────────────┬──────────────────────────────────────────────────────┘  │
│                  │ sdk.* 调用                                              │
│        ┌─────────┴─────────┬──────────────┬─────────────┬────────────┐     │
│        ▼                   ▼              ▼             ▼            ▼     │
│   module.call/list/    adapter.list/   SendDSL 发送  transcript    拓扑/   │
│   reload/get_info      reload/status                 最近消息      健康    │
└────────────────────────────────────────────────────────────────────────────┘
  • 机器人进程内:ApiMCP 模块经框架内置 HTTP server 暴露 REST 桥(/apimcp/*,token 鉴权)

  • 独立进程:erispulse-apimcp 命令以官方 mcp SDK 起 stdio server,把 MCP tools 转发到机器人 HTTP(keep-alive 持久连接,超时 10s)

  • 机器人不在线 / 桥未配置时,tools 返回可读错误与排查指引(不抛栈)

Related MCP server: grok-bot-mcp

安装

# 方式一:ErisPulse CLI(推荐,自动装进机器人环境)
epsdk install ErisPulse-ApiMCP

# 方式二:pip
pip install ErisPulse-ApiMCP

安装后重启机器人,ApiMCP 模块自动加载(启动即加载,非懒加载),REST 桥挂到框架 HTTP server(默认 0.0.0.0:8000)。

配置 token(必须显式配置)

token 不自动生成:[ApiMCP] token 未配置(且无环境变量)时,桥进入「未配置」状态——除 health 探活端点(仍返回 200,用于区分「桥未配置」与「机器人不在线」)外,所有端点返回 503 与可读指引。配置方式任选其一:

  • 配置文件:config.toml 中 [ApiMCP] 节设置 token = "你的长随机串"

  • 环境变量:ERISPULSE_APIMCP_TOKEN=你的长随机串(优先级高于配置文件)

配置后热更新或重启机器人即生效。快速自检(curl 探活):

# 已配置:返回健康摘要
curl -H "X-ApiMCP-Token: <token>" http://127.0.0.1:8000/apimcp/health
# 未配置:仍返回 200,data.status = "unconfigured"(据此区分桥未配置与机器人离线)
curl http://127.0.0.1:8000/apimcp/health

Claude Desktop 接入

编辑 claude_desktop_config.json(macOS: ~/Library/Application Support/Claude/claude_desktop_config.json;Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "erispulse": {
      "command": "erispulse-apimcp",
      "env": {
        "ERISPULSE_APIMCP_URL": "http://127.0.0.1:8000",
        "ERISPULSE_APIMCP_TOKEN": "你的token"
      }
    }
  }
}
  • 若 erispulse-apimcp 不在 PATH,把 command 换为解释器内的绝对路径(python -c "import ErisPulse_ApiMCP.server as s; print(s.__file__)" 定位安装位置,或直接用 command: python + args: ["-m", "ErisPulse_ApiMCP.server"])

  • 地址/Token 也可用命令行参数 --url / --token 传入(优先于环境变量),但 --token 会暴露在进程列表中——推荐只用环境变量;--url 必须带 http:// 或 https://

  • 保存后完全退出并重启 Claude Desktop,工具列表出现 erispulse 服务器即接入成功

MCP Tools(17 个)

Tool

说明

list_modules

列出已注册模块及状态(loaded/registered/disabled、enabled、failed、stale)

get_module_info(name)

模块注册信息 + 元信息(版本/描述/服务契约/最近错误)

call_module(name, method, args?, kwargs?, rpc_timeout?)

跨模块 RPC;私有方法拒绝;受 module_call_whitelist 白名单约束;RPC 超时用 rpc_timeout(秒,仅协程方法生效;kwargs 里的 timeout 无法透传会被剔除并在响应 note 提示);被调方异常只回类型名,详情进机器人日志

reload_module(name)

模块热重载(allow_module_reload,默认允许)

list_adapters

列出平台适配器及状态、Bot 在线概况

get_adapter_status(platform)

单平台运行状态与 Bot 详情

reload_adapter(platform)

适配器重载(allow_adapter_reload,默认禁用)

send_message(platform, target_type, target_id, method, content, account?)

发消息:target_type 限 user/group/channel/guild/thread(private 自动转 user);Text 文本 / Image Voice Video File 传 URL 或 base64(content ≤ 32KB);受 send_target_whitelist 白名单约束;account 指定多 bot 部署下的发送账户;方法需要额外参数时提前拒绝并列出缺参

recent_messages(platform?, session?, limit=50)

最近消息回看(经 transcript;会话键 平台:类型:ID,类型限 private/group/user/channel/guild/thread,格式非法 400;limit 接受字符串数字)

subscribe_events(types)

订阅事件(message/notice/request/meta 或 *),返回 subscription_id 与全部活跃订阅;活跃订阅总数上限 32

unsubscribe(subscription_id)

取消订阅,返回剩余全部活跃订阅

poll_events(since_ts, since_seq, limit?, subscription_id?)

增量轮询缓冲事件;首次传 0,之后传上次返回的 next_since_ts/next_since_seq;可选 subscription_id 只返回该订阅声明类型的事件;响应含 dropped(累计淘汰数),静默期仍在淘汰时附 warning

get_topology

运行时拓扑(模块/适配器/作用域归属),已脱敏

sdk_health

SDK 版本 / 运行时长 / 模块数 / 适配器状态 / 缓冲统计摘要

search_erispulse_docs(query, top_k=5)

检索 ErisPulse 框架文档(独立文档引擎:按框架版本下载并缓存,不依赖其它模块)

read_erispulse_doc(file, limit=8000)

读取文档单文件(路径来自检索结果的 file 字段)

refresh_erispulse_docs()

强制同步文档缓存到当前框架版本

事件观测模式:先 subscribe_events(["message"]),之后周期性 poll_events。事件在机器人侧环形缓冲(默认 1000 条,超限淘汰最旧,响应 dropped 字段可观测累计淘汰量)。入缓冲的消息段为摘要形态:文本截断 500 字符,file/base64/data/url 大块字段替换为 <omitted:len=N>,超 50 段截断。

REST 桥端点(/apimcp/*)

所有端点默认 POST(health 额外支持 GET),请求头携带 X-ApiMCP-Token,请求体 JSON:

端点

对应 tool

请求体要点

/apimcp/modules/list

list_modules

{}

/apimcp/modules/info

get_module_info

{"name": "..."}

/apimcp/modules/call

call_module

{"name","method","args":[],"kwargs":{}}

/apimcp/modules/reload

reload_module

{"name": "..."}

/apimcp/adapters/list

list_adapters

{}

/apimcp/adapters/status

get_adapter_status

{"platform": "..."}

/apimcp/adapters/reload

reload_adapter

{"platform": "..."}

/apimcp/messages/send

send_message

{"platform","target_type","target_id","method","content"}

/apimcp/messages/recent

recent_messages

{"platform"?,"session"?,"limit"?}

/apimcp/events/subscribe

subscribe_events

{"types": ["message"]}

/apimcp/events/unsubscribe

unsubscribe

{"subscription_id": "..."}

/apimcp/events/poll

poll_events

{"since_ts":0,"since_seq":0,"limit"?}

/apimcp/docs/search

search_erispulse_docs

{"query", "top_k"?}

/apimcp/docs/read

read_erispulse_doc

{"file", "limit"?}

/apimcp/docs/refresh

refresh_erispulse_docs

{}

/apimcp/topology

get_topology

{}

/apimcp/health

sdk_health

{}

统一响应:{"ok": true, "data": {...}};失败 {"ok": false, "error": "可读错误"} + 对应状态码(400 参数 / 401 鉴权 / 403 开关或白名单拒绝 / 404 未注册 / 413 请求体或 content 超限 / 500 内部(仅 internal: <异常类型>,详情只进机器人日志)/ 503 桥未配置或 handler 不完整)。

  • token 未配置时除 health(200,data.status = "unconfigured")外全部 503

  • 全部端点默认限流 30 请求/分钟/客户端 IP(SDK RouterManager 内置限流,超限 429 + Retry-After),AI 客户端异常循环重试会被截断

  • 请求体 ≤ 256KB、messages/send 的 content ≤ 32KB(超限 413;大文件请用平台 URL 引用);活跃事件订阅总数 ≤ 32(超出 403)

  • 数值参数(limit / since_ts / since_seq / rpc_timeout)接受数字或字符串数字(如 "50"),非法值 400「须为数字」

配置项(config.toml [ApiMCP] 节)

配置项

默认

说明

token

""

REST 桥访问令牌;必须显式配置,留空则桥不启用(health 探活仍 200,其余 503);支持环境变量 ERISPULSE_APIMCP_TOKEN 覆盖

allow_module_reload

true

允许 AI 触发模块热重载

allow_adapter_reload

false

允许 AI 触发适配器重载(断连风险高,默认关闭)

module_call_whitelist

[]

MCP 可调用模块白名单;["Mod"] 放行整模块公开方法,["Mod.method"] 精确放行;空 = 不限制(仍受目标模块自身 services 契约与私有方法禁令约束)

send_target_whitelist

[]

允许发送消息的目标白名单;条目 "类型:ID"(如 "user:123")精确放行,"类型:*"(如 "group:*")放行该类型全部 ID;空 = 不限制(任何目标均可发送,有越权发送风险,不信任的 AI 环境务必配置)

event_types_allowed

[]

允许订阅的事件类型;空 = 不限制

event_buffer_size

1000

事件环形缓冲容量(10–100000)

max_poll_events

200

单次轮询最多返回事件数(≤500)

recent_window_seconds

3600

最近消息回溯窗口(秒)

所有配置支持热更新:token 设置/切换/清空、缓冲容量调整即时生效。

安全注意事项

  • 只监听本机(强烈建议置顶执行):框架 HTTP server 默认 0.0.0.0:8000,公网/局域网可达面即 REST 桥可达面。仅本机使用时在框架配置设置 server.host = "127.0.0.1";跨机器必须走内网 + 反向代理加 TLS

  • token 必须显式配置:未配置时桥不启用(503),不生成临时 token;token 热更新(设置/切换/清空)即时生效

  • token 即完全控制权,且单 token = 单信任域:持有 token 的客户端可读消息、发消息、调用任意(白名单内)模块方法、查看全部订阅事件(事件缓冲与 dropped 淘汰基线为全桥共享,不按订阅隔离)。多租户/多方接入请拆多个机器人实例。切勿提交到仓库、截图或粘贴到公开频道

  • stdio 命令行的 token 优先走环境变量:--token 参数会暴露在进程列表(ps/任务管理器)中;Claude Desktop 配置的 env 字段即环境变量方式

  • --url 必须带 http:// 或 https:// scheme(无 scheme 的 localhost:8000 会被拒绝并明确报错,避免静默错连 127.0.0.1:80)

  • 最小授权:不信任的 AI 环境请配置 module_call_whitelist 收窄可调用面、配置 send_target_whitelist 收窄发送目标、保持 allow_adapter_reload = false;模块启动时对「白名单为空」「允许模块重载」的宽默认姿态会输出 warning 提示

  • 输出净化声明:拓扑 / modules/call 结果为键名级(密钥类 / 路径类键名整键丢弃)+ 字符串叶子路径形态(盘符 / 前导 / / UNC / file://)+ 含 .. 的值丢弃——注意业务文本字段若以 / 开头(如斜杠命令消息)也会被该规则丢弃;事件入缓冲前消息段已净化为摘要形态。深度净化是目标模块自身的责任,敏感会话仍勿开放订阅

开发

cd ErisPulse-ApiMCP
uv sync          # 安装(含测试依赖)
uv run pytest    # 运行测试(假 SDK 对象,无需真实机器人)
uv run erispulse-apimcp --help

已知限制

  • 事件流为轮询模型(订阅 → 环形缓冲 → AI 轮询),非实时推送;缓冲超限淘汰最旧事件(响应 dropped 字段为累计淘汰量;无新事件但淘汰仍在增加时响应附 warning 提示),高频场景请缩短轮询间隔或调大 event_buffer_size;缓冲与淘汰计数为全桥共享,subscription_id 过滤只作用于返回视图

  • poll_events 游标基于 (ts, seq):机器人重启后缓冲清空,游标从 0 重新开始即可

  • call_module 的 rpc_timeout 透传 SDK module.call 原生超时,仅对协程方法生效(同步方法无超时约束)

  • 事件缓冲中的 message 为摘要形态(文本截断 500 字符、大块字段 <omitted:len=N> 占位、超 50 段截断),不适合作为完整消息回放源;完整消息请用 recent_messages

  • sdk_health 的运行时长以 ApiMCP 模块本次加载时间为基准(模块随框架启动加载,与进程启动时长的误差通常在秒级)

  • recent_messages 跨会话查询依赖 transcript(框架消息记录),历史深度受其保留策略限制

  • recent_messages 的 session 会话键中段类型限 SDK 会话类型集(private/group/user/channel/guild/thread);适配器经 register_custom_type 注册的自定义会话类型默认被 400 拒绝,如需支持须扩展桥层允许集

  • 发送媒体类消息(Image 等)的 content 为 URL 或 base64 字符串(≤ 32KB),文件句柄/本地路径语义取决于各平台适配器实现

  • mcp SDK 兼容 1.x(FastMCP)与 2.x(MCPServer);服务器为同步 HTTP 转发(keep-alive 持久连接,多线程 tool 调用经锁串行化复用),单请求超时默认 10 秒(ERISPULSE_APIMCP_TIMEOUT 可调),仅幂等 GET 类请求在连接失败时重试 1 次

交流

问题与建议请提 Issue。

许可证

MIT

Available Tools

17 tools
call_moduleA

调用机器人内某模块的公开服务方法(跨模块 RPC)。

仅允许公开方法;机器人侧可配置 module_call_whitelist 白名单限制可调用范围, 白名单外调用会被拒绝并返回原因。注意:kwargs 中的 timeout 无法透传(被 SDK 占用),RPC 超时请用独立的 rpc_timeout 参数。

Args: name: 目标模块名 method: 目标方法名(可先用 get_module_info 查看模块声明的 services 契约) args: 位置参数列表(可省略) kwargs: 关键字参数对象(可省略;timeout 键会被剔除) rpc_timeout: RPC 超时秒数(可省略;仅对协程方法生效)

Inputs: name (required), method (required), args, kwargs, +1 more. Returns: result

get_adapter_statusA

查询指定平台适配器的运行状态与各 Bot 在线概况。

Args: platform: 平台名(如 onebot11 / telegram)

Inputs: platform (required). Returns: result

get_module_infoA

查询指定模块的注册信息与元信息(版本/描述/作者/服务契约/最近错误现场)。

Args: name: 模块名(先用 list_modules 获取候选)

Inputs: name (required). Returns: result

get_topologyA

获取机器人运行时拓扑(模块的命令/事件处理器/路由归属、适配器与 Bot 状态、作用域绑定)。 已脱敏:不包含绝对路径与密钥类字段。

Inputs: no named parameters. Returns: result

list_adaptersA

列出机器人已注册的平台适配器及状态(status: started/stopped/disabled,Bot 在线情况)。 发消息前可用本工具确认目标平台名与在线状态。

Inputs: no named parameters. Returns: result

list_modulesA

列出机器人已注册的全部模块及状态(status: loaded/registered/disabled,enabled,failed,stale)。 排查模块问题、了解机器人装了哪些模块时先调用本工具。

Inputs: no named parameters. Returns: result

poll_eventsA

轮询拉取已订阅的新事件(增量游标)。首次传 since_ts=0;之后传上次返回的 next_since_ts / next_since_seq。 响应含 dropped(缓冲累计淘汰数);无新事件但淘汰增加时附 warning 提示。

Args: since_ts: 游标时间戳(首次 0;之后用上次返回的 next_since_ts) since_seq: 游标序号(同秒事件区分;用上次返回的 next_since_seq) limit: 本次最多返回条数(默认机器人侧配置) subscription_id: 可选,只返回该订阅声明类型的事件(subscribe_events 返回的 ID)

Inputs: limit, since_ts, since_seq, subscription_id. Returns: result

read_erispulse_docA

读取框架文档单文件全文(路径来自 search_erispulse_docs 结果的 file 字段)。

Args: file: 文档相对路径(相对文档根目录) limit: 最多返回字符数(默认 8000)

Inputs: file (required), limit. Returns: result

recent_messagesA

查询机器人最近收发的消息(会话记录,非实时订阅)。

实时观测新消息请用 subscribe_events + poll_events;本工具适合回看上下文。

Args: platform: 可选,按平台过滤(如 onebot11) session: 可选,会话键 "平台:类型:ID"(如 "onebot11:group:123456",类型 private/group/user/channel/guild/thread)精确查询该会话;与 platform 同给时须前缀匹配 limit: 最多返回条数(默认 50,上限 500)

Inputs: limit, session, platform. Returns: result

refresh_erispulse_docsA

强制同步框架文档缓存到当前已安装框架版本(框架升级后文档对不上时用)。

Inputs: no named parameters. Returns: result

reload_adapterB

热重载指定平台适配器(会断开并重连平台连接,影响在线消息收发)。

受机器人配置 allow_adapter_reload 开关控制,默认禁用;开启后调用才生效。

Args: platform: 平台名

Inputs: platform (required). Returns: result

reload_moduleA

热重载指定模块(改动模块代码后无需重启机器人)。

受机器人配置 allow_module_reload 开关控制(默认允许);重载失败时返回失败原因。

Args: name: 模块名

Inputs: name (required). Returns: result

sdk_healthA

机器人健康摘要:SDK 版本、运行时长、已加载模块数、各适配器状态、事件缓冲与订阅情况。

Inputs: no named parameters. Returns: result

search_erispulse_docsA

检索 ErisPulse 框架文档(写模块/查 API 用法时先查这里再动手;需机器人装有 QvQChat 模块)。

Args: query: 检索关键词(如 "发送消息"、"register_http_route"、"适配器开发") top_k: 最多返回条数(默认 5,最大 20)

Inputs: query (required), top_k. Returns: result

send_messageA

向指定平台发送消息(经平台适配器 SendDSL)。

Args: platform: 平台名(如 onebot11,先用 list_adapters 确认) target_type: 目标类型:user(私聊)/ group(群聊)/ channel / guild / thread(private 也可,自动转为 user) target_id: 目标 ID(用户 ID / 群号,字符串,≤128 字符) method: 发送方法名:Text(文本)/ Image / Voice / Video / File(后四者为 URL 或 base64) content: 消息内容(Text 为文本字符串;媒体类为 URL 或 base64 字符串) account: 可选,指定发送账户 ID(多 bot 部署时区分用哪个账户发;缺省用适配器默认账户)

Inputs: method (required), content (required), platform (required), target_id (required), +2 more. Returns: result

subscribe_eventsA

订阅机器人事件流(订阅后匹配事件进入机器人侧环形缓冲,供 poll_events 拉取)。 响应含本次 subscription_id 与当前全部活跃订阅(active_subscriptions)。

Args: types: 事件类型列表(OneBot12 标准类型:"message" / "notice" / "request" / "meta",或 "*" 全部)

Inputs: types (required). Returns: result

unsubscribeA

取消事件订阅(停止向环形缓冲写入对应类型事件)。响应含剩余全部活跃订阅。

Args: subscription_id: subscribe_events 返回的 subscription_id

Inputs: subscription_id (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 17 tools

    Disambiguation4/5

    Most tools map to a clear resource+action pair (modules, adapters, events, docs, messaging), and descriptions explicitly disambiguate the tricky pairs (recent_messages vs subscribe_events/poll_events). The main soft spot is status reporting: list_adapters, get_adapter_status, sdk_health and get_topology all surface adapter/Bot state, so an agent may hesitate over which one to reach for.

    Naming Consistency4/5

    The set is overwhelmingly consistent snake_case verb_noun (list_modules, get_module_info, reload_adapter, send_message, subscribe_events, poll_events). A few outliers break the pattern — recent_messages and sdk_health are noun-only, and unsubscribe lacks a noun — but none are confusing.

    Tool Count4/5

    17 tools is slightly above the comfortable range but each covers a distinct capability area (docs, modules, adapters, messaging, event stream, diagnostics) with no obviously redundant tool. The workload is broad enough to justify the count rather than feeling padded.

    Completeness4/5

    Lifecycle coverage is strong: module list/info/call/reload, adapter list/status/reload, event subscribe/poll/unsubscribe, doc refresh/search/read, plus send_message and diagnostics. The notable gap is state mutation — modules surface enabled/disabled/loaded status but there is no enable/disable/start/stop tool, and adapters have reload but not start/stop, leaving a few operations as dead ends.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables clients to interact with PipesHub data and functionality through MCP, including chat, search, record retrieval, directory browsing, sources, and agents.
      7
      17
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to manage Grok Bots through MCP: create, list, search, and delete bots, send and receive messages, read conversation transcripts, search message history, and check usage.
      11
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables any MCP client to access xtiandOS's brain, memory, chat, message bus, shell, Docker, and artifact capabilities through tools, resources, prompts, roots, and sampling.
      ISC
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI clients to connect to example tools, resources, and prompts over MCP, demonstrating integration with IDEs, chatbots, and agent frameworks.
      -