# Reported issues for crosspad-mcp

Pod holds 16 of 20 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [crosspad-mcp](/mcp/crosspad-mcp).

## Most discussed

### test: add E2E tests with mock simulator and git repos

## Summary
Unit tests cover parsing logic, but no E2E tests for full tool dispatch. Need mock TCP server + fake git repos for roundtrip testing.

## Scope
- Mock TCP server mimicking simulator protocol
- Fake git repos with controlled state
- E2E tests for each tool/action combination
- CI integration (vitest)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

[Read the thread](https://github.com/CrossPad/crosspad-mcp/issues/14) · 2026-04-09 · closed · 3 comments

### crosspad_input click takes window coordinates while crosspad_screenshot returns LCD space

`crosspad_screenshot` returns LCD-space images, `crosspad_input action=click` takes window-space coordinates, and nothing in either tool says so. There is no way to convert between the two without reverse-engineering the window geometry, so any click derived from a screenshot is a guess.

## What happens

1. `crosspad_screenshot region=lcd` returns a 320x240 image — the coordinate space the UI code, `ENC_GROUP` labels and LVGL itself use.
2. `crosspad_input action=click x=<lcd_x> y=<lcd_y>` clic

[Read the thread](https://github.com/CrossPad/crosspad-mcp/issues/26) · 2026-08-29 · closed · 1 comment

### feat: return MCP image content from screenshot tool

## Summary
Screenshot tool returns JSON with file path or base64 string. Should return proper MCP \`image\` content type so Claude can visually inspect the UI.

**Status: Implemented** — returns \`{ type: "image", data: base64, mimeType: "image/png" }\` alongside text metadata. Works for both save-to-file and inline modes.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

[Read the thread](https://github.com/CrossPad/crosspad-mcp/issues/19) · 2026-04-09 · closed · 1 comment

### perf: cache app registry with TTL

## Summary
Each \`crosspad_apps list\` call re-reads and parses registry JSON from disk. Add in-memory cache with 5-minute TTL.

**Status: Implemented** — \`loadRegistryJsonFrom\` caches by file path with 5min TTL.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

[Read the thread](https://github.com/CrossPad/crosspad-mcp/issues/18) · 2026-04-09 · closed · 1 comment

### fix: add retry logic for simulator TCP connections

## Summary
\`sendRemoteCommand\` fails immediately on timeout. Should retry 2-3x with backoff — simulator may be in the middle of loading/rendering.

**Status: Implemented** — retries up to 3x with incremental backoff (500ms, 1s, 1.5s). Skips retry on ECONNREFUSED (simulator not running).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

[Read the thread](https://github.com/CrossPad/crosspad-mcp/issues/17) · 2026-04-09 · closed · 1 comment

### fix: validate Python availability before app_manager delegation

## Summary
\`crosspadAppInstall/Remove/Update/Sync\` delegate to Python subprocess without checking if \`python3\` or \`app_manager.py\` exist. Should fail-fast with a clear error message.

**Status: Implemented** — checks python3 availability (cached) and script existence before spawning subprocess.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

[Read the thread](https://github.com/CrossPad/crosspad-mcp/issues/16) · 2026-04-09 · closed · 1 comment

### feat: parse build progress percentage from CMake/Ninja

## Summary
CMake/Ninja outputs \`[45/120]\` progress markers. Parse these into structured progress data for potential UI progress bars.

## Scope
- Parse \`[N/M]\` from build output lines
- Emit structured progress via MCP logging (percentage, current/total)
- Don't break existing raw line streaming

## Priority
Low — nice UX improvement for long builds.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

[Read the thread](https://github.com/CrossPad/crosspad-mcp/issues/13) · 2026-04-09 · closed · 1 comment

### feat: scaffold auto-install option

## Summary
\`crosspad_code scaffold\` generates boilerplate files but doesn't write them, register the app, or trigger a build. Add optional auto-install flow.

## Scope
- Add \`auto_install\` boolean param (default false)
- When true: write files → fullclean → build → verify
- Return build result alongside scaffold output

## Priority
Low — quality of life for app creation workflow.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

[Read the thread](https://github.com/CrossPad/crosspad-mcp/issues/12) · 2026-04-09 · closed · 1 comment

## Most recent

### fix: read server version from package.json instead of hardcoding

## Summary
\`index.ts\` hardcodes \`version: "5.0.0"\` while package.json has \`"5.1.0"\`. Version should be read dynamically from package.json.

**Status: Implemented** — using \`createRequire\` to read package.json at startup.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

[Read the thread](https://github.com/CrossPad/crosspad-mcp/issues/15) · 2026-04-09 · closed · 0 comments

### feat: add CI-like pipeline action to crosspad_build

## Summary
Add a `pipeline` action that runs build → test → report in one invocation instead of 3 separate tool calls.

## Scope
- New action `pipeline` in crosspad_build
- Sequential: build PC → run tests → collect results
- Return structured report: per-stage pass/fail, timing, error summary
- Optional: include IDF build as stage

🤖 Generated with [Claude Code](https://claude.com/claude-code)

[Read the thread](https://github.com/CrossPad/crosspad-mcp/issues/11) · 2026-04-09 · closed · 1 comment

### feat: add MCP Resources for static project context

## Summary
The server exposes only Tools, no MCP Resources. Resources would provide static context without tool invocations:

- \`crosspad://architecture\` — CLAUDE.md + architecture overview
- \`crosspad://registry\` — current app-registry.json
- \`crosspad://interfaces\` — crosspad-core interface list
- \`crosspad://hardware\` — hardware quick reference

## Scope
- Register resources via MCP SDK \`server.resource()\`
- Read from filesystem on demand (CLAUDE.md files, registry.json)
- Consider 

[Read the thread](https://github.com/CrossPad/crosspad-mcp/issues/10) · 2026-04-09 · closed · 1 comment

### feat: add context_lines option to crosspad_code search

## Summary
Symbol search returns single matching lines via `git grep`. Add `context_lines` parameter (like `grep -C`) to show surrounding code.

## Scope
- Add optional `context_lines` param (default 0, max ~10)
- Pass `-C N` to git grep
- Adjust result parsing to handle context blocks

🤖 Generated with [Claude Code](https://claude.com/claude-code)

[Read the thread](https://github.com/CrossPad/crosspad-mcp/issues/9) · 2026-04-09 · closed · 1 comment

### feat: add platform param to crosspad_test for future IDF tests

## Summary
Tests are PC-only (Catch2). Prepare for IDF unit tests (Unity framework) by adding `platform` parameter.

## Scope
- Add optional `platform` enum (pc/idf) defaulting to pc
- Current behavior unchanged for pc
- Stub for idf: return "not yet supported" or detect unity test runner

## Priority
Low — future-proofing for when IDF tests exist.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

[Read the thread](https://github.com/CrossPad/crosspad-mcp/issues/8) · 2026-04-09 · closed · 1 comment

### feat: detect unregistered apps in pc build-check

## Summary
`idf-build.ts` detects new app directories requiring fullclean, but `build-check.ts` (PC) doesn't. Should check `src/app/*/` for new directories vs last build.

## Scope
- In `build-check.ts`, scan for app directories not present in last CMake configure
- Flag in health check result: `newApps: ["app_name"]`
- Suggest `reconfigure` mode when detected

🤖 Generated with [Claude Code](https://claude.com/claude-code)

[Read the thread](https://github.com/CrossPad/crosspad-mcp/issues/7) · 2026-04-09 · closed · 1 comment

### feat: integrate crosspad-docs context generation

## Summary
Add `docs` action to `crosspad_code` for accessing aggregated documentation from crosspad-docs repo.

## Scope
- Read/generate CROSSPAD_CONTEXT.md from crosspad-docs
- Optionally trigger sync/aggregate/build pipeline
- Return documentation sections on demand

## Priority
Low — useful for giving Claude full project context without reading each repo.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

[Read the thread](https://github.com/CrossPad/crosspad-mcp/issues/6) · 2026-04-09 · closed · 1 comment

### feat: add submodule_update action to crosspad_repo

## Summary
Updating submodules (crosspad-core, crosspad-gui) across repos requires manual git commands. Add `submodule_update` action.

## Scope
- `crosspad_repo action=submodule_update submodule=crosspad-core repo=idf`
- Runs: `cd <submodule_path> && git fetch origin && git checkout origin/main`
- Then: `cd <parent_repo> && git add <submodule_path>`
- Report: old SHA → new SHA, files changed

## Acceptance
- Updates pinned submodule ref to latest main
- Works across all platform repos (idf, pc,

[Read the thread](https://github.com/CrossPad/crosspad-mcp/issues/5) · 2026-04-09 · closed · 1 comment

The remaining reports are on [the project's issue tracker](https://github.com/CrossPad/crosspad-mcp/issues).