Skip to content

HANDOFF.md

Latest commit

 

History

History
126 lines (108 loc) · 7.73 KB

HANDOFF.md

File metadata and controls

126 lines (108 loc) · 7.73 KB
Raw

HANDOFF

Metadata

  • Project: Codex CircuitPython MCP
  • Repository Root: C:\Users\georg\Codex_Projects\Codex-Circuitpython-MCP
  • GitHub: https://github.com/neusse/Codex-Circuitpython-MCP
  • Branch: main
  • Last Commit: 60b5fe9 Document Codex MCP installation
  • Last Updated Local: 2026-05-03 18:55 America/Los_Angeles
  • Last Updated UTC: 2026-05-04T01:55:05Z
  • Stale After Hours: 24
  • Staleness: FRESH
  • Owner: George Neusse

Current Objective

Maintain and publish a local stdio MCP server that lets Codex safely discover, inspect, edit, deploy to, and serial-control CircuitPython boards such as the current Pimoroni Pico Plus 2 W PicoCalc setup.

Current State

  • Repo is initialized, public on GitHub, and clean on main tracking origin/main.
  • README is GitHub-ready with a banner, platform support table, MCP tool inventory, and Codex installation instructions.
  • MCP server exposes both Pico-focused tools and compatibility aliases.
  • Windows/Linux/macOS drive discovery is split into platform adapters under src/circuitpython_mcp/platforms.
  • Current local machine has no Codex MCP server entries configured yet; codex mcp list reports none.
  • Current board observed earlier in this session: G:\ labeled CIRCUITPY, serial COM12, board pimoroni_pico_plus2w.

Operational Rules In Force

  • On every new start, read HANDOFF.md first and report current state plus next actions.
  • Preserve user changes; do not reset or revert without explicit instruction.
  • Use PowerShell-native commands on this Windows machine.
  • Serial tools can only work when no other process owns the board serial port.
  • Avoid arbitrary serial REPL execution until explicit safety rules are designed.

Current Status

The project is published and usable as a local MCP server. The next practical task is to run the documented codex mcp add circuitpython-pico -- uv --directory "<repo path>" run circuitpython-mcp command on any machine that should expose the Pico tools, then start a new Codex session and verify the tools appear.

Completed Since Last Handoff

  • Published public GitHub repo: https://github.com/neusse/Codex-Circuitpython-MCP.
  • Added .gitattributes and switched the branch to main.
  • Polished README with SVG banner at docs/assets/circuitpython-mcp-banner.svg.
  • Added README installation instructions for Codex MCP client setup.
  • Verified repo metadata: public visibility, default branch main, description set.
  • Ran validation: uv run pytest and uv run ruff check ..
  • Earlier hardware checks confirmed the board at G:\ and serial COM12; help('modules') was captured; picocalc_FLW was run successfully from serial REPL.

In Progress

  • Codex MCP client registration - Status: documented but not applied on this machine - Next: run the codex mcp add command from the README if this machine should expose the tools.

Blockers

  • Original shared ChatGPT conversation body was not accessible - Impact: any exact tool semantics from the original chat may still be missing - Needed: paste/export that chat if exact prior requirements matter.
  • No arbitrary REPL command tool yet - Impact: some run/debug flows still require manual serial commands - Needed: define guardrails before adding.

Decisions and Rationale

  • One MCP server for Windows/Linux/macOS - Why: the same MCP tool surface can stay stable while board discovery changes by platform adapter.
  • Keep serial write/REPL execution out for now - Why: arbitrary REPL commands can change board state and need explicit safety rules.
  • Use repo-local SVG banner instead of generated bitmap - Why: it renders crisply on GitHub, stays small, and is editable in Git.
  • Codex MCP setup is documented, not embedded - Why: MCP server registration is machine-local under each user's Codex config.

Repo State Snapshot

  • Working tree: clean
  • Remote: origin https://github.com/neusse/Codex-Circuitpython-MCP.git
  • Tracking: main...origin/main
  • Changed files: none
  • Unpushed commits: none

Validation

  • Build/package: pass - uv sync previously completed; current environment already synced.
  • Tests: pass - uv run pytest -> 9 passed on 2026-05-04T01:55Z.
  • Lint/Typecheck: pass - uv run ruff check . -> all checks passed on 2026-05-04T01:55Z.
  • Manual checks: pass - GitHub repo metadata verified; codex mcp list currently shows no configured MCP servers.

Known Risks

  • Serial port contention: pico_reset, pico_serial_read, and related tools will fail if another process has the serial port open.
  • Multiple connected CircuitPython boards require explicit root or port; auto-selection only works cleanly with one board.
  • Linux serial access may require group/udev permission setup that has not been tested in this repo yet.
  • macOS/Linux adapters are unit-tested for selection and documented paths, but live hardware validation has only happened on Windows.
  • Secrets on the board, such as G:\secrets.py, should never be copied into this repo or posted publicly.

Open Questions

  • Should the server add a guarded pico_run_repl_command or similar tool?
  • Should README include an Adafruit library install/sync workflow?
  • Should the repo include a short demo GIF or screenshots of Codex using the tools?
  • Should the MCP server get a packaged release path beyond local uv usage?

Resume Steps

  1. Read this file and confirm staleness from Last Updated UTC.
  2. Run git status --short --branch and confirm main...origin/main is clean.
  3. Run uv sync.
  4. Run uv run pytest and uv run ruff check ..
  5. If MCP tools should be available on the current machine, run codex mcp add circuitpython-pico -- uv --directory "C:\Users\georg\Codex_Projects\Codex-Circuitpython-MCP" run circuitpython-mcp.
  6. Start a new Codex session and verify pico_status, pico_list_files, and pico_serial_read are available.
  7. Decide whether to implement a guarded REPL command tool, Adafruit library installer, or more docs/examples.

Quick Commands

cd C:\Users\georg\Codex_Projects\Codex-Circuitpython-MCP
git status --short --branch
uv sync
uv run pytest
uv run ruff check .
codex mcp add circuitpython-pico -- uv --directory "C:\Users\georg\Codex_Projects\Codex-Circuitpython-MCP" run circuitpython-mcp
codex mcp list
codex mcp get circuitpython-pico

Important Files

  • C:\Users\georg\Codex_Projects\Codex-Circuitpython-MCP\README.md - Public GitHub landing page and install docs.
  • C:\Users\georg\Codex_Projects\Codex-Circuitpython-MCP\src\circuitpython_mcp\server.py - MCP tool definitions.
  • C:\Users\georg\Codex_Projects\Codex-Circuitpython-MCP\src\circuitpython_mcp\board_files.py - Board file path confinement and file operations.
  • C:\Users\georg\Codex_Projects\Codex-Circuitpython-MCP\src\circuitpython_mcp\serial_tools.py - Serial read, interrupt, and reset helpers.
  • C:\Users\georg\Codex_Projects\Codex-Circuitpython-MCP\src\circuitpython_mcp\platforms - Windows/Linux/macOS board discovery adapters.
  • C:\Users\georg\Codex_Projects\Codex-Circuitpython-MCP\tests - Current unit tests.
  • C:\Users\georg\Codex_Projects\Codex-Circuitpython-MCP\docs\assets\circuitpython-mcp-banner.svg - README banner.

Machine Notes

  • OS: Microsoft Windows 11 Home, version 10.0.26200, build 26200.
  • Python: 3.13.11.
  • uv: 0.8.3.
  • Codex CLI: codex-cli 0.128.0.
  • GitHub CLI authenticated as neusse.
  • GitHub repo visibility: PUBLIC.
  • Local board observed: G:\ / COM12, UID B9D00C5DCA1EF065.

Change Log

  • 2026-05-04T01:55:05Z - Dropoff refresh: recorded GitHub publication, README install docs, clean repo state, current validation, machine notes, blockers, and deterministic resume steps.
  • 2026-05-04T01:47:53Z - Added README instructions for registering the server with codex mcp add.
  • 2026-05-04T01:03:03Z - Added Windows/Linux/macOS platform adapters and validation notes.