🦀 Agent Guidance MCP Server

Agent Guidance is a native, high-performance MCP (Model Context Protocol) Server & Autonomous Orchestrator written in Rust. It supervises AI Coding Agents (Antigravity, Claude Code, Cursor, Windsurf, Devin, OpenCode) to enforce enterprise architecture patterns, isolate multi-IDE session states, prevent context window blowups via token compression, and deliver sub-millisecond Smart Skills Calls via local ML vector search.

---

🚀 Quickstart & Installation

Automatic One-Line Install (Recommended)

Run the one-liner setup script for your operating system to download the latest release binary, pre-cache local ML models, and auto-register agent-guidance across all detected IDE clients:

Windows (PowerShell / CMD):

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

Linux / macOS:

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

Manual Build via Cargo

git clone https://github.com/JunMystery/Agent-Guidance-Rust.git
cd Agent-Guidance-Rust
cargo build --release
./target/release/agent-guidance --setup

---

🛠️ MCP Tool Suite Reference

Agent Guidance exposes 6 high-efficiency MCP tools designed to minimize agent round-trips and token waste:

---

🎯 Key Capabilities

1. Hierarchical Codebase GraphRAG (Global, Local, DRIFT Search)

• Leiden Hierarchical Community Clustering: Partitions codebase symbols and AST relationships into Level 0 (Macro Subsystems), Level 1 (Feature Modules), and Level 2 (Micro Clusters).
• The 4 Query Modes:
  • Global Search: High-level reasoning across community summaries.
  • Local Search: Targeted symbol search with 1-hop & 2-hop DAG call/import fan-out.
  • DRIFT Search: Dual-route combining macro community layer context with micro AST signatures.
  • Basic Search: Fast HNSW vector and FTS5 fallback.
• Continuous Reactive Watcher: Background file watcher automatically updates AST nodes and re-clusters community summaries upon code modifications.

2. Autonomous Single-Entrypoint Orchestration

• Governs the complete AI agent lifecycle through task_pipeline. The MCP server inspects the workspace, unlocks priority gates, selects skills, and dynamically directs next steps.
• Enforces enterprise architecture styles (Clean Architecture, Layered Architecture, Package-by-Feature, CLI Pipeline, Flat Library, Orchestrator) with cross-session persistence in .agent-context/architecture.json.

3. High-Speed 6-Phase Search Cascade (<100ms)

• Replaces slow raw disk scans with an instant multi-tier cascade stored in <project_root>/.agent-context/code_graph.db:
  1. Phase 1: Alias Cache (<1ms): Instant lookup for learned natural language queries.
  2. Phase 2: Symbol FTS5 (<5ms): SQLite FTS5 index on all functions, structs, enums, classes, and traits.
  3. Phase 3: Symbol Vectors (<50ms): BERT semantic similarity on symbol signatures.
  4. Phase 4: Content FTS5 (<5ms): Full-text search across 50-line code chunks.
  5. Phase 5: RAG Content Vectors (<100ms): Multilingual-E5 semantic search on actual code chunks.
  6. Phase 6: Linked Projects (<120ms): Cross-workspace semantic and symbol search across linked repositories.
• Adaptive Alias Learning: Automatically learns successful queries, increasing confidence with reuse and decaying inactive mappings (50% reduction after 30 days, purged after 90 days).
• Proactive Background File Watcher: Uses OS-level file monitoring (notify) with a 5s debounce to incrementally update AST symbols, DAG edges, and RAG chunks before the agent even issues a query.

4. Hardened 300 LOC Cap & Upfront Decomposition

• Physically clamps file reads at 300 lines max and automatically injects architectural decomposition mandates on large files.
• Generates concrete Upfront Split Blueprints per pattern during pre-code guidance.

5. Universal In-Engine Token Compression

• Automatically intercepts and compresses all outgoing MCP tool responses, stripping HTML comments, badges, and redundant whitespace.
• Reduces context payload size by 30–50% while logging real-time token savings to SQLite (~/.agent-guidance/usage.db).

6. Multi-Session & Multi-IDE Isolation

• Assigns process-isolated Session IDs (session_{PID}_{ClientName}) to eliminate state collisions across concurrent IDEs (VS Code, Cursor, Antigravity) or CLI tools in the same codebase.

7. Real-Time Web Dashboard & Visual GraphRAG

• Interactive Multi-Mode Architecture Graph: Real-time canvas visualizer with 3 distinct inspection modes:
  • Mode 1 (File Dependencies): Inter-file dependency graphs (1-N & N-1), interactive Subgraph Isolation, and Directory & File Container Navigator (#graph-symbol-list-container).
  • Mode 2 (File Functions Drill-Down): Caller/callee function call paths with directed color-coded arrows, searchable file combobox, and global 'Show all' codebase call maps.
  • Mode 3 (Symbol Graph): Full AST symbol graph with ForceAtlas2 physics simulation, contrast halos, and Leiden community clusters.
• Calibrated 10% Dim Capacity: Unselected nodes and edges gracefully dim to 10% opacity (0.10) for focused architecture inspection.
• Deep Symbol & Blast Radius Inspector: Click any node or search by name to inspect callers, dependencies, architectural tiers, and blast radius risk scores.
• Parallel Symbol & Function Navigator: Search and navigate across all project files and functions simultaneously with instantaneous filtering.
• Token Savings & Velocity Dynamics: Interactive telemetry charts tracking original vs. compressed payload waves, peak velocity, and execution traces.
• Bilingual Interface (i18n): Full native parity for English (en) and Vietnamese (vi) with instant dynamic switching and persistent preferences.
• Zero-Friction Singleton Daemon: Runs quietly in the background, serving all concurrent IDE instances, and automatically shuts down immediately once the last IDE window closes.

8. Deep Graph Federation & Multi-Workspace Monorepos

• Automated Workspace Discovery: Scans Cargo workspace members ([workspace] members), npm/pnpm/yarn workspaces, and Go work roots to seamlessly bind virtual monorepos into a single unified knowledge graph.
• Cross-Repo Call Graph Traversal: Discovers callers and callees spanning across linked repository boundaries (project_context(operation="callers" | "callees")), tagged with clear repository namespaces ([repo:lib-name]).

9. Continuous Learning Graph & Evolutionary Co-Change Alerts

• Pairwise Co-Change Tracking: Automatically records co-edited file pairs into SQLite co_change_edges on session persistence (session_continuity(operation="save")).
• Predictive Forgotten File Sentinel: Evaluates historical co-change coupling ($\ge 60%$) during edit authorization (workflow_gate(action="authorize_edit")), warning agents when tightly coupled code files or test suites are accidentally overlooked.

10. Architecture Healing Sentinel (Cycles & Dead Code)

• Circular Dependency Detection: Directed DFS engine detects dependency loops between modules with rotational deduplication.
• Dead & Orphan Symbol Scanning: Isolates unused internal symbols with zero callers and zero callees directly within project_context(operation="architecture").

11. Distributed Graph Memory & Verified Snapshots

• Portable Snapshot Archival: Export and import verified GraphRAG database snapshots (.agpack) with SQLite WAL checkpointing, streaming SHA256 checksums, and pre-installation PRAGMA quick_check validation.
• Zero-Latency Team Onboarding: Distribute pre-indexed code graphs across CI/CD runners or distributed multi-agent clusters without redundant 50,000 LOC AST parsing.

---

🏗️ Architectural Workflow

The 7-Stage Workflow Gate

Context $\longrightarrow$ Plan $\longrightarrow$ Ask_Revise $\longrightarrow$ Build $\longrightarrow$ Test_Recheck $\longrightarrow$ Fix $\longrightarrow$ Proposal

• Composite Gate Action (workflow_gate action="advance"): Performs stage check, transition, and architecture pattern authorization in a single composite MCP call.
• Hard Edit Gate (workflow_gate action="authorize_edit"): Code modification is BLOCKED until plan_approved = true and a valid architecture_pattern is verified.
• Circuit Breaker: If 3 consecutive fix attempts fail during Fix, the MCP server automatically trips, resets stage to Ask_Revise, and requests human intervention.

---

🧠 Smart Skills System

The built-in ML catalog engine leverages local Rust bindings for Hugging Face candle to perform sub-millisecond semantic skill discovery:

• Stage 1 (Cosine Similarity): Scans 279 embedded skills (440 precomputed vector embeddings) using Candle BERT vector embeddings with precomputed binary vector acceleration ($<5\text{ ms}$).
• Stage 2 (Intent Reranking): Cross-encoder (ms-marco-MiniLM-L-6-v2) reranks top candidates with language profile boosting.
• On-Demand Loading: Skills are injected dynamically into context via select_skills(skills=[...]) only when confirmed.

Custom Skill Sets (User Extensibility)

You can easily add your own custom skills without rebuilding or reconfiguring the MCP server:

• Global Custom Skills: Simply copy or paste your skill directories/markdown files directly into:
  • ~/.agent-guidance/skills/ (or ~/.agents/skills/)
• Workspace-Specific Skills: Place custom skills directly in your active project repository under:
  • <project_root>/.agents/skills/
  • <project_root>/.opencode/skills/
  • <project_root>/.claude/skills/

All .md files in these directories are automatically scanned, parsed for YAML frontmatter (name: ...), and indexed into the local search catalog on the fly.

---

⚡ Universal Token Optimization

• Hard Clamping: Capped at 300 LOC per file read, 20 results per search, 30 references per symbol search, and 15 items per tree preview.
• Symbol-Targeted Extraction: Extract exact function/struct blocks using project_context(operation="read", target_symbol="...") saving up to 85% of tokens.
• Dynamic Compression: Automatic stripping of markdown comments, badges, and empty lines across all responses.
• SQLite Analytics: All tool metrics, durations, and token savings are logged to ~/.agent-guidance/usage.db.

---

🔒 Multi-Session Isolation

When running multiple AI agents across different IDEs or terminals simultaneously in the same repository, Agent Guidance maintains total isolation:

.agent-context/
├── architecture.json                    (Persistent Architecture Memory)
├── sessions/
│   ├── session_14820_antigravity.json   (Build Stage - Plan Approved)
│   ├── session_29401_cursor.json        (Plan Stage - Awaiting Approval)
│   └── session_8812_cli.json            (Context Stage)
└── session.json                         (Legacy Atomic Pointer)

• Automated GC Policy: On startup and session load, stale session files older than 30 days are automatically purged. If total session files exceed 100, the oldest files are pruned.

---

💻 CLI Commands & Maintenance

agent-guidance provides built-in CLI commands for managing IDE clients, updates, and metrics:

agent-guidance [OPTIONS]

Options:
  --setup                  Install and configure MCP server across all IDE clients
  --verify-setup           Verify MCP configuration paths in all IDE clients
  --upgrade                Download and install latest release package, update IDE configs
  --self-update            Alias for --upgrade
  --daemon, -d             Force start in background singleton daemon mode
  --proxy                  Force connect as client proxy to daemon; exit if no daemon
  --dashboard              Start real-time web usage dashboard at http://127.0.0.1:11997
  --port, -p <PORT>        Custom dashboard port (default: 11997, alias: --dashboard-port)
  --project <PATH>         Filter dashboard to a specific project path or name
  --prune-missing          Prune non-existent projects from usage tracking registry
  --cleanup                Auto-clean expired logs, prune dead projects, and vacuum SQLite DB
  --retention-days <N>     Retention window in days for detail logs (default: 7)
  --reindex-skills         Precompute and build rich semantic vector index for all skills
  --uninstall              Remove MCP server configurations from all IDE clients
  --help, -h               Print help message

---

📂 Project Structure

Agent-Guidance-Rust/
├── src/
│   ├── main.rs                   # CLI entrypoint, argument parsing, stdio MCP dispatcher
│   ├── catalog/                  # Built-in and custom skills scanner, indexer, YAML parser
│   ├── context/                  # Codebase indexing, AST parsing, GraphRAG, 5-phase cascade search
│   │   ├── graph_rag/            # Hierarchical Leiden community clustering, DRIFT/Local/Global search
│   │   ├── indexer/              # Tree-sitter AST symbol and reference extraction
│   │   ├── scanner/              # File walker, gitignore resolution, change detection
│   │   └── watcher/              # Real-time background filesystem watcher
│   ├── daemon/                   # Zero-friction singleton daemon, IPC named pipe/socket, client lifecycle
│   ├── dashboard/                # Embedded tiny_http web server, REST endpoints, SQLite telemetry queries
│   ├── dashboard_src/            # Frontend SPA (Vanilla JS + CSS, zero runtime npm dependencies)
│   │   ├── index.html            # Dashboard layout and accessible view containers
│   │   ├── js/i18n/              # Modular bilingual dictionaries (EN/VI: core, telemetry, graph)
│   │   └── js/render/            # Canvas graph visualizer, ForceAtlas2 layout engine, symbol inspector
│   ├── mcp/                      # Model Context Protocol implementation & tool execution handlers
│   │   ├── tools/                # task_pipeline, select_skills, workflow_gate, project_context, guidance
│   │   ├── state/                # Multi-session state machine, priority gate, checkpointing
│   │   └── db/                   # SQLite database operations, automatic cleanup, and vacuuming
│   ├── ml/                       # Candle BERT neural embeddings, vector similarity, ONNX inference
│   └── optimizer/                # Universal token compression engine, AST code skeletonizer
├── skills/                       # Pre-packaged domain skills catalog (279 embedded skills, 440 vectors)
├── docs/                         # Architectural diagrams, specifications, setup guides
│   └── images/                   # Dashboard screenshots, hero banners, and flowcharts
└── scripts/                      # Automated installation and maintenance scripts (PowerShell, Bash)

---

📚 Documentation Index

Comprehensive guides, architecture deep-dives, and client setup instructions are available in the docs/ directory:

---

🙏 Credits & Acknowledgments

This project references and acknowledges the following third-party security resources:

---

📄 License

Distributed under the MIT License. See LICENSE for details.