littlejohn-mcp

Little John MCP

Little John MCP 是一个本地 Robinhood Chain MCP 应用和交互式 CLI。它 读取资产和合约，构建 USDG / Stock Token 兑换决策， 通过 WalletConnect 请求连接的钱包直接确认交易，并在本地记录 收到的哈希和实际交易结果。

本文档介绍源码检出版本。对于已安装的发布版本， 请参阅该版本源码修订对应的文档。

当前支持范围见 产品政策。 兑换操作已实现。Robinhood Wallet 的交易和替换行为尚未完成资格验证。该软件包不声称 支持可执行或已验证收据的功能。 数据签名支持通过 App 控件和交互式 CLI 签署个人消息和 EIP-712 类型化数据。使用 Robinhood Wallet 和各 MCP Host 应用进行的实际资格验证尚未完成。

安装已发布版本

使用符合软件包 engines 字段要求的 Node.js：

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

从源码安装

在仓库检出目录中使用符合相同 Node.js 要求的版本：

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

只有在自动化软件包检查通过后，发布检查才会创建 tarball。 它不会发布到 npm，也不会对实体 Wallet 进行资格验证。SQLite 是 npm 依赖项；无需另行安装 SQLite 服务端或命令行工具。 其原生插件仍会在 npm install 过程中安装。必须先解决安装错误， 然后才能启动程序。

连接 MCP Host

MCP Host 术语定义见 架构。

在 MCP Host 的 MCP 设置中，将名为 littlejohn-mcp 的本地 stdio 服务配置为：

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

如果 MCP Host 无法继承 Shell 的可执行文件搜索路径，请使用已安装可执行文件的绝对路径。无需网站、公共服务、浏览器登录或 可导航的 loopback 页面。不带参数的进程提供 MCP 服务；CLI 命令使用相同的本地后端和 Wallet 会话。

如需使用可选 RPC 端点，请将 LITTLEJOHN_MCP_RPC_URL 添加到该服务的环境中。 省略此项时会使用 Runtime 的公共默认值。不要设置为空字符串。提供的 URL 必须通过当前 HTTPS 配置准入检查；如果失败，不会切换 到其他提供方。包含凭据的 URL 应保存在 MCP Host 的安全配置中，而不是命令参数中。 标准设置字段见 server.json。

LITTLEJOHN_MCP_DATA_DIR 用于选择其他本地配置目录。 LITTLEJOHN_MCP_WALLETCONNECT_PROJECT_ID 用于覆盖 Wallet 适配器的项目 ID。 所有共享同一配置目录的进程必须使用相同配置。后端 使用固定的 loopback 端口；若该端口已被其他程序占用，应报错，而不是改用 其他端口。完整的配置行为参见 架构。

后端生命周期与维护

正常使用 MCP 和 CLI 时，会自动启动一个独立的本地后端。即使 Host 关闭 MCP 连接，该后端仍会保持 Wallet 会话和待处理工作。后台 Node 进程及其 SDK 工作进程会继续使用内存和本地文件，直到显式停止、被操作系统终止，或因致命后端故障而停止。后端不会因空闲而关闭。

使用与已连接客户端相同的配置文件和配置：

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

这些命令不会启动后端。停止操作会影响所有共享该后端的客户端，但不会撤销已批准的 Wallet 会话。它只会停止一个已观察到的后端实例；之后，普通客户端请求仍可能启动另一个实例。维护、更新、卸载或移除 npx 缓存前，请暂停受影响的 MCP 连接，然后停止后端，并在确认状态为 released 后再移除其文件。请直接在其他 Host 应用中配置这些应用。

如果 stop 返回 shutdown_unconfirmed，请保留其目标。打印出的 runtime status --shutdown <owner-instance-id> 命令会读取该实例保存的结果，不会启动或停止任何内容。监听器缺失或收到停止确认，本身都不能证明资源已释放。不兼容的已安装软件包或配置会导致安全关闭；Little John MCP 不会自动终止或更新该其他进程。

如果端口由不同的配置文件或已安装版本占用，请暂停受影响的 Host 连接，并使用该后端原先可信的安装、配置文件和配置运行 runtime stop。新版本无法停止不兼容的后端。如果无法使用该安装，或后端已不再响应，请在操作系统的进程管理工具中找到确切的 Little John MCP 后端，并手动终止。请勿终止所有 Node 进程，也不要删除数据库或凭据来解决端口冲突。未经身份验证的监听器报告的进程不是可信的终止目标。移除文件前，请确认后端及其 SDK 工作进程已不再使用该配置文件。手动终止不能证明请求已取消或资源已释放；恢复后请检查原操作，不要重新发送状态不明的交易或签名请求。

使用应用

在支持 App 的 MCP 主机中，用日常语言提出所需的资产读取或交易决策。选择 Stock Token、池、发送或接收数量、精确值/最大值/最小值条件、费用上限和执行截止时间。代币单位与底层股票份额不同。Little John MCP 不会默默替你决定缺失的交易关键条件。

使用 App 的直接控制功能，在 Wallet 中请求执行所显示的交易。Wallet 会另行请求批准。模型可见的工具无法授权该请求。没有 App 直接控制功能的 MCP 主机仍无法授权交易；CLI 是独立的界面。

CLI 通过 littlejohn-mcp --help 提供完整的当前语法：

• littlejohn-mcp wallet connect 会显示连接决策和配对二维码。
• littlejohn-mcp uniswap-v4 list-pools <stock-token-address> 会列出当前官方资产快照中仍保留的已打包候选池。这并不代表对流动性或最佳路由的判断。
• littlejohn-mcp exchange start ... 会构建新的决策，并在向 Wallet 请求之前要求交互式输入一次 y。输入和输出都必须是 TTY；标志、重定向输入和 JSON 输出均无法确认交易。
• littlejohn-mcp exchange replace-fees ... 会根据独立读取的待处理请求构建新的决策。exchange start --replaces <hash> ... 会在已观察到的 nonce 上选择一笔新的受支持交易。两者都不会重放已保存的请求，也不保证请求会被接受或交易会被纳入区块。
• littlejohn-mcp activity get <hash> --address <address> 和 activity list --address <address> 仅读取本地记录。activity inspect <hash> --address <address> 会在有限等待时间内明确重新查询链上状态。

每个所需的代币或路由器授权都是独立的决策和 Wallet 请求。完成一项授权不会自动发送下一笔交易。

终端二维码的显示方式及其当前配置文件限制详见 架构。 littlejohn-mcp wallet connect 使用已安装软件包中的二维码渲染器。

签名数据

请能够使用 App 的 MCP Host 为确切的消息或类型化数据创建签名决策。检查完整数据和域，然后使用直接控制，并在 Wallet 中单独批准。已验证的签名只会显示在该 App 结果面板中。选择完整值并使用设备的复制命令；面板提供「关闭」控件。MCP Host 可以查看此私密结果。关闭面板不会撤销签名，也不会删除 Little John MCP 之外的副本。

对于 CLI，请将负载放在用户拥有的 JSON 文件中。例如，以下合成消息不会授予任何应用操作权限：

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

运行 littlejohn-mcp signing start --active --file message.json，并在回答 y 前阅读完整决策。输出还必须显示在交互式终端中。address 选择器以及准确的读取／丢弃语法请参阅 littlejohn-mcp --help。十六进制消息必须显式使用 "encoding":"hex"；以 0x 开头的文本值仍是文本。类型化输入使用 "kind":"typed_data"，并包含 types、primaryType、domain 和 message；整数值必须是精确的十进制字符串。它会显式声明 EIP712Domain，并使用独立的消息类型。提供的域链必须是 Robinhood Chain。

现有的仅发送会话需要明确批准断开连接／连接，以启用额外的签名方法。权限缺失时绝不会自动重新连接。此功能不会将签名提交给服务、广播交易或创建账本记录。其验证配置文件为 65 字节的 secp256k1 签名；不支持验证合约账户签名。迟到的响应会被丢弃，交付状态未知时不会再次发送请求。不存在签名缓存、持久签名记录或后续签名检索命令。CLI 滚动缓冲区以及用户拥有的输入文件或副本不受产品处置控制。确切的签名权限和结果含义请参阅交易策略。

结果和本地状态

返回哈希不代表执行成功。记录会区分纳入的成功结果、回滚、观察到的待处理状态、未找到和读取不可用。实际请求与效果的比较仍与执行状态分开。缺失的证据不会被视为匹配结果。回滚仍会消耗 Gas。

停止等待无法取消已发送的 Wallet 请求。在原始的有界 SDK 生命周期内稍后观察到的哈希，会被记录下来，而不会发起新的网络查询。显式查询或后续交易命令可以核对已知哈希。定时器、重启或已完成的审批都不会重新发送金融请求。

交易决策、未签名请求和授权均保存在临时内存中。执行账本仅在收到哈希及其发送前比较参考信息后开始记录。账本存储实际结果，而不是可重复使用的交易或完整审核信息。已保存的交易卡片可以显示其已关闭状态或结果，但不会恢复已过期或已消耗的决策、请求或授权。无关的读取快照和持久化 Wallet 管理操作各自保留其生命周期。

保留的交易、卡片和不可变结果历史没有总行数或字节数配额，也不会自动删除。磁盘占用可能增加；实际写入失败时，会保留此前已提交的值。大型 MCP 读取会返回其精确保存的源数据，而不会截断结果。元数据和有界结果分段携带原始字节；部分传递不构成完整结果。读取数据不会开启决策，也不会授权 Wallet 请求。

默认配置文件位置遵循操作系统的应用状态目录。仅所有者可访问的文件包括产品数据库、单独的 WalletConnect 恢复存储和本地控制凭据。不要将不兼容的配置文件视为可自动迁移的配置文件，也不要仅为绕过启动错误而将其删除。

确切的权限和结果含义见交易策略。第三方声明和许可证包含在分发包中。

Little John MCP 的源代码许可证为 MIT。依赖项遵循各自独立的条款，详见第三方声明和许可证，其中包括 WalletConnect Community License。