convez.ai
MCP ServerAutomaçãoAvançado
GhostXia

AIRP MCP Server

GhostXia/AIRP-MCP-Server

Gerenciador de dados para roleplay puro MCP, sem AI inference

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP puro em Rust para gerenciamento de dados de roleplay com IA, sem chamar APIs externas ou criar runtimes. Oferece 38 ferramentas para importar character cards, gerenciar sessões, aplicar world books, manter estado e memória — funciona como um sistema de armazenamento e montagem de contexto para clientes MCP como Claude Code, Cursor ou pi.

Instalação

$npx convez-ai GhostXia/AIRP-MCP-Server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
35
Forks
4
Acompanhando
0
Saúde
28%
Último commit
há 3 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Construir sistemas de roleplay com personagens persistentes em Claude Code ou Cursor
  • Gerenciar world books, presets e histórico de conversas para narrativas longas
  • Integrar character cards de SillyTavern em fluxos MCP standalone

Veredito

Ferramenta técnica sólida para quem quer roleplay complexo sem caixa-preta: separa claramente armazenamento de dados da lógica de IA. Exige Rust, configuração de cliente MCP e compreensão profunda de character cards, não é plug-and-play.

README

A tradução para o português deste README ainda está na fila.

AIRP MCP Server

致谢:本项目的部分理念与实践,参考、借鉴自 Discord 社区 「类脑ΟΔΥΣΣΕΙΑ」 内的相关讨论与教程,并与社区成果相互参照。

AIRP = AI Roleplay Data Manager

CI License: MIT OR Apache-2.0

一个纯 MCP 协议的角色扮演数据管理服务器。不调用任何 AI API,不自造 Agent runtime,不做推理。 所有推理、叙事推进、角色演绎,都由 MCP Client(Claude Code / Cursor / pi / Codex)通过 AIRP 暴露的 Tools / Resources / Prompts 完成。AIRP 只负责把角色卡、世界书、预设、会话、状态、记忆存好、取好、装配好。

独立可用 · 非全家桶:本仓是自包含的标准 MCP server——零依赖其他 AIRP 仓库,配任何 MCP 客户端(Claude Code / Cursor / pi / Codex / 自研皆可)即可单独运行,38 个工具任取子集使用。 下方提到的 AIRP-Core / AIRP-Gateway 是可选、各自独立的伙伴项目,不是前置依赖——按需拆用, 像乐高积木,不必整套。

AIRP-MCP-Server 是 AIRP 的轻量级 MCP 版本。若需完整的流式 SSE 网关、实时角色状态面板、 守护进程部署、OpenAI 兼容 API 代理等高级功能,可选用 AIRP-Core —— AIRP 项目的全面版本(独立项目,非本仓依赖)。


快速开始

# 编译
cargo build --release

# Stdio 模式(推荐:Claude Code / Cursor / pi)
./target/release/airp-mcp mcp --data-dir ./data

# HTTP 模式(局域网:电脑跑后端、手机同 wifi 对话)
./target/release/airp-mcp serve --bind 0.0.0.0:3000 --data-dir ./data
# 局域网暴露建议开鉴权:所有 /mcp/v1 请求须带 Authorization: Bearer <密钥>
AIRP_HTTP_TOKEN=your-secret ./target/release/airp-mcp serve --bind 0.0.0.0:3000 --data-dir ./data

/mcp/v1 是标准 MCP Streamable HTTP 端点(spec 2025-06-18,基于 rmcp):真实 JSON-RPC 派发、initialize 生命周期、会话 Mcp-Session-Id、MCP-Protocol-Version 校验、application/json↔text/event-stream 协商。任何 MCP 客户端(如 AIRP-Gateway)可直接对接。鉴权见安全与部署。

MCP Client 配置

Claude Code / Cursor(mcp.json 或 cursor.json):

{
  "mcpServers": {
    "airp": {
      "command": "airp-mcp",
      "args": ["mcp", "--data-dir", "./data"]
    }
  }
}

最小用法(单块乐高)

配好上面的 Client 即可——无需任何工作流、无需其他 AIRP 仓库。一个能用的最小闭环只用少数几个工具:

  1. import_card 导入角色卡(PNG / JSON)→ 拿到 character_id
  2. start_session 开一个会话
  3. 之后 append_message 追加对话、get_recent_context 取回上下文

就这些。其余 30+ 工具、下面 SKILL.md 的 6 阶段 / 三幕范例、Core / Gateway —— 全是可选增强,按需取用,不必整套。

Agent 用法指南

项目根目录的 SKILL.md 是给 AI Agent 阅读的操作手册:

  • §0.5 使用前优先评估清单(决策提示,见下方「RP 文风质量」)
  • 完整 RP 工作流(6 阶段标准轮次 + 三幕叙事弧)
  • 并行调用策略(2–4x 加速)、多角色场景管理、预设文风一键移植
  • §16 执行隔离:用隔离 subagent 书写 RP
  • 38 个工具 / 19 个资源 / 12 个提示词的速查表

功能总览

38 个 MCP Tools

类别工具用途
角色卡import_card导入 SillyTavern 角色卡。推荐 png_path(服务端读盘解析,base64 不进上下文、不烧 token)或 png_base64;≤ 10 MiB
角色卡list_characters列出所有角色
角色卡get_character查看角色详情
角色卡delete_character删除角色及所有数据
会话start_session创建新会话(自动加载 preset + lorebook + state)
会话list_sessions列出角色的所有会话
会话append_message向会话追加消息(JSONL)
会话get_recent_context获取最近 N 条消息
会话rollback_messages回滚最后 N 条消息
记忆seal_volume封存当前会话为归档卷(支持清空,省 token)
世界书apply_lorebook关键词扫描 → 返回匹配的世界书条目
世界书update_lorebook更新世界书
状态update_state更新实时状态(HP / MP / 位置 / 关系值)
状态get_live_state获取当前状态
分析analyze_card4 档分级角色卡分析(Tier 0–3)
分析get_gating_status查看检查点进度
预设list_presets列出所有 AI 预设
预设get_preset查看预设详情
预设import_preset导入 SillyTavern 预设 JSON
预设write_preset_artifactAgent 写入预设分析产物
预设list_preset_regex_scripts列出预设正则脚本(含元数据)
预设remove_preset_regex_script删除预设正则脚本
预设set_preset_regex_enabled启用/禁用预设正则脚本
拆解/导出decompose_character拆解角色卡为 7 个 Markdown 文件(分析模板,含 TODO 占位)
拆解/导出decompose_preset拆解预设为结构化文档
拆解/导出export_context_bundle导出自包含成品上下文包(context.md + raw sidecar),交接给隔离 subagent;可选 thinking_mode_text 置于正文最前;未知捆绑内容原样旁路不解析
场景create_scene创建多角色场景
场景list_scenes列出所有场景
场景get_scene查看场景配置
场景add_character_to_scene向场景添加角色
场景merge_lorebooks合并多角色世界书(去重排序,纯算法)
场景build_scene_system_prompt装配多角色场景系统提示词(前载 union 世界书;可选 style_enhance 注入对话范例+suffix 文风锚)
插件plugin_kv_get / plugin_kv_set插件 KV(plugins/{name}/{key}.json,任意 JSON,零 schema)
插件plugin_jsonl_append / plugin_jsonl_read插件 JSONL(O(1) 追加 / 分页读,带字节上限)
插件plugin_blob_write / plugin_blob_read插件任意文件。读默认 encoding=auto:服务端探测 UTF-8 → 返文本;二进制只返描述符不倒 base64(乱码白烧 token),需要才 encoding=base64。单次 32 KiB raw

M_PLUGIN_DATA(戒律 4 · 开放接入):任何第三方插件、任何语言,取一个 plugin_name 命名空间即可在 data/plugins/{plugin_name}/ 存取自己的数据 —— 无 manifest、无注册、无 schema 强制。AIRP 不解析、不校验、不索引其语义。

19 个 MCP Resource URIs

URI内容
airp://characters角色 ID 列表
airp://characters/{id}/card角色卡完整 JSON
airp://characters/{id}/greetings开场语库(含备选问候语)
airp://characters/{id}/world/lorebook世界书
airp://characters/{id}/state/live实时状态
airp://characters/{id}/memory/current当前会话摘要
airp://characters/{id}/memory/index卷索引
airp://characters/{id}/memory/volumes/{n}归档卷(n="latest"=最新)
airp://characters/{id}/gating/checkpoints检查点进度
airp://presets预设 ID 列表
airp://presets/{id}预设详情
airp://presets/{id}/raw预设原始 JSON(>100KB 截断 + 翻页提示)
airp://presets/{id}/artifacts预设分析产物文件树
airp://presets/{id}/regex预设正则脚本列表
airp://scenes场景列表
airp://scenes/{id}场景完整配置
airp://plugins插件命名空间列表
airp://plugins/{name}/files插件文件相对路径列表(递归)
airp://plugins/{name}/data/{path}插件文件内容(UTF-8;二进制用 plugin_blob_read;超限截断)

12 个 MCP Prompts

Prompt用途
build_system_prompt组装角色系统提示词(支持 preset 注入,含 mes_example)
filter_text应用预设正则过滤(八股后处理)
state_update_instruction状态更新 <state> 格式说明
seal_volume卷封存 Agent 指导
build_scene多角色场景装配(含并行加载引导)
analyze_preset预设分析 3 步 workflow
tune_preset按用户反馈热调预设文风(改预设源头,非洗输出;best-effort 不保证)
prompt_decompose_character角色卡拆解的 Agent 指导(6 步)
prompt_enhance_analysis增强分析的 Agent 指导(5 步)
prompt_build_session_context会话上下文构建的 Agent 指导
validate_card角色卡内容验证(未知宏 / 孤儿代码 / 破损 markup)
validate_preset预设验证(破损正则 / 未知 identifier / 参数异常)

RP 文风质量与 Agent 决策提示

AIRP 不调 LLM、不强制工作流,但会主动给 Agent 决策提示:在 MCP instructions 与 SKILL.md §0.5 写明「使用前优先评估」的得失清单(为何该做 + 不做的代价),让 Agent 知情自选,而非被命令。社区实践中「文风死人化 / 出戏」的常见成因都有对应解:

决策提示治什么相关能力
隔离 subagent 书写 RP主 Agent 编程上下文压扁文笔(「死人化」)export_context_bundle 产成品上下文包
首轮注入思考模式思考层没入戏(比文风更上游,社区公认第一杠杆)export_context_bundle 的 thinking_mode_text 槽
文风僵 → 改预设源头跨模型预设错配;洗输出只治标tune_preset
Token 纪律 / 世界书关键词触发整文件 / 全历史灌爆预算分页读 + seal_volume + apply_lorebook
八股语病 → 正则后处理prompt 硬禁反伤模型思考预设 regex_scripts + filter_text

全部非强制:内容(思考模式块、文风、预设等)是用户数据,AIRP 不代写、不解析;Agent 自行决断。详见 SKILL.md §0.5(决策清单)/ §16(执行隔离)。


架构

┌──────────────────────────────────────────────┐
│  MCP Client (Claude Code / Cursor / pi ...)    │  ← 推理、叙事、状态判断
│  ─ read SKILL.md → call AIRP tools ──────────  │
│                                                │
│  最终决策权在 Agent。AIRP 的 Tools / Resources │
│  / Prompts / SKILL.md 均为建议(含决策提示),  │
│  Agent 自行选择用哪些、怎么用。                 │
└─────────────┬──────────────────────────────────┘
              │ MCP 协议 (stdio / HTTP)
┌─────────────▼──────────────────────────────────┐
│  AIRP MCP Server (本项目)                        │  ← 只做数据管理
│  src/models/    数据模型                         │
│  src/storage/   文件存储 + 迁移 + 路径安全        │
│  src/mcp/       MCP 协议实现(tools/resources/   │
│                 prompts)                         │
│  src/transport/ stdio / HTTP                     │
└──────────────────────────────────────────────────┘

四条边界(贯穿设计的「铁律」):

  • 不调任何 AI LLM API —— PresetConfig 里的 temperature/top_p 等仅供 Agent 参考
  • 不做推理 —— 叙事推演、角色扮演、状态判断全由 Agent 完成
  • 不维护 UI —— 界面由 MCP Client 提供
  • 不强制工作流,但给决策提示 —— 一切是建议;用得失提示抬高优先级、引导而非命令(AI 自行决断)。改法通用优先于特供,不为单一客户端/模型特判

数据目录结构

data/
├── characters/
│   └── {id}/
│       ├── card.json              # 角色卡
│       ├── card.png               # 原始 PNG
│       ├── data.json              # 元数据(分析 tier 等)
│       ├── world/lorebook.json    # 世界书
│       ├── state/live.json        # 实时状态
│       ├── state/history.jsonl    # 状态变更历史
│       ├── gating/checkpoints.json
│       ├── analysis/              # analyze_card 产物
│       ├── memory/
│       │   ├── index.md           # 卷索引
│       │   └── volumes/vol_*.md   # 归档卷
│       └── sessions/{id}/
│           ├── meta.json
│           └── chat.jsonl
├── presets/
│   └── {name}/
│       ├── preset.json            # SillyTavern 预设
│       ├── regex/*.json           # 正则脚本
│       └── analysis/              # Agent 分析产物
├── scenes/
│   └── {id}/
│       └── scene.json             # 多角色场景配置
└── plugins/
    └── {plugin_name}/             # 第三方插件自管数据(零 schema)

开发

cargo build --release                  # 构建 lib + bin
cargo test --test plugin_data_test     # 独立测试目标(全绿)
cargo fmt
  • CI:GitHub Actions 在每次 push / PR 跑 cargo build + cargo test --test plugin_data_test(见徽章)。
  • 全量 cargo test 暂缓:tests/integration_test.rs 在 main 上预存损坏(crate:: 路径 + PNG zTXt/base64 测试辅助),属独立 follow-up。

安全与部署

AIRP 的威胁模型假设 本地、单用户、stdio / loopback 运行。基于此:

  • 路径安全:所有插件/预设的读写经组件式校验 —— 拒 .. 逃逸、拒绝对路径、拒符号链接,结果锁在 data/ 根内(Storage::safe_resolve_for_write)。
  • 输入限制:import_card 的 PNG ≤ 10 MiB(png_path 走 metadata 预检,炸弹文件不读即拒),PNG 解码器设分配上限(挡 zlib 压缩炸弹);工具单次读 ≤ 32 KiB(≈9K token 文本;base64 约 1.33×;可用环境变量 AIRP_MAX_READ_BYTES 覆盖,下限 1 KiB);plugin_blob_read 默认 encoding=auto,二进制只返描述符不倒 base64;预设 raw / JSONL 超限截断或分页。
  • PNG 导入用 png_path 而非 png_base64:让 AIRP 服务端直接读盘解析,base64 永不进模型上下文 —— 否则 Agent 为产生 base64 得先把 PNG 读进上下文(10 MiB 卡 ≈ 13 MiB 文本),烧光 token。
  • 插件信任模型:data/plugins/ 是零 schema、开放接入(戒律 4)—— AIRP 不解析、不校验、不沙箱化插件数据语义。插件写入被限制在自己的 plugins/{name}/ 命名空间内(拒 ../绝对路径/符号链接),但内容本身不受信任。⚠️ 只安装可信来源的插件。
  • HTTP 暴露:局域网 OK,公网 NO。serve --bind 支持同 wifi 下「电脑跑后端 + 手机对话」这类用法。
    • 可选 bearer 鉴权:设环境变量 AIRP_HTTP_TOKEN=<你的密钥>,之后所有 /mcp/v1 请求须带 Authorization: Bearer <密钥>(/health 不校验)。LAN 暴露时强烈建议设置 —— 否则同网段任何设备都能调读写接口(含 png_path 服务端读文件)。绑定非 loopback 且未设 token 时会有启动警告。
    • 切勿绑定公网 IP 或做公网端口转发。需要远程访问请走 VPN / SSH 隧道,别裸暴露。
  • 备份:数据是本地文件,建议定期备份 data/ 目录。

隐私

AIRP MCP Server 是 本地优先 的二进制工具:

  • 所有数据存储在用户本地磁盘
  • 通信走本机(stdio)或自部署 HTTP(默认 loopback;可选局域网,见安全与部署);不经任何第三方
  • 项目方不收集、不接收、不存储任何用户数据

许可

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Ver o original no GitHub

Bom para

Relacionados