@dforge-core/dforge-mcp

MCP server for dForge module authoring. Exposes 35 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.

Ships with five Claude Skills (skills/): a router plus one skill per lifecycle stage — design (Phase 0), build (Phases 1-5), and ship (Phase 6) — and dforge-1c-import for porting a 1C infobase, with its Python toolkit. The router directory carries 25 reference files (field types, flags, traits, formulas, DSL, security, etc.) and two annotated example modules.

New here? Start with 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).

The server also bundles @dforge-core/metadata — the canonical, dependency-free registry of field types, traits, column types, and the JSON schemas (the same package the dForge app, SDK, and VS Code extension use). It's the source of truth for the authoring-time validation below (valid fieldTypeCd / columnType / trait codes, dbDatatype derivation) and for the vendored schemas. Bundled at build time, so there's nothing extra to install.

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:

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.

For AI-assisted module repair, Phase 6 is intentionally tool-driven: the skill runs dforge_module_validate, dforge_module_pack, and dforge_module_install itself. If install fails because the module is invalid, the install tool returns the raw CLI/server output plus exitCode and command; the AI reads that output, fixes the referenced module files, and repeats validate → pack → install. User action is needed only for environment failures such as missing CLI, missing/expired credentials, an unreachable tenant/API, permissions, or an invalid path.

Install + wire into Claude Code

Recommended — via claude mcp add (writes ~/.claude.json for you)

claude mcp add dforge --scope user -- npx -y @dforge-core/dforge-mcp

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.

Manual — per-project

Write .mcp.json at the repo root (not under .claude/):

{
  "mcpServers": {
    "dforge": {
      "command": "npx",
      "args": ["-y", "@dforge-core/dforge-mcp"],
      "env": {
        "DFORGE_CLI_BINARY": "/optional/abs/path/to/dForge.Cli"
      }
    }
  }
}

Restart Claude Code → approve on first prompt.

Verify it's alive

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 35 dforge_* tools should be listed.

Cursor / Zed

Same command + args config shape; check their docs for the file location. Verification is via their respective tool listings.

What it exposes

Tools (34)

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.

Phase 0 (identity → requirements → design → validation) is orchestrated by the dforge_module_plan tool together with the dforge-mcp-author skill: the tool tracks progress from the on-disk docs/ artifacts and gates scaffolding, while the AI authors those artifacts under its direction.

Module-level

Entities (Phase 1)

Composite entity tools (Phase 1) — one call per concept, prefer these

Each of these spans several coordinated keys that hand-assembly gets wrong. They exist so the broken shapes aren't expressible.

The field/entity tools validate against the @dforge-core/metadata registry: an unknown fieldTypeCd (e.g. integer, reference), columnType, or trait code is rejected at authoring time with a "did you mean" hint, and dbDatatype is auto-derived from the field type (currency → numeric(18,2), text → varchar; reference/formula columns get none) unless you set it explicitly.

Behavior (Phase 2 — optional)

Views, menus + reports (Phase 3)

Polish (Phase 4)

Security (Phase 5)

Cross-cutting

Writing files: preview vs apply

Every patch tool returns { summary, files, deletes? } for the client to write, so the agent can preview a diff with the user first. Passing apply: true instead writes the files (and honours deletes) directly and returns only the paths touched.

// preview (default) — full file contents come back through the model's context
{ "moduleDir": "/path/to/mod", "entityName": "order", "fieldName": "note", "field": { ... } }

// apply — writes to disk, returns { applied: true, written: [...], deleted: [...] }
{ "moduleDir": "/path/to/mod", "entityName": "order", "fieldName": "note", "field": { ... }, "apply": true }

Use apply for routine patches inside an already-approved plan, and for every rename/delete refactor — it guarantees the deletes half is applied, which is easy to drop by hand. It refuses to write outside moduleDir, and never writes the _inspect.json / _validate.json / _action_check.json report payloads, which only reuse the file-map shape for transport.

Resources

Served over MCP with descriptions and mime types, so the agent can tell what a URI is for before pulling it.

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:

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 Skills — router + three stage skills

Authoring guidance ships as four skills, split by lifecycle stage. Each stage needs a different half of the knowledge base — Phase 0 needs none of the field-type/DSL detail, Phase 6 needs none of the intake guardrails — so loading only the active stage is what keeps a full module build inside one context window.

The handoff is deterministic rather than vibes-based: dforge_module_plan({ action: "check" }) returns currentPhase and nextSkill, derived from the Phase 0 artifacts, the phase ledger in docs/phase.json, and evidence read from the module itself (entities without fields, entities without a view, entities without a Select grant).

The router directory also holds the shared assets:

Skills are NOT auto-installed by npm install — they ship in the npm tarball, but Claude Code looks in ~/.claude/skills/, not node_modules. Use the installer, which is a Node script so it behaves identically on Windows (cmd.exe / PowerShell), macOS, Linux, Git Bash and WSL:

# Straight from the published package — no clone needed:
npx -y -p @dforge-core/dforge-mcp dforge-install-skills

# From a local checkout:
npm run install-skills

# Equivalently, without npm:
node scripts/install-skills.mjs [--from-npm]

Destination resolution, in order: DEST → CLAUDE_CONFIG_DIR/skills → <home>/.claude/skills. The home directory comes from Node's os.homedir(), so on Windows it's %USERPROFILE% no matter which shell invoked it.

DEST=/path/to/skills npm run install-skills

It replaces each skill directory wholesale — a stale reference file left behind is worse than a missing one, because the agent will happily author against it.

Re-run after every dforge-mcp upgrade. The skill version isn't checked at runtime, so stale skills against new tools will misroute calls.

Note on CLAUDE.md: Every module gets a CLAUDE.md in its root, authored during Phase 0a (the AI drafts it; you write it) and kept current as later phases complete. It tells Claude Code that the directory is a dForge module, points at the skills, describes the module layout, and carries a live Module status tracker so future sessions resume accurately.

The phases:

Key principles encoded in the skills: inspect-before-patch, one-at-a-time, composite-tools-first, deterministic backtrack on the earliest-phase-first rule, a tool-failure protocol that distinguishes auth/connectivity from module defects, and user-driven end-of-session cleanup.

For maintainers

Local development

pnpm install
pnpm build          # tsup → dist/server.js (bundles SDK + zod + dforge-cli/templates + metadata)
pnpm typecheck      # tsc --noEmit
pnpm test           # vitest — validation + dbDatatype derivation + trait flow
node dist/server.js # stdio JSON-RPC — pipe a request to smoke-test

To iterate against an in-tree dforge-cli, temporarily pin the dep at the sibling path:

sed -i '' 's|"@dforge-core/dforge-cli": "\^0.2.[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

Schemas (resources/schemas/) are copied from the installed @dforge-core/metadata package — bumping that dep is how you pick up schema changes. They're served as MCP resources via dforge://schema/* and, in the published tarball, via jsdelivr.

pnpm sync-schemas      # node script — cross-platform (Windows/macOS/Linux)

You rarely run this by hand: prepublishOnly runs it automatically, so every publish regenerates the schemas from the exact metadata version this package depends on — they can't silently drift. The schemas are committed, so consumers always have them regardless.

scripts/vendor-resources.sh is a Unix convenience wrapper around the same Node script, and it additionally can pull the conventions doc + skill reference files from dForge-core — but only when VENDOR_REFS=1:

VENDOR_REFS=1 scripts/vendor-resources.sh   # also pull conventions + skill refs from ../dForge-core

That ref pull is off by default on purpose: the per-topic references under skills/dforge-mcp-author/references/ are authored in this repo and are ahead of dForge-core/skills/dforge-module-author/, so an unguarded pull would clobber them. Only set VENDOR_REFS=1 once you've confirmed core is the source of truth for those files. (This part is bash-only; on Windows use WSL/Git Bash for the ref pull — schema refresh via pnpm sync-schemas is native.)

Publishing

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
• pnpm test passes
• Smoke test stdio: tools/list returns 27 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.