MCP AI Agent Guidelines Server

[!CAUTION] Disclaimer -- Experimental / Early Stage: This 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

```bash

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

bash 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: demos/demo-code-analysis.hygiene.md
• Guidelines Validation: demos/demo-code-analysis.guidelines.md
• Hierarchical Prompt (Refactor plan): demos/demo-code-analysis.hierarchical.prompt.md
• Domain-neutral Prompt Template: demos/demo-code-analysis.domain-neutral.prompt.md
• Spark Prompt Card: demos/demo-code-analysis.spark.prompt.md
• Memory Context Optimization: demos/demo-code-analysis.memory.md
• Architecture Diagram (Mermaid): demos/demo-code-analysis.diagram.md
• Model Compatibility Analysis: demos/demo-code-analysis.model-compat.md
• Sprint Plan: demos/demo-code-analysis.sprint.md

See more in demos/README.md.

Demo scripts (.js)

Run demo scripts to generate or test artifacts:

```bash

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

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

Using Docker:

json { "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 diagram for our pipeline using mermaid-diagram-generator (flowchart)."

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

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.1.0 (matches internal resource versions).
• Tags vX.Y.Z trigger CI for NPM and Docker releases.
• Pin exact versions for production stability.

Development

Prerequisites: - Node.js 20+ - npm 10+

Setup:

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

bash 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

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

```bash

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:

json { "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 CONTRIBUTING.md. Keep changes typed, linted, and include tests when behavior changes.

License

MIT © Anselmoo — see LICENSE.

Acknowledgments

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