UNPKG

mcp-ai-agent-guidelines

Version:

A comprehensive Model Context Protocol server providing professional tools, resources, and prompts for implementing AI agent best practices

989 lines (988 loc) 77.1 kB
#!/usr/bin/env node /** * AI Agent Development Guidelines MCP Server * * This MCP server provides tools, resources, and prompts for implementing * AI agent best practices including hierarchical prompting, code hygiene * analysis, mermaid diagram generation, memory optimization, and sprint planning. */ // Dynamic version from package.json using createRequire for ESM compatibility import { createRequire } from "node:module"; import { Server } from "@modelcontextprotocol/sdk/server/index.js"; const require = createRequire(import.meta.url); // eslint-disable-next-line @typescript-eslint/no-var-requires -- acceptable for package metadata const pkg = require("../package.json"); import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js"; // Import prompts import { getPrompt, listPrompts } from "./prompts/index.js"; // Import resources import { getResource, listResources } from "./resources/index.js"; // Import tool schemas import { promptChainingBuilderSchema, promptFlowBuilderSchema, } from "./schemas/flow-tool-schemas.js"; import { gapFrameworksAnalyzers } from "./tools/analysis/gap-frameworks-analyzers.js"; import { strategyFrameworksBuilder } from "./tools/analysis/strategy-frameworks-builder.js"; import { cleanCodeScorer } from "./tools/clean-code-scorer.js"; import { codeHygieneAnalyzer } from "./tools/code-hygiene-analyzer.js"; import { designAssistant, } from "./tools/design/index.js"; import { guidelinesValidator } from "./tools/guidelines-validator.js"; import { iterativeCoverageEnhancer } from "./tools/iterative-coverage-enhancer.js"; import { memoryContextOptimizer } from "./tools/memory-context-optimizer.js"; import { mermaidDiagramGenerator } from "./tools/mermaid-diagram-generator.js"; import { modeSwitcher } from "./tools/mode-switcher.js"; import { modelCompatibilityChecker } from "./tools/model-compatibility-checker.js"; import { projectOnboarding } from "./tools/project-onboarding.js"; import { architectureDesignPromptBuilder } from "./tools/prompt/architecture-design-prompt-builder.js"; import { codeAnalysisPromptBuilder } from "./tools/prompt/code-analysis-prompt-builder.js"; import { debuggingAssistantPromptBuilder } from "./tools/prompt/debugging-assistant-prompt-builder.js"; import { documentationGeneratorPromptBuilder } from "./tools/prompt/documentation-generator-prompt-builder.js"; import { domainNeutralPromptBuilder } from "./tools/prompt/domain-neutral-prompt-builder.js"; // Import tool implementations import { hierarchicalPromptBuilder } from "./tools/prompt/hierarchical-prompt-builder.js"; import { hierarchyLevelSelector } from "./tools/prompt/hierarchy-level-selector.js"; import { promptChainingBuilder } from "./tools/prompt/prompt-chaining-builder.js"; import { promptFlowBuilder } from "./tools/prompt/prompt-flow-builder.js"; import { promptingHierarchyEvaluator } from "./tools/prompt/prompting-hierarchy-evaluator.js"; import { securityHardeningPromptBuilder } from "./tools/prompt/security-hardening-prompt-builder.js"; import { sparkPromptBuilder } from "./tools/prompt/spark-prompt-builder.js"; import { semanticCodeAnalyzer } from "./tools/semantic-code-analyzer.js"; import { sprintTimelineCalculator } from "./tools/sprint-timeline-calculator.js"; const server = new Server({ name: "ai-agent-guidelines", version: pkg.version, }, { capabilities: { tools: {}, resources: {}, prompts: {}, }, }); // Register tool handlers server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: "hierarchical-prompt-builder", description: "Build structured prompts with clear hierarchies and layers of specificity", inputSchema: { type: "object", properties: { context: { type: "string", description: "The broad context or domain", }, goal: { type: "string", description: "The specific goal or objective", }, requirements: { type: "array", items: { type: "string" }, description: "Detailed requirements and constraints", }, outputFormat: { type: "string", description: "Desired output format", }, audience: { type: "string", description: "Target audience or expertise level", }, includeDisclaimer: { type: "boolean", description: "Append a third-party disclaimer section", }, includeReferences: { type: "boolean", description: "Append a short references list", }, // 2025 techniques integration techniques: { type: "array", items: { type: "string", enum: [ "zero-shot", "few-shot", "chain-of-thought", "self-consistency", "in-context-learning", "generate-knowledge", "prompt-chaining", "tree-of-thoughts", "meta-prompting", "rag", "react", "art", ], }, description: "Optional list of technique hints to include", }, includeTechniqueHints: { type: "boolean", description: "Include a Technique Hints section", }, includePitfalls: { type: "boolean", description: "Include a Pitfalls section", }, autoSelectTechniques: { type: "boolean", description: "Infer techniques automatically from context/goal/requirements", }, provider: { type: "string", enum: [ "gpt-5", "gpt-4.1", "claude-4", "claude-3.7", "gemini-2.5", "o4-mini", "o3-mini", "other", ], description: "Model family for tailored tips", }, style: { type: "string", enum: ["markdown", "xml"], description: "Preferred prompt formatting style", }, }, required: ["context", "goal"], }, }, { name: "code-analysis-prompt-builder", description: "Generate comprehensive code analysis prompts with customizable focus areas (security, performance, maintainability)", inputSchema: { type: "object", properties: { codebase: { type: "string", description: "The codebase or code snippet to analyze", }, focusArea: { type: "string", enum: ["security", "performance", "maintainability", "general"], description: "Specific area to focus on", }, language: { type: "string", description: "Programming language of the code", }, mode: { type: "string" }, model: { type: "string" }, tools: { type: "array", items: { type: "string" } }, includeFrontmatter: { type: "boolean" }, includeReferences: { type: "boolean" }, includeMetadata: { type: "boolean" }, inputFile: { type: "string" }, forcePromptMdStyle: { type: "boolean" }, }, required: ["codebase"], }, }, { name: "architecture-design-prompt-builder", description: "Generate system architecture design prompts with scale-appropriate guidance", inputSchema: { type: "object", properties: { systemRequirements: { type: "string", description: "System requirements and constraints", }, scale: { type: "string", enum: ["small", "medium", "large"], description: "Expected system scale", }, technologyStack: { type: "string", description: "Preferred or required technology stack", }, mode: { type: "string" }, model: { type: "string" }, tools: { type: "array", items: { type: "string" } }, includeFrontmatter: { type: "boolean" }, includeReferences: { type: "boolean" }, includeMetadata: { type: "boolean" }, inputFile: { type: "string" }, forcePromptMdStyle: { type: "boolean" }, }, required: ["systemRequirements"], }, }, { name: "debugging-assistant-prompt-builder", description: "Generate systematic debugging and troubleshooting prompts with structured analysis", inputSchema: { type: "object", properties: { errorDescription: { type: "string", description: "Description of the error or issue", }, context: { type: "string", description: "Additional context about the problem", }, attemptedSolutions: { type: "string", description: "Solutions already attempted", }, mode: { type: "string" }, model: { type: "string" }, tools: { type: "array", items: { type: "string" } }, includeFrontmatter: { type: "boolean" }, includeReferences: { type: "boolean" }, includeMetadata: { type: "boolean" }, inputFile: { type: "string" }, forcePromptMdStyle: { type: "boolean" }, }, required: ["errorDescription"], }, }, { name: "documentation-generator-prompt-builder", description: "Generate technical documentation prompts tailored to content type and audience", inputSchema: { type: "object", properties: { contentType: { type: "string", description: "Type of documentation (API, user guide, technical spec)", }, targetAudience: { type: "string", description: "Intended audience for the documentation", }, existingContent: { type: "string", description: "Any existing content to build upon", }, mode: { type: "string" }, model: { type: "string" }, tools: { type: "array", items: { type: "string" } }, includeFrontmatter: { type: "boolean" }, includeReferences: { type: "boolean" }, includeMetadata: { type: "boolean" }, inputFile: { type: "string" }, forcePromptMdStyle: { type: "boolean" }, }, required: ["contentType"], }, }, { name: "strategy-frameworks-builder", description: "Compose strategy analysis sections from selected frameworks (SWOT, BSC, VRIO, etc.) with compliant aliases for certain trademarks", inputSchema: { type: "object", properties: { frameworks: { type: "array", items: { type: "string", enum: [ "asIsToBe", "whereToPlayHowToWin", "balancedScorecard", "swot", "objectives", "portersFiveForces", "mckinsey7S", "marketAnalysis", "strategyMap", "visionToMission", "stakeholderTheory", "values", "gapAnalysis", "ansoffMatrix", "pest", "bcgMatrix", "blueOcean", "scenarioPlanning", "vrio", "goalBasedPlanning", "gartnerQuadrant", ], }, description: "Framework identifiers to include", }, context: { type: "string", description: "Business context" }, objectives: { type: "array", items: { type: "string" } }, market: { type: "string" }, stakeholders: { type: "array", items: { type: "string" } }, constraints: { type: "array", items: { type: "string" } }, includeReferences: { type: "boolean" }, includeMetadata: { type: "boolean" }, inputFile: { type: "string" }, }, required: ["frameworks", "context"], }, }, { name: "gap-frameworks-analyzers", description: "Analyze gaps between current and desired states using various frameworks (capability, performance, maturity, etc.)", inputSchema: { type: "object", properties: { frameworks: { type: "array", items: { type: "string", enum: [ "capability", "performance", "maturity", "skills", "technology", "process", "market", "strategic", "operational", "cultural", "security", "compliance", ], }, description: "Gap analysis framework types to include", }, currentState: { type: "string", description: "Current state description", }, desiredState: { type: "string", description: "Desired state description", }, context: { type: "string", description: "Analysis context" }, objectives: { type: "array", items: { type: "string" } }, timeframe: { type: "string" }, stakeholders: { type: "array", items: { type: "string" } }, constraints: { type: "array", items: { type: "string" } }, includeReferences: { type: "boolean" }, includeMetadata: { type: "boolean" }, includeActionPlan: { type: "boolean" }, inputFile: { type: "string" }, }, required: ["frameworks", "currentState", "desiredState", "context"], }, }, { name: "spark-prompt-builder", description: "Build a generic UI/UX product prompt from structured inputs (title, features, colors, typography, etc.)", inputSchema: { type: "object", properties: { title: { type: "string", description: "Prompt title" }, summary: { type: "string", description: "Brief summary / outlook" }, experienceQualities: { type: "array", description: "List of UX qualities", items: { type: "object", properties: { quality: { type: "string" }, detail: { type: "string" }, }, required: ["quality", "detail"], }, }, complexityLevel: { type: "string" }, complexityDescription: { type: "string" }, primaryFocus: { type: "string" }, features: { type: "array", items: { type: "object", properties: { name: { type: "string" }, functionality: { type: "string" }, purpose: { type: "string" }, trigger: { type: "string" }, progression: { type: "array", items: { type: "string" } }, successCriteria: { type: "string" }, }, required: [ "name", "functionality", "purpose", "trigger", "progression", "successCriteria", ], }, }, edgeCases: { type: "array", items: { type: "object", properties: { name: { type: "string" }, handling: { type: "string" }, }, required: ["name", "handling"], }, }, designDirection: { type: "string" }, colorSchemeType: { type: "string" }, colorPurpose: { type: "string" }, primaryColor: { type: "string" }, primaryColorPurpose: { type: "string" }, secondaryColors: { type: "array", items: { type: "object", properties: { name: { type: "string" }, oklch: { type: "string" }, usage: { type: "string" }, }, required: ["name", "oklch", "usage"], }, }, accentColor: { type: "string" }, accentColorPurpose: { type: "string" }, foregroundBackgroundPairings: { type: "array", items: { type: "object", properties: { container: { type: "string" }, containerColor: { type: "string" }, textColor: { type: "string" }, ratio: { type: "string" }, }, required: ["container", "containerColor", "textColor", "ratio"], }, }, fontFamily: { type: "string" }, fontIntention: { type: "string" }, fontReasoning: { type: "string" }, typography: { type: "array", items: { type: "object", properties: { usage: { type: "string" }, font: { type: "string" }, weight: { type: "string" }, size: { type: "string" }, spacing: { type: "string" }, }, required: ["usage", "font", "weight", "size", "spacing"], }, }, animationPhilosophy: { type: "string" }, animationRestraint: { type: "string" }, animationPurpose: { type: "string" }, animationHierarchy: { type: "string" }, components: { type: "array", items: { type: "object", properties: { type: { type: "string" }, usage: { type: "string" }, variation: { type: "string" }, styling: { type: "string" }, state: { type: "string" }, functionality: { type: "string" }, purpose: { type: "string" }, }, required: ["type", "usage"], }, }, customizations: { type: "string" }, states: { type: "array", items: { type: "object", properties: { component: { type: "string" }, states: { type: "array", items: { type: "string" } }, specialFeature: { type: "string" }, }, required: ["component", "states"], }, }, icons: { type: "array", items: { type: "string" } }, spacingRule: { type: "string" }, spacingContext: { type: "string" }, mobileLayout: { type: "string" }, // Optional prompt md frontmatter controls mode: { type: "string" }, model: { type: "string" }, tools: { type: "array", items: { type: "string" } }, includeFrontmatter: { type: "boolean" }, includeDisclaimer: { type: "boolean" }, includeReferences: { type: "boolean" }, includeMetadata: { type: "boolean" }, inputFile: { type: "string" }, forcePromptMdStyle: { type: "boolean" }, }, required: [ "title", "summary", "complexityLevel", "designDirection", "colorSchemeType", "colorPurpose", "primaryColor", "primaryColorPurpose", "accentColor", "accentColorPurpose", "fontFamily", "fontIntention", "fontReasoning", "animationPhilosophy", "animationRestraint", "animationPurpose", "animationHierarchy", "spacingRule", "spacingContext", "mobileLayout", ], }, }, { name: "clean-code-scorer", description: "Calculate comprehensive Clean Code score (0-100) based on multiple quality metrics including code hygiene, test coverage, TypeScript, linting, documentation, and security", inputSchema: { type: "object", properties: { projectPath: { type: "string", description: "Path to the project root directory", }, codeContent: { type: "string", description: "Code content to analyze", }, language: { type: "string", description: "Programming language", }, framework: { type: "string", description: "Framework or technology stack", }, coverageMetrics: { type: "object", description: "Test coverage metrics", properties: { statements: { type: "number", description: "Statement coverage percentage (0-100)", }, branches: { type: "number", description: "Branch coverage percentage (0-100)", }, functions: { type: "number", description: "Function coverage percentage (0-100)", }, lines: { type: "number", description: "Line coverage percentage (0-100)", }, }, }, includeReferences: { type: "boolean", description: "Include external best-practice links", }, includeMetadata: { type: "boolean", description: "Include metadata in output", }, inputFile: { type: "string", description: "Input file path for reference", }, }, required: [], }, }, { name: "code-hygiene-analyzer", description: "Analyze codebase for outdated patterns, unused dependencies, and code hygiene issues", inputSchema: { type: "object", properties: { codeContent: { type: "string", description: "Code content to analyze", }, language: { type: "string", description: "Programming language" }, framework: { type: "string", description: "Framework or technology stack", }, includeReferences: { type: "boolean", description: "Include external best-practice links", }, }, required: ["codeContent", "language"], }, }, { name: "iterative-coverage-enhancer", description: "Iteratively analyze code coverage, detect dead code, generate test suggestions, and adapt coverage thresholds for continuous improvement", inputSchema: { type: "object", properties: { projectPath: { type: "string", description: "Path to the project root directory", }, language: { type: "string", description: "Primary programming language", }, framework: { type: "string", description: "Framework or technology stack", }, analyzeCoverageGaps: { type: "boolean", description: "Analyze and identify coverage gaps", }, detectDeadCode: { type: "boolean", description: "Detect unused code for elimination", }, generateTestSuggestions: { type: "boolean", description: "Generate test suggestions for uncovered code", }, adaptThresholds: { type: "boolean", description: "Recommend adaptive coverage threshold adjustments", }, currentCoverage: { type: "object", description: "Current coverage metrics", properties: { statements: { type: "number", minimum: 0, maximum: 100 }, functions: { type: "number", minimum: 0, maximum: 100 }, lines: { type: "number", minimum: 0, maximum: 100 }, branches: { type: "number", minimum: 0, maximum: 100 }, }, }, targetCoverage: { type: "object", description: "Target coverage goals", properties: { statements: { type: "number", minimum: 0, maximum: 100 }, functions: { type: "number", minimum: 0, maximum: 100 }, lines: { type: "number", minimum: 0, maximum: 100 }, branches: { type: "number", minimum: 0, maximum: 100 }, }, }, outputFormat: { type: "string", enum: ["markdown", "json", "text"], description: "Output format for the report", }, includeReferences: { type: "boolean", description: "Include references and best practice links", }, includeCodeExamples: { type: "boolean", description: "Include code examples in suggestions", }, generateCIActions: { type: "boolean", description: "Generate CI/CD integration actions", }, }, required: [], }, }, { name: "mermaid-diagram-generator", description: "Generate Mermaid diagrams from text descriptions following best practices. Supports advanced diagram types and customization options for richer documentation.", inputSchema: { type: "object", properties: { description: { type: "string", description: "Description of the system or process to diagram. Be specific and detailed for better diagram generation.", }, diagramType: { type: "string", enum: [ "flowchart", "sequence", "class", "state", "gantt", "pie", "er", "journey", "quadrant", "git-graph", "mindmap", "timeline", ], description: "Type of diagram to generate", }, theme: { type: "string", description: "Visual theme for the diagram (e.g., 'default', 'dark', 'forest', 'neutral')", }, direction: { type: "string", enum: ["TD", "TB", "BT", "LR", "RL"], description: "Direction for flowcharts: TD/TB (top-down), BT (bottom-top), LR (left-right), RL (right-left)", }, strict: { type: "boolean", description: "If true, never emit invalid diagram; fallback to minimal diagram if needed (default: true)", default: true, }, repair: { type: "boolean", description: "Attempt auto-repair on diagram validation failure (default: true)", default: true, }, accTitle: { type: "string", description: "Accessibility title (added as a Mermaid comment)", }, accDescr: { type: "string", description: "Accessibility description (added as a Mermaid comment)", }, customStyles: { type: "string", description: "Custom CSS/styling directives for advanced customization", }, advancedFeatures: { type: "object", description: "Type-specific advanced features (e.g., {autonumber: true} for sequence diagrams)", }, }, required: ["description", "diagramType"], }, }, { name: "memory-context-optimizer", description: "Optimize prompt caching and context window usage for AI agents", inputSchema: { type: "object", properties: { contextContent: { type: "string", description: "Context content to optimize", }, maxTokens: { type: "number", description: "Maximum token limit" }, cacheStrategy: { type: "string", enum: ["aggressive", "conservative", "balanced"], description: "Caching strategy", }, includeReferences: { type: "boolean", description: "Include external links on caching", }, }, required: ["contextContent"], }, }, { name: "domain-neutral-prompt-builder", description: "Build a domain-neutral, non-visual prompt/template (objectives, scope, inputs/outputs, workflow, capabilities, risks, acceptance)", inputSchema: { type: "object", properties: { title: { type: "string", description: "Document title" }, summary: { type: "string", description: "One-paragraph summary" }, objectives: { type: "array", items: { type: "string" } }, nonGoals: { type: "array", items: { type: "string" } }, background: { type: "string" }, stakeholdersUsers: { type: "string" }, environment: { type: "string" }, assumptions: { type: "string" }, constraints: { type: "string" }, dependencies: { type: "string" }, inputs: { type: "string" }, outputs: { type: "string" }, dataSchemas: { type: "array", items: { type: "string" } }, interfaces: { type: "array", items: { type: "object", properties: { name: { type: "string" }, contract: { type: "string" }, }, required: ["name", "contract"], }, }, workflow: { type: "array", items: { type: "string" } }, capabilities: { type: "array", items: { type: "object", properties: { name: { type: "string" }, purpose: { type: "string" }, preconditions: { type: "string" }, inputs: { type: "string" }, processing: { type: "string" }, outputs: { type: "string" }, successCriteria: { type: "string" }, errors: { type: "string" }, observability: { type: "string" }, }, required: ["name", "purpose"], }, }, edgeCases: { type: "array", items: { type: "object", properties: { name: { type: "string" }, handling: { type: "string" }, }, required: ["name", "handling"], }, }, risks: { type: "array", items: { type: "object", properties: { description: { type: "string" }, likelihoodImpact: { type: "string" }, mitigation: { type: "string" }, }, required: ["description"], }, }, successMetrics: { type: "array", items: { type: "string" } }, acceptanceTests: { type: "array", items: { type: "object", properties: { setup: { type: "string" }, action: { type: "string" }, expected: { type: "string" }, }, required: ["setup", "action", "expected"], }, }, manualChecklist: { type: "array", items: { type: "string" } }, performanceScalability: { type: "string" }, reliabilityAvailability: { type: "string" }, securityPrivacy: { type: "string" }, compliancePolicy: { type: "string" }, observabilityOps: { type: "string" }, costBudget: { type: "string" }, versioningStrategy: { type: "string" }, migrationCompatibility: { type: "string" }, changelog: { type: "array", items: { type: "string" } }, milestones: { type: "array", items: { type: "object", properties: { name: { type: "string" }, deliverables: { type: "string" }, eta: { type: "string" }, }, required: ["name"], }, }, openQuestions: { type: "array", items: { type: "string" } }, nextSteps: { type: "array", items: { type: "string" } }, // Optional prompt md frontmatter controls mode: { type: "string" }, model: { type: "string" }, tools: { type: "array", items: { type: "string" } }, includeFrontmatter: { type: "boolean" }, includeDisclaimer: { type: "boolean" }, includeReferences: { type: "boolean" }, includeTechniqueHints: { type: "boolean" }, includePitfalls: { type: "boolean" }, includeMetadata: { type: "boolean" }, inputFile: { type: "string" }, forcePromptMdStyle: { type: "boolean" }, }, required: ["title", "summary"], }, }, { name: "security-hardening-prompt-builder", description: "Build specialized security hardening and vulnerability analysis prompts for AI-guided security assessment", inputSchema: { type: "object", properties: { codeContext: { type: "string", description: "The code context or description to analyze for security", }, securityFocus: { type: "string", enum: [ "vulnerability-analysis", "security-hardening", "compliance-check", "threat-modeling", "penetration-testing", ], description: "Primary security analysis focus", }, securityRequirements: { type: "array", items: { type: "string" }, description: "Specific security requirements to check", }, complianceStandards: { type: "array", items: { type: "string", enum: [ "OWASP-Top-10", "NIST-Cybersecurity-Framework", "ISO-27001", "SOC-2", "GDPR", "HIPAA", "PCI-DSS", ], }, description: "Compliance standards to evaluate against", }, language: { type: "string", description: "Programming language of the code", }, framework: { type: "string", description: "Framework or technology stack", }, riskTolerance: { type: "string", enum: ["low", "medium", "high"], description: "Risk tolerance level for security assessment", }, analysisScope: { type: "array", items: { type: "string", enum: [ "input-validation", "authentication", "authorization", "data-encryption",