# Muse Code

Meta의 터미널 코딩 에이전트인 Muse Code를 ~/.config/muse/settings.json의 mcpServers 항목 하나로 OAuth를 통해 XMemo에 연결합니다.

- Canonical: https://docs.xmemo.dev/ko/docs/mcp/muse-code
- Locale: ko-KR
- Content-Locale: ko-KR
- Canonical-Content-Digest: c631844310ded8cc16c2cad894551ed2d09965b65311a9761a503f7d931352f8
- Edition-Digest: 6859576e6a9f44052ba425993b6c27f7882ed3e3e731b1a689903b07037f2573
- 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 릴리스에서 곧 제공될 예정입니다. 그때까지는 아래의 수동 구성을 사용하십시오.

## settings.json에 XMemo 추가

~/.config/muse/settings.json은 Muse 외부의 터미널에서 편집하십시오. Muse 샌드박스는 Muse 세션 내부에서 이 파일을 편집하는 것을 거부합니다. 최상위 camelCase 키인 mcpServers 아래에 xmemo 항목을 추가합니다. 이 파일에는 토큰이나 Authorization 헤더를 넣지 않습니다.

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

## mcpServers만 유지

Muse의 공개 웹 문서에는 아직 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 도구 확인

도구를 호출하지 않고 XMemo 도구 목록을 표시하도록 Muse에 요청합니다.

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

## 실제 recall 호출로 테스트

첫 번째 MCP 호출은 읽기 전용으로 수행합니다. 이것은 헬스체크 플레이스홀더가 아닌 실제 회상 호출이며 메모리를 작성하지 않습니다.

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

## 예상 응답 (리터럴 형태)

성공적인 호출은 아래의 공개 순위 지정 텍스트 형태를 반환합니다. 참조 및 콘텐츠는 승인된 메모리 공간의 실제 값입니다.

```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"}}}
```