feat: prototype shared-runtime embedded MCP for MOSS CLI

AGENTS.md

@@ -22,6 +22,7 @@ Core commands:
 - `mega moss fund`: open the wallet deposit flow for the active account.
 - `mega moss debug`: inspect local profile, balance, and relay key status without private key output.
 - `mega moss logout`: delete the local profile and delegated private key material; it does not revoke on-chain.
+- `mega moss mcp serve`: run the embedded MCP server for agent/host integrations.
 
 Mainnet is the default network. Testnet is supported with `--network testnet`
 and uses a separate local profile path plus testnet chain/token defaults.
@@ -240,6 +241,31 @@ spend row; add explicit spend rows for workflow token movement. Revoke should
 pass the stored key fee token to the wallet UI by default and support
 `--fee-token <symbol>` for explicit revocation payment-token overrides.
 
+## Embedded MCP
+
+The embedded MCP server is an agent-facing surface over the same wallet runtime
+used by CLI commands. Keep CLI and MCP behavior aligned; if shared runtime logic
+changes, update both command tests and MCP tests together.
+
+Current MCP tools:
+
+- Read: `moss_whoami`, `moss_list_keys`, `moss_permissions`, `moss_wallet_status`, `moss_debug`
+- Preview: `moss_transfer_preview`, `moss_execute_preview`
+- Execute: `moss_transfer_execute`, `moss_execute`
+
+See `docs/mcp/overview.md` for host configuration, readiness semantics, and
+operator-facing MCP guidance.
+
+MCP writes must stay preview-first:
+
+- preview tools should surface delegated-key readiness, issue codes, and permission deltas
+- execute tools should refuse when preview readiness is not `ready`
+- tool metadata should remain rich enough for hosts/agents to understand safety, pairing, requirements, and likely issue classes
+
+Trust-boundary creation remains human-governed and is intentionally excluded
+from MCP v1. Do not expose `login`, `create-key`, `revoke`, or `logout` as MCP
+write tools unless the product direction explicitly changes.
+
 ## Commands
 
 ```bash

README.md

@@ -278,3 +278,21 @@ Remove installed CLI files and local profiles:
 mega moss --help
 mega moss <command> --help
 ```
+
+
+## Embedded MCP
+
+This repository includes an embedded MCP server exposed through:
+
+```bash
+mega moss mcp serve
+```
+
+For host configuration, tool categories, readiness semantics, and safety
+recommendations, see:
+
+- [docs/mcp/overview.md](docs/mcp/overview.md)
+
+Trust-boundary creation flows such as `login`, `create-key`, `revoke`, and
+`logout` remain human-governed and are intentionally excluded from the initial
+MCP surface.

SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: mega-wallet-cli
-description: Use the MegaETH Wallet CLI to connect a MegaETH passkey wallet, create/manage scoped delegated session keys, inspect permissions, and use those keys for read-only calls, transfers, and relay-backed execution on MegaETH.
+description: Use the MegaETH Wallet CLI and embedded MCP surface to connect a MegaETH passkey wallet, create/manage scoped delegated session keys, inspect permissions, and use those keys for read-only calls, preview-gated transfers, and relay-backed execution on MegaETH.
 ---
 
 # MegaETH Wallet CLI
 
 Use this skill when an agent needs to operate a local MegaETH wallet through
-`mega moss` commands.
+`mega moss` commands or the embedded MCP surface exposed by `mega moss mcp serve`.
 
 ## Mental Model
 
@@ -200,6 +200,37 @@ with a different relay fee token.
 Read [references/permissions.md](references/permissions.md) only when building
 `--permissions ./permissions.json` files or debugging permission schema errors.
 
+## Embedded MCP
+
+Start the embedded MCP server with:
+
+```bash
+mega moss mcp serve
+```
+
+Current MCP tools:
+
+- Read: `moss_whoami`, `moss_list_keys`, `moss_permissions`, `moss_wallet_status`, `moss_debug`
+- Preview: `moss_transfer_preview`, `moss_execute_preview`
+- Execute: `moss_transfer_execute`, `moss_execute`
+
+For MCP host configuration, readiness semantics, and safety guidance, read
+`docs/mcp/overview.md` when working through the embedded MCP surface.
+
+Prefer MCP preview tools before write tools. Treat MCP execute tools as the
+same underlying delegated-key writes as `mega moss transfer` and
+`mega moss execute`.
+
+For agent workflows:
+
+- use read tools to inspect wallet/account state first
+- use preview tools to confirm readiness, missing permissions, and suggested next steps
+- use execute tools only when preview readiness is `ready` and the user asked for the write
+- treat `login`, `create-key`, `revoke`, and `logout` as human-governed trust-boundary flows, not MCP v1 automation flows
+
+`moss_wallet_status` is the best first tool when an agent needs a single
+high-signal view of account connection, active key, readiness, and issues.
+
 ## Read State
 
 ```bash

docs/mcp/host-config.md

@@ -0,0 +1,27 @@
+# MCP Host Configuration
+
+Start the embedded server with:
+
+```bash
+mega moss mcp serve
+```
+
+## Generic stdio configuration
+
+```json
+{
+  "mcpServers": {
+    "mega-moss": {
+      "transport": "stdio",
+      "command": "mega",
+      "args": ["moss", "mcp", "serve"]
+    }
+  }
+}
+```
+
+## Notes
+
+- the server uses stdio transport
+- formal JSON-RPC MCP flows are supported
+- `ping`, `initialize`, `tools/list`, and `tools/call` are supported

docs/mcp/overview.md

@@ -0,0 +1,21 @@
+# Embedded MCP
+
+The Wallet CLI includes an embedded MCP server exposed through:
+
+```bash
+mega moss mcp serve
+```
+
+## Documentation Map
+
+- [Host Configuration](host-config.md)
+- [Safety Model](safety.md)
+- [Agent Workflows](workflows.md)
+
+## Summary
+
+The embedded MCP server supports formal stdio MCP JSON-RPC flows including:
+- `initialize`
+- `ping`
+- `tools/list`
+- `tools/call`

docs/mcp/safety.md

@@ -0,0 +1,34 @@
+# MCP Safety Model
+
+## Tool classes
+
+### Read tools
+- `moss_whoami`
+- `moss_list_keys`
+- `moss_permissions`
+- `moss_wallet_status`
+- `moss_debug`
+
+### Preview tools
+- `moss_transfer_preview`
+- `moss_execute_preview`
+
+### Execute tools
+- `moss_transfer_execute`
+- `moss_execute`
+
+## Recommended host policy
+
+- auto-approve read tools only
+- use preview tools before execute tools
+- require human review for execute tools unless delegated scope is tightly controlled
+
+## Human-governed trust-boundary flows
+
+The following flows are intentionally excluded from MCP v1:
+- `login`
+- `create-key`
+- `revoke`
+- `logout`
+
+These remain human-governed because they establish, expand, or revoke wallet authority.

docs/mcp/workflows.md

@@ -0,0 +1,37 @@
+# MCP Workflows
+
+## Best first tool
+
+Start most agent sessions with:
+
+- `moss_wallet_status`
+
+It provides:
+- connected account status
+- delegated-key presence
+- readiness state
+- structured issue codes
+- suggested next actions
+
+## Readiness states
+
+### `ready`
+A delegated key is present and usable for delegated operations.
+
+### `needs_key`
+Additional delegated authorization is required before delegated writes can proceed.
+
+## Logged in, no delegated key
+
+Useful MCP operations still exist:
+- inspect account identity
+- list keys
+- inspect wallet readiness
+- preview transfers/calls and receive structured refusal or missing-capability guidance
+
+## Delegated key present
+
+The MCP server can additionally:
+- preview real delegated writes
+- execute delegated writes through the relay path
+- report missing call or spend permissions in structured form

scripts/install.sh

@@ -212,20 +212,21 @@ detect_pnpm() {
   fi
 
   if command -v corepack >/dev/null 2>&1; then
-    if ! confirm_install "pnpm is not installed. Activate $pnpm_package with Corepack now?"; then
-      echo "pnpm is required; install pnpm or rerun and approve Corepack activation" >&2
+    if corepack pnpm --version >/dev/null 2>&1; then
+      pnpm_cmd=(corepack pnpm)
+      return
+    fi
+
+    if ! confirm_install "pnpm is not installed. Prepare $pnpm_package with Corepack now?"; then
+      echo "pnpm is required; install pnpm or rerun and approve Corepack preparation" >&2
       exit 1
     fi
-    run corepack enable
     run corepack prepare "$pnpm_package" --activate
 
-    if command -v pnpm >/dev/null 2>&1; then
-      pnpm_cmd=(pnpm)
+    if corepack pnpm --version >/dev/null 2>&1; then
+      pnpm_cmd=(corepack pnpm)
       return
     fi
-
-    pnpm_cmd=(corepack pnpm)
-    return
   fi
 
   if command -v npm >/dev/null 2>&1; then

src/cli.test.ts

@@ -1,4 +1,6 @@
 import { execFile } from "node:child_process";
+import { chmod, rm } from "node:fs/promises";
+import { join } from "node:path";
 import { promisify } from "node:util";
 
 import { describe, expect, it } from "vitest";
@@ -41,7 +43,19 @@ describe("mega cli", () => {
     );
   });
 
-  it("runs compiled mega --help", async () => {
+  it("registers the moss mcp serve command", () => {
+    const program = createCli();
+    const wallet = program.commands.find((command) => command.name() === "moss");
+    const mcp = wallet?.commands.find((command) => command.name() === "mcp");
+    const serve = mcp?.commands.find((command) => command.name() === "serve");
+
+    expect(mcp).toBeDefined();
+    expect(serve).toBeDefined();
+  });
+
+  it("runs compiled mega --help", { timeout: 15_000 }, async () => {
+    await buildDist();
+
     const { stdout } = await execFileAsync(
       "npm",
       ["exec", "--package", ".", "--", "mega", "--help"],
@@ -55,3 +69,14 @@ describe("mega cli", () => {
     expect(stdout).toContain("moss");
   });
 });
+
+async function buildDist() {
+  const cwd = process.cwd();
+  await rm(join(cwd, "dist"), { recursive: true, force: true });
+  await execFileAsync(
+    process.execPath,
+    [join(cwd, "node_modules", "typescript", "bin", "tsc"), "-p", "tsconfig.json"],
+    { cwd },
+  );
+  await chmod(join(cwd, "dist", "index.js"), 0o755);
+}