Agent Guidance Python

Agent Guidance MCP

[](https://www.python.org/) [](https://opensource.org/licenses/MIT) [](https://modelcontextprotocol.io/)

[](https://ko-fi.com/JunMystery)

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 (

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="", query="") — 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](#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, projectcontext, uiux, sessioncontinuity, workflowgate). 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:

1. Builds the skill catalog
2. Passes the priority gate (writes sentinel file)
3. Runs agent-guidance-mcp_task_pipeline for default context
4. 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:/

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 (taskpipeline → guidance → projectcontext → 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](docs/reference/mcp-surface.md).

---

Documentation

• [Getting Started](d

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: JunMystery
• Source: JunMystery/Agent-Guidance-Python
• License: MIT

Install and usage instructions live in the source repository linked above.