MCP AI Agent Guidelines Server

[!CAUTION]
Disclaimer -- Experimental / Early Stage: This research demonstrator project references third‑party models, tools, pricing, and docs that evolve quickly. Treat outputs as recommendations and verify against official docs and your own benchmarks before production use.

A Model Context Protocol (MCP) server offering advanced tools and templates for hierarchical prompting, code hygiene, visualization, memory optimization, and agile planning.

📚 Table of Contents

• Installation
• Documentation
• Demos
• Features
• VS Code Integration
• Agent-Relative Calls
• Configuration
• Development
• Contributing
• Changelog
• License

Installation

# NPX (recommended)
npx mcp-ai-agent-guidelines

# NPM global
npm install -g mcp-ai-agent-guidelines

# From source
git clone https://github.com/Anselmoo/mcp-ai-agent-guidelines.git
cd mcp-ai-agent-guidelines
npm ci && npm run build && npm start

Scripts

npm run build      # TypeScript build
npm run start      # Build and start server
npm run test:all   # Unit + integration + demos + MCP smoke
npm run test:coverage:unit # Unit test coverage (c8) -> coverage/ + summary
npm run quality    # Type-check + Biome checks
npm run links:check # Check links in main markdown files
npm run links:check:all # Check links in all markdown files (slow)

Local Link Checking

The project includes automated link checking via GitHub Actions. To check links locally before committing:

# Quick check (README, CONTRIBUTING, DISCLAIMER)
npm run links:check

# Comprehensive check (all markdown files)
npm run links:check:all

# Or use npx directly
npx markdown-link-check --config .mlc_config.json README.md

Configuration is in .mlc_config.json. Ignored patterns and retries are configured there.

Documentation

Documentation

📖 Complete Documentation Index - Full guide to all tools and features

Getting Started Guides

• 🎯 AI Interaction Tips - Learn to ask targeted questions for better results
• 📊 Prompting Hierarchy - Understanding prompt levels and evaluation
• 🔗 Agent-Relative Call Patterns - Invoking tools in workflows

Advanced Features

• 🌊 Flow-Based Prompting - Multi-step prompt workflows
• 🔗 Agent-to-Agent (A2A) Orchestration - Tool-to-tool chaining with context propagation
• 📋 A2A Practical Examples - Real-world A2A workflow patterns
• 🎨 Mermaid Diagram Generation - Create flowcharts, sequences, ER diagrams
• 🔍 Code Quality Analysis - Hygiene scoring and best practices
• ⚡ Sprint Planning - Dependency-aware timeline calculation

Integration & Reference

• 🏗️ Bridge Connectors - Integration patterns for external systems
• 🔄 Serena Integration - Semantic analysis strategies
• 📚 Complete Reference - Credits, research papers, and citations

See docs/README.md for the complete documentation index.

Quick Links

For Users

• 🎯 AI Interaction Tips - Learn to ask targeted questions for better results
• 📊 Prompting Hierarchy - Understanding prompt levels and evaluation
• 🔗 Agent-Relative Call Patterns - Invoking tools in workflows
• 🌊 Flow-Based Prompting - Advanced chaining strategies
• 🎨 Mermaid Diagrams - Visual diagram generation

For Developers

• 🤝 Contributing Guidelines - How to contribute
• ✨ Clean Code Initiative - Quality standards (100/100 scoring)
• 🔧 Technical Improvements - Refactoring and enhancements
• ⚠️ Error Handling - Best practices
• 🏗️ Bridge Connectors - Integration patterns

For Maintainers

• 📦 Export Formats Guide - LaTeX, CSV, JSON export options and chat integration
• 🤖 Model Management Guide - Managing AI model definitions in YAML

See the complete documentation for the full list of guides organized by topic.

Demos

Explore real-world examples showing the tools in action. All demos are auto-generated and kept in sync with the codebase.

📖 Complete Demo Index - Full list of all demos with descriptions

Featured Examples

Code Analysis & Quality:

• Code Hygiene Report - Pattern detection and best practices
• Guidelines Validation - AI agent development standards
• Clean Code Scoring - Comprehensive quality metrics (0-100)

Prompt Engineering:

• Hierarchical Prompt - Structured refactoring plan
• Domain-Neutral Prompt - Generic template
• Security Hardening Prompt - OWASP-focused analysis
• Flow-Based Prompting - Multi-step workflows

Visualization & Planning:

• Architecture Diagram - Mermaid system diagrams
• Sprint Planning - Dependency-aware timeline
• Model Compatibility - AI model selection

Advanced Features:

• Memory Context Optimization - Token efficiency
• Strategy Frameworks - SWOT, BCG, Porter's Five Forces
• Gap Analysis - Current vs. desired state

Running Demos Locally

npm run build
node demos/demo-tools.js  # Generate sample tool outputs

Demos are automatically regenerated when tool code changes via GitHub Actions.

Features & Tools

32 professional tools (31 active + 1 unified tool) for AI-powered development workflows. Each tool is rated by complexity:

⭐ Complexity Ratings:

• ⭐ Simple - Single input, immediate output (5-10 min to master)
• ⭐⭐ Moderate - Multiple parameters, straightforward usage (15-30 min)
• ⭐⭐⭐ Advanced - Complex inputs, requires understanding of domain (1-2 hours)
• ⭐⭐⭐⭐ Expert - Multi-phase workflows, deep domain knowledge (half day)
• ⭐⭐⭐⭐⭐ Master - Enterprise-scale, comprehensive orchestration (1-2 days)

📖 Complete Tools Reference - Detailed documentation with examples

🎨 Prompt Builders (10 tools)

Build structured, effective prompts for various use cases.

⚠️ Deprecation Notice: Six individual prompt tools (hierarchical-prompt-builder, prompting-hierarchy-evaluator, hierarchy-level-selector, prompt-chaining-builder, prompt-flow-builder, quick-developer-prompts-builder) are deprecated as of v0.14.0 and will be removed in v0.15.0. Use prompt-hierarchy instead. See Migration Guide for details.

🔍 Code Analysis & Quality (7 tools)

Analyze and improve code quality with automated insights.

📊 Strategy & Planning (5 tools)

Business strategy analysis and agile project planning.

🎨 Design Workflow (1 tool)

Multi-phase design orchestration with constraint enforcement.

📝 Specification Tools (3 tools)

Generate and manage project specifications using Spec-Kit methodology.

📖 Spec-Kit Documentation - Complete guide to specification-driven development

🛠️ Utilities (3 tools)

Supporting tools for workflow optimization.

Deprecated Utilities (use prompt-hierarchy instead):

💡 Pro Tip: Start with ⭐ tools to learn the basics, then progress to ⭐⭐⭐+ tools for advanced workflows.

Output Strategies

MCP AI Agent Guidelines supports 7 output strategies for different documentation needs, allowing you to format the same analysis in multiple ways. Additionally, 6 cross-cutting capabilities can be added to any output format for automation and visualization.

Available Output Approaches

Cross-Cutting Capabilities

Add these to any output strategy:

• workflow - CI/CD pipeline definitions (GitHub Actions, GitLab CI)
• diagram - Visual documentation (Mermaid, PlantUML)
• shell-script - Automation scripts (Bash, PowerShell)
• config - Configuration files (JSON, YAML)
• issues - GitHub issue templates
• pr-template - Pull request templates

Usage Example

// Generate SpecKit with workflows and diagrams
const result = await server.callTool('design-assistant', {
  action: 'generate-artifacts',
  sessionId: 'my-session',
  outputFormat: 'speckit',
  crossCutting: ['workflow', 'diagram', 'config'],
});

📖 Complete Output Strategies Guide - Detailed documentation with examples for all 7 strategies

VS Code Integration (One-Click)

Use buttons below to add this MCP server to VS Code (User Settings → mcp.servers):

Manual settings (User Settings JSON):

{
  "mcp": {
    "servers": {
      "ai-agent-guidelines": {
        "command": "npx",
        "args": ["-y", "mcp-ai-agent-guidelines"]
      }
    }
  }
}

Using Docker:

{
  "mcp": {
    "servers": {
      "ai-agent-guidelines": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "-i",
          "ghcr.io/anselmoo/mcp-ai-agent-guidelines:latest"
        ]
      }
    }
  }
}

Use tools from a chat window (VS Code/Cline)

After adding the server, open your chat client (e.g., Cline in VS Code). The tools appear under the server name. You can:

• Run a tool directly by name:
  • hierarchical-prompt-builder — Provide context, goal, and optional requirements.
  • clean-code-scorer — Calculate comprehensive Clean Code score (0-100) with coverage metrics.
  • code-hygiene-analyzer — Paste code or point to a file and set language.
  • mermaid-diagram-generator — Describe the system and select a diagram type.
• Ask in natural language and pick the suggested tool.

Example prompts:

• "Use hierarchical-prompt-builder to create a refactor plan for src/index.ts with outputFormat markdown."
• "Use clean-code-scorer to analyze my project with current coverage metrics and get a quality score."
• "Analyze this Python file with code-hygiene-analyzer; highlight security issues."
• "Generate a Mermaid sequence diagram showing: User sends request to API, API queries Database, Database returns data, API responds to User."
• "Create an ER diagram for: Customer has Orders, Order contains LineItems, Product referenced in LineItems."
• "Build a user journey map for our checkout flow using mermaid-diagram-generator."

Tip: Most clients can pass file content automatically when you select a file and invoke a tool.

GitHub Chat (VS Code): In the chat, type your request and pick a tool suggestion, or explicitly reference a tool by name (e.g., “Use mermaid-diagram-generator to draw a flowchart for our pipeline”).

Agent-Relative Calls

This MCP server fully supports agent-relative calls, the MCP standard pattern for enabling AI agents to discover and invoke tools contextually. Following the GitHub MCP documentation, agents can use natural language patterns to orchestrate complex multi-tool workflows.

What Are Agent-Relative Calls?

Agent-relative calls are natural language patterns like:

Use the [tool-name] MCP to [action] with [parameters/context]

Quick Examples

Single Tool Invocation:

Use the hierarchical-prompt-builder MCP to create a code review prompt for our authentication module focusing on security best practices and OAuth2 implementation.

Multi-Tool Workflow:

1. Use the clean-code-scorer MCP to establish baseline quality metrics
2. Use the code-hygiene-analyzer MCP to identify specific technical debt
3. Use the security-hardening-prompt-builder MCP to create a remediation plan
4. Use the sprint-timeline-calculator MCP to estimate implementation timeline

Integration with Other MCP Servers:

# Accessibility Compliance Workflow

Use the Figma MCP to analyze design specifications for WCAG 2.1 AA compliance.
Use the security-hardening-prompt-builder MCP from AI Agent Guidelines to create accessibility security audit prompts.
Use the GitHub MCP to categorize open accessibility issues.
Use the iterative-coverage-enhancer MCP from AI Agent Guidelines to plan accessibility test coverage.
Use the Playwright MCP to create and run automated accessibility tests.

Comprehensive Guide

For complete documentation with 20+ detailed examples, workflow patterns, and best practices, see:

📘 Agent-Relative Call Patterns Guide

This guide covers:

• Core prompt patterns (single tool, chains, parallel, conditional)
• Tool categories with complete usage examples
• Multi-MCP server integration workflows
• Best practices for agent-driven development
• Performance optimization techniques
• Troubleshooting common issues

Available Resources

Access agent-relative call guidance via MCP resources:

Use the resource guidelines://agent-relative-calls to get comprehensive patterns and examples

Or access programmatically:

// MCP ReadResource request
{
  uri: "guidelines://agent-relative-calls";
}

Features

Usage: prompt-chaining-builder

Build sophisticated multi-step prompt workflows where each step can depend on outputs from previous steps. Supports error handling strategies (skip/retry/abort) and automatic Mermaid visualization.

Example:

{
  chainName: "Security Analysis Pipeline",
  steps: [
    {
      name: "Scan",
      prompt: "Scan for vulnerabilities",
      outputKey: "vulns"
    },
    {
      name: "Assess",
      prompt: "Assess severity of {{vulns}}",
      dependencies: ["vulns"],
      errorHandling: "retry"
    }
  ]
}

Usage: prompt-flow-builder

Create complex adaptive prompt flows with conditional branching, loops, parallel execution, and merge points. Automatically generates Mermaid flowcharts and execution guides.

Example:

{
  flowName: "Adaptive Code Review",
  nodes: [
    { id: "analyze", type: "prompt", name: "Analyze" },
    { id: "check", type: "condition", name: "Complex?",
      config: { expression: "complexity > 10" } },
    { id: "deep", type: "prompt", name: "Deep Review" },
    { id: "quick", type: "prompt", name: "Quick Check" }
  ],
  edges: [
    { from: "analyze", to: "check" },
    { from: "check", to: "deep", condition: "true" },
    { from: "check", to: "quick", condition: "false" }
  ]
}

Usage: semantic-code-analyzer

Performs semantic analysis to identify symbols, dependencies, patterns, and structure. Inspired by Serena's language server approach.

Usage: project-onboarding

Analyzes project structure, detects technologies, and generates memories for context retention. Based on Serena's onboarding system.

Usage: mode-switcher

Switches between operation modes with optimized tool sets and prompting strategies. Modes include: planning, editing, analysis, interactive, one-shot, debugging, refactoring, documentation.

Usage: hierarchical-prompt-builder

Usage: code-hygiene-analyzer

Usage: security-hardening-prompt-builder

Security Focus Areas:

• 🔍 Vulnerability analysis with OWASP Top 10 coverage
• 🛡️ Security hardening recommendations
• 📋 Compliance checking against industry standards
• ⚠️ Threat modeling and risk assessment
• 🧪 Penetration testing guidance

Compliance Standards: OWASP Top 10, NIST Cybersecurity Framework, ISO 27001, SOC 2, GDPR, HIPAA, PCI-DSS

Usage: mermaid-diagram-generator

Generates Mermaid diagrams with intelligent parsing of descriptions for rich, customizable visualizations.

Enhanced Features:

• Intelligent Description Parsing: All diagram types now parse descriptions to extract relevant entities, relationships, and structures
• New Diagram Types:
  • er - Entity Relationship diagrams for database schemas
  • journey - User journey maps for UX workflows
  • quadrant - Quadrant/priority charts for decision matrices
  • git-graph - Git commit history visualization
  • mindmap - Hierarchical concept maps
  • timeline - Event timelines and roadmaps
• Advanced Customization: Direction control, themes, custom styles, and type-specific features
• Smart Fallbacks: Generates sensible default diagrams when description parsing is ambiguous

Examples:

# Sequence diagram with participants auto-detected from description
{
  "description": "User sends login request to API. API queries Database for credentials. Database returns user data. API responds to User with token.",
  "diagramType": "sequence",
  "advancedFeatures": {"autonumber": true}
}

# Class diagram with relationships extracted
{
  "description": "User has id and email. Order contains Product items. User places Order. Product has price and name.",
  "diagramType": "class"
}

# ER diagram for database schema
{
  "description": "Customer places Order. Order contains LineItem. Product is referenced in LineItem.",
  "diagramType": "er"
}

# User journey map
{
  "description": "Shopping Journey. Section Discovery: User finds product. User reads reviews. Section Purchase: User adds to cart. User completes checkout.",
  "diagramType": "journey"
}

# Gantt chart with tasks from description
{
  "description": "Project: Feature Development. Phase Planning: Research requirements. Design architecture. Phase Development: Implement backend. Create frontend. Phase Testing: QA validation.",
  "diagramType": "gantt"
}

# Flowchart with custom direction
{
  "description": "Receive request. Validate input. Process data. Return response.",
  "diagramType": "flowchart",
  "direction": "LR"
}

Usage: memory-context-optimizer

Usage: sprint-timeline-calculator

Usage: model-compatibility-checker

Usage: guidelines-validator

Configuration

• Node.js 20+ required (see engines in package.json).
• Tools are exposed by the MCP server and discoverable via client schemas.
• Mermaid diagrams render client-side (Markdown preview). No server rendering.

Versioning

• Package version: 0.7.0 (matches internal resource versions).
• Tags vX.Y.Z trigger CI for NPM and Docker releases.
• Pin exact versions for production stability.

Release Setup

Use the Release Setup Issue Form to streamline the release process:

• Automated version management: Update version numbers across the codebase
• GitHub Copilot compatible: Structured form enables bot automation
• Quality gates: Pre-release checklist ensures reliability
• CI/CD integration: Supports existing NPM and Docker publishing workflow

To create a new release, open a release setup issue with the target version and release details.

Development

Prerequisites:

• Node.js 20+
• npm 10+

Setup:

git clone https://github.com/Anselmoo/mcp-ai-agent-guidelines.git
cd mcp-ai-agent-guidelines
npm install
npm run build    # ⚠️ Required: Generates types from models.yaml
npm start

Important: The build step generates TypeScript types from src/tools/config/models.yaml. These generated files are not committed to version control (gitignored) and must be generated locally. See ADR-0001 for the architectural decision.

Project structure:

/src      - TypeScript source (tools, resources, server)
/tests    - Test files and utilities
/scripts  - Shell scripts and helpers
/demos    - Demo scripts and generated artifacts
/.github  - CI and community health files

Testing and quality:

npm run test:unit        # Unit tests
npm run test:integration # Integration tests
npm run test:demo        # Demo runner
npm run test:mcp         # MCP smoke script
npm run test:coverage:unit # Unit test coverage (text-summary, lcov, html)
npm run quality          # Type-check + Biome check
npm run audit            # Security audit (production dependencies)
npm run audit:fix        # Auto-fix vulnerabilities
npm run audit:production # Audit production dependencies only

Automated Demo Regeneration 🔄

Demo files are automatically regenerated when tools change via GitHub Actions:

• Trigger: Any changes to src/tools/**/*.ts in a pull request
• Action: Automatically runs npm run test:demo to regenerate demos
• Result: Updated demo files are committed to the PR automatically

Benefits:

• ✅ Documentation always stays in sync with code
• ✅ No manual steps to remember
• ✅ Reviewers can see demo changes alongside code changes

Workflow: .github/workflows/auto-regenerate-demos.yml

Manual regeneration (if needed):

npm run build
npm run test:demo

Git Hooks with Lefthook 🪝

This project uses Lefthook for fast, reliable Git hooks that enforce code quality and security standards.

Mandatory for GitHub Copilot Agent: All quality gates must pass before commits and pushes.

Setup (automatic via npm install):

npm run hooks:install    # Install lefthook git hooks
npm run hooks:uninstall  # Remove lefthook git hooks
npx lefthook run pre-commit  # Run pre-commit checks manually
npx lefthook run pre-push    # Run pre-push checks manually

Pre-commit hooks (fast, parallel execution):

• 🔒 Security: Gitleaks secret detection
• 🟨 Code Quality: Biome formatting & linting
• 🔷 Type Safety: TypeScript type checking
• 🧹 Code Hygiene: Trailing whitespace & EOF fixes

Pre-push hooks (comprehensive validation):

• 🔒 Security Audit: Dependency vulnerability scanning (moderate+ level)
• 🧪 Testing: Full test suite (unit, integration, demo, MCP)
• ⚡ Quality: Type checking + Biome validation

Why Lefthook?

• ⚡ Fast: Written in Go, parallel execution
• 🔄 Reliable: Better error handling than pre-commit
• 🤖 CI Integration: Mandatory quality gates for GitHub Copilot Agent
• 📝 Simple: Single YAML configuration file

Configuration: lefthook.yml

Coverage reporting

• CI publishes a coverage summary in the job’s Summary and uploads coverage/ as an artifact.
• Coverage is also uploaded to Codecov on Node 22 runs; see the badge above for status.

Docker

# Run with Docker
docker run -p 3000:3000 ghcr.io/anselmoo/mcp-ai-agent-guidelines:latest

# Build locally
docker build -t mcp-ai-agent-guidelines .
docker run -p 3000:3000 mcp-ai-agent-guidelines

VS Code + Docker settings:

{
  "mcp": {
    "servers": {
      "mcp-ai-agent-guidelines": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "-i",
          "ghcr.io/anselmoo/mcp-ai-agent-guidelines:latest"
        ]
      }
    }
  }
}

Security

• Dependency Scanning: Automated vulnerability scanning runs on every PR and push to main
  • Production dependencies: fails on moderate+ vulnerabilities
  • All dependencies: audited and reported (dev dependencies don't block builds)
  • Local audit: npm run audit or npm audit --audit-level=moderate
  • Auto-fix: npm run audit:fix to automatically fix vulnerabilities when possible
  • Pre-push hook: automatically checks for vulnerabilities before pushing code
• Secrets Protection: No secrets committed; releases use provenance where supported
• Supply Chain Security: Docker images are signed (Cosign); artifacts signed via Sigstore
• Vulnerability Reporting: Report security issues via GitHub Security tab or Issues

Remediation Steps for Maintainers

When vulnerabilities are detected:

1. Review the vulnerability: npm audit provides details about affected packages
2. Update dependencies: npm run audit:fix to apply automatic fixes
3. Manual updates: If auto-fix doesn't work, update package.json manually:

   npm update <package-name>
   # or for major version updates
   npm install <package-name>@latest
   

4. Test changes: Run npm run test:all to ensure updates don't break functionality
5. Override if needed: For false positives or accepted risks, document in security policy

Documentation

• MCP Specification: https://modelcontextprotocol.io/
• Tools implementation: see src/tools/ in this repo.
• Generated examples: see demos/ and links above.

Disclaimer

This project references third-party tools, frameworks, APIs, and services for informational purposes. See DISCLAIMER.md for important information about external references, trademarks, and limitations of liability.

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

Developer Resources

• Complete Documentation - Full documentation index
• Clean Code Standards - Quality requirements and scoring
• Error Handling Patterns - Best practices for error handling
• Architecture Guide - System architecture and integration patterns
• Type System Organization - TypeScript conventions

Quality Standards

• TypeScript strict mode - All code must pass type checking
• 100% test coverage goal - See Clean Code Initiative
• Biome linting - Code must pass npm run quality
• Git hooks - Automated checks via Lefthook (see lefthook.yml)

Keep changes typed, linted, and include tests when behavior changes.

License

MIT © Anselmoo — see LICENSE.

References & Acknowledgments

For a comprehensive list of references, research papers, and detailed attribution, see docs/tips/references.md.

Key Acknowledgments

• Model Context Protocol team for the specification
• Anthropic for prompt caching research
• Mermaid community for diagram tooling
• @ruvnet/claude-flow - Inspired flow-based prompting features
• @oraios/serena - Influenced semantic analysis and mode switching
• All open-source contributors whose work has shaped this project

See docs/tips/references.md for the complete list of research papers, projects, and inspirations.