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

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:

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:

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:

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

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

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