Skip to content
mcpgen

Ownership model and regeneration

Every file in a generated project has exactly one owner: mcpgen or user. The manifest at .mcpgen/manifest.json records the owner and the sha256 of each file at generation time. Regeneration uses that manifest to decide per file: create, overwrite, or skip.

The manifest

Section titled “The manifest”
{
  "generator": "mcpgen",
  "version": "1.0.0",
  "files": {
    "cmd/weather/main.go": { "owner": "mcpgen", "sha256": "33ef1732..." },
    "internal/mcpapp/tools/handlers/greet.go": { "owner": "user", "sha256": "9f2c..." }
  }
}
  • mcpgen-owned files carry a // Code generated by mcpgen vX.Y.Z. DO NOT EDIT. header.
  • user-owned files are the handler/prompt/resource implementations and their tests. They carry a // User-owned file: mcpgen never overwrites this file (use --force to replace). header. The only way mcpgen overwrites one is mcpgen add --force.

The decision table

Section titled “The decision table”

On every run (including --dry-run), mcpgen computes a plan with one action and one reason per file. The actions and reason strings below are the exact values from the generator (internal/generator/generator.go), captured from a real --dry-run on an existing project:

Situation Action Reason string
File does not exist create —
mcpgen-owned, hash matches the manifest overwrite —
mcpgen-owned, hash differs (you edited it) skip modified since generation (hash mismatch)
user-owned, file exists skip user-owned file already exists
Exists but is not in the manifest, content identical skip already up to date
Exists but is not in the manifest, content differs skip exists and is not managed by mcpgen
File cannot be read skip unreadable: <error>

Two safety properties follow from this table:

  1. Your code is never clobbered. Untracked files and user-owned files are always skipped.
  2. A skipped mcpgen-owned file keeps its old manifest entry. The baseline hash is not reset, so the next regen still sees your edit and still skips the file.

mcpgen.json and .mcpgen/manifest.json are always rewritten (they are the source of truth and the bookkeeping).

How the decision is made, visually

Section titled “How the decision is made, visually”
For each planned file, on regen:File exists on disk?no → createOwner = user?yes → skip (user-owned file already exists)Tracked in manifest as mcpgen-owned?no → skip (not managed / up to date)sha256 matches manifest entry?yes → overwrite · no → skip (hash mismatch)

Try it

Section titled “Try it”
Terminal window
# Preview the plan without writing anything:
mcpgen new ./weather --force --dry-run --json

The plan.files array lists every file with action, owner, and reason. Edit an mcpgen-owned file (for example internal/mcpapp/instructions.go), re-run the dry run, and watch that file flip to skip with modified since generation (hash mismatch).

Removing a capability

Section titled “Removing a capability”

To remove a tool, prompt, or resource: delete its entry from mcpgen.json, delete its user-owned files first, then regenerate with mcpgen new <dir> --force --no-check. The regen removes the registration and prunes orphaned manifest entries.

Next steps

Section titled “Next steps”