# Muse Code

通过 OAuth，在 ~/.config/muse/settings.json 中添加一个 mcpServers 条目，将 Meta 的终端编码代理 Muse Code 连接到 XMemo。

- Canonical: https://docs.xmemo.dev/zh/docs/mcp/muse-code
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: c631844310ded8cc16c2cad894551ed2d09965b65311a9761a503f7d931352f8
- Edition-Digest: dcccd512ffcc449f2e39fc510a1b9fdeb1bd5cc000c6bb8a7e43ec0872d5cdaf
- Source-Revision: sha256:e4bb1025634b1d0521ab71134877bf1e2b23afe54bf4b03acb52c414a035e7f5

## 前置条件

使用从 ~/.config/muse/settings.json 读取 MCP 服务器的 Muse Code 安装。Muse Code 作为 OAuth 客户端连接到 XMemo，因此配置文件中不包含任何令牌。

- 端点: https://xmemo.dev/mcp。
- 认证模式: OAuth（浏览器 PKCE），支持动态客户端注册。
- 配置文件: ~/.config/muse/settings.json。其中必须包含 "schema_version": 1。
- 授予的权限范围: memory:read、memory:write、knowledge:read 和 knowledge:write。
- 自动设置: xmemo setup muse-code 即将随下一个 XMemo CLI 版本推出。在此之前，请使用下方的手动配置。

## 将 XMemo 添加到 settings.json

请在 Muse 之外的终端中编辑 ~/.config/muse/settings.json；Muse 的沙箱会拒绝在 Muse 会话内对该文件所做的编辑。在顶层 camelCase 键 mcpServers 下添加一个 xmemo 条目。此文件中不应包含任何令牌或 Authorization 请求头。

```json
{"schema_version": 1, "mcpServers": {"xmemo": {"type": "streamable-http", "url": "https://xmemo.dev/mcp", "mode": "optional"}}}
```

## 仅保留 mcpServers

Muse 的公开 Web 文档仍显示 snake_case 的 mcp_servers 键，该信息已过时。如果 settings.json 同时包含 mcpServers 和 mcp_servers，Muse 会丢弃所有 MCP 服务器。请将现有的 mcp_servers 块重命名为 mcpServers 并将其条目合并进去，使文件中只保留 mcpServers。

## 使用 OAuth 登录

为 xmemo 服务器运行登录命令，并在浏览器中批准访问。在没有浏览器 UI 的机器上，请添加 --headless。

```bash
muse mcp login xmemo
# Without a browser UI:
muse mcp login xmemo --headless
```

## 重启客户端

登录后重启 Muse，使其使用新的 OAuth 授权加载 xmemo 服务器。

## 验证 XMemo 工具

让 Muse 列出 XMemo 工具，但不调用其中任何工具。

```bash
muse exec "List the names of the tools you have from the xmemo MCP server. Do not call any tools."
```

## 使用真实 recall 调用测试

首次 MCP 调用应为只读。这是实际的 recall 调用，而不是健康检查占位符，并且不会写入记忆。

```text
recall({ query: "connection check", limit: 1 })
```

## 预期响应（字面结构）

成功调用返回以下公开排序文本结构；reference 和 content 是来自已授权记忆空间的真实值。

```text
### XMemo Memory Results:
1. Reference: <opaque-memory-id> | Location: <location>
   > <memory content>
```

## XMemo Skill

Muse 会扫描 ~/.agents/skills、~/.claude/skills 和 ~/.codex/skills，因此已为 Claude Code 或 Codex 安装的 XMemo Skill 无需任何更改即可在 Muse 中使用。

## 常见错误

Muse Code 通过 OAuth 进行连接；大多数错误来自配置键、登录步骤或沙箱。

- 未列出任何 xmemo 工具: settings.json 同时包含 mcpServers 和 mcp_servers，因此 Muse 丢弃了所有 MCP 服务器。请仅保留 mcpServers。
- invalid_grant: 授权无效、已过期或已被使用，或者所选连接已不再有效。请再次运行 muse mcp login xmemo，然后重启 Muse。
- 403 insufficient_scope: 已批准的权限范围不涵盖该调用。请重新登录并批准 memory 和 knowledge 权限范围。
- 对 settings.json 的编辑被拒绝: 该更改是在 Muse 会话内进行的。请从外部终端编辑该文件。

## Muse Code

OAuth client: add xmemo under mcpServers in ~/.config/muse/settings.json, then run muse mcp login xmemo and restart Muse. No token goes in the config. Keep only mcpServers: if mcp_servers is also present, Muse drops every MCP server.

```
{"schema_version": 1, "mcpServers": {"xmemo": {"type": "streamable-http", "url": "https://xmemo.dev/mcp", "mode": "optional"}}}
```