✨ (speculos-mcp) [NO-ISSUE]: Add Speculos MCP server for Ledger device emulation#1335
Open
aussedatlo wants to merge 6 commits intodevelopfrom
Open
✨ (speculos-mcp) [NO-ISSUE]: Add Speculos MCP server for Ledger device emulation#1335aussedatlo wants to merge 6 commits intodevelopfrom
aussedatlo wants to merge 6 commits intodevelopfrom
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
Contributor
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds a new private @ledgerhq/speculos-mcp package that provides a Model Context Protocol (MCP) server for AI agents to interact with the Speculos Ledger device emulator. It enables signing Ethereum transactions and EIP-712 typed data, navigating device review screens, managing Docker-based Speculos lifecycle, and capturing screenshots through 14 MCP tools.
Changes:
- New
packages/speculos-mcp/package with 14 MCP tools (sign, swipe, approve, reject, etc.), prompts, resources, and Docker-based Speculos lifecycle management - Cursor IDE integration via
.cursor/mcp.jsonfor out-of-the-box MCP server usage - Updated
pnpm-lock.yamlwith new dependencies (@modelcontextprotocol/sdk,zod@3.25,hono, etc.)
Reviewed changes
Copilot reviewed 40 out of 41 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
packages/speculos-mcp/package.json |
New private package definition with workspace deps and MCP SDK |
packages/speculos-mcp/src/server.ts |
Main MCP server entry point with stdio transport |
packages/speculos-mcp/src/speculos-client.ts |
HTTP + device-controller client for Speculos API |
packages/speculos-mcp/src/dmk-session.ts |
DMK session management, signing state tracking |
packages/speculos-mcp/src/actions.ts |
Device interaction flows (approve, reject, blind signing) |
packages/speculos-mcp/src/docker-manager.ts |
Docker-based Speculos lifecycle (start/stop/status) |
packages/speculos-mcp/src/screen-events.ts |
Screen event parsing and button detection |
packages/speculos-mcp/src/screen-events.test.ts |
Unit tests for screen event parsing |
packages/speculos-mcp/src/logger.ts |
Ring-buffer logger with MCP logging integration |
packages/speculos-mcp/src/constants.ts |
UI pattern constants and delay values |
packages/speculos-mcp/src/tools/*.ts |
14 individual tool files (one-per-tool architecture) |
packages/speculos-mcp/src/prompts/*.ts |
MCP prompts for signing workflows |
packages/speculos-mcp/resources/workflow.md |
MCP resource describing the signing lifecycle |
.cursor/mcp.json |
Cursor IDE MCP server configuration |
pnpm-lock.yaml |
Lock file updates for new dependencies |
| Config files (.prettierrc, eslint, tsconfig, vitest) | Standard project configuration |
Files not reviewed (1)
- pnpm-lock.yaml: Language not supported
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
aussedatlo
force-pushed
the
feat/no-issue-mcp-speculos
branch
from
d069994 to
7953a7b
Compare
aussedatlo
force-pushed
the
feat/no-issue-mcp-speculos
branch
from
7953a7b to
22717f3
Compare
Made-with: Cursor
aussedatlo
force-pushed
the
feat/no-issue-mcp-speculos
branch
from
22717f3 to
fca52f2
Compare
…p-based waits with screen polling Convert dmk-session and cs-tester-manager from module-level globals into DmkSession and CsTesterManager classes, threaded through ToolDeps so tools never import global state directly. Replace all sleep(DELAY.postTap) waits with waitForScreenChange polling that detects actual screen transitions. Also fixes a bug where start_speculos errors were swallowed when the cs-tester child process exited before the polling loop detected the failure, and adds Docker troubleshooting guidance to workflow.md. Made-with: Cursor
…us responses Made-with: Cursor
Made-with: Cursor
…tions Made-with: Cursor
Renumber workflow steps from 1-6 (instead of 0-5) and restructure the initial step to lead with speculos_status before read, using explicit branching for running vs not-running states. Made-with: Cursor
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
📝 Description
Add a new @ledgerhq/speculos-mcp package that provides a Model Context Protocol (MCP) server for interacting with the Speculos Ledger device emulator.
This enables AI agents (e.g. in Cursor IDE) to drive the Speculos emulator through a structured tool interface — signing Ethereum transactions and EIP-712 typed data, navigating review screens, reading device state, and capturing screenshots.
Key features:
14 MCP tools: sign_transaction, sign_typed_data, swipe, approve, reject, read, screenshot, start_speculos, stop_speculos, speculos_status, dismiss_transaction_check, accept_blind_signing, enable_blind_signing, get_logs
Automatic DMK session management with Speculos transport
Clear signing support with EIP-7730 context modules
Screen event monitoring via Speculos /events endpoint
Workflow resource describing the signing lifecycle for AI agents
Docker-based Speculos lifecycle management via start_speculos / stop_speculos
MCP-native logging via sendLoggingMessage() with categorized loggers (dmk, docker, server) and a get_logs tool for on-demand filtered retrieval
Device-aware interactions using speculos-device-controller (percentage-based actions instead of hardcoded pixel coordinates)
One-file-per-tool architecture for maintainability
Cursor MCP config (.cursor/mcp.json) for out-of-the-box IDE integration
❓ Context
✅ Checklist
Pull Requests must pass CI checks and undergo code review. Set the PR as Draft if it is not yet ready for review.
packages/speculos-mcp/package (private, not published).cursor/mcp.jsonconfiguration for the MCP serverpnpm-lock.yamlwith new dependenciesMade with Cursor