Skip to content

Add @decocms/local-dev MCP daemon for local filesystem access #2479

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
vibegui wants to merge 10 commits into
base: main
Choose a base branch
from
+8,545 −144
Open

Add @decocms/local-dev MCP daemon for local filesystem access #2479

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
fc876ff
feat: local-dev daemon, deco link CLI, preview plugin, and git panel
vibegui Feb 25, 2026
18a6111
fix(git-panel): close panel and clear change count after commit
vibegui Feb 25, 2026
baf79ab
feat(object-storage): add file viewer route with raw/preview toggle
vibegui Feb 25, 2026
6b12eb3
feat(object-storage): add JSON pretty-print with syntax coloring in f…
vibegui Feb 25, 2026
c46029d
fix(preview): sync git panel button state with shell layout
vibegui Feb 25, 2026
2b2d4fd
feat(local-dev): heuristic dev server detection + fix stale cache aft…
vibegui Feb 26, 2026
cede902
fix(git-panel): scope bash connection to current project
vibegui Feb 26, 2026
04b507e
fix(git-panel): fetch project ID before looking up plugin configs
vibegui Feb 26, 2026
90b6325
feat(preview): make URL bar clickable and editable
vibegui Feb 26, 2026
5abd900
fix(local-dev): reconcile port drift at proxy level
vibegui Feb 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,8 @@ apps/benchmark/data
# AI planning files (root-level only, not docs/plans/)
/plans
.cursor/plans
.claude/
.planning/

# Local demo/prototype directories
studio-demo/
Expand Down
116 changes: 58 additions & 58 deletions .planning/REQUIREMENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,43 +20,43 @@

### Deco Blocks Plugin (`packages/mesh-plugin-deco-blocks/`)

- [ ] **BLK-01**: plugin-deco-blocks scans a folder and returns all block definitions (name, props schema, file path)
- [ ] **BLK-02**: plugin-deco-blocks scans a folder and returns all loader definitions (name, props schema, return type)
- [ ] **BLK-03**: plugin-deco-blocks defines DECO_BLOCKS_BINDING — the binding a connection must implement to be treated as a deco site
- [ ] **BLK-04**: plugin-deco-blocks provides `isDecoSite(connection)` binding checker usable by other plugins and flows
- [ ] **BLK-05**: plugin-deco-blocks ships with the canonical BLOCKS_FRAMEWORK.md spec as a package asset
- [ ] **BLK-06**: plugin-deco-blocks includes the Claude skill for implementing deco blocks (`.claude/commands/deco/blocks-framework.md`)
- [x] **BLK-01**: plugin-deco-blocks scans a folder and returns all block definitions (name, props schema, file path)
- [x] **BLK-02**: plugin-deco-blocks scans a folder and returns all loader definitions (name, props schema, return type)
- [x] **BLK-03**: plugin-deco-blocks defines DECO_BLOCKS_BINDING — the binding a connection must implement to be treated as a deco site
- [x] **BLK-04**: plugin-deco-blocks provides `isDecoSite(connection)` binding checker usable by other plugins and flows
- [x] **BLK-05**: plugin-deco-blocks ships with the canonical BLOCKS_FRAMEWORK.md spec as a package asset
- [x] **BLK-06**: plugin-deco-blocks includes the Claude skill for implementing deco blocks (`.claude/commands/deco/blocks-framework.md`)

### Site Editor Plugin (`packages/mesh-plugin-site-editor/`)

- [ ] **EDT-01**: User can view and navigate all pages in a deco site project
- [ ] **EDT-02**: User can create, rename, and delete pages
- [ ] **EDT-03**: User can view all available blocks and their prop schemas
- [ ] **EDT-04**: User can view all available loaders and their prop schemas
- [ ] **EDT-05**: User can open the visual composer for any page
- [ ] **EDT-06**: User can add, remove, and reorder sections on a page via drag-and-drop
- [ ] **EDT-07**: User can edit section props via auto-generated form (RJSF)
- [ ] **EDT-08**: User can bind a loader to a section prop
- [ ] **EDT-09**: User can preview the page live in an iframe with edit/interact mode toggle
- [ ] **EDT-10**: User can undo and redo changes in the composer
- [ ] **EDT-11**: User sees pending changes (sections added/modified/deleted vs git HEAD) with diff badges — powered by bash git calls via local-dev
- [ ] **EDT-12**: User can commit pending changes from Mesh UI with a Claude-generated commit message — via bash git commit
- [ ] **EDT-13**: User can view git history for the current page with commit list and diff preview — via bash git log/show
- [ ] **EDT-14**: User can revert to a previous commit with a confirmation dialog — via bash git checkout
- [ ] **EDT-15**: Site editor activates automatically when the project connection implements DECO_BLOCKS_BINDING
- [x] **EDT-01**: User can view and navigate all pages in a deco site project
- [x] **EDT-02**: User can create, rename, and delete pages
- [x] **EDT-03**: User can view all available blocks and their prop schemas
- [x] **EDT-04**: User can view all available loaders and their prop schemas
- [x] **EDT-05**: User can open the visual composer for any page
- [x] **EDT-06**: User can add, remove, and reorder sections on a page via drag-and-drop
- [x] **EDT-07**: User can edit section props via auto-generated form (RJSF)
- [x] **EDT-08**: User can bind a loader to a section prop
- [x] **EDT-09**: User can preview the page live in an iframe with edit/interact mode toggle
- [x] **EDT-10**: User can undo and redo changes in the composer
- [x] **EDT-11**: User sees pending changes (sections added/modified/deleted vs git HEAD) with diff badges — powered by bash git calls via local-dev
- [x] **EDT-12**: User can commit pending changes from Mesh UI with a Claude-generated commit message — via bash git commit
- [x] **EDT-13**: User can view git history for the current page with commit list and diff preview — via bash git log/show
- [x] **EDT-14**: User can revert to a previous commit with a confirmation dialog — via bash git checkout
- [x] **EDT-15**: Site editor activates automatically when the project connection implements DECO_BLOCKS_BINDING

> **Note:** EDT-11 through EDT-14 (git UX) activate only when the connection also exposes the bash tool. No direct dependency on local-dev package — capability-checked at runtime.

### `deco link` command (`packages/cli/`)

- [ ] **LNK-01**: Developer can run `deco link ./my-folder` to register a local project folder with a running Mesh instance
- [ ] **LNK-02**: `deco link` starts a local-dev daemon for the given folder (or connects to an already-running one)
- [ ] **LNK-03**: `deco link` creates (or reuses) a Connection in Mesh pointing at the local-dev daemon
- [ ] **LNK-04**: `deco link` creates (or reuses) a Project in Mesh wired to that Connection
- [ ] **LNK-05**: If the folder is a deco site (`.deco/` present), `deco link` auto-enables the site-editor plugin on the project
- [ ] **LNK-06**: `deco link` opens the browser to the project URL in Mesh, already logged in
- [ ] **LNK-07**: `deco link` keeps running as a daemon — when Ctrl+C is pressed, local-dev shuts down cleanly
- [ ] **LNK-08**: `deco link` is designed for both local Mesh (v1.3) and remote Mesh via tunnel (v1.4) — the Mesh URL is configurable
- [x] **LNK-01**: Developer can run `deco link ./my-folder` to register a local project folder with a running Mesh instance
- [x] **LNK-02**: `deco link` starts a local-dev daemon for the given folder (or connects to an already-running one)
- [x] **LNK-03**: `deco link` creates (or reuses) a Connection in Mesh pointing at the local-dev daemon
- [x] **LNK-04**: `deco link` creates (or reuses) a Project in Mesh wired to that Connection
- [x] **LNK-05**: If the folder is a deco site (`.deco/` present), `deco link` auto-enables the site-editor plugin on the project
- [x] **LNK-06**: `deco link` opens the browser to the project URL in Mesh, already logged in
- [x] **LNK-07**: `deco link` keeps running as a daemon — when Ctrl+C is pressed, local-dev shuts down cleanly
- [x] **LNK-08**: `deco link` is designed for both local Mesh (v1.3) and remote Mesh via tunnel (v1.4) — the Mesh URL is configurable

> **Note:** deco-cli (`packages/cli`) already exists with login support. `deco link` is a new command added to it. The CLI is the portable piece; Mesh can be local or remote.

Expand Down Expand Up @@ -97,35 +97,35 @@
| LDV-05 | Phase 15 | Pending |
| LDV-06 | Phase 15 | Pending |
| LDV-07 | Phase 15 | Pending |
| BLK-01 | Phase 16 | Pending |
| BLK-02 | Phase 16 | Pending |
| BLK-03 | Phase 16 | Pending |
| BLK-04 | Phase 16 | Pending |
| BLK-05 | Phase 16 | Pending |
| BLK-06 | Phase 16 | Pending |
| EDT-01 | Phase 17 | Pending |
| EDT-02 | Phase 17 | Pending |
| EDT-03 | Phase 17 | Pending |
| EDT-04 | Phase 17 | Pending |
| EDT-05 | Phase 17 | Pending |
| EDT-06 | Phase 17 | Pending |
| EDT-07 | Phase 17 | Pending |
| EDT-08 | Phase 17 | Pending |
| EDT-09 | Phase 17 | Pending |
| EDT-10 | Phase 17 | Pending |
| EDT-11 | Phase 17 | Pending |
| EDT-12 | Phase 17 | Pending |
| EDT-13 | Phase 17 | Pending |
| EDT-14 | Phase 17 | Pending |
| EDT-15 | Phase 17 | Pending |
| LNK-01 | Phase 18 | Pending |
| LNK-02 | Phase 18 | Pending |
| LNK-03 | Phase 18 | Pending |
| LNK-04 | Phase 18 | Pending |
| LNK-05 | Phase 18 | Pending |
| LNK-06 | Phase 18 | Pending |
| LNK-07 | Phase 18 | Pending |
| LNK-08 | Phase 18 | Pending |
| BLK-01 | Phase 16 | Complete |
| BLK-02 | Phase 16 | Complete |
| BLK-03 | Phase 16 | Complete |
| BLK-04 | Phase 16 | Complete |
| BLK-05 | Phase 16 | Complete |
| BLK-06 | Phase 16 | Complete |
| EDT-01 | Phase 17 | Complete |
| EDT-02 | Phase 17 | Complete |
| EDT-03 | Phase 17 | Complete |
| EDT-04 | Phase 17 | Complete |
| EDT-05 | Phase 17 | Complete |
| EDT-06 | Phase 17 | Complete |
| EDT-07 | Phase 17 | Complete |
| EDT-08 | Phase 17 | Complete |
| EDT-09 | Phase 17 | Complete |
| EDT-10 | Phase 17 | Complete |
| EDT-11 | Phase 17 | Complete |
| EDT-12 | Phase 17 | Complete |
| EDT-13 | Phase 17 | Complete |
| EDT-14 | Phase 17 | Complete |
| EDT-15 | Phase 17 | Complete |
| LNK-01 | Phase 18 | Complete |
| LNK-02 | Phase 18 | Complete |
| LNK-03 | Phase 18 | Complete |
| LNK-04 | Phase 18 | Complete |
| LNK-05 | Phase 18 | Complete |
| LNK-06 | Phase 18 | Complete |
| LNK-07 | Phase 18 | Complete |
| LNK-08 | Phase 18 | Complete |

**Coverage:**
- v1.3 requirements: 36 total (7 LDV + 6 BLK + 15 EDT + 8 LNK)
Expand Down
32 changes: 22 additions & 10 deletions .planning/ROADMAP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,10 +36,10 @@ Git site binding tools, pending changes UI, commit dialog with Claude-generated

## Phases

- [ ] **Phase 15: local-dev daemon** - MCP server for local filesystem, object storage, git, and dev server management
- [ ] **Phase 16: plugin-deco-blocks** - Standalone deco blocks framework: scanners, DECO_BLOCKS_BINDING, Claude skill
- [ ] **Phase 17: site-editor plugin** - Full site editor UI with visual composer and git UX
- [ ] **Phase 18: deco link command** - `deco link ./folder` in packages/cli connects local project to Mesh
- [x] **Phase 15: local-dev daemon** - MCP server for local filesystem, object storage, git, and dev server management (completed 2026-02-20, on feat/local-dev-daemon branch)
- [x] **Phase 16: plugin-deco-blocks** - Standalone deco blocks framework: scanners, DECO_BLOCKS_BINDING, Claude skill (completed 2026-02-21)
- [x] **Phase 17: site-editor plugin** - Full site editor UI with visual composer and git UX (completed 2026-02-21)
- [x] **Phase 18: deco link command** - `deco link ./folder` in packages/cli connects local project to Mesh (completed 2026-02-22)

## Phase Details

Expand Down Expand Up @@ -78,7 +78,15 @@ Git site binding tools, pending changes UI, commit dialog with Claude-generated
3. User can preview the page live in an iframe and toggle between edit mode and interact mode
4. User sees pending changes (additions, edits, deletions vs git HEAD) with diff badges, and can commit them from the UI with a Claude-generated commit message
5. User can view the git history for a page, see a diff preview per commit, and revert to any previous commit with a confirmation dialog
**Plans**: TBD
**Plans**: 6 plans

Plans:
- [ ] 17-01-PLAN.md — Package scaffold + plugin shell (package.json, shared.ts, ClientPlugin, ServerPlugin stub)
- [ ] 17-02-PLAN.md — Data layer: page-api, block-api, git-api, query-keys
- [ ] 17-03-PLAN.md — TDD: useUndoRedo hook (tested) + useIframeBridge hook
- [ ] 17-04-PLAN.md — Pages UI: pages list, create/rename/delete modals, plugin router
- [ ] 17-05-PLAN.md — Composer: section list DnD, RJSF prop editor, loader drawer, preview iframe, undo/redo
- [ ] 17-06-PLAN.md — Git UX footer, commit message server route, apps/mesh plugin registration

### Phase 18: deco link command
**Goal**: A developer can run `deco link ./my-folder` (from the existing deco-cli) and immediately see their local project in a running Mesh instance — browser opens, project ready, no manual wiring
Expand All @@ -90,7 +98,11 @@ Git site binding tools, pending changes UI, commit dialog with Claude-generated
3. Running the same command again on an existing setup reuses the existing Connection and Project — nothing is duplicated
4. Pressing Ctrl+C shuts down local-dev cleanly — the project goes offline in Mesh
5. The Mesh URL is configurable so the same `deco link` command can target a remote Mesh instance (tunnel wiring deferred to v1.4, but the config surface is ready)
**Plans**: TBD
**Plans**: 2 plans

Plans:
- [ ] 18-01-PLAN.md — Foundation libs: mesh-url, mesh-auth, mesh-client, local-dev-manager
- [ ] 18-02-PLAN.md — Link command: orchestration, Connection + Project creation, site-editor auto-enable, browser open, idempotency, clean shutdown

> **Amended 2026-02-20:** Replaced `npx @decocms/mesh ./folder` with `deco link` in packages/cli (deco-cli). CLI is the portable piece — Mesh can be local or remote. Auto-setup (admin/admin) remains needed for local Mesh but lives in Mesh startup, not in the CLI.

Expand All @@ -100,7 +112,7 @@ Git site binding tools, pending changes UI, commit dialog with Claude-generated

| Phase | Milestone | Plans Complete | Status | Completed |
|-------|-----------|----------------|--------|-----------|
| 15. local-dev daemon | v1.3 | 0/? | Not started | - |
| 16. plugin-deco-blocks | v1.3 | 0/? | Not started | - |
| 17. site-editor plugin | v1.3 | 0/? | Not started | - |
| 18. deco link command | v1.3 | 0/? | Not started | - |
| 15. local-dev daemon | v1.3 | 5/5 | Complete | 2026-02-20 |
| 16. plugin-deco-blocks | 4/4 | Complete | 2026-02-21 | - |
| 17. site-editor plugin | 6/6 | Complete | 2026-02-21 | - |
| 18. deco link command | 2/2 | Complete | 2026-02-22 | - |
64 changes: 51 additions & 13 deletions .planning/STATE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,33 +5,43 @@
See: .planning/PROJECT.md (updated 2026-02-20)

**Core value:** Developers can connect any MCP server to Mesh and get auth, routing, observability, and a visual site editor for Deco sites.
**Current focus:** Milestone v1.3 — Phase 15: local-dev daemon (ready to plan)
**Current focus:** Milestone v1.3 — Phase 18: deco-link-command (executing)

## Current Position

Phase: 15 of 18 (local-dev daemon)
Plan: — of — (not yet planned)
Status: Ready to plan
Last activity: 2026-02-20 — Roadmap created, v1.3 phases 15–18 defined
Phase: 18 of 18 (deco-link-command)
Plan: 2 of 2 complete
Status: Complete
Last activity: 2026-02-22 — Plan 18-02 complete: deco link command — meshLinkCommand with full orchestration (Connection + Project creation, site-editor auto-enable, idempotency, SIGINT teardown)

Progress: [░░░░░░░░░░] 0%
Progress: [██████████] 100%

## Performance Metrics

**Velocity:**
- Total plans completed: 0
- Average duration: —
- Total execution time: —
- Total plans completed: 2
- Average duration: 2 min
- Total execution time: 4 min

**By Phase:**

| Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|----------|
| - | - | - | - |
| 16-plugin-deco-blocks | 2 | 4 min | 2 min |

**Recent Trend:** No data yet
**Recent Trend:** Phase 16 plans 1-2 each executed in 2 min

*Updated after each plan completion*
| Phase 16 P03 | 2 | 2 tasks | 3 files |
| Phase 16-plugin-deco-blocks P04 | 4 | 2 tasks | 4 files |
| Phase 17-site-editor-plugin P01 | 2 | 2 tasks | 7 files |
| Phase 17-site-editor-plugin P02 | 3 | 2 tasks | 4 files |
| Phase 17-site-editor-plugin P03 | 2 | 2 tasks | 3 files |
| Phase 17-site-editor-plugin P04 | 3 | 2 tasks | 5 files |
| Phase 17-site-editor-plugin P05 | 3 | 2 tasks | 8 files |
| Phase 17-site-editor-plugin P06 | 3 | 2 tasks | 8 files |
| Phase 18-deco-link-command P01 | 3 | 2 tasks | 4 files |
| Phase 18 P02 | 3 | 2 tasks | 2 files |

## Accumulated Context

Expand All @@ -50,6 +60,34 @@ Recent decisions affecting current work:
- Bash tool is unrestricted, scoped to project folder — like Claude Code's bash
- deco-cli (packages/cli) already exists with login; `deco link` is a new command added to it
- Browser auto-opens on `deco link` (best DX, confirmed)
- z.record(z.string(), z.unknown()) required for Zod v4 — two-arg form, single-arg deprecated
- DECO_BLOCKS_BINDING lives in packages/bindings/ not in the plugin — enables site-editor import without plugin dependency
- [Phase 16-plugin-deco-blocks]: Skills placed at packages/mesh-plugin-deco-blocks/.claude/commands/deco/ satisfying BLK-06 in-package requirement
- [Phase 16-plugin-deco-blocks]: RootlessError (not NoRootTypeError) is the actual error class in ts-json-schema-generator — caught for Props-not-named-Props fallback
- [Phase 16-plugin-deco-blocks]: index.ts re-exports DECO_BLOCKS_BINDING for consumers who don't want to import @decocms/bindings directly
- [Phase 16-plugin-deco-blocks]: extractReturnTypeSchema handles T[] return types by stripping suffix, generating element schema, wrapping in array schema
- [Phase 17-site-editor-plugin]: Plugin uses ClientPlugin<typeof DECO_BLOCKS_BINDING> for binding-filtered activation — tab hides automatically for projects without the binding
- [Phase 17-site-editor-plugin]: server/index.ts stub with empty routes() — extended in plan 17-06 with commit-message route
- [Phase 17-site-editor-plugin]: registerPluginRoutes([]) in plan 01 setup — routes wired in plan 17-04 when TanStack Router setup exists
- [Phase 17-site-editor-plugin]: GenericToolCaller separate from TypedToolCaller — filesystem/bash tools not in DECO_BLOCKS_BINDING
- [Phase 17-site-editor-plugin]: listPages handles both { entries: [...] } and bare array response shapes defensively
- [Phase 17-site-editor-plugin]: hasBashTool gates git UI at runtime by checking connection.tools array for bash
- [Phase 17-site-editor-plugin]: Page/BlockInstance types defined inline in use-iframe-bridge.ts pending plan 17-02 page-api.ts completion
- [Phase 17-site-editor-plugin]: undoRedoReducer exported as named export to enable direct (non-renderHook) testing
- [Phase 17-site-editor-plugin]: @deco/ui imports require .tsx extension — bundler moduleResolution doesn't auto-resolve for workspace packages
- [Phase 17-site-editor-plugin]: usePluginContext uses typeof DECO_BLOCKS_BINDING (runtime value) as generic, not DecoBlocksBinding type alias
- [Phase 17-site-editor-plugin]: page-composer.tsx stub created in plan 17-04 to satisfy TS lazy import resolution in router.ts
- [Phase 17-site-editor-plugin]: Module-level keyboard store (_undoFn/_redoFn + kbStore singleton) with useSyncExternalStore — avoids useEffect ban for Cmd+Z/Cmd+Shift+Z keyboard shortcuts
- [Phase 17-site-editor-plugin]: typedCaller cast pattern — toolCaller cast to TypedToolCaller<DecoBlocksBinding> for block/loader tools and GenericToolCaller for filesystem tools
- [Phase 17-site-editor-plugin]: resetTrackerRef inline ref pattern — { current: '' } created in render body to detect pageId changes and call useUndoRedo.reset() without useEffect
- [Phase 17-site-editor-plugin]: FooterBar returns null when hasBashTool() is false — entire git UX absent for non-bash connections
- [Phase 17-site-editor-plugin]: Server /commit-message returns { message: "" } (not error) when ANTHROPIC_API_KEY is absent — graceful degradation to manual entry
- [Phase 18-deco-link-command]: System keychain storage via execSync platform CLIs (security/secret-tool) with ~/.deco_mesh_tokens.json fallback — no native addon
- [Phase 18-deco-link-command]: startLocalDev() returns null when daemon already running — null signals no child to manage
- [Phase 18-deco-link-command]: getOrganizationId() tries /api/auth/get-session then /api/auth/organization/list for resilience
- [Phase 18-deco-link-command]: OAuth callback supports both cookie-based sessions and token query param strategy
- [Phase 18]: Browser opens to plain project URL — no auto-login token per CONTEXT.md locked decision
- [Phase 18]: isDecoSite() evaluated before writeLinkState so .deco detection is pre-create (no false positives)

### Pending Todos

Expand All @@ -63,6 +101,6 @@ None yet.

## Session Continuity

Last session: 2026-02-20
Stopped at: Roadmap written, all 35 v1.3 requirements mapped to phases 15–18
Last session: 2026-02-22
Stopped at: Completed 18-02-PLAN.md — deco link command (mesh link mode + CLI registration)
Resume file: None
Loading
Loading