feat: prototype shared-runtime embedded MCP for MOSS CLI

[0xBreadguy]

Summary

This PR evolves the original embedded MCP architecture skeleton into a working prototype for MOSS CLI.

The goal is not just to expose CLI commands over MCP, but to demonstrate a shared-runtime architecture where:

• CLI and MCP can converge on the same wallet operations
• delegated-key capability state is inspectable and agent-usable
• write-capable tools follow a preview-first, safety-gated model
• MCP discovery is rich enough to support real host/agent orchestration

What this branch now includes

Shared runtime direction

Introduces and expands internal structure for:

• src/core/
• src/schemas/
• src/mcp/

This is no longer just a folder proposal — several wallet operations now run through shared runtime code consumed by the MCP layer.

Embedded MCP server

Adds:

• mega moss mcp serve

with a working stream-based MCP server and tool registry.

Current MCP tools

Read:

• moss_whoami
• moss_list_keys
• moss_permissions
• moss_wallet_status
• moss_debug

Preview-first:

• moss_transfer_preview
• moss_execute_preview

Execute:

• moss_transfer_execute
• moss_execute

Capability-aware delegated wallet runtime

This branch introduces a richer capability model so the MCP surface can reason about:

• whether delegated keys exist
• whether an active key is selected
• whether the key is expired/revoked/unusable locally
• whether required call permissions are missing
• whether required spend permissions are missing

This enables tools to return structured issues and guidance rather than only succeeding/failing.

Permission deltas / approval guidance

Preview tools now support structured permission-delta output for missing authority, including:

• missing call permissions
• missing spend permissions
• suggested next-step commands / approval guidance

This is intended to make MOSS MCP more than a generic wallet command wrapper: it becomes a delegated-authority-aware coordination surface for humans and agents.

Richer MCP introspection

mcp.tools now exposes more useful metadata, including:

• safety class
• requirements
• preview/execute pairing
• value movement hints
• possible issue codes

This makes the tool surface more self-describing for MCP hosts and agents.

Safety model

This branch keeps trust-boundary creation out of MCP v1.

Not exposed via MCP:

• login
• create-key
• revoke
• logout

The current design assumes:

• human-governed trust boundary creation
• agent use of already-authorized wallet state
• preview-first execution patterns
• refusal of write execution when readiness is not ready

Both moss_transfer_execute and moss_execute now share preview-gated execution semantics.

Tests

This branch now includes:

• targeted core tests for capability logic
• transfer preview tests
• transfer execute safety tests
• generic execute preview tests
• generic execute safety tests
• MCP schema consistency tests
• MCP end-to-end stream invocation tests
• MCP refusal-path tests
• existing wallet/debug command tests

Validated with:

• pnpm lint
• pnpm test

Why this matters

This PR is intended to show a more ambitious direction than “CLI commands exposed over MCP.”

The prototype demonstrates a path toward a permission-aware wallet runtime where:

• humans approve trust boundaries
• agents inspect available delegated authority
• preview/execute pairs are first-class
• missing permissions are explained in a structured way
• CLI and MCP can share the same conceptual operation model

Notes

This is still a prototype / feature-branch-quality implementation, not a final architectural endpoint.

What it is meant to prove:

1. embedded MCP is viable in this repo
2. a shared-runtime approach is materially better than a thin shell wrapper
3. delegated-key capability awareness is a meaningful product differentiator for MOSS
4. the branch is mature enough to support owner review and architectural discussion

Intended end-state architecture

The intended long-term direction is a shared wallet runtime with clear internal boundaries between:

• core/ — canonical wallet/business logic
• schemas/ — canonical input/output contracts and tool metadata
• cli/ — human/operator-facing rendering and command UX
• mcp/ — agent-facing MCP server and tool exposure

The goal is for CLI commands and MCP tools to derive from the same conceptual wallet operations rather than drift into separate implementations.

In the end state:

• read, preview, and execute flows should all share runtime logic
• preview/execute pairs should be first-class
• delegated-key capability reasoning should be a core product primitive
• trust-boundary creation (login, create-key, revoke, logout) should remain human-governed unless intentionally expanded later
• MCP introspection should be rich enough for agents/hosts to understand safety level, pairing, capability requirements, and likely issue classes

This branch is not that final architecture yet, but it is intended to move the repo concretely in that direction.