AgentCanon MCP (agentcanon-mcp)

One canonical source of truth for AI coding instructions across OpenAI Codex (AGENTS.md), Cursor (.cursor/rules/*.mdc), Claude Code (CLAUDE.md), and GitHub Copilot (.github/copilot-instructions.md) — with deterministic generation, SHA-256 drift detection, and approval-bound synchronization.

Why AgentCanon MCP?

Modern open-source and enterprise repositories are worked on by contributors using different AI coding agents: OpenAI Codex, Cursor, Claude Code, and GitHub Copilot. Maintaining separate instruction files (AGENTS.md, CLAUDE.md, .cursor/rules/*.mdc, .github/copilot-instructions.md) leads to:

1. Instruction Drift: Rules updated in AGENTS.md are forgotten in .cursor/rules or CLAUDE.md.

2. Silent Overwrites: Naive rule generators blindly overwrite manual tweaks made by developers.

3. Monorepo Complexity: OpenAI Codex supports hierarchical AGENTS.md files per directory, whereas Cursor uses glob-scoped .mdc frontmatter.

AgentCanon MCP solves this by storing typed, validated rules in .agentcanon/rules.yaml and projecting them into each agent's native format through a strict Preview → Approve → Apply transaction.

Related MCP server: mcp-rule-engine

Key Features

• Canonical Rule Model (.agentcanon/rules.yaml): Typed Zod schema with rule IDs, priorities, categories, glob scopes, directory scopes, and target lists.

• First-Class OpenAI Codex Support (AGENTS.md): Generates root AGENTS.md as well as nested directory AGENTS.md files (e.g., packages/api/AGENTS.md) when scope.directory is specified.

• Native Multi-Agent Adapters:

  • OpenAI Codex: AGENTS.md (root & nested directories)

  • Cursor: .cursor/rules/<rule-id>.mdc with YAML frontmatter (description, globs, alwaysApply)

  • Claude Code: CLAUDE.md

  • GitHub Copilot: .github/copilot-instructions.md

• Transactional Safety (Preview → Approve → Apply):

  • Cryptographically unpredictable planId bound to a SHA-256 fingerprint of both .agentcanon/rules.yaml and target files on disk.

  • Detects manual human edits (conflict_modified_by_user) and pre-existing unmanaged files (conflict_unmanaged_exists), refusing silent overwrites.

  • Protects against path traversal (../) and symlink escape attacks.

• CI Drift Check CLI: Run npx agentcanon-mcp --check in GitHub Actions to guarantee all agent instruction files stay synchronized with .agentcanon/rules.yaml.

Quick Start

1. Initialize or Import Existing Instructions in Your Repo

npx agentcanon-mcp --init

If your repository already has an AGENTS.md or CLAUDE.md, AgentCanon imports it into .agentcanon/rules.yaml.

2. Sync Rules via CLI (or via MCP Tools)

# Generate and apply all configured agent files
npx agentcanon-mcp --sync-yes

# Verify zero drift in CI
npx agentcanon-mcp --check

3. Configure as an MCP Server

OpenAI Codex / Claude Code / Cursor MCP Configuration (mcp.json):

{
  "mcpServers": {
    "agentcanon": {
      "command": "npx",
      "args": ["-y", "agentcanon-mcp"]
    }
  }
}

Exposed MCP Tools

Security & Threat Model

• Path Traversal & Symlink Defense: Every target path is verified via assertSafeRelativePath and assertNoSymlinkEscape (fs.lstatSync + fs.realpathSync) to ensure writes never escape the repository root.

• TOCTOU Prevention: apply_sync recomputes the SHA-256 fingerprint of all target files and rejects the plan if any file was modified after preview_sync.

• No Shell Execution: Rule content is treated strictly as untrusted data; AgentCanon MCP never executes shell commands.

Development & Self-Dogfooding

This repository dogfoods agentcanon-mcp to manage its own AGENTS.md, CLAUDE.md, .cursor/rules/*.mdc, and .github/copilot-instructions.md (verified on every push in .github/workflows/ci.yml).

npm install
npm test
npm run build
npm run dogfood
npm run check:drift

License

MIT © touhi13