# Agent Guidance Python

> MCP server providing coding standards, skills, and workflows for AI agents (Claude, Cursor, Cline)

- **Type:** MCP server
- **Install:** `agentstack add mcp-junmystery-agent-guidance-python`
- **Verified:** Pending review
- **Seller:** [JunMystery](https://agentstack.voostack.com/s/junmystery)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [JunMystery](https://github.com/JunMystery)
- **Source:** https://github.com/JunMystery/Agent-Guidance-Python

## Install

```sh
agentstack add mcp-junmystery-agent-guidance-python
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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, 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:

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

```bash
# 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 (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](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](https://github.com/JunMystery)
- **Source:** [JunMystery/Agent-Guidance-Python](https://github.com/JunMystery/Agent-Guidance-Python)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-junmystery-agent-guidance-python
- Seller: https://agentstack.voostack.com/s/junmystery
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.