ErisPulse-ApiMCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ErisPulse-ApiMCP send 'Hello everyone!' to group 123456 on telegram"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
简体中文 | 繁體中文 | 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命令以官方mcpSDK 起 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/healthClaude 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 | 说明 |
| 列出已注册模块及状态(loaded/registered/disabled、enabled、failed、stale) |
| 模块注册信息 + 元信息(版本/描述/服务契约/最近错误) |
| 跨模块 RPC;私有方法拒绝;受 |
| 模块热重载( |
| 列出平台适配器及状态、Bot 在线概况 |
| 单平台运行状态与 Bot 详情 |
| 适配器重载( |
| 发消息: |
| 最近消息回看(经 transcript;会话键 |
| 订阅事件( |
| 取消订阅,返回剩余全部活跃订阅 |
| 增量轮询缓冲事件;首次传 0,之后传上次返回的 |
| 运行时拓扑(模块/适配器/作用域归属),已脱敏 |
| SDK 版本 / 运行时长 / 模块数 / 适配器状态 / 缓冲统计摘要 |
| 检索 ErisPulse 框架文档(独立文档引擎:按框架版本下载并缓存,不依赖其它模块) |
| 读取文档单文件(路径来自检索结果的 |
| 强制同步文档缓存到当前框架版本 |
事件观测模式:先
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 | 请求体要点 |
| list_modules |
|
| get_module_info |
|
| call_module |
|
| reload_module |
|
| list_adapters |
|
| get_adapter_status |
|
| reload_adapter |
|
| send_message |
|
| recent_messages |
|
| subscribe_events |
|
| unsubscribe |
|
| poll_events |
|
| search_erispulse_docs |
|
| read_erispulse_doc |
|
| refresh_erispulse_docs |
|
| get_topology |
|
| 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] 节)
配置项 | 默认 | 说明 |
|
| REST 桥访问令牌;必须显式配置,留空则桥不启用(health 探活仍 200,其余 503);支持环境变量 |
|
| 允许 AI 触发模块热重载 |
|
| 允许 AI 触发适配器重载(断连风险高,默认关闭) |
|
| MCP 可调用模块白名单; |
|
| 允许发送消息的目标白名单;条目 |
|
| 允许订阅的事件类型;空 = 不限制 |
|
| 事件环形缓冲容量(10–100000) |
|
| 单次轮询最多返回事件数(≤500) |
|
| 最近消息回溯窗口(秒) |
所有配置支持热更新:token 设置/切换/清空、缓冲容量调整即时生效。
安全注意事项
只监听本机(强烈建议置顶执行):框架 HTTP server 默认
0.0.0.0:8000,公网/局域网可达面即 REST 桥可达面。仅本机使用时在框架配置设置server.host = "127.0.0.1";跨机器必须走内网 + 反向代理加 TLStoken 必须显式配置:未配置时桥不启用(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透传 SDKmodule.call原生超时,仅对协程方法生效(同步方法无超时约束)事件缓冲中的
message为摘要形态(文本截断 500 字符、大块字段<omitted:len=N>占位、超 50 段截断),不适合作为完整消息回放源;完整消息请用recent_messagessdk_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。
Telegram:https://t.me/ErisPulse
许可证
Available Tools
17 toolscall_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
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.
Maintenance
Related MCP Connectors
Build and run AI workflows, agents, data tables and 1000+ API integrations from any MCP client.
Agent communication platform for agent to agent messaging via MCP. Messages, channels, skills.
Connect AI clients to your Dactic work context through a hosted MCP service.
Discover and call AI agents via MCP. Supports A2A agents and platform agents with async tasks.
Related MCP Servers
AlicenseAqualityBmaintenanceEnables clients to interact with PipesHub data and functionality through MCP, including chat, search, record retrieval, directory browsing, sources, and agents.717Apache 2.0- AlicenseAqualityCmaintenanceEnables 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.113MIT
- AlicenseNot gradedqualityDmaintenanceEnables 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
- FlicenseNot gradedqualityDmaintenanceEnables AI clients to connect to example tools, resources, and prompts over MCP, demonstrating integration with IDEs, chatbots, and agent frameworks.-