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 professional tools and templates for hierarchical prompting, code hygiene, visualization, memory optimization, and agile planning.

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

Demos

Explore generated demo reports in the repository:

• Code Hygiene Report:
• Guidelines Validation:
• Hierarchical Prompt (Refactor plan):
• Domain-neutral Prompt Template:
• Security Hardening Prompt:
• Spark Prompt Card:
• Memory Context Optimization:
• Architecture Diagram (Mermaid):
• Model Compatibility Analysis:
• Sprint Plan:

See more in .

Demo scripts (.js)

Run demo scripts to generate or test artifacts:

# Build first
npm run build

# Run sample tool calls
node demos/demo-tools.js

# Generate demo reports
node demos/demo-tools.js

Scripts:

• demos/demo-tools.js — invokes several tools with sample inputs
• demos/generate-demo-reports.js — produces end-to-end demo outputs
• demos/generate-hygiene-reports.js — hygiene-focused reports

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.
  • 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."
• "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”).

Features

# 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, 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
npm start

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

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

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

• No secrets committed; releases use provenance where supported.
• Docker images are signed (Cosign); supply‑chain security via Sigstore.
• Report vulnerabilities via GitHub Security tab or Issues.

Documentation

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

Contributing

Contributions welcome. Please see . Keep changes typed, linted, and include tests when behavior changes.

License

MIT © Anselmoo — see .

Acknowledgments

• Model Context Protocol team for the spec
• Anthropic for prompt caching research
• Mermaid community for diagram tooling