Agent Guidance MCP

MCP server serving AI agent guidance through a 185-skill catalog, bundled guidance corpus, workflow prompts, bounded project-code context tools, and a token optimization engine — all over Stdio transport.

⚡ Looking for the ultra-fast Rust version (< 1ms startup, ~35MB RAM)? Check out Agent-Guidance-Rust!

Installation

Install the Agent Guidance MCP server and configure all local IDE clients with a single command:

Linux / macOS (Bash):

curl -fsSL https://raw.githubusercontent.com/JunMystery/Agent-Guidance-Python/main/scripts/install.sh | bash

Windows (CMD / PowerShell):

powershell -Command "irm https://raw.githubusercontent.com/JunMystery/Agent-Guidance-Python/main/scripts/install.ps1 | iex"

No prior Python installation required — the script bootstraps uv (a single-binary Python toolchain) automatically.

Verify Installation

Test locally with MCP Inspector:

DANGEROUSLY_OMIT_AUTH=true npx @modelcontextprotocol/inspector .venv/bin/python -m agent_guidance_mcp

Then call agent-guidance-mcp_task_pipeline(...) to load guidance and bounded project context. See Usage Guide for workflows.

Upgrading

Server + IDE registrations: rerun the install command above.

Standards catalog & skills only:

agent-guidance-mcp --update

Executable package only:

uv tool update agent-guidance-mcp

Scheduled Auto-Update

agent-guidance-mcp --auto-update          # weekly (default)
agent-guidance-mcp --auto-update monthly  # monthly

Or via environment variable: AGENT_AUTO_UPDATE_INTERVAL=weekly

Uninstalling

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/JunMystery/Agent-Guidance-MCP/main/scripts/install.sh | bash -s -- --uninstall

Windows:

powershell -Command "irm https://raw.githubusercontent.com/JunMystery/Agent-Guidance-MCP/main/scripts/uninstall.ps1 | iex"

Manual / Developer Install

python -m venv .venv
.venv/bin/pip install -e ".[dev]"      # Linux / macOS
.venv\Scripts\pip install -e ".[dev]"  # Windows

agent-guidance-mcp
.venv/bin/python -m agent_guidance_mcp          # Linux / macOS
.venv\Scripts\python.exe -m agent_guidance_mcp  # Windows

Custom corpus path:

AGENT_GUIDANCE_ROOT=/path/to/Agent-Guidance

Platform notes: Installation · Client Setup

Supported IDEs

Works with any MCP-compatible client. Auto-configured by the installer:

MCP Surface

Tools

Tool	Gate	Role	Key Operations
`agent-guidance-mcp_task_pipeline`	Unlocks	Call first — context prep	Recommendations + tree + search + UI + execution sequence
`agent-guidance-mcp_guidance`	Gated	Standards & skill catalog + workflow/precode/verify/feedback	`list`, `get`, `search`, `recommend`, `reason`, `docs` (Context7), `workflow`, `precode`, `verify`, `feedback`
`agent-guidance-mcp_project_context`	Gated	Project file ops + 3-tier search	`tree`, `search` (FTS5 docs config general), `read`, `symbols`, `references`, `structure`, `callers`, `callees`, `diff`, `snapshot`
`agent-guidance-mcp_ui_ux`	Gated	Design guidance	`search`, `design_system`, `slides`
`agent-guidance-mcp_session_continuity`	Gated	Task state persistence	`save`, `load`, `clear`
`agent-guidance-mcp_workflow_gate`	Gated	Stage enforcement	`status`, `check`, `set_stage`
`agent-guidance-mcp_require_edit_approval`	Not gated	Edit permission gate	`project_path`
`agent-guidance-mcp_usage_report`	Not gated	Usage statistics	`session`, `all`
`agent-guidance-mcp_health_check` / `agent-guidance-mcp_diagnose` / `agent-guidance-mcp_token_stats`	Whitelisted	Operational	Server status, self-diagnostics, token savings

Gated tools return PRIORITY_REQUIRED if called before agent-guidance-mcp_task_pipeline. Whitelisted tools bypass the gate.

Resources

URI	Description
`standards://manifest`	Indexed standards manifest (JSON)
`standards://skill/{name}`	On-demand skill capsule (Markdown)
`standards://document/{identifier}`	Standards document by slug (Markdown)
`standards://version`	Server version info (JSON)
`agent-guidance-mcp://system/priority`	Priority gate instructions — returned by `PRIORITY_REQUIRED` errors
`agent-guidance-mcp://system/gate`	Priority gate status: passed + sentinel present (JSON)
`agent-guidance-mcp://system/edit-allowed`	Edit permission check based on workflow stage (JSON)

Workflow (consolidated into `guidance`)

agent-guidance-mcp_guidance(operation="workflow", identifier="<mode>", query="<subject>") — Load workflow by mode: plan, test, deploy, debug, etc. The previous workflow / workflow_prompt tools were merged into guidance.

For stage lifecycle management (workflow_gate), see the Workflow Stage Enforcement section.

Why Agent Guidance MCP

AI coding agents burn context fast. Every file read, every grep, every web search eats into the context window — and when it's gone, the agent forgets everything. Agent Guidance MCP solves this with four layers:

Layer	What It Does	Your Gain
Priority Enforcement	`agent-guidance-mcp_task_pipeline` must be called before gated tools (guidance, project_context, ui_ux, session_continuity, workflow_gate). Session-start hook auto-passes gate.	Agent always has project context before acting. No more "forgot to call task_pipeline"
Context Budgeting	Caps file reads at 300 lines; smart-truncates source code preserving structure	Agent stays focused on relevant code, never drowns in noise
Guidance Catalog	185 skills + coding standards + security rules served on-demand	Agent follows production patterns without you reminding it
Token Optimization	Strips comments, collapses whitespace, deduplicates output before it hits the LLM	40–80% fewer tokens per MCP response

What You Save

Measured on a typical 500-line React component refactor task:

                    Without MCP          With Agent Guidance MCP
                    ─────────────        ──────────────────────
Tool round-trips    12–18 calls          4–6 calls (task_pipeline consolidates)
Context used        ~45,000 tokens       ~12,000 tokens
File reads          8+ full reads        3 capped reads (300 lines ea.)
Standards lookup    Manual / guessed     Automatic via guidance()
Dead-ends           2–3 wrong searches   Zero (search-first discipline)
Time to first fix   ~4 minutes           ~45 seconds

Token Optimization Pipeline

Every MCP response passes through an 8-stage filter before reaching your agent:

Raw Response
  │
  ├─ Stage 1  ANSI strip          ── removes terminal color codes
  ├─ Stage 2  Regex replace       ── collapses noise patterns
  ├─ Stage 3  Match/short-circuit ── skips empty payloads
  ├─ Stage 4  Line filter         ── keep only relevant output lines
  ├─ Stage 5  Smart truncation    ── preserves imports, signatures, constants
  ├─ Stage 6  Head/tail keep      ── first + last N lines with omission marker
  ├─ Stage 7  Max lines cap       ── absolute ceiling
  └─ Stage 8  Empty guard         ── fallback message if everything filtered
  │
  ▼
Optimized Response (40–80% smaller)

Semantic Skill Search & Local Workspace Skills

Agent Guidance MCP features a hybrid semantic search engine designed to dynamically load relevant skills based on intent and task context.

Pre-computed Embeddings: The 185 global catalog skills have pre-computed embeddings mapped using the lightweight intfloat/multilingual-e5-small model. This ensures instant retrieval on startup.
Workspace-Local Skills: The server automatically scans your project workspace for custom local skills defined in .agents/skills/, .opencode/skills/, or .claude/skills/ directories, dynamically embeds them on startup, and merges them into the search index.
Hybrid Similarity Ranking: agent-guidance-mcp_guidance(operation="search") blends traditional keyword matching with vector cosine similarity calculations to rank skills accurately, even when the task query contains no exact keyword overlaps (e.g., matching "reducing context size" to the context-budget skill).
Zero-Configuration Download: The query embedding model is automatically downloaded on-demand when the server first runs, requiring zero manual setup or configuration.

Priority Enforcement

Agent Guidance MCP ensures that agent-guidance-mcp_task_pipeline is always called before any gated tool, across all agents and IDEs.

Three Enforcement Layers

Session starts
  │
  ├─ Layer 1: Session-start hook
  │    hooks/session-start.sh → agent-guidance-mcp --session-start
  │    → Writes ~/.agent-guidance/.gate_passed sentinel
  │    → Injects project context into conversation
  │
  ├─ Layer 2: Persistent sentinel file
  │    MCP server starts → reads sentinel → gate pre-passed
  │    Bridges hook process and server process
  │
  └─ Layer 3: In-process gate
       task_pipeline → priority_gate_pass() unlocks gate
       Gated tools → priority_gate_check() blocks if not passed

Tool Gate Status

Tool	Gate Behavior
`agent-guidance-mcp_task_pipeline`	Unlocks gate — call first to enable all gated tools
`agent-guidance-mcp_guidance`, `agent-guidance-mcp_project_context`, `agent-guidance-mcp_ui_ux`, `agent-guidance-mcp_session_continuity`, `agent-guidance-mcp_workflow_gate`	Gated — return `PRIORITY_REQUIRED` error if called before `agent-guidance-mcp_task_pipeline`
`agent-guidance-mcp_require_edit_approval`, `agent-guidance-mcp_usage_report`	Not gated — always callable, no priority check
`agent-guidance-mcp_health_check`, `agent-guidance-mcp_diagnose`, `agent-guidance-mcp_token_stats`	Whitelisted — always available, no gate check

Per-Phase Reset Rule

For each new work phase (plan → implement → test → review → refactor), re-call agent-guidance-mcp_task_pipeline with the phase goal. This refreshes skill recommendations, project context, and execution sequence for the new scope. The rule is deployed to all IDEs via AGENTS.md and SKILL.md files.

Session-Start Hook

Every supported CLI agent fires a session-start hook that auto-calls agent-guidance-mcp --session-start --project-path .. This:

Builds the skill catalog
Passes the priority gate (writes sentinel file)
Runs agent-guidance-mcp_task_pipeline for default context
Returns a JSON payload injected into the conversation

The hook tries: installed binary → python -m agent_guidance_mcp → legacy meta-skill fallback.

Tagged Section Deployment

Rule blocks and skill content are wrapped in HTML-comment tags ( / ). The --setup command uses these tags to find and replace sections across all IDE/CLI config files — no stale copies, no manual cleanup.

Workflow Stage Enforcement

Beyond the priority gate, Agent Guidance MCP enforces a 7-stage workflow lifecycle that gates file edits: Context → Plan → Ask_Revise → Build → Test_Recheck → Fix → Proposal

Stage	Edit allowed?	What gates block
`Context`	No	All tools except `task_pipeline`, `workflow_gate`, `session_continuity`
`Plan`	No	`diff` and `architecture` operations on `project_context`
`Ask_Revise`	No	Code reads (`read`, `search`, `symbols`, `references`, `structure`, `callers`, `callees`, `diff`) and `precode`/`verify`
`Build`	✅ Yes (if approved)	All tools blocked if `plan_approved=false`
`Test_Recheck`	No	`precode` operation
`Fix`	✅ Yes	Circuit breaker resets to `Ask_Revise` after 3 failed attempts
`Proposal`	No	`diff`, `structure`, `symbols` operations

Tools for stage management:

Tool/Resource	Purpose
`agent-guidance-mcp_workflow_gate(action="status")`	View current stage, plan approval, fix attempts
`agent-guidance-mcp_workflow_gate(action="check", user_message=...)`	Parse user approval from natural language ("proceed", "ok", "do it")
`agent-guidance-mcp_workflow_gate(action="set_stage", target_stage=...)`	Transition to a new stage (validates rules + circuit breaker)
`agent-guidance-mcp_require_edit_approval(project_path=...)`	Final gate check — returns error unless stage is `Build` + `plan_approved=true`
`agent-guidance-mcp://system/edit-allowed`	Read-only resource for low-friction permission check (JSON)

Circuit breaker: If the agent fails to fix an issue 3 times (3 transitions to Fix), the stage automatically resets to Ask_Revise with plan_approved=false, forcing re-approval before any further edits.

The require_edit_approval tool and agent-guidance-mcp://system/edit-allowed resource together form the edit gate — callable by agents before any write/edit/bash to confirm the workflow stage permits edits.

How It Works In Practice

Scenario: "Add JWT authentication to my Express API"

Step 1 — Agent calls agent-guidance-mcp_task_pipeline (ONE call)

Agent: task_pipeline(task="Add JWT auth to Express API", focus="backend")

Returns in a single response:

Recommendations: 8 relevant skills (api-design, security-review, backend-patterns, express-patterns...)
Project tree: Directory structure of your Express project
Code search: Pre-grepped results for "auth", "jwt", "token", "middleware"
Execution sequence: Skills sorted in lifecycle order (spec → plan → build → test → review)

Step 2 — Agent consults standards

Agent: guidance(operation="search", query="JWT authentication middleware Express")

Returns: security-review skill, api-design patterns, OWASP auth cheatsheet — all pre-loaded, zero web search round-trips.

Step 3 — Agent searches codebase using 3-tier fallback

Agent: project_context(operation="search", query="JWT middleware auth")

Returns ranked results using a three-tier pipeline:

Tier 1: Docs and manifests (README, ARCHITECTURE.md, pyproject.toml) — fast, high-signal
Tier 2: Config, entry points, test dirs (Dockerfile, main.py, src/) — structural context
Tier 3: General code files, capped at 300 — slowest, only reached if tiers 1–2 miss

FTS5 (SQLite full-text index) resolves ~90% of queries instantly, bypassing all three fallback tiers. The 3-tier fallback only fires when FTS5 is empty or the index isn't ready.

Step 4 — Agent implements with live docs

Agent: guidance(operation="docs", query="jsonwebtoken sign options", identifier="node-jsonwebtoken")

Returns: current jsonwebtoken API docs from Context7 — no hallucinated API calls.

Result: Agent writes production-grade JWT middleware in ~3 tool calls instead of 15+, with automatic security review awareness.

Usage Dashboard

Agent Guidance MCP includes a lightweight usage dashboard to visualize tool calls, token savings, skill loads, and embed queries per session.

Start the dashboard

# Standalone dashboard server (no ML model needed, pure stdlib)
agent-guidance-mcp --dashboard
# Dashboard: http://127.0.0.1:<port>/

Automatically tracked data

Data	Tracked via	Shown in dashboard
Tool calls	Every `agent-guidance-mcp_task_pipeline`, `agent-guidance-mcp_guidance`, `agent-guidance-mcp_project_context`, `agent-guidance-mcp_ui_ux`, `agent-guidance-mcp_session_continuity` call	Actions Log view
Token savings	Per-tool origin vs optimized token counts	Token Savings view
Skill loads	`agent-guidance-mcp_guidance(get)`, `standards://skill/{name}` resource	Dashboard view
Embed queries	`agent-guidance-mcp_guidance(search)`, `agent-guidance-mcp_guidance(recommend)`	Embed Status view
Session identity	`AGENT_CLIENT_NAME` env var or `--client-name` flag	Session selector

Dashboard views

View	Content
Dashboard	Session summary cards, top skills list, embed status
Actions Log	Live-updating table of tool calls, polled every 5s
Token Savings	Per-session savings percentage + lifetime orig/opt/saved bars
Embed Status	Model loaded status, active clients (daemon mode), total embed queries
Quick Guides	4-step workflow reference (task_pipeline → guidance → project_context → session_continuity)
MCP Tools	Complete tool reference with gate status and operations

Data is persisted to .agent-context/usage.db in the project directory and survives server restarts.

Environment Variables

Variable	Purpose	Default
`AGENT_GUIDANCE_ROOT`	Custom standards corpus path	Bundled corpus
`AGENT_PROJECT_ROOT`	Override project root for context tools	`.` (cwd)
`AGENT_PROJECT_ALLOWED_ROOTS`	Whitelist directories for security	Project root only (set to expand)
`AGENT_EMBEDDING_DAEMON`	Disable embed daemon (forces in-process model)	`1` (enabled)
`AGENT_WATCHER_ENABLED`	Enable/disable CodeGraph file watcher	`true`
`AGENT_WATCHER_INTERVAL`	Watcher poll interval (seconds)	`30`
`AGENT_WATCHER_DEBOUNCE_MULTIPLIER`	Debounce multiplier after changes	`2.0`
`AGENT_WATCHER_REF_THRESHOLD`	Batch size before full reference resolve	`50`
`AGENT_AUTO_UPDATE_INTERVAL`	Auto-update schedule via env var	`weekly`
`--auto-update` / `--update`	CLI flags for manual update + model download	—
`--session-start`	CLI flag for session-start hook auto-activation	—
`--embed-daemon`	Start embedding daemon as foreground process	—
`--dashboard`	Start usage dashboard server	—
`--re-gate`	Re-pass priority gate for subagent recovery	—
`--no-optimize`	Disable token optimization and savings tracking	—

For full tool documentation, response formats, and examples, see MCP Surface.

Documentation

Getting Started — first-time walkthrough.
Installation — automatic and manual setup.
Usage Guide — recommended agent workflows and examples.
Client Setup — VS Code, Copilot, Cursor, Gemini, OpenCode, Windsurf, Antigravity.
MCP Surface — all tools, prompts, and resources.
Project Context Tools — tree, search, read, snapshot, symbols, references.
Skills Overview — full catalog of 185+ skills.
Integrated Repositories — third-party repos in the codebase.
Multi-IDE Guide — memory usage, SSE mode, recommendations.
Development Guide — tests, project structure, maintainer notes.
MCP Integrations Guide — SQLite caching, CodeGraph, Context7 docs.

Multi-IDE Usage

Each IDE/CLI spawns its own MCP server subprocess, but the embedding model is shared via a local HTTP daemon — one per user, one model load.

VS Code         → MCP process A ──┐
Cursor          → MCP process B ──┼──► embed_daemon (127.0.0.1)
Claude Desktop  → MCP process C ──┘     │
                                    [SentenceTransformer]
                                    intfloat/multilingual-e5-small

Total RAM: ~466 MB for the daemon, regardless of how many IDEs you open.

How it works

Layer	Mechanism
Daemon spawn	First MCP process needing embeddings acquires `~/.agent-guidance/daemon.lock` (fcntl flock on POSIX, msvcrt on Windows) and spawns the daemon subprocess
Service discovery	Daemon writes `~/.agent-guidance/daemon.json` with its port and PID on startup
Client connection	All MCP processes POST to `http://127.0.0.1:<port>/embed` for inference
Health checks	Daemon exposes `GET /health` echoing its PID + `embed_ready` flag; clients probe before reusing a manifest
Client registration	Each MCP process calls `POST /register` with its PID; daemon background-reaps dead clients
Auto-shutdown	Daemon exits after 600s idle or when all clients disconnect (30s grace)

Which tools trigger model load

The daemon is spawned lazily on the first call to any tool that needs embeddings, not only guidance(search):

Tool	Triggers daemon?
`agent-guidance-mcp_task_pipeline`	❌ — uses precomputed `skills_embeddings.json`
`agent-guidance-mcp_guidance(operation="search")`	✅ — first call spawns daemon, subsequent calls reuse
`agent-guidance-mcp_guidance(operation="list\|get\|recommend")`	❌ — catalog only
`agent-guidance-mcp_project_context`	❌ — file ops only
`agent-guidance-mcp_session_continuity`	❌ — state only
`agent-guidance-mcp_health_check / diagnose / token_stats`	❌ — server info

On first call, the daemon loads the model in ~1 second. Subsequent calls are instant HTTP requests to the already-running daemon.

Fallback (daemon unavailable)

If the daemon cannot start (lock contention, AGENT_EMBEDDING_DAEMON=0, or under pytest), each MCP process falls back to a process-local singleton — each loads its own 466 MB model. This is transparent to the caller.

SSE mode (future)

Even with the shared embedding daemon, each MCP process still runs its own stdio server. Adding SSE transport (--transport sse) would allow all IDEs to share a single MCP daemon process. See Multi-IDE Guide for details and current limitations.

Development

python -m pytest

The test suite verifies catalog discovery, MCP handler registration, standards search, recommendation behavior, project-context tooling (18 tests), and priority + workflow gate enforcement (13 tests covering block/pass/reset/thread-safety/sentinel persistence/edit-approval). See Development Guide for more detail.

Name		Name	Last commit message	Last commit date
.agents/skills/agent-guidance		.agents/skills/agent-guidance
.github		.github
agent-guidance		agent-guidance
agents		agents
changelog		changelog
commands		commands
docs		docs
evals		evals
hooks		hooks
karpathy		karpathy
references		references
scripts		scripts
skills		skills
src/agent_guidance_mcp		src/agent_guidance_mcp
tests		tests
.aider.instructions.md		.aider.instructions.md
.clauderules		.clauderules
.clinerules		.clinerules
.codexrules		.codexrules
.copilotrules		.copilotrules
.cursorrules		.cursorrules
.geminirules		.geminirules
.gitattributes		.gitattributes
.gitignore		.gitignore
.roorules		.roorules
.windsurfrules		.windsurfrules
AGENTS.md		AGENTS.md
LICENSE		LICENSE
PROJECT-STANDARDS.md		PROJECT-STANDARDS.md
README.md		README.md
SKILL-REFERENCE.md		SKILL-REFERENCE.md
plugin.json		plugin.json
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Agent Guidance MCP

Installation

Verify Installation

Upgrading

Scheduled Auto-Update

Uninstalling

Manual / Developer Install

Supported IDEs

MCP Surface

Tools

Resources

Workflow (consolidated into guidance)

Why Agent Guidance MCP

What You Save

Token Optimization Pipeline

Semantic Skill Search & Local Workspace Skills

Priority Enforcement

Three Enforcement Layers

Tool Gate Status

Per-Phase Reset Rule

Session-Start Hook

Tagged Section Deployment

Workflow Stage Enforcement

How It Works In Practice

Scenario: "Add JWT authentication to my Express API"

Usage Dashboard

Start the dashboard

Automatically tracked data

Dashboard views

Environment Variables

Documentation

Multi-IDE Usage

How it works

Which tools trigger model load

Fallback (daemon unavailable)

SSE mode (future)

Development

About

Topics

Resources

Stars

Watchers

Forks

Sponsor this project

Packages

Contributors

Languages

Workflow (consolidated into `guidance`)