ErisPulse-ApiMCP
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| ERISPULSE_APIMCP_URL | No | Base URL of the ErisPulse ApiMCP REST bridge, e.g. http://127.0.0.1:8000. Must include the http:// or https:// scheme (a bare host:port is rejected). Can also be passed via the --url command line argument, which takes precedence over the environment variable. | |
| ERISPULSE_APIMCP_TOKEN | Yes | Access token for the ErisPulse ApiMCP REST bridge, sent as the X-ApiMCP-Token header. Must match the token configured in the robot's config.toml [ApiMCP] section (or its ERISPULSE_APIMCP_TOKEN). The bridge stays disabled (503 on all endpoints except health) when no token is configured. Can also be passed via --token, but that exposes the token in the process list, so the environment variable is recommended. | |
| ERISPULSE_APIMCP_TIMEOUT | No | Timeout in seconds for each HTTP request forwarded to the robot's REST bridge (default 10). |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
本服务把 ErisPulse 机器人运行时开放为 MCP tools:收发消息、调用模块 API、管理模块/适配器、订阅并轮询事件流、查看运行拓扑与健康状态。事件观测请先 subscribe_events 再用 poll_events 增量轮询。
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_modulesA | 列出机器人已注册的全部模块及状态(status: loaded/registered/disabled,enabled,failed,stale)。 排查模块问题、了解机器人装了哪些模块时先调用本工具。 |
| get_module_infoA | 查询指定模块的注册信息与元信息(版本/描述/作者/服务契约/最近错误现场)。 Args: name: 模块名(先用 list_modules 获取候选) |
| 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 超时秒数(可省略;仅对协程方法生效) |
| reload_moduleA | 热重载指定模块(改动模块代码后无需重启机器人)。 受机器人配置 allow_module_reload 开关控制(默认允许);重载失败时返回失败原因。 Args: name: 模块名 |
| list_adaptersA | 列出机器人已注册的平台适配器及状态(status: started/stopped/disabled,Bot 在线情况)。 发消息前可用本工具确认目标平台名与在线状态。 |
| get_adapter_statusA | 查询指定平台适配器的运行状态与各 Bot 在线概况。 Args: platform: 平台名(如 onebot11 / telegram) |
| reload_adapterB | 热重载指定平台适配器(会断开并重连平台连接,影响在线消息收发)。 受机器人配置 allow_adapter_reload 开关控制,默认禁用;开启后调用才生效。 Args: platform: 平台名 |
| 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 部署时区分用哪个账户发;缺省用适配器默认账户) |
| search_erispulse_docsA | 检索 ErisPulse 框架文档(写模块/查 API 用法时先查这里再动手;需机器人装有 QvQChat 模块)。 Args: query: 检索关键词(如 "发送消息"、"register_http_route"、"适配器开发") top_k: 最多返回条数(默认 5,最大 20) |
| read_erispulse_docA | 读取框架文档单文件全文(路径来自 search_erispulse_docs 结果的 file 字段)。 Args: file: 文档相对路径(相对文档根目录) limit: 最多返回字符数(默认 8000) |
| refresh_erispulse_docsA | 强制同步框架文档缓存到当前已安装框架版本(框架升级后文档对不上时用)。 |
| recent_messagesA | 查询机器人最近收发的消息(会话记录,非实时订阅)。 实时观测新消息请用 subscribe_events + poll_events;本工具适合回看上下文。 Args: platform: 可选,按平台过滤(如 onebot11) session: 可选,会话键 "平台:类型:ID"(如 "onebot11:group:123456",类型 private/group/user/channel/guild/thread)精确查询该会话;与 platform 同给时须前缀匹配 limit: 最多返回条数(默认 50,上限 500) |
| subscribe_eventsA | 订阅机器人事件流(订阅后匹配事件进入机器人侧环形缓冲,供 poll_events 拉取)。 响应含本次 subscription_id 与当前全部活跃订阅(active_subscriptions)。 Args: types: 事件类型列表(OneBot12 标准类型:"message" / "notice" / "request" / "meta",或 "*" 全部) |
| unsubscribeA | 取消事件订阅(停止向环形缓冲写入对应类型事件)。响应含剩余全部活跃订阅。 Args: subscription_id: subscribe_events 返回的 subscription_id |
| 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) |
| get_topologyA | 获取机器人运行时拓扑(模块的命令/事件处理器/路由归属、适配器与 Bot 状态、作用域绑定)。 已脱敏:不包含绝对路径与密钥类字段。 |
| sdk_healthA | 机器人健康摘要:SDK 版本、运行时长、已加载模块数、各适配器状态、事件缓冲与订阅情况。 |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 17 tools
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.
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.
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.
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.