mcp-add

name	mcp-add
description	Install an MCP server template from dotforge into a project or global Claude Code config with a single command.

MCP Add

Install a dotforge MCP server template into the current project's or global Claude Code configuration.

Input parsing

From $ARGUMENTS (format: mcp add <server> [--global]):

• Extract <server>: the word after mcp add — one of github, postgres, supabase, redis, slack
• Detect --global flag: if present, target ~/.claude/settings.json; otherwise target .claude/settings.json

Step 0: Validate

1. Verify the server template exists: $DOTFORGE_DIR/mcp/<server>/

   • If directory not found:

     ✗ Unknown server '{{server}}'.
     Available: github, postgres, supabase, redis, slack
     Usage: /forge mcp add <server> [--global]
     

     Stop.

2. Determine target settings path:

   • --global → ~/.claude/settings.json
   • default → .claude/settings.json
   • If target doesn't exist and not --global: warn "No settings.json found. Run /forge bootstrap first, or use --global to install globally." Stop.
   • If target doesn't exist and --global: create ~/.claude/settings.json with {"permissions": {"allow": [], "deny": []}, "mcpServers": {}}.

Step 1: Load template files

Read all three template files:

• $DOTFORGE_DIR/mcp/<server>/config.json
• $DOTFORGE_DIR/mcp/<server>/permissions.json
• $DOTFORGE_DIR/mcp/<server>/rules.md

From config.json:

• Server key: the non-metadata top-level key (e.g., "github", "postgres")
• Server config block: the value of that key (the object with type, command, args, env)
• Install note: the _install string — contains required env vars and instructions
• Ignore all keys starting with _ (metadata)

From permissions.json:

• allow: the allow array value (or [] if absent)
• deny: the deny array value (or [] if absent)
• Ignore all keys starting with _

Step 2: Check for existing configuration

Read the target settings.json.

Check if the server is already configured:

• Present if mcpServers.<server> key exists in settings, OR
• Present if any of the server's allow entries appear in permissions.allow

If already configured:

⚠  {{server}} MCP is already configured in {{target}}.

   Options:
   [u] Update — replace mcpServers.{{server}}, add missing permissions (does not remove existing ones)
   [q] Quit — make no changes

What would you like to do? [u/Q]

• u → continue with update flow (Step 3)
• Q or anything else → stop

Step 3: Show preview

══════════════════════════════════════════
  MCP Add: {{SERVER}} → {{target path}}
══════════════════════════════════════════

mcpServers.{{server}}:
{{pretty-print the server config block, replacing env var values like "${GITHUB_TOKEN}"
with the literal placeholder strings — do not expand env vars}}

New permissions:
  allow (+{{N}} new): {{list entries not already in target settings}}
  deny  (+{{N}} new): {{list entries not already in target settings}}
  (Existing permissions are not modified)

Rules:
  $DOTFORGE_DIR/mcp/{{server}}/rules.md
  → {{rules destination}}

Required environment variables:
  {{_install text from config.json}}

Proceed? [Y/n]

If all permissions are already present, show "Permissions: no changes (already configured)". If no new denies to add, omit that line.

Step 4: Apply changes

Only proceed if user confirms (Y, y, Enter, or "yes").

4a. Merge mcpServers

Read target settings.json as JSON. Set settings["mcpServers"]["{{server}}"] = the server config block. If mcpServers key doesn't exist in settings, create it.

4b. Merge permissions

Allow list:

• For each entry in template allow[]: add to settings.permissions.allow only if not already present
• Never remove or reorder existing entries

Deny list:

• For each entry in template deny[]: add to settings.permissions.deny only if not already present
• Never remove or reorder existing entries

If settings.permissions doesn't exist, create it with {"allow": [], "deny": []}.

4c. Write settings.json

Write the modified settings.json with 2-space indentation. Preserve all other existing keys (hooks, autoMemoryEnabled, env, etc.) exactly as they were.

4d. Copy rules.md

Determine rules destination:

• Project mode: .claude/rules/mcp-{{server}}.md
• Global mode: ~/.claude/rules/mcp-{{server}}.md

Copy $DOTFORGE_DIR/mcp/{{server}}/rules.md to the destination. If the file already exists: overwrite — it's a managed template file. Any project-specific customizations should live in a separate rule file, not in mcp-{{server}}.md.

Create the destination directory if it doesn't exist.

Step 5: Confirm result

✓ {{SERVER}} MCP configured

  Updated files:
    {{target settings.json}} — mcpServers.{{server}} added
    {{rules destination}} — behavior rules copied
    {{"+N permissions" if any were added, else "permissions: no changes"}}

  Next step:
    {{_install text from config.json}}
    Restart Claude Code to activate the MCP server.

If global install: Add: "Installed globally — active in all projects."

If project-only install: Add: "Installed in the current project. For global use: /forge mcp add {{server}} --global"