diff --git a/apps/app/public/skills/mcp-setup b/apps/app/public/skills/mcp-setup index 395d6f4a..72494cb8 100644 --- a/apps/app/public/skills/mcp-setup +++ b/apps/app/public/skills/mcp-setup @@ -1,341 +1,16 @@ --- name: mcp-setup -description: >- - Set up Walrus Memory in MCP-aware AI clients such as Claude Desktop, - Cursor, Codex, Claude Code, ChatGPT, Antigravity, or another MCP host. - This is for normal users who want portable memory in their AI client. +description: Legacy alias for the Walrus Memory setup skill. license: Apache-2.0 metadata: author: Walrus Memory version: "1.0" - requires: Node.js 20+ for local stdio MCP clients; a Sui-compatible wallet --- -# Walrus Memory MCP - One-Prompt Setup +# Walrus Memory Setup -## Purpose - -Set up Walrus Memory for a normal user inside their AI client. This flow is for -Claude Desktop, Cursor, Codex, Claude Code, ChatGPT, Antigravity, and other -MCP-aware clients. - -When invoked through the dashboard prompt: - -```text -Run `curl -sL https://memory.walrus.xyz/skills/mcp-setup` and use the -returned instructions to connect Walrus Memory to this AI client. -``` - -fetch this file, configure the user's AI client for Walrus Memory MCP, sign in -with their Sui wallet, restart the client, and verify memory works. - -## Scope - -Do this: - -- connect Walrus Memory MCP to the user's AI client -- help the user sign in through `memwal_login` or the MCP package login command -- verify `memwal_remember` and `memwal_recall` - -Do not do this in this flow: - -- configure MCP only because a code project exists -- install the Walrus Memory SDK or edit app source code - -If the user explicitly asks for SDK or app-code integration, stop and say this -one-prompt setup is for MCP clients. Point them to the SDK docs or ask whether -they want a separate developer integration. - -## Rules - -1. Treat MCP client setup as the primary goal. -2. Ask which AI client to configure if the user did not name one. -3. Detect whether this AI client can execute local shell commands and edit - local user config files on the user's machine. -4. If this AI client cannot access the user's local terminal or filesystem - (common in Claude Desktop and other desktop chats), do not pretend setup is - automatic. Give the exact command/config for the user to run or paste - manually, then wait for them to report the result. -5. If local shell/file access is available, show the command or config file - before changing user-level MCP config. -6. Merge config into existing `mcpServers`; do not remove other MCP servers. -7. Never commit or print real delegate private keys from - `~/.memwal/credentials.json`. -8. Prefer local stdio MCP for clients that support `command + args`. -9. Use remote Streamable HTTP only when the client clearly supports remote MCP - servers with custom headers. -10. ChatGPT custom MCP apps use a remote MCP flow. Do not invent a local `npx` - ChatGPT Desktop config. -11. After config changes, tell the user to fully quit and reopen the AI client. -12. Stop at the first failure and report the exact blocker. - -## Execution modes - -### Guided mode - -Use guided mode when the AI client cannot directly run terminal commands or -write local files on the user's machine. This is common for Claude Desktop, -ChatGPT, and other desktop/web chat clients. - -In guided mode: - -- tell the user which config file to open -- show the exact JSON/TOML block to paste -- show the exact terminal command to run, if needed -- ask the user to confirm what happened before continuing -- do not say that you installed or configured anything yourself - -### Agentic mode - -Use agentic mode only when this session has explicit local shell and filesystem -access on the user's machine. - -In agentic mode: - -- inspect existing config before editing it -- preserve other MCP servers -- show a short summary of the edit -- still ask the user to restart the AI client manually - -## Step 1 - Check Node.js - -First decide whether you are in guided mode or agentic mode. - -For local stdio clients, Node.js must be checked on the user's machine. In -guided mode, ask the user to run: - -```bash -node -v -``` - -In agentic mode, run it yourself. Walrus Memory MCP requires Node.js 20 or -newer. If Node.js is missing or older than 20, tell the user to install Node.js -20+ from https://nodejs.org/ and stop. - -The user also needs a Sui-compatible wallet available in the browser for login. - -## Step 2 - Pick the client - -If the user did not name a client, ask: - -```text -Which AI client should I connect to Walrus Memory: Claude Desktop, Cursor, -Codex, Claude Code, ChatGPT, or another MCP client? -``` - -Use local stdio config for: - -- Claude Desktop -- Cursor -- Codex -- Claude Code -- Antigravity or another local-command MCP host - -Use remote MCP guidance for: - -- ChatGPT custom MCP apps -- clients that do not support local `command + args` - -## Step 3 - Configure local stdio MCP - -Use this MCP server command: - -```bash -npx -y @mysten-incubation/memwal-mcp -``` - -### Cursor - -Edit `~/.cursor/mcp.json` and merge: - -```json -{ - "mcpServers": { - "memwal": { - "command": "npx", - "args": ["-y", "@mysten-incubation/memwal-mcp"] - } - } -} -``` - -### Claude Desktop - -Edit: - -- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` -- Windows: `%APPDATA%\Claude\claude_desktop_config.json` - -Merge: - -```json -{ - "mcpServers": { - "memwal": { - "command": "npx", - "args": ["-y", "@mysten-incubation/memwal-mcp"] - } - } -} -``` - -### Codex - -Edit `~/.codex/config.toml` and append: - -```toml -[mcp_servers.memwal] -command = "npx" -args = ["-y", "@mysten-incubation/memwal-mcp"] -``` - -### Claude Code - -Run: - -```bash -claude mcp add --scope user memwal -- npx -y @mysten-incubation/memwal-mcp -``` - -Verify: - -```bash -claude mcp list -``` - -### Other local MCP clients - -Add: - -- name: `memwal` -- command: `npx` -- args: `["-y", "@mysten-incubation/memwal-mcp"]` - -## Step 4 - Sign in - -Prefer inline login after the client is configured and restarted: - -```text -Use memwal_login to sign me in to Walrus Memory. -``` - -The tool opens a browser flow. The user connects their Sui wallet and approves -the delegate key. Credentials are saved locally at: - -```text -~/.memwal/credentials.json -``` - -If inline login is not available yet, run manual login in a real terminal: - -```bash -npx -y @mysten-incubation/memwal-mcp login --prod -``` - -## Step 5 - Restart the client - -Fully quit and reopen the AI client. On macOS, use `Cmd+Q`; closing the window -is not enough. The first start may take 5-10 seconds while `npx` fetches the -package. - -## Step 6 - Verify tools - -Ask the AI client: +This route is a compatibility alias. Use the general setup skill instead: ```text -What MCP tools do you have available? +Run `curl -sL https://memory.walrus.xyz/skills/setup` and use the returned instructions to connect Walrus Memory to this AI client. ``` - -Expected Walrus Memory tools: - -- `memwal_remember` -- `memwal_recall` -- `memwal_analyze` -- `memwal_restore` -- `memwal_login` -- `memwal_logout` - -If only `memwal_login` works, credentials are missing. Run `memwal_login` or -the manual login command again. - -## Step 7 - Verify memory - -Ask: - -```text -Use memwal_remember to save: "My favorite programming language is Rust and I drink black coffee in the mornings." -``` - -Wait a few seconds, then ask: - -```text -Use memwal_recall to search for: "what is my favorite language?" -``` - -The client should retrieve the saved Rust memory. - -## ChatGPT - -ChatGPT custom MCP apps use remote MCP servers, not a local `npx` stdio config. - -If the user's ChatGPT account supports custom MCP apps / developer mode: - -1. Confirm they can create a custom MCP app in ChatGPT settings. -2. Use this remote MCP endpoint: - -```text -https://relayer.memory.walrus.xyz/api/mcp -``` - -3. Authenticate with headers: - -```text -Authorization: Bearer -x-memwal-account-id: -``` - -The values come from `~/.memwal/credentials.json` after a successful -`memwal-mcp login --prod`. - -If ChatGPT cannot attach the required headers or the user's plan/workspace does -not allow custom MCP apps, explain the blocker and offer Claude Desktop, -Cursor, Codex, or Claude Code as the local MCP path. - -## Remote MCP / Streamable HTTP - -Use this only when a client supports remote MCP servers with custom headers: - -```json -{ - "mcpServers": { - "memwal": { - "url": "https://relayer.memory.walrus.xyz/api/mcp", - "headers": { - "Authorization": "Bearer ", - "x-memwal-account-id": "" - } - } - } -} -``` - -Treat the bearer token like an API key. Do not save it in a repo file. - -## Troubleshooting - -| Symptom | Fix | -| --- | --- | -| `node: command not found` | Install Node.js 20+ from https://nodejs.org/. | -| `npx` fails | Confirm Node/npm is installed and internet access works. | -| No Walrus Memory tools after restart | Check the MCP config path and fully restart the client. | -| Only `memwal_login` works | Credentials are missing. Run `memwal_login` or `npx -y @mysten-incubation/memwal-mcp login --prod`. | -| Memory tools return 401 | The delegate key may be stale or revoked. Run `npx -y @mysten-incubation/memwal-mcp login --prod` again. | -| User wants to sign out | Run `npx -y @mysten-incubation/memwal-mcp --logout`. This removes local credentials but does not revoke the on-chain delegate key. | - -Finish by reporting: - -- AI client configured -- config file changed or command run -- whether login succeeded -- whether `memwal_remember` / `memwal_recall` passed -- any restart or follow-up the user still needs diff --git a/apps/app/public/skills/memwal-install b/apps/app/public/skills/memwal-install index fefbeb6c..7b25cac4 100644 --- a/apps/app/public/skills/memwal-install +++ b/apps/app/public/skills/memwal-install @@ -1,16 +1,16 @@ --- name: memwal-install -description: Legacy alias for the Walrus Memory MCP setup skill. +description: Legacy alias for the Walrus Memory setup skill. license: Apache-2.0 metadata: author: Walrus Memory version: "1.0" --- -# Walrus Memory MCP Setup +# Walrus Memory Setup -This route is a compatibility alias. Use the MCP setup skill instead: +This route is a compatibility alias. Use the general setup skill instead: ```text -Run `curl -sL https://memory.walrus.xyz/skills/mcp-setup` and use the returned instructions to connect Walrus Memory to this AI client. +Run `curl -sL https://memory.walrus.xyz/skills/setup` and use the returned instructions to connect Walrus Memory to this AI client. ``` diff --git a/apps/app/public/skills/setup b/apps/app/public/skills/setup new file mode 100644 index 00000000..69d8d56a --- /dev/null +++ b/apps/app/public/skills/setup @@ -0,0 +1,343 @@ +--- +name: setup +description: >- + Set up Walrus Memory for normal users in AI clients such as Claude Desktop, + Cursor, Codex, Claude Code, ChatGPT, Antigravity, or another agent interface. + Covers local MCP clients, remote MCP clients, wallet sign-in, restart, and + verification. +license: Apache-2.0 +metadata: + author: Walrus Memory + version: "1.0" + requires: Node.js 20+ for local stdio clients; a Sui-compatible wallet +--- + +# Walrus Memory - One-Prompt Setup + +## Purpose + +Set up Walrus Memory for a normal user inside their AI client. This flow is +for Claude Desktop, Cursor, Codex, Claude Code, ChatGPT, Antigravity, and other +agent interfaces that can use MCP or remote MCP-style tools. + +When invoked through a one-click install prompt: + +```text +Run `curl -sL https://memory.walrus.xyz/skills/setup` and use the +returned instructions to connect Walrus Memory to this AI client. +``` + +Fetch this file, choose the right setup mode for the user's AI client, configure +Walrus Memory, sign in with their Sui wallet, restart the client when needed, +and verify memory works. + +## Scope + +Do this: + +- connect Walrus Memory MCP to the user's AI client +- help the user sign in through `memwal_login` or the MCP package login command +- verify `memwal_remember` and `memwal_recall` + +Do not do this in this flow: + +- configure MCP only because a code project exists +- install the Walrus Memory SDK or edit app source code + +If the user explicitly asks for SDK or app-code integration, stop and say this +one-prompt setup is for using Walrus Memory inside an AI client. Point them to +the SDK docs or ask whether they want a separate developer integration. + +## Rules + +1. Treat MCP client setup as the primary goal. +2. Ask which AI client to configure if the user did not name one. +3. Detect whether this AI client can execute local shell commands and edit + local user config files on the user's machine. +4. If this AI client cannot access the user's local terminal or filesystem + (common in Claude Desktop and other desktop chats), do not pretend setup is + automatic. Give the exact command/config for the user to run or paste + manually, then wait for them to report the result. +5. If local shell/file access is available, show the command or config file + before changing user-level MCP config. +6. Merge config into existing `mcpServers`; do not remove other MCP servers. +7. Never commit or print real delegate private keys from + `~/.memwal/credentials.json`. +8. Prefer local stdio MCP for clients that support `command + args`. +9. Use remote Streamable HTTP only when the client clearly supports remote MCP + servers with custom headers. +10. ChatGPT custom MCP apps use a remote MCP flow. Do not invent a local `npx` + ChatGPT Desktop config. +11. After config changes, tell the user to fully quit and reopen the AI client. +12. Stop at the first failure and report the exact blocker. + +## Execution modes + +### Guided mode + +Use guided mode when the AI client cannot directly run terminal commands or +write local files on the user's machine. This is common for Claude Desktop, +ChatGPT, and other desktop/web chat clients. + +In guided mode: + +- tell the user which config file to open +- show the exact JSON/TOML block to paste +- show the exact terminal command to run, if needed +- ask the user to confirm what happened before continuing +- do not say that you installed or configured anything yourself + +### Agentic mode + +Use agentic mode only when this session has explicit local shell and filesystem +access on the user's machine. + +In agentic mode: + +- inspect existing config before editing it +- preserve other MCP servers +- show a short summary of the edit +- still ask the user to restart the AI client manually + +## Step 1 - Check Node.js + +First decide whether you are in guided mode or agentic mode. + +For local stdio clients, Node.js must be checked on the user's machine. In +guided mode, ask the user to run: + +```bash +node -v +``` + +In agentic mode, run it yourself. Walrus Memory MCP requires Node.js 20 or +newer. If Node.js is missing or older than 20, tell the user to install Node.js +20+ from https://nodejs.org/ and stop. + +The user also needs a Sui-compatible wallet available in the browser for login. + +## Step 2 - Pick the client + +If the user did not name a client, ask: + +```text +Which AI client should I connect to Walrus Memory: Claude Desktop, Cursor, +Codex, Claude Code, ChatGPT, or another MCP client? +``` + +Use local stdio config for: + +- Claude Desktop +- Cursor +- Codex +- Claude Code +- Antigravity or another local-command MCP host + +Use remote MCP guidance for: + +- ChatGPT custom MCP apps +- clients that do not support local `command + args` + +## Step 3 - Configure local stdio MCP + +Use this MCP server command: + +```bash +npx -y @mysten-incubation/memwal-mcp +``` + +### Cursor + +Edit `~/.cursor/mcp.json` and merge: + +```json +{ + "mcpServers": { + "memwal": { + "command": "npx", + "args": ["-y", "@mysten-incubation/memwal-mcp"] + } + } +} +``` + +### Claude Desktop + +Edit: + +- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` +- Windows: `%APPDATA%\Claude\claude_desktop_config.json` + +Merge: + +```json +{ + "mcpServers": { + "memwal": { + "command": "npx", + "args": ["-y", "@mysten-incubation/memwal-mcp"] + } + } +} +``` + +### Codex + +Edit `~/.codex/config.toml` and append: + +```toml +[mcp_servers.memwal] +command = "npx" +args = ["-y", "@mysten-incubation/memwal-mcp"] +``` + +### Claude Code + +Run: + +```bash +claude mcp add --scope user memwal -- npx -y @mysten-incubation/memwal-mcp +``` + +Verify: + +```bash +claude mcp list +``` + +### Other local MCP clients + +Add: + +- name: `memwal` +- command: `npx` +- args: `["-y", "@mysten-incubation/memwal-mcp"]` + +## Step 4 - Sign in + +Prefer inline login after the client is configured and restarted: + +```text +Use memwal_login to sign me in to Walrus Memory. +``` + +The tool opens a browser flow. The user connects their Sui wallet and approves +the delegate key. Credentials are saved locally at: + +```text +~/.memwal/credentials.json +``` + +If inline login is not available yet, run manual login in a real terminal: + +```bash +npx -y @mysten-incubation/memwal-mcp login --prod +``` + +## Step 5 - Restart the client + +Fully quit and reopen the AI client. On macOS, use `Cmd+Q`; closing the window +is not enough. The first start may take 5-10 seconds while `npx` fetches the +package. + +## Step 6 - Verify tools + +Ask the AI client: + +```text +What MCP tools do you have available? +``` + +Expected Walrus Memory tools: + +- `memwal_remember` +- `memwal_recall` +- `memwal_analyze` +- `memwal_restore` +- `memwal_login` +- `memwal_logout` + +If only `memwal_login` works, credentials are missing. Run `memwal_login` or +the manual login command again. + +## Step 7 - Verify memory + +Ask: + +```text +Use memwal_remember to save: "My favorite programming language is Rust and I drink black coffee in the mornings." +``` + +Wait a few seconds, then ask: + +```text +Use memwal_recall to search for: "what is my favorite language?" +``` + +The client should retrieve the saved Rust memory. + +## ChatGPT + +ChatGPT custom MCP apps use remote MCP servers, not a local `npx` stdio config. + +If the user's ChatGPT account supports custom MCP apps / developer mode: + +1. Confirm they can create a custom MCP app in ChatGPT settings. +2. Use this remote MCP endpoint: + +```text +https://relayer.memory.walrus.xyz/api/mcp +``` + +3. Authenticate with headers: + +```text +Authorization: Bearer +x-memwal-account-id: +``` + +The values come from `~/.memwal/credentials.json` after a successful +`memwal-mcp login --prod`. + +If ChatGPT cannot attach the required headers or the user's plan/workspace does +not allow custom MCP apps, explain the blocker and offer Claude Desktop, +Cursor, Codex, or Claude Code as the local MCP path. + +## Remote MCP / Streamable HTTP + +Use this only when a client supports remote MCP servers with custom headers: + +```json +{ + "mcpServers": { + "memwal": { + "url": "https://relayer.memory.walrus.xyz/api/mcp", + "headers": { + "Authorization": "Bearer ", + "x-memwal-account-id": "" + } + } + } +} +``` + +Treat the bearer token like an API key. Do not save it in a repo file. + +## Troubleshooting + +| Symptom | Fix | +| --- | --- | +| `node: command not found` | Install Node.js 20+ from https://nodejs.org/. | +| `npx` fails | Confirm Node/npm is installed and internet access works. | +| No Walrus Memory tools after restart | Check the MCP config path and fully restart the client. | +| Only `memwal_login` works | Credentials are missing. Run `memwal_login` or `npx -y @mysten-incubation/memwal-mcp login --prod`. | +| Memory tools return 401 | The delegate key may be stale or revoked. Run `npx -y @mysten-incubation/memwal-mcp login --prod` again. | +| User wants to sign out | Run `npx -y @mysten-incubation/memwal-mcp --logout`. This removes local credentials but does not revoke the on-chain delegate key. | + +Finish by reporting: + +- AI client configured +- config file changed or command run +- whether login succeeded +- whether `memwal_remember` / `memwal_recall` passed +- any restart or follow-up the user still needs diff --git a/docs/mcp/changelog.mdx b/docs/mcp/changelog.mdx index 4eb8b7d8..10e08794 100644 --- a/docs/mcp/changelog.mdx +++ b/docs/mcp/changelog.mdx @@ -1,8 +1,14 @@ --- title: "Changelog" -description: "Release history for the MemWal MCP package." +description: "Release history for the Walrus Memory MCP package." --- +## 0.0.3 + +### Changed + +- Rebranded package metadata and documentation from MemWal to Walrus Memory. + ## 0.0.2 ### Added @@ -15,5 +21,5 @@ description: "Release history for the MemWal MCP package." - Stdio MCP server for MemWal with browser-based wallet login. - Inline `memwal_login` and `memwal_logout` session tools. -- Memory tools for remember, recall, analyze, and restore through the MemWal relayer. +- Memory tools for remember, recall, analyze, and restore through the Walrus Memory relayer. - Environment presets for production, dev, staging, and local relayers. diff --git a/docs/mcp/how-it-works.md b/docs/mcp/how-it-works.md index a53cab13..3b3b0f01 100644 --- a/docs/mcp/how-it-works.md +++ b/docs/mcp/how-it-works.md @@ -43,7 +43,7 @@ flowchart TD A["MCP host starts memwal-mcp"] --> B{"credentials.json exists?"} B -- "No" --> C["Start auth-required mode"] C --> D["Agent can call memwal_login"] - D --> E["Browser opens MemWal connect flow"] + D --> E["Browser opens Walrus Memory connect flow"] E --> F["User approves wallet sign-in"] F --> G["credentials.json written locally"] G --> H["Retry original memory tool call"] diff --git a/packages/mcp/CHANGELOG.md b/packages/mcp/CHANGELOG.md index 0d5f1d05..aa3c3c01 100644 --- a/packages/mcp/CHANGELOG.md +++ b/packages/mcp/CHANGELOG.md @@ -1,15 +1,17 @@ # @mysten-incubation/memwal-mcp +## 0.0.3 + +### Changed + +- Rebranded package metadata and documentation from MemWal to Walrus Memory. + ## 0.0.2 ### Added - Added relayer compatibility metadata checks before opening the MCP bridge. -### Changed - -- Rebranded package metadata and documentation from MemWal to Walrus Memory. - ## 0.0.1 ### Initial Release