@cg3/equip

Universal MCP server + behavioral rules installer for AI coding agents.

Equip handles the hard part of distributing your MCP tool: detecting which AI coding platforms are installed, writing the correct config format for each one, and managing versioned behavioral rules — all with zero dependencies.

Supported Platforms

Equip supports 11 platforms across two tiers, depending on whether the platform has a writable location for behavioral rules.

Full Support — MCP + Behavioral Rules

These platforms get both MCP server config and auto-installed behavioral rules. Rules teach agents when to use your tool (e.g., "search before debugging") and are versioned for idempotent updates.

| Platform | MCP Config | Rules | |---|---|---| | Claude Code | ~/.claude.json (JSON, mcpServers) | ~/.claude/CLAUDE.md (append) | | Windsurf | ~/.codeium/windsurf/mcp_config.json (JSON, mcpServers) | global_rules.md (append) | | Cline | globalStorage/.../cline_mcp_settings.json (JSON, mcpServers) | ~/Documents/Cline/Rules/ (standalone file) | | Roo Code | globalStorage/.../cline_mcp_settings.json (JSON, mcpServers) | ~/.roo/rules/ (standalone file) | | Codex | ~/.codex/config.toml (TOML, mcp_servers) | ~/.codex/AGENTS.md (append) | | Gemini CLI | ~/.gemini/settings.json (JSON, mcpServers, httpUrl) | ~/.gemini/GEMINI.md (append) |

MCP Only — No Writable Rules Path

These platforms get MCP server config but don't have a writable global rules file (rulesPath: null). The MCP tools work fine — but equip can't auto-install behavioral rules.

| Platform | MCP Config | |---|---| | Cursor | ~/.cursor/mcp.json (JSON, mcpServers) | | VS Code | Code/User/mcp.json (JSON, servers, type: "http") | | Junie (JetBrains) | ~/.junie/mcp/mcp.json (JSON, mcpServers) | | Copilot (JetBrains) | ~/.config/github-copilot/intellij/mcp.json (JSON, mcpServers) | | Copilot CLI | ~/.copilot/mcp-config.json (JSON, mcpServers) |

For these platforms, installRules() returns { action: "clipboard" } if the platform is in the configurable clipboardPlatforms list (default: ["cursor", "vscode"]), or { action: "skipped" } otherwise. It's up to the consumer to decide how to handle this — e.g., copying rules to the clipboard, printing instructions, or skipping silently.

Hooks — Structural Enforcement

Some platforms support lifecycle hooks — scripts that run automatically at key moments (e.g., after a tool fails, when the agent finishes responding). Hooks provide structural enforcement that behavioral rules alone cannot:

| Platform | Hooks Support | Events | |---|---|---| | Claude Code | ✅ | PostToolUseFailure, Stop, PreToolUse, PostToolUse | | All others | ❌ | — |

When hooks are supported, equip installs lightweight Node.js scripts to ~/.prior/hooks/ and registers them in the platform's settings. Hooks are a silent enhancement — if the platform doesn't support them, equip installs only MCP + rules without any error or warning.

Hooks are opt-in per platform via the capabilities model. As more platforms add hook support, equip can enable them without consumer code changes.

Quick Start

npx @cg3/equip prior

That's it. Detects your platforms, authenticates, installs MCP + rules, and verifies — all in one command. Pass --dry-run to preview without writing files.

CLI Usage

You can invoke any npm package that has an equip-based setup command:

# Full package name + command
npx @cg3/equip @cg3/prior-node setup

# Shorthand (if registered)
npx @cg3/equip prior

The CLI runs npx -y <package>@latest <command> with any extra args forwarded (e.g. --dry-run, --platform codex).

Shorthand Registry

Registered shorthands save typing. Open a PR to bin/equip.js to add yours:

| Shorthand | Expands to | |---|---| | prior | @cg3/prior-node setup |

Programmatic Usage

const { Equip } = require("@cg3/equip");

const equip = new Equip({
  name: "my-tool",
  serverUrl: "https://mcp.example.com",
  rules: {
    content: `<!-- my-tool:v1.0.0 -->\n## My Tool\nAlways check My Tool first.\n<!-- /my-tool -->`,
    version: "1.0.0",
    marker: "my-tool",
    fileName: "my-tool.md",  // For platforms with rules directories
  },
});

// Detect installed platforms
const platforms = equip.detect();

// Install MCP + rules on all detected platforms
for (const p of platforms) {
  equip.installMcp(p, "api_key_here");
  equip.installRules(p);
}

// Uninstall
for (const p of platforms) {
  equip.uninstallMcp(p);
  equip.uninstallRules(p);
}

API

new Equip(config)

• config.name — Server name in MCP configs (required)
• config.serverUrl — Remote MCP server URL (required unless stdio provided)
• config.rules — Behavioral rules config (optional)
  • content — Markdown content with version markers
  • version — Version string for idempotency tracking
  • marker — Marker name used in <!-- marker:vX.X --> comments
  • fileName — Standalone filename for directory-based platforms
  • clipboardPlatforms — Platform IDs that use clipboard (default: ["cursor", "vscode"])
• config.stdio — Stdio transport config (optional, alternative to HTTP)
  • command, args, envKey

Instance Methods

• equip.detect() — Returns array of detected platform objects
• equip.installMcp(platform, apiKey, options?) — Install MCP config
• equip.uninstallMcp(platform, dryRun?) — Remove MCP config
• equip.updateMcpKey(platform, apiKey, transport?) — Update API key
• equip.installRules(platform, options?) — Install behavioral rules
• equip.uninstallRules(platform, dryRun?) — Remove behavioral rules
• equip.readMcp(platform) — Check if MCP is configured
• equip.buildConfig(platformId, apiKey, transport?) — Build MCP config object
• equip.installHooks(platform, options?) — Install lifecycle hooks (if supported)
• equip.uninstallHooks(platform, options?) — Remove hooks
• equip.hasHooks(platform, options?) — Check if hooks are installed
• equip.supportsHooks(platform) — Check if platform supports hooks

Primitives

All internal functions are also exported for advanced usage:

const { detectPlatforms, installMcpJson, installRules, createManualPlatform, platformName, cli } = require("@cg3/equip");

Key Features

• Zero dependencies — Pure Node.js, works with Node 18+
• 11 platforms — Covers ~80% of active AI coding tool users
• Platform-aware — Handles each platform's config quirks (JSON vs TOML, root keys, URL fields, type requirements)
• Non-destructive — Merges into existing configs, creates backups, preserves other servers
• Versioned rules — Marker-based blocks enable idempotent updates without clobbering user content
• Dry-run support — Preview changes without writing files
• CLI helpers — Colored output, prompts, clipboard utilities included

Limitations — Why Rules Matter (and Why They're Not Enough)

MCP tool descriptions alone don't reliably trigger agent behavior. Research on 856 MCP tools found that 97.1% of tool descriptions contain quality issues, and even fully optimized descriptions only improve task success by ~6 percentage points.

Behavioral rules (the .md files equip installs) are stronger — they live in the agent's system prompt or project context, closer to how agents make decisions. But they have limits too:

• Context window compaction can drop rules from the agent's working memory during long sessions
• No platform hooks exist to enforce tool calls — the agent always decides whether to act
• No open standard for server-initiated actions (MCP sampling exists in spec but isn't widely implemented)

Equip gives you the best available distribution: MCP config for tool availability + behavioral rules for usage guidance + lifecycle hooks for structural enforcement on platforms that support them. Hooks bridge the gap between "the agent knows the rules" and "the agent actually follows them" by injecting reminders at the exact moment an error occurs.

License

MIT — CG3 LLC