@dforge-core/dforge-mcp 0.1.0-rc.4 → 0.1.0-rc.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +110 -73
  2. package/package.json +1 -1
  3. package/skills/dforge-mcp-author/SKILL.md +8 -5
package/README.md CHANGED
@@ -1,25 +1,49 @@
1
1
  # @dforge-core/dforge-mcp
2
2
 
3
- MCP server for dForge module authoring. Exposes a small set of 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.
3
+ 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.
4
4
 
5
5
  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.
6
6
 
7
- ## Install
7
+ > **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.
8
+
9
+ ## What it depends on at runtime
10
+
11
+ ```
12
+ your AI editor (Claude Code / Cursor / Zed)
13
+ │
14
+ ▼ stdio JSON-RPC
15
+ @dforge-core/dforge-mcp ← this package; pure JS / TS
16
+ │
17
+ ▼ shells out for pack / install
18
+ @dforge-core/dforge-cli ← installed as a transitive dep; thin JS wrapper
19
+ │
20
+ ▼ optionalDependencies
21
+ @dforge-core/dforge-cli-<platform> ← native C# binary per platform (~35 MB)
22
+ ```
23
+
24
+ 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).
25
+
26
+ 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:
8
27
 
9
28
  ```bash
10
- # As an MCP server invoked by an AI editor — usually no install needed,
11
- # the editor runs it via npx on demand. See "Wiring it up" below.
29
+ DFORGE_CLI_BINARY=/Users/me/projects/dForge-core/cli/bin/dForge.Cli
30
+ ```
31
+
32
+ (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.
33
+
34
+ ## Install + wire into Claude Code
12
35
 
13
- # Local install (for development / debugging):
14
- npm install -g @dforge-core/dforge-mcp
15
- dforge-mcp # speaks JSON-RPC over stdio; ctrl+C to quit
36
+ ### Recommended — via `claude mcp add` (writes ~/.claude.json for you)
37
+
38
+ ```bash
39
+ claude mcp add dforge --scope user -- npx -y @dforge-core/dforge-mcp
16
40
  ```
17
41
 
18
- ## Wiring it up
42
+ 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.
19
43
 
20
- ### Claude Code
44
+ ### Manual — per-project
21
45
 
22
- Add to `~/.claude/config.json` (or the project-local `.claude/mcp.json`):
46
+ Write `.mcp.json` at **the repo root** (not under `.claude/`):
23
47
 
24
48
  ```json
25
49
  {
@@ -28,40 +52,49 @@ Add to `~/.claude/config.json` (or the project-local `.claude/mcp.json`):
28
52
  "command": "npx",
29
53
  "args": ["-y", "@dforge-core/dforge-mcp"],
30
54
  "env": {
31
- "DFORGE_CLI_BINARY": "/optional/path/to/dForge.Cli"
55
+ "DFORGE_CLI_BINARY": "/optional/abs/path/to/dForge.Cli"
32
56
  }
33
57
  }
34
58
  }
35
59
  }
36
60
  ```
37
61
 
38
- `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`, or let npx fetch it on demand).
62
+ Restart Claude Code → approve on first prompt.
63
+
64
+ ### Verify it's alive
65
+
66
+ ```bash
67
+ claude mcp list
68
+ # Should show: dforge — npx -y @dforge-core/dforge-mcp — connected
69
+ ```
70
+
71
+ Or inside a Claude Code session, type `/mcp` to see all connected servers + their tools. The 18 `dforge_*` tools should be listed.
39
72
 
40
73
  ### Cursor / Zed
41
74
 
42
- Same shape — both editors take a `command + args` MCP config. Refer to their docs for the exact file path.
75
+ Same `command + args` config shape; check their docs for the file location. Verification is via their respective tool listings.
43
76
 
44
77
  ## What it exposes
45
78
 
46
79
  ### Tools (18)
47
80
 
48
- Grouped by typical phase in the wizard flow. All return-not-write tools emit a `{ summary, files: { '<relPath>': '<contents>' } }` map; the client decides whether to write the files (lets the AI preview diffs with the user before committing).
81
+ 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.
49
82
 
50
83
  **Module-level**
51
84
  | Tool | Behavior |
52
85
  |---|---|
53
- | `dforge_module_create` | New module scaffold — file map for the client to write |
54
- | `dforge_module_inspect` | Read current module state from disk; returns structured summary of entities, views, roles, actions, etc. Call this BEFORE any patch |
86
+ | `dforge_module_create` | New module scaffold |
87
+ | `dforge_module_inspect` | Read current module state. Full structured data is in `files["_inspect.json"]`; `summary` is one-line stats |
55
88
  | `dforge_module_pack` | Shells to `dforge-cli module pack`. Returns tarball path + size |
56
- | `dforge_module_install` | Shells to `dforge-cli module install`. Runs the full server-side validator — the only real validator |
89
+ | `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 |
57
90
 
58
91
  **Entities (Phase 1)**
59
92
  | Tool | Behavior |
60
93
  |---|---|
61
94
  | `dforge_entity_add` | Add an entity to an existing module |
62
- | `dforge_entity_field_add` | Patch a single field onto an existing entity |
95
+ | `dforge_entity_field_add` | Patch a single field |
63
96
  | `dforge_entity_field_modify` | Replace a field's spec |
64
- | `dforge_entity_field_remove` | Drop a field (warns about dependent views / roles / formulas) |
97
+ | `dforge_entity_field_remove` | Drop a field (warns about dependents) |
65
98
 
66
99
  **Behavior (Phase 2 — optional)**
67
100
  | Tool | Behavior |
@@ -73,81 +106,79 @@ Grouped by typical phase in the wizard flow. All return-not-write tools emit a `
73
106
  |---|---|
74
107
  | `dforge_view_add` | Add a data view |
75
108
  | `dforge_view_modify` | Replace a view's spec |
76
- | `dforge_report_add` | Add a report (layout + datasets + parameters) |
77
- | `dforge_setting_add` | Configurable module-level setting (folder-scoped at runtime) |
109
+ | `dforge_report_add` | Add a report |
110
+ | `dforge_setting_add` | Configurable module-level setting |
78
111
 
79
112
  **Security (Phase 5)**
80
113
  | Tool | Behavior |
81
114
  |---|---|
82
- | `dforge_role_add` | Add a role + per-object rights matrix |
83
- | `dforge_role_right_set` | Grant/revoke a single right on a single object (cheap backtrack) |
84
- | `dforge_folder_add` | Add a security folder under root or a parent path (optional — most modules ship with just the root) |
115
+ | `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 |
116
+ | `dforge_role_right_set` | Grant/revoke one right on one object (cheap backtrack) |
117
+ | `dforge_folder_add` | Add a security folder (optional — most modules ship with just root) |
85
118
 
86
119
  **Cross-cutting**
87
120
  | Tool | Behavior |
88
121
  |---|---|
89
- | `dforge_dependency_add` | Add a dep on another dForge module (supports the `{ version, entities }` partial-coupling form) |
90
- | `dforge_dbml_import` | Stub. Returns "not yet implemented" until the underlying CLI command lands |
122
+ | `dforge_dependency_add` | Add a dep on another dForge module |
123
+ | `dforge_dbml_import` | Stub — not implemented yet |
91
124
 
92
125
  ### Resources (13)
93
126
 
94
- Read-only context. Pull these into the conversation at session start; the wizard Skill instructs the AI to consult schemas before emitting files of each kind.
95
-
96
127
  | URI | Content |
97
128
  |---|---|
98
- | `dforge://schema/manifest` | JSON Schema for manifest.json |
99
- | `dforge://schema/entity` | JSON Schema for entity files |
100
- | `dforge://schema/data-views` | JSON Schema for ui/data_views.json |
101
- | `dforge://schema/folders` | JSON Schema for ui/folders.json |
102
- | `dforge://schema/menus` | JSON Schema for ui/menus.json |
103
- | `dforge://schema/roles` | JSON Schema for security/roles.json |
104
- | `dforge://schema/jobs` | JSON Schema for logic/jobs.json |
105
- | `dforge://schema/seed-data` | JSON Schema for seed-data/*.json |
106
- | `dforge://schema/reports` | JSON Schema for ui/reports.json |
107
- | `dforge://schema/settings` | JSON Schema for settings.json |
108
- | `dforge://schema/traits` | JSON Schema for entity trait codes |
109
- | `dforge://schema/webhooks` | JSON Schema for ui/webhooks.json |
110
- | `dforge://docs/conventions` | MODULE_CONVENTIONS.md — naming, FK+Reference pattern, traits, security model |
111
-
112
- Schemas + conventions are vendored at build time from `dForge-core/docs/`. Refresh with `scripts/vendor-resources.sh`. The published npm tarball ships them under `resources/`, and jsdelivr serves them publicly at:
129
+ | `dforge://schema/manifest` | manifest.json JSON Schema |
130
+ | `dforge://schema/entity` | entity files |
131
+ | `dforge://schema/data-views` | ui/data_views.json |
132
+ | `dforge://schema/folders` | ui/folders.json |
133
+ | `dforge://schema/menus` | ui/menus.json |
134
+ | `dforge://schema/roles` | security/roles.json |
135
+ | `dforge://schema/jobs` | logic/jobs.json |
136
+ | `dforge://schema/seed-data` | seed-data/*.json |
137
+ | `dforge://schema/reports` | ui/reports.json |
138
+ | `dforge://schema/settings` | settings.json |
139
+ | `dforge://schema/traits` | entity trait codes |
140
+ | `dforge://schema/webhooks` | ui/webhooks.json |
141
+ | `dforge://docs/conventions` | MODULE_CONVENTIONS.md |
142
+
143
+ 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:
113
144
 
114
145
  ```
115
146
  https://cdn.jsdelivr.net/npm/@dforge-core/dforge-mcp@latest/resources/schemas/<name>.schema.json
116
147
  ```
117
148
 
118
- The dForge VS Code extension bundles them locally (no jsdelivr dependency at runtime).
149
+ **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.
119
150
 
120
151
  ## Claude Skill — the wizard
121
152
 
122
- `skills/dforge-mcp-author/SKILL.md` teaches the AI how to drive the tools as a six-phase wizard:
153
+ `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:
154
+
155
+ ```bash
156
+ # from the published npm tarball
157
+ mkdir -p ~/.claude/skills/dforge-mcp-author
158
+ curl -fsSL https://cdn.jsdelivr.net/npm/@dforge-core/dforge-mcp@latest/skills/dforge-mcp-author/SKILL.md \
159
+ -o ~/.claude/skills/dforge-mcp-author/SKILL.md
160
+
161
+ # or from this repo
162
+ mkdir -p ~/.claude/skills/dforge-mcp-author
163
+ curl -fsSL https://raw.githubusercontent.com/dforge-core/dforge-mcp/main/skills/dforge-mcp-author/SKILL.md \
164
+ -o ~/.claude/skills/dforge-mcp-author/SKILL.md
165
+ ```
166
+
167
+ 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.
168
+
169
+ The phases:
123
170
 
124
171
  | Phase | Required? | Tools used |
125
172
  |---|---|---|
126
- | 0. Intake | yes | (none — captures a brief in `_brief/00-intake.md`) |
127
- | 1. Domain (entities) | yes | `module_create`, `entity_add`, `entity_field_*` |
173
+ | 0. Intake | yes | (brief written manually) |
174
+ | 1. Domain | yes | `module_create`, `entity_add`, `entity_field_*` |
128
175
  | 2. Actions | optional | `action_add` |
129
- | 3. Views + Reports | views yes, reports optional | `view_add`/`_modify`, `report_add`, `setting_add` |
176
+ | 3. Views + Reports | views yes, reports optional | `view_*`, `report_add`, `setting_add` |
130
177
  | 4. Polish (translations, seed) | optional | (file map authored directly) |
131
178
  | 5. Security | roles required, folders optional | `role_add`, `role_right_set`, `folder_add` |
132
179
  | 6. Verify | yes | `module_pack`, `module_install` |
133
180
 
134
- **Key principles encoded in the Skill:**
135
- - **Inspect before patch.** `module_inspect` is the first call in any session that touches an existing module.
136
- - **One thing at a time.** Loop per-entity / per-view / per-role, not batch dumps.
137
- - **Backtrack protocol.** When a later phase exposes a gap from earlier, the AI stops, names the issue, gets user sign-off, patches via the smallest tool that fits, propagates forward.
138
- - **Changelog.** Each backtrack appends to `_brief/changelog.md` so the user has a paper trail.
139
- - **Verify-or-it-didn't-happen.** Phase 6 install is non-skippable — it's the only true validator.
140
-
141
- **To enable the Skill in Claude Code:**
142
-
143
- ```bash
144
- mkdir -p ~/.claude/skills/dforge-mcp-author
145
- curl -fsSL https://raw.githubusercontent.com/dforge-core/dforge-mcp/main/skills/dforge-mcp-author/SKILL.md \
146
- -o ~/.claude/skills/dforge-mcp-author/SKILL.md
147
- # or project-local:
148
- mkdir -p .claude/skills/dforge-mcp-author
149
- cp <repo>/skills/dforge-mcp-author/SKILL.md .claude/skills/dforge-mcp-author/
150
- ```
181
+ 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.
151
182
 
152
183
  ## For maintainers
153
184
 
@@ -157,15 +188,15 @@ cp <repo>/skills/dforge-mcp-author/SKILL.md .claude/skills/dforge-mcp-author/
157
188
  pnpm install
158
189
  pnpm build # tsup → dist/server.js (bundles SDK + zod + dforge-cli/templates)
159
190
  pnpm typecheck # tsc --noEmit
160
- node dist/server.js # smoke-test via stdio JSON-RPC
191
+ node dist/server.js # stdio JSON-RPC — pipe a request to smoke-test
161
192
  ```
162
193
 
163
- To iterate against an in-tree `dforge-cli`, temporarily point the dep at it:
194
+ To iterate against an in-tree `dforge-cli`, temporarily pin the dep at the sibling path:
164
195
 
165
196
  ```bash
166
- sed -i '' 's|"@dforge-core/dforge-cli": "\^0.1.0"|"@dforge-core/dforge-cli": "file:../dforge-cli"|' package.json
197
+ sed -i '' 's|"@dforge-core/dforge-cli": "\^0.1.[0-9.]*"|"@dforge-core/dforge-cli": "file:../dforge-cli"|' package.json
167
198
  rm -rf node_modules pnpm-lock.yaml && pnpm install
168
- # Flip back before publish, otherwise the published package.json is unresolvable for consumers.
199
+ # Flip back before publish — file: deps don't resolve for npm consumers.
169
200
  ```
170
201
 
171
202
  ### Refresh vendored resources
@@ -177,21 +208,27 @@ scripts/vendor-resources.sh # auto-locate ../dForge
177
208
  DFORGE_CORE=/abs/path/to/dForge-core scripts/vendor-resources.sh
178
209
  ```
179
210
 
180
- This refreshes `resources/schemas/` and `resources/docs/`. Republish the npm package to update jsdelivr-served schemas. The VS Code extension vendors them at its own build time, so a separate VS Code repackage is needed for that consumer too.
211
+ Republish to update jsdelivr-served schemas + the bundled resources.
181
212
 
182
- ### Publishing to npm
213
+ ### Publishing
183
214
 
184
215
  ```bash
185
216
  scripts/publish.sh 0.1.0-rc.N --tag latest --otp <code>
186
217
  ```
187
218
 
188
- `prepublishOnly` runs `tsup` so the published tarball gets a fresh `dist/server.js`. No platform binaries to manage — one publish covers everything.
219
+ `prepublishOnly` runs `tsup` so the tarball gets a fresh `dist/server.js`. No platform binaries to manage.
220
+
221
+ **Pre-publish checklist:**
222
+ - [ ] `@dforge-core/dforge-cli` dep is a real version (not `file:...`)
223
+ - [ ] `pnpm typecheck` passes
224
+ - [ ] Smoke test stdio: `tools/list` returns 18 tools
225
+ - [ ] Skill updated for any new/changed tools (it's a SEPARATE artifact; users sync it manually after upgrades)
189
226
 
190
227
  ### Adding a new tool
191
228
 
192
229
  1. Drop it in `src/tools/<name>.ts`. Use shared helpers from `src/tools/_helpers.ts` (`loadManifest`, `readJsonOrDefault`, `jsonText`, `makeResult`, `withTodayStamp`). Return a `ToolResult`.
193
230
  2. Import + register in `src/server.ts` via the `envelope()` wrapper.
194
- 3. Mention it in the wizard `SKILL.md` if it fits a phase.
231
+ 3. Mention it in `skills/dforge-mcp-author/SKILL.md` (which phase, which backtrack scenarios use it).
195
232
  4. Bump `package.json` version, publish.
196
233
 
197
234
  Conventions:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dforge-core/dforge-mcp",
3
- "version": "0.1.0-rc.4",
3
+ "version": "0.1.0-rc.5",
4
4
  "description": "MCP server for dForge module authoring. Exposes scaffold/pack/install tools and schema resources so AI agents (Claude Code, Cursor, Zed) can create and ship dForge modules.",
5
5
  "license": "MIT",
6
6
  "homepage": "https://github.com/iash44/dForge-core",
package/skills/dforge-mcp-author/SKILL.md CHANGED
@@ -13,7 +13,7 @@ The phase column below indicates the **typical** use. During a backtrack, the ba
13
13
 
14
14
  | Tool | Typical phase | What it does |
15
15
  |---|---|---|
16
- | `dforge_module_inspect` | any | Read current module state. **Read-only** — its output does NOT require user confirmation to view; you summarize it and continue. |
16
+ | `dforge_module_inspect` | any | Read current module state. **Read-only** — output does NOT require user confirmation. The one-line `summary` is for the user; the full structured state lives in `files["_inspect.json"]` (entities + their fields, views + their data sources, roles + rights matrix, actions, reports, settings, folders tree). Parse `_inspect.json` before planning patches — don't rely on summary text alone. |
17
17
  | `dforge_module_create` | 1 | Scaffold a new module (returns file map; user writes) |
18
18
  | `dforge_entity_add` | 1 | Add a whole entity to an existing module |
19
19
  | `dforge_entity_field_add` | 1 | Patch one field onto an existing entity |
@@ -121,7 +121,9 @@ When the user has a real business operation: read the DSL reference section of `
121
121
 
122
122
  ### 3a. Default grids (required, do FIRST)
123
123
 
124
- For every entity in the manifest, call `dforge_view_add` with `viewType: "grid"` and `dataSources: [{ entityCode: <entity>, columns: [...] }]`. Use `viewName: "default"` for the first grid per entity — this is **mandatory**; the platform looks for it.
124
+ For every entity in the manifest, call `dforge_view_add` with `viewType: "grid"` and `dataSources: [{ entityCode: <entity>, columns: [...] }]`.
125
+
126
+ **View naming.** View codes in `ui/data_views.json` are semantic — convention is the entity name (`feedback_item`), the plural (`invoices`), or descriptive (`invoices_kanban`, `feedback_by_status`). Do NOT use the literal code `default`. When `ui/folders.json` entities reference `viewName: "default"`, the platform resolves that to the entity's first view declared in `data_views.json` — it's a fallback alias, not a required view code. (The scaffolder already wrote a default grid keyed by entity code in Phase 1, so often you'll `view_modify` it rather than `view_add`.)
125
127
 
126
128
  **Do not propose any specialized view until every entity has its default grid.**
127
129
 
@@ -159,9 +161,10 @@ Add reports only when management aggregation/grouping isn't covered by views. `d
159
161
 
160
162
  ### 5a. Roles + rights matrix (required)
161
163
 
162
- 1. Inventory roles. Default for simple modules: one `<code>.admin` role with full rights on everything. If intake mentioned multiple user groups, propose one role per group.
163
- 2. Show the rights matrix as a table (rows = entities/actions/reports, columns = roles, cells = rights string). Get user sign-off.
164
- 3. Call `dforge_role_add` per role. Use `dforge_role_right_set` for one-off edits.
164
+ 1. **Inspect first.** Run `dforge_module_inspect` and read the `roles` array. The scaffolder pre-creates `<code>.admin` with `SIUDC` on every entity declared at scaffold time. That role exists already — don't try to re-create it.
165
+ 2. Inventory roles. Default for simple modules: the existing `<code>.admin` covers admins; add one role per additional user group from intake (e.g. `<code>.user`, `<code>.viewer`).
166
+ 3. Show the rights matrix as a table (rows = entities/actions/reports, columns = roles, cells = rights string). Get user sign-off.
167
+ 4. **For new roles**: call `dforge_role_add`. **For amending existing roles** (the scaffolded admin, or grants on actions/reports added in Phases 2-3 that aren't yet in any role): call `dforge_role_right_set` per grant — it's the smallest tool and doesn't conflict with the scaffolded admin role. Calling `dforge_role_add` against an existing role code fails — use `role_right_set` to amend instead.
165
168
 
166
169
  **Rights semantics** (additive — multiple roles UNION, never revoke):
167
170
  - Entities: any subset of `SIUDC` (Select / Insert / Update / Delete / Clone)