mcp-ai-agent-guidelines

[!CAUTION] Experimental / Early Stage: This research demonstrator project references third‑party models, tools, pricing, and docs that evolve quickly. Treat outputs as recommendations and verify against official docs and your own benchmarks before production use.

A TypeScript ESM MCP server exposing 20 public instruction tools and 7 utility tools, backed by 102 internal skills across 18 domain families — from requirements discovery and code quality through governance, resilience, and physics-inspired analysis.

📖 Full documentation on GitHub Pages

---

Table of Contents

• Requirements
• Installation
• VS Code Integration (One-Click)
• MCP Server Configuration
• CLI Usage
• Features
• Instruction Workflows
• Skill Taxonomy
• Configuration
• Development
• Environment Variables
• Contributing
• License

---

Requirements

Runtime	Version
Node.js	≥ 22.7.5
npm	≥ 10.0.0

---

Installation

npx (zero-install, recommended for MCP config)

npx -y mcp-ai-agent-guidelines@latest

Global install

npm install -g mcp-ai-agent-guidelines

# MCP stdio server entrypoint
mcp-ai-agent-guidelines

# Interactive CLI
mcp-cli info

Local install (monorepo / project dependency)

npm install mcp-ai-agent-guidelines

---

VS Code Integration (One-Click)

Click a badge below to add this MCP server directly to VS Code (User Settings → mcp.servers):

Or add manually to User Settings JSON:

{
  "mcp": {
    "servers": {
      "ai-agent-guidelines": {
        "command": "npx",
        "args": ["-y", "mcp-ai-agent-guidelines@latest"]
      }
    }
  }
}

Using Docker:

{
  "mcp": {
    "servers": {
      "ai-agent-guidelines": {
        "command": "docker",
        "args": ["run", "--rm", "-i", "ghcr.io/anselmoo/mcp-ai-agent-guidelines:latest"]
      }
    }
  }
}

---

MCP Server Configuration

Add the server to your MCP host config. The entry-point is dist/index.js and communicates over stdin/stdout.

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)

[!IMPORTANT] Claude Desktop spawns the server with a different working directory than your project. Set MCP_WORKSPACE_ROOT to the absolute path of the project you want the server to write state into.

{
  "mcpServers": {
    "ai-agent-guidelines": {
      "command": "npx",
      "args": ["-y", "mcp-ai-agent-guidelines@latest"],
      "env": {
        "MCP_WORKSPACE_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

VS Code (.vscode/mcp.json or user settings)

{
  "servers": {
    "ai-agent-guidelines": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-ai-agent-guidelines@latest"],
      "env": {
        "MCP_WORKSPACE_ROOT": "${workspaceFolder}"
      }
    }
  }
}

From local build

{
  "mcpServers": {
    "ai-agent-guidelines": {
      "command": "node",
      "args": ["/path/to/repo/dist/index.js"]
    }
  }
}

---

CLI Usage

An interactive CLI wizard is included for standalone use outside an MCP host. The published package exposes two entrypoints:

• mcp-ai-agent-guidelines — MCP stdio server entrypoint for editors and MCP hosts
• mcp-cli — interactive CLI for onboarding, orchestration, and diagnostics

# Project onboarding
mcp-cli onboard init

# Re-open the orchestration editor
mcp-cli orchestration edit

# Quick re-entry for environment + model fleet only
mcp-cli orchestration edit --quick

# Direct skill invocation
mcp-cli --skill core-prompt-engineering --request "Write a system prompt for a coding assistant"

Instruction-tool input schema — the public instruction workflows share this shape:

{
  request: string;        // required — the task description
  context?: string;       // optional — background context
  options?: object;       // optional — skill-specific overrides
}

---

Configuration Files

• .mcp-ai-agent-guidelines/config/orchestration.toml — primary orchestration authority (local, not tracked in git)
• src/config/orchestration-defaults.ts — builtin bootstrap defaults used to auto-create the workspace config in advisory mode when orchestration.toml is absent

First-time runs auto-create orchestration.toml from builtin advisory defaults, including semantic role placeholders so routing can proceed before model discovery. Run mcp-cli onboard init to customize the setup or mcp-cli orchestration edit to reopen the interactive editor.

---

Features

• 20 public instruction tools exposed through the MCP instruction surface
• 7 public utility tools for workspace, memory, session, snapshot, orchestration, model-discovery, and visualization operations (before any HIDDEN_TOOLS filtering)
• 102 internal skills across 18 domain prefixes — see Skill Taxonomy
• Physics-inspired analysis: 15 quantum-mechanics (qm-*) + 15 general-relativity (gr-*) skills
• Bio-inspired adaptive routing: ACO, Hebbian, Slime-mould, Quorum, Homeostatic, Clone-Mutate, Replay
• Governance layer: prompt-injection hardening, PII guardrails, policy validation, regulated-workflow design
• Model orchestration guidance: 5 multi-model patterns (parallel critique, draft-review, majority vote, cascade, free triple)
• Zero runtime LLM calls — advisory outputs; wire a concrete executor to enable real LLM dispatch
• xstate v5 state-machine orchestration built-in
• graphology graph routing for topological skill sequencing

---

Public MCP Surface

ListTools currently exposes 27 tools total:

Category	Count	Tools
Instruction (workflow)	17	meta-routing, bootstrap, implement, refactor, debug, testing, design, review, research, orchestrate, adapt, resilience, evaluate, prompt-engineering, plan, document, govern
Instruction (discovery)	3	enterprise, physics-analysis, onboard_project
Utility	7	agent-workspace, agent-memory, agent-session, agent-snapshot, orchestration-config, model-discover, graph-visualize

The 102 skill definitions are internal workflow assets — not individually exposed as MCP tools. See docs for full tool reference.

---

Skill Taxonomy

Skills are organised under 18 domain-specific prefixes:

Prefix	Domain	Count
req-	Requirements Discovery	4
orch-	Orchestration	4
doc-	Documentation	4
qual-	Code Analysis & Quality	5
synth-	Research & Synthesis	4
flow-	Workflow	3
eval-	Evaluation & Benchmarking	5
debug-	Debugging	4
strat-	Strategy & Decision Making	4
arch-	Architecture Design	4
prompt-	Prompting	4
adapt-	Bio-inspired Adaptive Routing	5
bench-	Advanced Evals	3
lead-	Leadership & Enterprise	7
resil-	Resilience & Self-repair	5
gov-	Safety & Governance	7
qm-	Quantum Mechanics metaphors	15
gr-	General Relativity metaphors	15

Physics skills (qm-*, gr-*) require explicit justification before invocation. Route through the physics-analysis instruction first.

Full taxonomy details: docs/architecture/03-skill-graph.md.

---

Instruction Workflows

20 mission-driven instruction workflows orchestrate internal skills into complete task flows:

Instruction	Purpose
meta-routing	Master routing — choose which instruction to invoke
bootstrap	Scope clarification and requirements extraction
implement	Build new features end-to-end
refactor	Improve existing code safely
debug	Diagnose and fix problems
testing	Write, run, and verify tests
design	Architecture and system design
review	Code quality and security review
research	Synthesis, comparison, recommendations
orchestrate	Compose multi-agent workflows
adapt	Bio-inspired adaptive routing
resilience	Self-healing and fault tolerance
evaluate	Benchmark and assess AI quality
prompt-engineering	Build, evaluate, optimise prompts
plan	Strategy, roadmap, sprint planning
document	Generate documentation artifacts
govern	Safety, compliance, guardrails
enterprise	Leadership and enterprise-scale AI strategy
physics-analysis	QM + GR physics-inspired codebase analysis
onboard_project	Session-start project orientation

---

Architecture

See docs/architecture/ for ADRs and full module layout. The entry-point is src/index.ts; instructions live in src/instructions/, skills in src/skills/, and generated tool definitions in src/generated/ (do not edit by hand).

---

Development

# Install dependencies
npm install

# Type-check
npm run type-check

# Build (tsc → dist/)
npm run build

# Watch mode
npm run dev

# Run MCP server
node dist/index.js

Code Quality

npm run check          # biome check (lint + format)
npm run check:fix      # auto-fix
npm run quality        # full suite: verify_matrix + type-check + workflow-docs + biome

Regenerate generated tool definitions after editing canonical registries or workflow specs

python3 scripts/generate-tool-definitions.py
npm run build

Verify skill/instruction coverage matrix (zero orphans required)

python3 scripts/verify_matrix.py

---

Testing

npm test                  # vitest run
npm run test:coverage     # vitest + v8 coverage (80% threshold)

Tests live both co-located with source (src/**/*.test.ts) and in src/tests/.

Published package note: the npm package ships dist/, README.md, and LICENSE. Repository-only source assets such as docs/, .github/, and scripts/ are development references, not package runtime files.

---

Environment Variables

Variable	Default	Description
HIDDEN_TOOLS	""	Comma-separated list of tool names to exclude from ListTools
LOG_LEVEL	"info"	Observability log level (debug, info, warn, error)
ALLOW_GOVERNANCE_SKILLS	unset / "false"	Must be true to allow gov-* skills through criticalSkillGuard
DISABLE_ADAPTIVE_ROUTING	unset / "false"	Set to true to hide routing-adapt and block adapt-* skills; enabled by default (opt-out model)
ALLOW_INTENSIVE_SKILLS	unset / "false"	Must be true to allow resource-intensive skills such as bench-eval-suite, eval-prompt-bench, qm-path-integral-historian, and gr-spacetime-debt-metric
ENABLE_PHYSICS_SKILLS	unset / "false"	Required by input validation when physics skills are not otherwise authorized; physics skills also require conventional-evidence schema validation
MCP_WORKSPACE_ROOT	unset	Absolute path to the project directory the server should write state into (.mcp-ai-agent-guidelines/). Required when using npx via Claude Desktop, Cursor, or Windsurf — these clients do not preserve the terminal's working directory. VS Code supports ${workspaceFolder}.
MCP_SLIM_MODE	unset / "false"	Set to true to expose only the minimal surface: task-bootstrap, meta-routing, and project-onboard (useful for low-context agents)

Skill gates

Skill execution is gated by environment variables above. Physics skills (qm-*, gr-*) additionally require ENABLE_PHYSICS_SKILLS=true and conventional-evidence input. Model availability is derived from .mcp-ai-agent-guidelines/config/orchestration.toml; strict_mode = false allows warnings-only, strict_mode = true blocks on missing models.

---

Auto Mode & Session Hooks

Long-running agent sessions (VS Code Copilot, Claude Code, Copilot CLI) can drift away from MCP tools after the first few exchanges. The session hooks mechanism counteracts this by injecting lightweight reminders at the IDE lifecycle boundaries.

What the hooks do

Hook	Trigger	Effect
SessionStart	New chat session begins	Reminds agent to call task-bootstrap / meta-routing first
PreToolUse	Before every tool call	Detects consecutive non-MCP calls; nudges agent to re-orient

Quick install

# VS Code / Copilot CLI (writes to ~/.copilot/hooks/)
mcp-cli hooks setup --client vscode

# Claude Code (writes to ~/.claude/)
mcp-cli hooks setup --client claude-code

# Inspect what will be written without touching the filesystem
mcp-cli hooks print --client vscode

Manual install

Copy the following JSON to ~/.copilot/hooks/mcp-ai-agent-guidelines-hooks.json:

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "mcp-ai-agent-guidelines hooks remind-session"
      }
    ],
    "PreToolUse": [
      {
        "type": "command",
        "command": "mcp-ai-agent-guidelines hooks remind-drift"
      }
    ]
  }
}

Routing guidance

The .agent/rules/ directory contains IDE-readable routing tables:

• .agent/rules/default.md — universal symptom → tool pipeline table and anti-patterns
• .agent/rules/copilot.md — VS Code Copilot-specific quick reference and session-start checklist

These files are automatically picked up by Copilot's custom instructions system and by Serena's hook integration layer.

[!NOTE] The published npm package does not include .agent/rules/. If you install from npm and want these routing rules, copy them from the GitHub repository into your workspace.

---

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines, code standards, and the skill/instruction development workflow.

---

License

MIT © 2025 Anselmoo