Littlejohn MCP README

Little John MCP

Little John MCP is a local Robinhood Chain MCP application and interactive CLI. It reads assets and contracts, constructs USDG / Stock Token exchange decisions, requests the directly confirmed transaction in the connected wallet through WalletConnect, and records received hashes and actual transaction results locally.

This document describes the source checkout. For an installed published artifact, use the documentation at that release's source revision.

The current support projection is in Product Policy. Exchange actions are implemented. Robinhood Wallet transaction and replacement behavior is not qualified. The package makes no executable or receipt-verified support claim. Data signing supports personal messages and EIP-712 typed data through direct App controls and interactive CLI. Physical qualification with Robinhood Wallet and each MCP Host application is incomplete.

Install a published release

Use Node.js satisfying the package's engines field:

npm install --global @zktx.io/littlejohn-mcp
littlejohn-mcp --help

Install from source

From a repository checkout using the same Node.js requirement:

npm ci
LITTLEJOHN_MCP_RELEASE_OUTPUT=/absolute/path/littlejohn-mcp.tgz npm run release:check
npm install --global /absolute/path/littlejohn-mcp.tgz
littlejohn-mcp --help

The release check creates the tarball only after its automated package checks pass. It does not publish to npm or qualify a physical Wallet. SQLite is an npm dependency; a separate SQLite server or command-line installation is unnecessary. Its native addon installation remains part of the npm install. An installation error must be resolved before starting the program.

Connect an MCP Host

MCP Host terminology is defined in Architecture.

Configure a local stdio server named littlejohn-mcp in the MCP Host's MCP settings:

{
  "mcpServers": {
    "littlejohn-mcp": {
      "command": "littlejohn-mcp",
      "args": []
    }
  }
}

Use the installed executable's absolute path if the MCP Host does not inherit the shell's executable search path. No website, public server, browser login, or navigable loopback page is needed. The no-argument process serves MCP; CLI commands use the same local backend and Wallet session.

For an optional RPC endpoint, add LITTLEJOHN_MCP_RPC_URL to that server's environment. Omitting it uses Runtime's public default. Do not set an empty string. A supplied URL must pass the current HTTPS configuration admission; failure does not switch to another provider. Keep URLs containing credentials in the MCP Host's secure configuration rather than command arguments. The standard setup field is in server.json.

LITTLEJOHN_MCP_DATA_DIR selects a different local profile directory. LITTLEJOHN_MCP_WALLETCONNECT_PROJECT_ID overrides the Wallet adapter's project ID. All processes sharing a profile must use the same configuration. The backend uses its fixed loopback port; a foreign owner is an error, not a reason to select another port. Complete configuration behavior belongs to Architecture.

Backend lifetime and maintenance

Normal MCP and CLI use automatically start an independent local backend. It keeps the Wallet session and pending work alive after a Host closes its MCP connection. The background Node process and its SDK worker continue using memory and local files until explicitly stopped, terminated by the operating system, or stopped by a fatal backend failure. There is no idle shutdown.

Use the same profile and configuration as the connected clients:

littlejohn-mcp runtime status --json
littlejohn-mcp runtime stop --json

These commands do not start a backend. Stop affects all clients sharing that backend, but does not revoke an approved Wallet session. It stops one observed backend generation; a later ordinary client request can start another. Pause the affected MCP connections before maintenance, updates, uninstalling or removing an npx cache, then stop the backend and confirm released before removing its files. Configure other Host applications directly in those apps.

If stop returns shutdown_unconfirmed, preserve its target. The printed runtime status --shutdown <owner-instance-id> command reads that generation's saved result without starting or stopping anything. A missing listener or a stop acknowledgement alone does not prove release. An incompatible installed package or configuration fails closed; Little John MCP does not terminate or update that other process automatically.

If a different profile or installed version owns the port, pause the affected Host connections and use that backend's original trusted installation, profile and configuration to run runtime stop. A new version cannot stop an incompatible backend. If that installation is unavailable or the backend no longer responds, identify the exact Little John MCP backend in your operating system's process tools and terminate it manually. Do not terminate every Node process or delete a database or credential to clear a port conflict. A process reported by an unauthenticated listener is not a trusted termination target. Confirm that the backend and its SDK worker no longer use the profile before removing files. Manual termination does not prove a request was cancelled or resources were released; inspect the original operation after recovery and do not resend an uncertain transaction or signing request.

Use the application

In an App-capable MCP Host, ask for the desired asset read or transaction decision in ordinary language. Select the Stock Token, pool, sent or received quantity, exact/maximum/minimum conditions, fee caps and execution deadline. Token units are distinct from underlying shares. Little John MCP does not choose missing transaction-critical conditions silently.

Use the App's direct control to request the displayed transaction in the Wallet. The Wallet separately asks for approval. A model-visible tool cannot authorize that request. An MCP Host without direct App controls remains unable to authorize a transaction; the CLI is an independent interface.

The CLI exposes its complete current syntax through littlejohn-mcp --help:

• littlejohn-mcp wallet connect presents the connection decision and pairing QR.
• littlejohn-mcp uniswap-v4 list-pools <stock-token-address> lists the packaged candidates that remain in the current official asset snapshot. This is not a liquidity or best-route claim.
• littlejohn-mcp exchange start ... constructs a new decision and asks for one interactive y before requesting it in the Wallet. Both input and output must be a TTY; flags, redirected input and JSON output cannot confirm a transaction.
• littlejohn-mcp exchange replace-fees ... constructs a new decision from the independently read pending request. exchange start --replaces <hash> ... selects a new supported transaction at that observed nonce. Neither replays a saved request or guarantees acceptance or inclusion.
• littlejohn-mcp activity get <hash> --address <address> and activity list --address <address> read local records only. activity inspect <hash> --address <address> explicitly rechecks the chain within a finite wait.

Each required token or router allowance is a separate decision and Wallet request. Finishing an approval does not automatically send the next transaction.

Terminal QR presentation and its current profile limitation are documented in Architecture. littlejohn-mcp wallet connect uses the QR renderer from the installed package.

Sign data

Ask an App-capable MCP Host to create a signing decision for the exact message or typed data. Inspect the complete data and domain, then use the direct control and approve separately in the Wallet. A verified signature appears only in that App result panel. Select the complete value and use your device's copy command; the panel provides a Dismiss control. The MCP Host can observe this private result. Closing the panel does not revoke the signature or erase copies outside Little John MCP.

For CLI, put the payload in a user-owned JSON file. For example, this synthetic message grants no application action:

{"kind":"personal","encoding":"utf8","value":"Little John MCP signing check. This message grants no action."}

Run littlejohn-mcp signing start --active --file message.json and read the complete decision before answering y. The output must also be an interactive terminal. An address selector and the exact read/discard syntax are described by littlejohn-mcp --help. A hex message explicitly uses "encoding":"hex"; a text value starting with 0x remains text. Typed input uses "kind":"typed_data" with types, primaryType, domain and message; integer values are exact decimal strings. It declares EIP712Domain explicitly and uses a distinct message type. A supplied domain chain must be Robinhood Chain.

An existing send-only session needs explicit disconnect/connect approval for the additional signing methods. Missing permission never triggers automatic reconnection. This feature does not submit signatures to services, broadcast transactions or create ledger entries. Its verification profile is a 65-byte secp256k1 signature; contract-account signature validation is unavailable. Late responses are discarded and unknown delivery never triggers another request. No signature cache, durable signature record or later signature-retrieval command exists. CLI scrollback and user-owned input files or copies are outside product disposal control. Exact signing authority and result meaning remain in Transaction Policy.

Results and local state

A returned hash is not execution success. Records distinguish included success, revert, observed pending, not found and unavailable reads. Actual request and effect comparisons remain separate from execution status. Missing evidence never becomes a matching result. A revert still consumes gas.

Stopping a wait cannot cancel a delivered Wallet request. A hash observed later during the original bounded SDK lifetime is recorded without a new network lookup. An explicit query or a later transaction command can reconcile known hashes. No timer, restart or completed approval resends a financial request.

Transaction decisions, unsigned requests and grants are temporary memory. The execution ledger begins only with a received hash and its pre-send comparison reference. It stores actual results, not a reusable transaction or full Review. A saved transaction card can show its closed state or outcome without restoring an expired or consumed decision, request or grant. Unrelated read snapshots and durable Wallet-management operations retain their own lifetimes.

Retained transaction, card and immutable-result history has no total row or byte quota and is not deleted automatically. Disk use can grow; an actual write failure preserves preceding committed values. A large MCP read returns its exact saved source rather than truncating the result. Metadata and bounded result parts carry the original bytes; a partial delivery is not a complete result. Reading data never opens a decision or authorizes a Wallet request.

Default profile locations follow the operating system's application-state directory. Owner-only files include the product database, separate WalletConnect restoration store and local control credential. Do not treat an incompatible profile as an automatic migration or erase it merely to bypass a startup error.

Exact authority and result meanings are defined by Transaction Policy. Third-party notices and licenses are included in the distributed package.

Little John MCP's source license is MIT. Dependencies retain their separate terms in third-party notices and licenses, including the WalletConnect Community License.