mcp-ai-agent-guidelines

A TypeScript ESM MCP server exposing 19 public instruction tools and 3 utility tools, backed by 72 internal skills across 16 domain families — from requirements discovery and code quality through governance and resilience.

📖 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

Related MCP server: MCP Server TypeScript

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

# IDE hook + skill-file installer
mcp-cli --help

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)

{
  "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

The published package exposes two entrypoints:

• mcp-ai-agent-guidelines — MCP stdio server entrypoint for editors and MCP hosts (the primary surface; an agent reaches all functionality through this)

• mcp-cli — a thin IDE-integration installer. It does not duplicate MCP server functionality; its only purpose is to wire up the hook scripts and per-IDE SKILL.md files that an agent itself cannot install.

# Install SessionStart / PreToolUse hooks for an IDE
mcp-cli hooks setup --client vscode        # or copilot-cli / claude-code
mcp-cli hooks print --client claude-code   # preview without writing

# Emit per-IDE skill files for every public instruction
mcp-cli onboard skills --target all        # copilot + claude + codex
mcp-cli onboard skills --target claude --global   # user-home install

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 — optional orchestration overrides. The MCP server no longer auto-writes this file; defaults come from src/config/orchestration-defaults.ts in memory. Write the file explicitly (via mcp-cli is no longer available — edit by hand, or persist via the model-discover MCP tool's save action) if you need to override the advisory defaults.

• src/config/orchestration-defaults.ts — builtin defaults used in memory whenever a workspace config is absent.

Features

• 19 public instruction tools exposed through the MCP instruction surface

• 3 public utility tools for workspace, model-discovery, and visualization operations (before any HIDDEN_TOOLS filtering)

• 72 internal skills across 16 domain prefixes — see Skill Taxonomy

• 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 exposes 22 tools on the full surface (MCP_FULL_SURFACE=true); the default slim surface exposes only task-bootstrap and meta-routing:

The 72 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:

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

Target-oriented output & the slim surface. The situation-transform that turns a tool's keyword-matched template into a project-specific deliverable applies to 19 of the 20 public tools — the domain tools (code-review, issue-debug, feature-implement, …) plus both slim-surface tools (meta-routing → routing decision, task-bootstrap → orientation brief). analogy-think is the sole passthrough (it already gates to a request-specific metaphor). The hidden domain tools remain callable by name; set MCP_FULL_SURFACE=true to list them for discovery.

| MCP_SERENA_COMMAND | unset | Opt-in. When set, the server spawns Serena as a child MCP server over stdio and resolves Serena queries directly. When unset (default), the server emits structured advisories that the host model executes via its own Serena connection — recommended when the host (e.g. Claude Code) already runs Serena. | | MCP_SERENA_ARGS | unset | Space-separated args passed to MCP_SERENA_COMMAND. Example: --from git+https://github.com/oraios/serena serena-mcp-server. | | MCP_SERENA_CWD | unset | Working directory for the spawned Serena child. Defaults to the parent process cwd. |

Symbol & memory backend (Serena)

Tool responses can be enriched with Serena's LSP-backed symbol surface and per-project memories. Two modes:

• Advisory mode (default) — no setup. Tool responses append a 🧭 Serena enrichment available footer that names the exact Serena tool (mcp__serena__find_symbol, mcp__serena__list_memories, etc.) and arguments the host model should call. Use this when your MCP host already loads Serena as a sibling server (e.g. Claude Code with Serena configured).

• Child-spawn mode (opt-in) — set MCP_SERENA_COMMAND=uvx and MCP_SERENA_ARGS="--from git+https://github.com/oraios/serena serena start-mcp-server --project <your-project-path>". The server spawns Serena once on startup and resolves queries directly, embedding the data in the response footer. Pin --project explicitly because Serena's global registry won't auto-activate a fresh cwd. Use this mode when no host-level Serena is available. Verify the wiring with npm run test:mcp:serena (requires MCP_SERENA_E2E=1 and uvx installed).

Both modes go through the same internal seam (src/serena/client.ts), so tool code paths are identical regardless of mode.

Skill gates

Skill execution is gated by environment variables above. 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"
      }
    ]
  }
}

Manual install: add scripts/hooks/session-start-bootstrap.mjs as a SessionStart hook in ~/.claude/settings.json (or ~/.copilot/hooks/).

Routing guidance

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

• .claude/rules/default.md — universal symptom → tool pipeline table and anti-patterns

• .claude/rules/copilot.md — VS Code Copilot-specific quick reference and session-start checklist

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

Contributing

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

License

MIT © 2025 Anselmoo