Musael MCP 服务器

服务器

服务器 URL: https://app.musael.com/api/mcp?lang=zh-Hans
传输: Streamable HTTP，无状态 JSON 响应。用 POST 发送 JSON-RPC 消息；GET 和 DELETE 返回 405。
服务器名称: musael

身份验证

每个请求都需要请求头 Authorization: Bearer <token>。没有令牌，或令牌已撤销、过期、错误时，服务器返回 401，并带有指向其 OAuth 元数据的 WWW-Authenticate 头。

OAuth 登录

适用于 ChatGPT、Claude、Cursor、VS Code 以及其他通过登录连接的客户端。客户端按照 MCP 授权规范，从 401 响应中发现一切：

受保护资源元数据（RFC 9728）: https://app.musael.com/.well-known/oauth-protected-resource/api/mcp
授权服务器元数据（RFC 8414）: https://app.musael.com/.well-known/oauth-authorization-server
动态客户端注册（RFC 7591）：仅限公开客户端，无密钥；重定向地址须为 HTTPS，仅回环地址可用 HTTP，或使用应用协议。
带 PKCE 的授权码（仅 S256）。写作者登录后，选择「只读」或「读取与添加」及项目，然后允许或取消。
访问令牌有效期一小时；刷新令牌有效期 90 天，每次使用后更换。
范围：read 和 suggest（对写作者显示为「读取与添加」）。

个人访问令牌

适用于手动配置的客户端，如 Codex、Claude Code 或脚本。写作者在 Musael 的「设置 → 已连接的应用」中创建令牌，选择名称、项目、访问权限和过期时间。

令牌以 sti_ 开头，只显示一次；Musael 只保存它的哈希。
一个账号最多可有 20 个有效令牌。撤销会立即停用令牌。
通过 Authorization 请求头发送。切勿放进 URL。

访问与限制

每次调用都以连接该应用的写作者的身份执行，权限为其当时拥有的权限，范围是为该连接选定的项目。
没有任何工具会修改或删除写作者的文本。添加类工具会创建新的幕、章节、场景或世界条目；suggest_edit 会留下一条提议，由写作者在 Musael 中接受或拒绝。
所有工具始终列出。方案或连接不允许的工具会返回原因，并且什么也不做。
每个令牌每五分钟最多 300 次调用。超过 200,000 个字符的响应会被截断，并附说明建议一次读取一章或一个场景。

工具

共 15 个工具。读取书中文本与提出修改建议包含在 Press 方案中。

工具	作用	方案	访问
`list_projects`	此连接可见的项目，包括其工作区、写作者的角色、场景和最近一次修改。请先使用它：其他每个工具都需要项目 id。	所有方案	读取
`get_profile`	已连接的 Musael 账号：一个永不改变的 id、名称和邮箱。	所有方案	读取
`get_outline`	项目的结构：书、幕、带简介的章节、按阅读顺序排列并带状态、视角和字数的场景，以及未完成的任务。	所有方案	读取
`create_project`	根据一个想法创建新项目，含幕、章节、带简介的空场景和世界条目。	所有方案	读取与添加
`add_to_plan`	在现有项目中添加新的幕、章节和场景。	所有方案	读取与添加
`add_world_entries`	新的角色、地点、物品和派系。已存在的名称保持原样。	所有方案	读取与添加
`read_scene`	以 Markdown 返回一个场景，含其章节、状态、视角、地点和简介。	Press	读取
`read_chapter`	按顺序以 Markdown 返回一个章节的所有场景。	Press	读取
`search_project`	在场景和世界中搜索词语，附简短摘录。	Press	读取
`list_world`	按类型列出世界条目，附别名、标签和笔记开头。	Press	读取
`get_world_entry`	完整的一个世界条目：笔记、关系、已记录的事实，以及提到它的场景。	Press	读取
`get_timeline`	按故事顺序列出世界事件及展示每个事件的场景，并标出不按顺序讲述的。	Press	读取
`get_style_report`	应用对某个场景的风格报告，由固定规则生成，不用 AI。	Press	读取
`get_reader_stats`	已发布书籍的读者逐章数据，供所有者和编辑查看。	Press	读取
`suggest_edit`	对某段文字提出的替换建议或评论。只有写作者接受后文本才会改变。	Press	读取与添加

向侧面滚动以查看完整表格。

示例

把 MUSAEL_TOKEN 设为个人访问令牌。initialize 之后，发送 notifications/initialized，然后列出或调用工具。

Initialize

curl https://app.musael.com/api/mcp?lang=zh-Hans \
  -H "Authorization: Bearer $MUSAEL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"example","version":"1.0.0"}}}'

列出工具

curl https://app.musael.com/api/mcp?lang=zh-Hans \
  -H "Authorization: Bearer $MUSAEL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

curl https://app.musael.com/api/mcp?lang=zh-Hans \
  -H "Authorization: Bearer $MUSAEL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

调用工具

curl https://app.musael.com/api/mcp?lang=zh-Hans \
  -H "Authorization: Bearer $MUSAEL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_projects","arguments":{}}}'

Codex

# ~/.codex/config.toml
[mcp_servers.musael]
url = "https://app.musael.com/api/mcp?lang=zh-Hans"
bearer_token_env_var = "MUSAEL_TOKEN"

Claude Code

claude mcp add --transport http --scope user musael https://app.musael.com/api/mcp?lang=zh-Hans --header "Authorization: Bearer $MUSAEL_TOKEN"

不带令牌

HTTP/2 401
www-authenticate: Bearer realm="Musael", resource_metadata="https://app.musael.com/.well-known/oauth-protected-resource/api/mcp"

{"error":"TOKEN_INVALID"}