Anselmoo/mcp-ai-agent-guidelines

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
• 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

- Full guide to all tools and features

Getting Started Guides

• - Learn to ask targeted questions for better results
• - Understanding prompt levels and evaluation
• - Invoking tools in workflows

Advanced Features

• - Multi-step prompt workflows
• - Tool-to-tool chaining with context propagation
• - Real-world A2A workflow patterns
• - Create flowcharts, sequences, ER diagrams
• - Hygiene scoring and best practices
• - Dependency-aware timeline calculation

Integration & Reference

• - Integration patterns for external systems
• - Semantic analysis strategies
• - Credits, research papers, and citations

See for the complete documentation index.

Quick Links

For Users

• - Learn to ask targeted questions for better results
• - Understanding prompt levels and evaluation
• - Invoking tools in workflows
• - Advanced chaining strategies
• - Visual diagram generation

For Developers

• - How to contribute
• - Quality standards (100/100 scoring)
• - Refactoring and enhancements
• - Best practices
• - Integration patterns

For Maintainers

• - LaTeX, CSV, JSON export options and chat integration
• - Managing AI model definitions in YAML

See the 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.

- Full list of all demos with descriptions

Featured Examples

Code Analysis & Quality:

• - Pattern detection and best practices
• - AI agent development standards
• - Comprehensive quality metrics (0-100)

Prompt Engineering:

• - Structured refactoring plan
• - Generic template
• - OWASP-focused analysis
• - Multi-step workflows

Visualization & Planning:

• - Mermaid system diagrams
• - Dependency-aware timeline
• - AI model selection

Advanced Features:

• - Token efficiency
• - SWOT, BCG, Porter's Five Forces
• - 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)

📖 - 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 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.

📖 - 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'],
});

📖 - 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:

📘

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

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

{
  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" }
  ]
}

# 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"
}

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

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:

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 for important information about external references, trademarks, and limitations of liability.

Contributing

Contributions welcome! Please see for guidelines.

Developer Resources

• - Full documentation index
• - Quality requirements and scoring
• - Best practices for error handling
• - System architecture and integration patterns
• - TypeScript conventions

Quality Standards

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

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

License

MIT © Anselmoo — see .

References & Acknowledgments

For a comprehensive list of references, research papers, and detailed attribution, see .

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 for the complete list of research papers, projects, and inspirations.