@dforge-core/dforge-mcp 0.1.0-rc.1 → 0.1.0-rc.11

package/README.md

@@ -1,26 +1,51 @@
 # @dforge-core/dforge-mcp
 
-MCP server for dForge module authoring. Exposes scaffold / pack / install
-tools and schema resources so AI agents (Claude Code, Cursor, Zed, etc.)
-can create and ship dForge modules through structured tool calls instead
-of free-form JSON generation.
+MCP server for dForge module authoring. Exposes 18 composable tools and the canonical schemas so AI agents (Claude Code, Cursor, Zed, etc.) can drive the full module lifecycle — scaffold → entities → actions → views → security → install — through structured tool calls instead of free-form JSON generation.
 
-## Install
+Ships with a wizard Skill (`skills/dforge-mcp-author/SKILL.md`) that walks the AI through six phases with explicit backtrack support when later phases expose earlier gaps.
+
+**New here?** Start with **[docs/creating-modules.md](docs/creating-modules.md)** — three ways to scaffold a module (terminal CLI, VS Code sidebar, AI wizard) and when to pick each.
+
+> **Two GitHub repos to know:** this MCP server lives at `dforge-core/dforge-mcp`. The dForge platform itself (entities, validator, native CLI source) lives at `iash44/dForge-core` — referenced in `homepage` because the schemas + DSL conventions come from there.
+
+## What it depends on at runtime
+
+```
+your AI editor (Claude Code / Cursor / Zed)
+    │
+    ▼ stdio JSON-RPC
+@dforge-core/dforge-mcp       ← this package; pure JS / TS
+    │
+    ▼ shells out for pack / install
+@dforge-core/dforge-cli        ← installed as a transitive dep; thin JS wrapper
+    │
+    ▼ optionalDependencies
+@dforge-core/dforge-cli-<platform>   ← native C# binary per platform (~35 MB)
+```
+
+The native binary actually talks to your tenant. The npm-CLI wrapper is just a launcher that picks the right platform binary and exec's it. **You don't need to install dforge-cli separately** — it comes along when you install dforge-mcp (or when `npx -y @dforge-core/dforge-mcp` runs cold).
+
+If you want to use a hand-built native binary instead of the npm-shipped one, point `DFORGE_CLI_BINARY` at the executable file's absolute path:
 
 ```bash
-# As an MCP server invoked by an AI editor — usually no install needed,
-# the editor runs it via npx on demand. See "Wiring it up" below.
+DFORGE_CLI_BINARY=/Users/me/projects/dForge-core/cli/bin/dForge.Cli
+```
+
+(macOS / Linux: no extension. Windows: `dForge.Cli.exe`.) If the path doesn't exist or isn't executable the server reports an error at the first pack/install call.
 
-# Local install (for development / debugging):
-npm install -g @dforge-core/dforge-mcp
-dforge-mcp                # speaks JSON-RPC over stdio; ctrl+C to quit
+## Install + wire into Claude Code
+
+### Recommended — via `claude mcp add` (writes ~/.claude.json for you)
+
+```bash
+claude mcp add dforge --scope user -- npx -y @dforge-core/dforge-mcp
 ```
 
-## Wiring it up
+This appends to `~/.claude.json` (the global config — single file in your home dir, no subdirectory). Restart Claude Code; on the first session that activates the server you'll see "Approve MCP server 'dforge'?" — accept it.
 
-### Claude Code
+### Manual — per-project
 
-Add to `~/.claude/config.json` (or the project-local `.claude/mcp.json`):
+Write `.mcp.json` at **the repo root** (not under `.claude/`):
 
 ```json
 {
@@ -29,55 +54,136 @@ Add to `~/.claude/config.json` (or the project-local `.claude/mcp.json`):
       "command": "npx",
       "args": ["-y", "@dforge-core/dforge-mcp"],
       "env": {
-        "DFORGE_CLI_BINARY": "/optional/path/to/dForge.Cli"
+        "DFORGE_CLI_BINARY": "/optional/abs/path/to/dForge.Cli"
       }
     }
   }
 }
 ```
 
-`DFORGE_CLI_BINARY` is only needed if you want `dforge_module_pack` /
-`dforge_module_install` to use a non-published native binary (e.g. a
-local C# build). Otherwise the server uses whatever `dforge-cli` is on
-PATH (install via `npm install -g @dforge-core/dforge-cli`).
+Restart Claude Code → approve on first prompt.
+
+### Verify it's alive
+
+```bash
+claude mcp list
+# Should show: dforge — npx -y @dforge-core/dforge-mcp — connected
+```
+
+Or inside a Claude Code session, type `/mcp` to see all connected servers + their tools. The 18 `dforge_*` tools should be listed.
 
 ### Cursor / Zed
 
-Same shape — both editors take a `command + args` MCP config. Refer to
-their docs for the exact file path.
+Same `command + args` config shape; check their docs for the file location. Verification is via their respective tool listings.
 
 ## What it exposes
 
-### Tools
+### Tools (18)
+
+Grouped by typical phase in the wizard flow. All "return" tools emit `{ summary, files: { '<relPath>': '<contents>' } }`; the client decides whether to write — lets the AI preview diffs with the user before committing.
 
+**Module-level**
 | Tool | Behavior |
 |---|---|
-| `dforge_module_create` | Returns a file map for a new module. Client writes the files. |
-| `dforge_entity_add` | Reads an existing module, returns the updated file map (manifest + new entity + regenerated UI/security). |
-| `dforge_module_pack` | Shells to `dforge-cli module pack`. Returns tarball path + size. |
-| `dforge_module_install` | Shells to `dforge-cli module install`. Returns CLI output. |
-| `dforge_dbml_import` | Stub. Returns "not yet implemented" until the underlying CLI command lands. |
+| `dforge_module_create` | New module scaffold |
+| `dforge_module_inspect` | Read current module state. Full structured data is in `files["_inspect.json"]`; `summary` is one-line stats |
+| `dforge_module_pack` | Shells to `dforge-cli module pack`. Returns tarball path + size |
+| `dforge_module_install` | Shells to `dforge-cli module install`. Args: `pathOrTarball`, optional `tenantUrl` / `token` / `tenantCode` — fall back to `DFORGE_URL` / `DFORGE_TOKEN` env. `tenantCode` is an optional `--code` sanity check the server cross-references against the JWT |
 
-The `create` and `entity_add` tools deliberately **return** instead of writing — the LLM previews the file map with the user before commit.
+**Entities (Phase 1)**
+| Tool | Behavior |
+|---|---|
+| `dforge_entity_add` | Add an entity to an existing module |
+| `dforge_entity_field_add` | Patch a single field |
+| `dforge_entity_field_modify` | Replace a field's spec |
+| `dforge_entity_field_remove` | Drop a field (warns about dependents) |
+
+**Behavior (Phase 2 — optional)**
+| Tool | Behavior |
+|---|---|
+| `dforge_action_add` | DSL script + `ui/actions.json` entry |
 
-### Resources
+**Views + reports (Phase 3)**
+| Tool | Behavior |
+|---|---|
+| `dforge_view_add` | Add a data view |
+| `dforge_view_modify` | Replace a view's spec |
+| `dforge_report_add` | Add a report |
+| `dforge_setting_add` | Configurable module-level setting |
+
+**Security (Phase 5)**
+| Tool | Behavior |
+|---|---|
+| `dforge_role_add` | Add a role + rights matrix. **Fails if role already exists** — the scaffolder pre-creates `<code>.admin`, so use `role_right_set` to amend it instead |
+| `dforge_role_right_set` | Grant/revoke one right on one object (cheap backtrack) |
+| `dforge_folder_add` | Add a security folder (optional — most modules ship with just root) |
+
+**Cross-cutting**
+| Tool | Behavior |
+|---|---|
+| `dforge_dependency_add` | Add a dep on another dForge module |
+| `dforge_dbml_import` | Stub — not implemented yet |
+
+### Resources (13)
 
 | URI | Content |
 |---|---|
-| `dforge://schema/manifest` | JSON Schema for manifest.json |
-| `dforge://schema/entity` | JSON Schema for entity files |
-| `dforge://schema/data-view` | JSON Schema for ui/data_views.json |
-| `dforge://docs/conventions` | MODULE_CONVENTIONS.md from dForge-core |
+| `dforge://schema/manifest` | manifest.json JSON Schema |
+| `dforge://schema/entity` | entity files |
+| `dforge://schema/data-views` | ui/data_views.json |
+| `dforge://schema/folders` | ui/folders.json |
+| `dforge://schema/menus` | ui/menus.json |
+| `dforge://schema/roles` | security/roles.json |
+| `dforge://schema/jobs` | logic/jobs.json |
+| `dforge://schema/seed-data` | seed-data/*.json |
+| `dforge://schema/reports` | ui/reports.json |
+| `dforge://schema/settings` | settings.json |
+| `dforge://schema/traits` | entity trait codes |
+| `dforge://schema/webhooks` | ui/webhooks.json |
+| `dforge://docs/conventions` | MODULE_CONVENTIONS.md |
+
+Schemas + conventions are vendored at build time from `iash44/dForge-core`'s `docs/`. The published npm tarball ships them under `resources/`, and jsdelivr serves them at:
 
-The schemas + conventions doc are vendored at build time from
-`dForge-core/docs/`. Refresh with `scripts/vendor-resources.sh`.
+```
+https://cdn.jsdelivr.net/npm/@dforge-core/dforge-mcp@latest/resources/schemas/<name>.schema.json
+```
+
+**Compatibility:** schemas vendored for this release came from `iash44/dForge-core` `main` as of the publish date stamped in `package.json`. If the platform adds new entity properties / field types after this release, generated modules using those features may validate locally but be rejected at install time. Bump the dforge-mcp version when the platform schemas change materially.
 
-## Claude Skill
+## Claude Skill — the wizard
 
-`skills/dforge-mcp-author/SKILL.md` is a Skill file that teaches Claude
-how to drive the tools — gather requirements → preview → write → iterate.
-Copy it into your `~/.claude/skills/` (or per-project `.claude/skills/`)
-to enable.
+`skills/dforge-mcp-author/SKILL.md` teaches Claude how to drive the tools as a six-phase wizard. **It is NOT auto-installed by `npm install` — the Skill file ships in the npm tarball but Claude Code looks for Skills in `~/.claude/skills/`, not in node_modules.** Sync it manually:
+
+```bash
+# Resolve the actual latest published version from the npm registry,
+# then pin the jsdelivr URL to it. We don't use jsdelivr's `@latest`
+# alias directly — that CDN endpoint caches aggressively (6-12h lag
+# after a new publish), which silently serves stale Skill content.
+VERSION=$(npm view @dforge-core/dforge-mcp version)
+mkdir -p ~/.claude/skills/dforge-mcp-author
+curl -fsSL "https://cdn.jsdelivr.net/npm/@dforge-core/dforge-mcp@${VERSION}/skills/dforge-mcp-author/SKILL.md" \
+  -o ~/.claude/skills/dforge-mcp-author/SKILL.md
+
+# Or, straight from GitHub main (always fresh, but pre-release content):
+# curl -fsSL https://raw.githubusercontent.com/dforge-core/dforge-mcp/main/skills/dforge-mcp-author/SKILL.md \
+#   -o ~/.claude/skills/dforge-mcp-author/SKILL.md
+```
+
+Re-run after every dforge-mcp upgrade — the Skill version isn't checked at runtime, so a stale Skill against new tools will misroute calls.
+
+The phases:
+
+| Phase | Required? | Tools used |
+|---|---|---|
+| 0. Intake | yes | (brief written manually) |
+| 1. Domain | yes | `module_create`, `entity_add`, `entity_field_*` |
+| 2. Actions | optional | `action_add` |
+| 3. Views + Reports | views yes, reports optional | `view_*`, `report_add`, `setting_add` |
+| 4. Polish (translations, seed) | optional | (file map authored directly) |
+| 5. Security | roles required, folders optional | `role_add`, `role_right_set`, `folder_add` |
+| 6. Verify | yes | `module_pack`, `module_install` |
+
+Key principles encoded in the Skill: inspect-before-patch, one-at-a-time, deterministic backtrack on earliest-phase-first rule, tool-failure protocol that distinguishes auth/connectivity from module defects, end-of-session cleanup user-driven.
 
 ## For maintainers
 
@@ -85,15 +191,18 @@ to enable.
 
 ```bash
 pnpm install
-pnpm build          # tsup → dist/server.js
+pnpm build          # tsup → dist/server.js (bundles SDK + zod + dforge-cli/templates)
 pnpm typecheck      # tsc --noEmit
-node dist/server.js # smoke-test via stdio JSON-RPC
+node dist/server.js # stdio JSON-RPC — pipe a request to smoke-test
 ```
 
-The `@dforge-core/dforge-cli` dep is currently pinned to a `file:`
-sibling path so this repo can be developed alongside `dforge-cli`. Before
-publishing, change to a real npm version (`^0.1.0-rc.5` or higher — the
-first version that exposes the `templates` subpath export).
+To iterate against an in-tree `dforge-cli`, temporarily pin the dep at the sibling path:
+
+```bash
+sed -i '' 's|"@dforge-core/dforge-cli": "\^0.1.[0-9.]*"|"@dforge-core/dforge-cli": "file:../dforge-cli"|' package.json
+rm -rf node_modules pnpm-lock.yaml && pnpm install
+# Flip back before publish — file: deps don't resolve for npm consumers.
+```
 
 ### Refresh vendored resources
 
@@ -104,16 +213,34 @@ scripts/vendor-resources.sh                              # auto-locate ../dForge
 DFORGE_CORE=/abs/path/to/dForge-core scripts/vendor-resources.sh
 ```
 
-### Publishing to npm
+Republish to update jsdelivr-served schemas + the bundled resources.
 
-(Same approach as dforge-cli — `prepublishOnly` runs tsup so the
-published tarball gets a fresh `dist/server.js`. No platform binaries to
-manage, so a single `npm publish` covers it.)
+### Publishing
 
 ```bash
-npm publish --access public --tag next
+scripts/publish.sh 0.1.0-rc.N --tag latest --otp <code>
 ```
 
+`prepublishOnly` runs `tsup` so the tarball gets a fresh `dist/server.js`. No platform binaries to manage.
+
+**Pre-publish checklist:**
+- [ ] `@dforge-core/dforge-cli` dep is a real version (not `file:...`)
+- [ ] `pnpm typecheck` passes
+- [ ] Smoke test stdio: `tools/list` returns 18 tools
+- [ ] Skill updated for any new/changed tools (it's a SEPARATE artifact; users sync it manually after upgrades)
+
+### Adding a new tool
+
+1. Drop it in `src/tools/<name>.ts`. Use shared helpers from `src/tools/_helpers.ts` (`loadManifest`, `readJsonOrDefault`, `jsonText`, `makeResult`, `withTodayStamp`). Return a `ToolResult`.
+2. Import + register in `src/server.ts` via the `envelope()` wrapper.
+3. Mention it in `skills/dforge-mcp-author/SKILL.md` (which phase, which backtrack scenarios use it).
+4. Bump `package.json` version, publish.
+
+Conventions:
+- Return file maps relative to the module root. Don't write to disk.
+- Reject if the target key already exists (force users to call the matching `*_modify` / `*_remove`).
+- Bump `manifest.updated` on every patch.
+
 ## License
 
 MIT.