Skip to main content

📖 Complete API Reference

MCP ADR Analysis Server - All available tools, parameters, and usage examples

Version: 2.14.12 | Tools: 63 tools (on wire) | Updated: September 2026

🎯 Quick Navigation​

🔍 Core Analysis Tools​

📝 ADR Generation & Management​

🔒 Security & Content Protection​

📊 Project Health & Deployment​

🛠️ Workflow & Development​

🔬 Research & Knowledge​

⚙️ Rules & Validation​

🗂️ File & Cache Management​

  • read_file - Read files with security validation (removed in ADR-023; use host's native file-read)
  • write_file - Write files with safety checks (removed in ADR-023; use host's native file-write)
  • list_directory - List directory contents securely (removed in ADR-023; use host's native directory-listing)
  • manage_cache - Manage analysis cache
  • manage_todo_json - Manage TODO JSON files

🔧 Configuration & Utilities​

🌐 ADR Aggregator Integration​

🔧 Core Analysis Tools​

analyze_project_ecosystem​

Purpose: Comprehensive recursive project ecosystem analysis with advanced AI prompting techniques

Use Cases:

  • Initial project understanding and architecture discovery
  • Complete technology stack analysis
  • Knowledge graph building with architectural insights
  • Context establishment for downstream analysis tools

Parameters:

{
  "projectPath": "string (required) - Path to project root",
  "enhancedMode": "boolean (default: false) - Enable enhanced analysis",
  "knowledgeEnhancement": "boolean (default: false) - Enable knowledge generation",
  "learningEnabled": "boolean (default: false) - Enable reflexion learning",
  "includeEnvironment": "boolean (default: false) - Include environment analysis",
  "recursiveDepth": "string (enum: 'shallow'|'medium'|'deep'|'comprehensive', default: 'medium')",
  "conversationContext": "object (optional) - Conversation context for continuity",
  "strictMode": "boolean (default: true) - Enable strict validation"
}

Example Usage:

{
  "projectPath": ".",
  "enhancedMode": true,
  "knowledgeEnhancement": true,
  "recursiveDepth": "comprehensive",
  "includeEnvironment": true
}

Response Format:

{
  "status": "success",
  "analysis": {
    "projectOverview": "string",
    "technologies": ["array of detected technologies"],
    "architecturalPatterns": ["array of patterns"],
    "recommendations": ["array of recommendations"],
    "knowledgeGraph": "object (if knowledgeEnhancement enabled)",
    "environmentAnalysis": "object (if includeEnvironment enabled)"
  },
  "metadata": {
    "analysisTime": "number",
    "confidence": "number (0-1)",
    "toolsUsed": ["array of tools"]
  }
}

get_architectural_context​

Purpose: Extract architectural context, patterns, and decision history from project

Parameters:

{
  "projectPath": "string (required)",
  "includePatterns": "boolean (default: true)",
  "includeDecisions": "boolean (default: true)",
  "contextDepth": "string (enum: 'basic'|'detailed'|'comprehensive', default: 'detailed')"
}

discover_existing_adrs​

Purpose: Discover, catalog, and analyze existing Architectural Decision Records

Parameters:

{
  "projectPath": "string (required)",
  "adrDirectory": "string (default: './adrs')",
  "includeMetadata": "boolean (default: true)",
  "validateStructure": "boolean (default: true)"
}

review_existing_adrs​

Purpose: Review existing ADRs with advanced tree-sitter code analysis

Parameters:

{
  "projectPath": "string (required)",
  "adrDirectory": "string (default: './adrs')",
  "includeTreeSitter": "boolean (default: true)",
  "analysisDepth": "string (enum: 'basic'|'detailed'|'comprehensive', default: 'detailed')"
}

analyze_environment​

Purpose: Analyze project environment, containerization, and deployment configuration

Parameters:

{
  "projectPath": "string (required)",
  "analysisType": "string (enum: 'specs'|'containerization'|'requirements'|'compliance'|'comprehensive', default: 'comprehensive')",
  "knowledgeEnhancement": "boolean (default: true)",
  "enhancedMode": "boolean (default: true)",
  "currentEnvironment": "string (required for compliance analysis)",
  "requirements": "array (required for compliance analysis)"
}

📝 ADR Generation & Management​

generate_adr_from_decision​

Purpose: Create an ADR from structured decision data

Parameters:

{
  "projectPath": "string (required) - Path to project root",
  "decision": "object (required) - Decision data including title, context, and options",
  "outputDirectory": "string (default: './adrs') - Output directory for ADR",
  "adrTemplate": "string (enum: 'nygard'|'madr'|'custom', default: 'nygard')"
}

generate_adr_todo​

Purpose: Extract TODO items and action items from existing ADRs

Parameters:

{
  "projectPath": "string (required)",
  "adrDirectory": "string (default: './adrs')",
  "includeCompleted": "boolean (default: false) - Include completed TODOs",
  "outputFormat": "string (enum: 'markdown'|'json', default: 'markdown')"
}

interactive_adr_planning​

Purpose: Interactive workflow for planning and creating ADRs collaboratively

Parameters:

{
  "projectPath": "string (required)",
  "sessionId": "string (optional) - Resume existing session",
  "stakeholders": "array (optional) - List of stakeholders to involve",
  "decisionContext": "string (optional) - Initial decision context"
}

generate_adrs_from_prd​

Purpose: Generate comprehensive ADRs from Product Requirements Document

Parameters:

{
  "prdContent": "string (required) - PRD content",
  "projectPath": "string (default: '.')",
  "outputDirectory": "string (default: './adrs')",
  "adrTemplate": "string (enum: 'nygard'|'madr'|'custom', default: 'nygard')",
  "includeImplementationPlan": "boolean (default: true)"
}

suggest_adrs​

Purpose: Suggest missing ADRs based on code analysis and architectural gaps

Parameters:

{
  "projectPath": "string (required)",
  "existingAdrs": "array (optional) - Existing ADR summaries",
  "beforeCode": "string (optional) - Code before changes",
  "afterCode": "string (optional) - Code after changes",
  "enableTreeSitterAnalysis": "boolean (default: false)",
  "analysisDepth": "string (enum: 'basic'|'detailed'|'comprehensive', default: 'detailed')"
}

generate_adr_bootstrap​

Purpose: Bootstrap ADR validation scripts and compliance checking

Parameters:

{
  "projectPath": "string (required)",
  "adrDirectory": "string (default: './adrs')",
  "enableTreeSitterAnalysis": "boolean (default: false)",
  "validationLevel": "string (enum: 'basic'|'standard'|'strict', default: 'standard')"
}

🔒 Security & Content Protection​

analyze_content_security​

Purpose: Detect sensitive content, secrets, and security vulnerabilities with AI

Parameters:

{
  "content": "string (required) - Content to analyze",
  "contentType": "string (optional) - Content type hint",
  "securityLevel": "string (enum: 'basic'|'standard'|'strict', default: 'standard')",
  "enableTreeSitterAnalysis": "boolean (default: false)",
  "customPatterns": "array (optional) - Custom security patterns"
}

generate_content_masking​

Purpose: Create intelligent masking instructions for sensitive content

Parameters:

{
  "content": "string (required)",
  "securityFindings": "array (required) - Security analysis results",
  "maskingStrategy": "string (enum: 'conservative'|'balanced'|'aggressive', default: 'balanced')",
  "preserveStructure": "boolean (default: true)"
}

apply_basic_content_masking​

Purpose: Apply content masking patterns to protect sensitive information

Parameters:

{
  "content": "string (required) - Content to mask",
  "patterns": "array (required) - Masking patterns to apply",
  "preserveFormat": "boolean (default: true) - Maintain content structure"
}

validate_content_masking​

Purpose: Validate that masking was applied correctly and effectively

Parameters:

{
  "originalContent": "string (required) - Original unmasked content",
  "maskedContent": "string (required) - Content after masking",
  "appliedPatterns": "array (required) - Patterns that were applied",
  "strictValidation": "boolean (default: true) - Enable strict validation"
}

configure_custom_patterns​

Purpose: Configure custom security detection patterns for content analysis

Parameters:

{
  "patterns": "array (required) - Custom pattern definitions",
  "category": "string (optional) - Pattern category",
  "severity": "string (enum: 'low'|'medium'|'high'|'critical', default: 'medium')",
  "persist": "boolean (default: true) - Save patterns for future use"
}

📊 Project Health & Deployment​

smart_score​

Purpose: AI-powered comprehensive project health scoring

Parameters:

{
  "projectPath": "string (required)",
  "scoringCriteria": "array (optional) - Custom scoring criteria",
  "includeRecommendations": "boolean (default: true)",
  "detailedAnalysis": "boolean (default: false)"
}

compare_adr_progress​

Purpose: Compare and validate ADR progress against implementation milestones

Parameters:

{
  "projectPath": "string (required)",
  "adrDirectory": "string (default: './adrs')",
  "milestones": "array (optional) - Expected milestones to compare against",
  "includeMetrics": "boolean (default: true)"
}

deployment_readiness​

Purpose: Comprehensive deployment readiness analysis with security validation

Parameters:

{
  "projectPath": "string (required)",
  "environment": "string (enum: 'development'|'staging'|'production', default: 'production')",
  "enableTreeSitterAnalysis": "boolean (default: false)",
  "treeSitterLanguages": "array (optional) - Languages to analyze",
  "strictMode": "boolean (default: true)"
}

analyze_deployment_progress​

Purpose: Analyze deployment progress and identify blockers

Parameters:

{
  "projectPath": "string (required)",
  "deploymentPlan": "object (optional) - Deployment plan to compare against",
  "checkpoints": "array (optional) - Deployment checkpoints",
  "includeBlockers": "boolean (default: true)"
}

generate_deployment_guidance​

Purpose: Generate deployment guidance based on project analysis

Parameters:

{
  "projectPath": "string (required)",
  "targetEnvironment": "string (enum: 'development'|'staging'|'production')",
  "deploymentType": "string (enum: 'initial'|'update'|'rollback', default: 'update')",
  "includeChecklist": "boolean (default: true)"
}

🛠️ Workflow & Development​

troubleshoot_guided_workflow​

Purpose: Systematic troubleshooting workflow with intelligent guidance

Parameters:

{
  "projectPath": "string (required)",
  "issueDescription": "string (required) - Description of the issue",
  "troubleshootingLevel": "string (enum: 'basic'|'intermediate'|'advanced', default: 'intermediate')",
  "includeSystemInfo": "boolean (default: true)"
}

get_workflow_guidance​

Purpose: Intelligent workflow recommendations based on project state

Parameters:

{
  "projectPath": "string (required)",
  "currentPhase": "string (optional) - Current development phase",
  "teamSize": "number (optional) - Team size",
  "preferences": "object (optional) - Workflow preferences"
}

get_development_guidance​

Purpose: Development roadmap guidance and best practice recommendations

Parameters:

{
  "projectPath": "string (required)",
  "focusArea": "string (optional) - Specific area to focus on",
  "includeEstimates": "boolean (default: true)",
  "teamContext": "object (optional) - Team context information"
}

tool_chain_orchestrator​

Purpose: Orchestrate multiple tool workflows for complex analysis tasks

Parameters:

{
  "projectPath": "string (required)",
  "workflow": "string (enum: 'full_analysis'|'security_audit'|'deployment_prep'|'custom')",
  "tools": "array (required for custom workflow) - Tools to orchestrate",
  "parallelExecution": "boolean (default: false)"
}

smart_git_push​

Purpose: Intelligent Git operations with validation

Note: This tool has been superseded by smart_git_push_v2 which includes additional security features and deployment readiness validation. Use smart_git_push_v2 for new integrations.

Parameters:

{
  "branch": "string (optional) - Target branch",
  "message": "string (optional) - Commit message",
  "dryRun": "boolean (default: false) - Preview changes without pushing",
  "projectPath": "string (optional) - Project path"
}

smart_git_push_v2​

Note: This tool does not exist in the current codebase (v2.14.12). This section needs to be regenerated from source. The source file smart-git-push-tool-v2.ts exists but no tool with the exact name smart_git_push_v2 is registered in mcp-tool-schemas.ts.

Purpose: Security-focused Git push with deployment readiness validation and metrics tracking

Use Cases:

  • Secure git pushes with comprehensive security scanning
  • Deployment readiness validation before pushing
  • Metrics tracking for deployment success rates
  • Prevention of credential leaks and sensitive data exposure
  • Repository hygiene enforcement

Parameters:

{
  "branch": "string (optional) - Target branch",
  "message": "string (optional) - Commit message",
  "testResults": "object (optional) - Test execution results",
  "skipSecurity": "boolean (optional) - Skip security scanning (default: false)",
  "dryRun": "boolean (optional) - Preview changes without pushing (default: false)",
  "projectPath": "string (optional) - Project path (default: cwd)",
  "forceUnsafe": "boolean (optional) - Force push despite issues (default: false)",
  "humanOverrides": "array (optional) - Human override decisions",
  "requestHumanConfirmation": "boolean (optional) - Request human confirmation",
  "checkDeploymentReadiness": "boolean (optional) - Check deployment readiness (default: false)",
  "targetEnvironment": "string (optional) - Target environment (staging|production|integration)",
  "enforceDeploymentReadiness": "boolean (optional) - Enforce deployment readiness (default: false)",
  "strictDeploymentMode": "boolean (optional) - Strict deployment mode (default: true)"
}

Example Usage:

{
  "branch": "main",
  "message": "feat: add new authentication system",
  "checkDeploymentReadiness": true,
  "targetEnvironment": "production",
  "strictDeploymentMode": true,
  "testResults": {
    "success": true,
    "testsRun": 25,
    "testsPassed": 25,
    "testsFailed": 0
  }
}

Response Format:

{
  "content": [
    {
      "type": "text",
      "text": "# Smart Git Push V2 Results\n\n## Security Scan Results\n[security findings]\n\n## Deployment Readiness\n[readiness assessment]\n\n## Push Status\n[push results]\n\n## Metrics Updated\n[deployment metrics]"
    }
  ]
}

Key Features:

  • Security Scanning: Detects credentials, secrets, and sensitive data
  • Repository Hygiene: Blocks irrelevant files (temp, build artifacts)
  • Deployment Readiness: Validates deployment readiness before pushing
  • Metrics Tracking: Updates deployment success rates and test results
  • Human Overrides: Supports human confirmation for edge cases

Cache Dependencies:

  • Creates/Updates: .mcp-adr-cache/deploy-history.json (deployment metrics)
  • Uses: Enhanced sensitive detector for security scanning

Blocking Conditions:

  • Critical security issues detected
  • Failed tests (when testResults provided)
  • Deployment readiness failures (when enabled)
  • Irrelevant files detected (unless overridden)

🔬 Research & Knowledge​

perform_research​

Purpose: Answer research questions using cascading data sources (project files → knowledge graph → environment → web search)

Use Cases:

  • Investigate architectural decisions and patterns
  • Understand project implementation details
  • Research deployment and configuration approaches
  • Gather context for ADR creation
  • Validate architectural assumptions

Parameters:

{
  "question": "string (required) - The research question to investigate",
  "projectPath": "string (optional) - Path to project root (defaults to cwd)",
  "adrDirectory": "string (optional) - ADR directory relative to project (defaults to './adrs')",
  "confidenceThreshold": "number (optional) - Minimum confidence for results (0-1, defaults to 0.6)",
  "performWebSearch": "boolean (optional) - Enable web search as fallback (defaults to true)"
}

Example Usage:

{
  "question": "What authentication methods are used in this project?",
  "confidenceThreshold": 0.8,
  "performWebSearch": false
}

Response Format:

{
  "content": [
    {
      "type": "text",
      "text": "# Research Results: [question]\n\n## Summary\n[research findings]\n\n## Confidence Score: [percentage]\n\n## Sources Consulted\n[detailed source information]\n\n## Research Metadata\n[execution details]\n\n## Next Steps\n[recommendations]"
    }
  ]
}

Research Sources (in order of priority):

  1. 📁 Project Files - Code, configs, documentation
  2. 🧠 Knowledge Graph - ADR relationships and decisions
  3. 🔧 Environment Resources - Live system data (Kubernetes, Docker, etc.)
  4. 🌐 Web Search - External information (fallback only)

Confidence Scoring:

  • High (≥80%): Reliable answer from project sources
  • Moderate (60-79%): Good answer, may need validation
  • Low (<60%): Limited information, web search recommended

generate_research_questions​

Purpose: Generate targeted research questions for architectural investigation

Parameters:

{
  "projectPath": "string (required)",
  "researchArea": "string (optional) - Specific area of focus",
  "questionCount": "number (default: 10) - Number of questions to generate",
  "complexity": "string (enum: 'basic'|'intermediate'|'advanced', default: 'intermediate')"
}

create_research_template​

Purpose: Create structured research templates for architectural investigation

Parameters:

{
  "projectPath": "string (required)",
  "researchTopic": "string (required) - Topic for research template",
  "templateType": "string (enum: 'exploration'|'comparison'|'decision', default: 'exploration')",
  "includeQuestions": "boolean (default: true)"
}

incorporate_research​

Purpose: Integrate research findings into ADRs and documentation

Parameters:

{
  "projectPath": "string (required)",
  "researchFindings": "object (required) - Research findings to incorporate",
  "targetAdr": "string (optional) - Specific ADR to update",
  "createNewAdr": "boolean (default: false) - Create new ADR from findings"
}

memory_loading​

Purpose: Load and manage architectural memory for knowledge persistence

Parameters:

{
  "projectPath": "string (required)",
  "memoryType": "string (enum: 'architectural'|'decisions'|'patterns'|'all', default: 'all')",
  "loadStrategy": "string (enum: 'incremental'|'full'|'selective', default: 'incremental')"
}

⚙️ Rules & Validation​

generate_rules​

Purpose: Generate architectural validation rules from ADRs and patterns

Parameters:

{
  "projectPath": "string (required)",
  "adrDirectory": "string (default: './adrs')",
  "ruleTypes": "array (optional) - Types of rules to generate",
  "strictness": "string (enum: 'lenient'|'moderate'|'strict', default: 'moderate')"
}

validate_rules​

Purpose: Validate code against architectural rules

Parameters:

{
  "projectPath": "string (required)",
  "rules": "array (required) - Rules to validate against",
  "filePatterns": "array (optional) - File patterns to validate",
  "reportFormat": "string (enum: 'summary'|'detailed'|'json', default: 'detailed')"
}

create_rule_set​

Purpose: Create machine-readable rule sets for automated validation

Parameters:

{
  "projectPath": "string (required)",
  "rulesetName": "string (required) - Name for the rule set",
  "rules": "array (required) - Rules to include in the set",
  "outputFormat": "string (enum: 'json'|'yaml', default: 'json')",
  "includeMetadata": "boolean (default: true)"
}

🗂️ File & Cache Management​

read_file​

⚠️ Removed in ADR-023. Use the MCP host's native file-read capability instead.

Purpose: Read files with security validation and content analysis

write_file​

⚠️ Removed in ADR-023. Use the MCP host's native file-write capability instead.

Purpose: Write files with safety checks and backup creation

list_directory​

⚠️ Removed in ADR-023. Use the MCP host's native directory-listing capability instead.

Purpose: List directory contents securely with filtering options


---

### `manage_cache`

**Purpose**: Manage analysis cache for performance optimization

**Parameters**:

```json
{
  "operation": "string (enum: 'clear'|'status'|'optimize'|'configure', required)",
  "cacheType": "string (optional) - Specific cache type",
  "maxAge": "number (optional) - Maximum cache age in seconds"
}

manage_todo_json​

Note: This tool does not exist in the current codebase (v2.14.12). This section needs to be regenerated from source.

Purpose: Manage TODO JSON files for task tracking

Parameters:

{
  "operation": "string (enum: 'read'|'write'|'update'|'delete', required)",
  "filePath": "string (optional) - Path to TODO JSON file",
  "todoData": "object (optional) - TODO data for write/update operations",
  "filter": "object (optional) - Filter criteria for read operations"
}

🔧 Configuration & Utilities​

configure_output_masking​

Purpose: Configure output masking for sensitive information protection

Parameters:

{
  "maskingRules": "array (required) - Masking rules configuration",
  "globalSettings": "object (optional) - Global masking settings",
  "testMode": "boolean (default: false) - Enable test mode"
}

request_action_confirmation​

Purpose: Request user confirmation before performing sensitive actions

Parameters:

{
  "action": "string (required) - Description of the action",
  "severity": "string (enum: 'low'|'medium'|'high'|'critical', default: 'medium')",
  "details": "object (optional) - Additional action details",
  "timeout": "number (optional) - Confirmation timeout in seconds"
}

AI Execution Status Check (removed in ADR-023)​

⚠️ Removed in ADR-023. This tool is no longer available on the wire.

Purpose: Check the current AI execution mode and status

Previously returned:

{
  "mode": "full|prompt",
  "aiProvider": "openrouter",
  "model": "anthropic/claude-3-sonnet",
  "status": "active|inactive",
  "config": {
    "temperature": 0.3,
    "maxTokens": 4096
  }
}

mcp_planning​

Purpose: MCP server planning and coordination for complex workflows

Parameters:

{
  "projectPath": "string (required)",
  "planningScope": "string (enum: 'project'|'architecture'|'deployment'|'comprehensive', default: 'comprehensive')",
  "includeTimeline": "boolean (default: true)",
  "stakeholders": "array (optional) - Project stakeholders"
}

📋 Response Patterns​

Standard Success Response​

{
  "status": "success",
  "data": {
    // Tool-specific response data
  },
  "metadata": {
    "executionTime": "number (milliseconds)",
    "toolVersion": "string",
    "confidence": "number (0-1)",
    "warnings": ["array of warnings"],
    "recommendations": ["array of recommendations"]
  }
}

Error Response​

{
  "status": "error",
  "error": {
    "code": "string - Error code",
    "message": "string - Human-readable error message",
    "details": "object - Additional error details",
    "suggestions": ["array of suggested fixes"]
  },
  "metadata": {
    "executionTime": "number",
    "toolVersion": "string"
  }
}

🚀 Getting Started​

Basic Project Analysis​

# Comprehensive project analysis
{
  "tool": "analyze_project_ecosystem",
  "arguments": {
    "projectPath": ".",
    "enhancedMode": true,
    "knowledgeEnhancement": true,
    "recursiveDepth": "comprehensive"
  }
}

Security-First Workflow​

# 1. Analyze content security
{
  "tool": "analyze_content_security",
  "arguments": {
    "content": "your-code-here",
    "securityLevel": "strict"
  }
}

# 2. Generate masking instructions
{
  "tool": "generate_content_masking",
  "arguments": {
    "content": "your-code-here",
    "securityFindings": "results-from-step-1"
  }
}

# 3. Check deployment readiness
{
  "tool": "deployment_readiness",
  "arguments": {
    "projectPath": ".",
    "environment": "production",
    "strictMode": true
  }
}

📚 Additional Resources​

🌐 ADR Aggregator Integration Tools​

These tools integrate with ADR Aggregator to provide centralized ADR management, cross-repository insights, and team collaboration features.

Prerequisites: Most tools require ADR_AGGREGATOR_API_KEY environment variable. Get your API key at adraggregator.com.

Tier Feature Matrix​

ToolFreePro+Team
sync_to_aggregator✅✅✅
get_adr_context✅✅✅
get_staleness_report✅✅✅
get_adr_templates✅✅✅
get_adr_priorities✅✅✅
analyze_gaps✅✅✅
get_gaps✅✅✅
get_adr_diagrams❌✅✅
validate_adr_compliance❌✅✅
update_implementation_status❌✅✅
get_knowledge_graph❌❌✅

sync_to_aggregator​

Purpose: Sync local ADRs to ADR Aggregator platform for centralized management

Tier: Free (with limits), Pro+, Team

Use Cases:

  • Push local ADRs to centralized platform
  • Enable cross-repository insights
  • Track ADR staleness across projects
  • Share ADRs with team members

Parameters:

{
  "full_sync": "boolean (default: false) - Replace all ADRs instead of incremental",
  "include_metadata": "boolean (default: true) - Include analysis metadata",
  "include_diagrams": "boolean (default: false) - Include Mermaid diagrams (Pro+)",
  "include_timeline": "boolean (default: false) - Include timeline data",
  "include_security_scan": "boolean (default: false) - Include security scan results",
  "include_code_links": "boolean (default: false) - Include AST-based code links (Pro+)",
  "adr_paths": "array (optional) - Specific ADR paths to sync",
  "projectPath": "string (optional) - Project path (defaults to PROJECT_PATH)"
}

Example Usage:

{
  "full_sync": false,
  "include_metadata": true,
  "include_timeline": true
}

Response Format:

# ADR Aggregator Sync Complete

## Summary

- **Repository:** owner/repo
- **ADRs Synced:** 5
- **Sync ID:** sync_abc123
- **Timestamp:** 2025-01-20T12:00:00Z
- **Tier:** pro

## Synced ADRs

- docs/adrs/001-use-typescript.md (accepted)
- docs/adrs/002-api-design.md (proposed)

get_adr_context​

Purpose: Get ADR context from aggregator for AI-assisted analysis

Tier: Free

Parameters:

{
  "include_diagrams": "boolean (optional) - Include Mermaid diagrams (Pro+)",
  "include_timeline": "boolean (default: true) - Include timeline data",
  "include_code_links": "boolean (optional) - Include code links (Pro+)",
  "include_research": "boolean (optional) - Include research context (Pro+)",
  "staleness_filter": "string (enum: 'all'|'fresh'|'stale'|'very_stale')",
  "graph_depth": "number (optional) - Knowledge graph depth (Team)",
  "projectPath": "string (optional) - Project path"
}

Example Usage:

{
  "include_timeline": true,
  "staleness_filter": "stale"
}

get_staleness_report​

Purpose: Get comprehensive ADR staleness report for governance

Tier: Free

Parameters:

{
  "threshold": "number (default: 90) - Days threshold for staleness",
  "projectPath": "string (optional) - Project path"
}

Response Format:

# ADR Staleness Report

## Summary

| Status     | Count |
| ---------- | ----- |
| Fresh      | 3     |
| Recent     | 2     |
| Stale      | 1     |
| Very Stale | 0     |

## Governance

- **Review Cycle Compliance:** 85%
- **Overdue Reviews:** 1

get_adr_templates​

Purpose: Get domain-specific ADR templates with best practices

Tier: Free (no API key required)

Parameters:

{
  "domain": "string (optional) - Domain filter (web_application, microservices, api, etc.)"
}

Available Domains:

  • web_application - Web application architecture patterns
  • microservices - Microservices design decisions
  • api - API design and versioning
  • database - Database selection and design
  • security - Security architecture decisions
  • infrastructure - Infrastructure and DevOps

get_adr_diagrams​

Purpose: Get Mermaid diagrams for ADR visualization

Tier: Pro+ required

Parameters:

{
  "adr_path": "string (optional) - Specific ADR path",
  "projectPath": "string (optional) - Project path"
}

Response Includes:

  • Workflow diagrams
  • Relationship diagrams
  • Impact flow diagrams

validate_adr_compliance​

Purpose: Validate ADR compliance with code implementation

Tier: Pro+ required

Parameters:

{
  "adr_paths": "array (optional) - Specific ADR paths to validate",
  "validation_type": "string (enum: 'implementation'|'architecture'|'security'|'all', default: 'all')",
  "projectPath": "string (optional) - Project path"
}

Response Format:

## ADR Compliance Results

### docs/adrs/001-use-typescript.md

| Metric           | Value        |
| ---------------- | ------------ |
| Compliance Score | **95%**      |
| Status           | ✅ compliant |
| Files Validated  | 12           |

### Findings

- ✅ All TypeScript files follow ADR guidelines
- ⚠️ 2 files using `any` type

### Recommendations

- Review files with `any` usage

get_knowledge_graph​

Purpose: Get cross-repository knowledge graph for enterprise insights

Tier: Team required

Parameters:

{
  "scope": "string (enum: 'repository'|'organization', default: 'repository')",
  "include_analytics": "boolean (default: true) - Include graph analytics",
  "projectPath": "string (optional) - Project path"
}

Response Includes:

  • Graph nodes and relationships
  • Cross-repository patterns
  • Pattern trends over time
  • Most connected ADRs
  • Orphan decisions (no links)

update_implementation_status​

Purpose: Update implementation status of synced ADRs

Tier: Pro+ required

Parameters:

{
  "updates": [
    {
      "adr_path": "string (required) - Path to ADR",
      "implementation_status": "string (enum: 'not_started'|'in_progress'|'implemented'|'deprecated'|'blocked')",
      "notes": "string (optional) - Status change notes"
    }
  ],
  "projectPath": "string (optional) - Project path"
}

Example Usage:

{
  "updates": [
    {
      "adr_path": "docs/adrs/001-use-typescript.md",
      "implementation_status": "implemented",
      "notes": "Migration completed in v2.0"
    },
    {
      "adr_path": "docs/adrs/002-api-design.md",
      "implementation_status": "in_progress"
    }
  ]
}

get_adr_priorities​

Purpose: Get ADR priorities for roadmap and backlog planning

Tier: Free

Parameters:

{
  "include_ai": "boolean (optional) - Include AI-based priority recommendations",
  "projectPath": "string (optional) - Project path"
}

Response Format:

# ADR Priorities

## Summary

- **Total ADRs:** 5
- **Implemented:** 2
- **In Progress:** 1
- **Not Started:** 2

## Prioritized Roadmap

### 1. Authentication Strategy

- **Priority Score:** 85/100 (AI)
- **Status:** ⏳ not_started
- **Dependencies:** None
- **Gap Count:** 3

analyze_gaps​

Purpose: Analyze gaps between ADRs and codebase

Tier: Free

Use Cases:

  • Detect missing file references in ADRs
  • Find technologies without ADR coverage
  • Identify architectural patterns lacking documentation

Parameters:

{
  "projectPath": "string (optional) - Project path",
  "reportToAggregator": "boolean (default: true) - Report gaps to aggregator",
  "includeDismissed": "boolean (default: false) - Include dismissed gaps",
  "scanDirectories": "array (optional) - Directories to scan (default: ['src', 'lib', 'app'])",
  "includePatterns": "array (optional) - File patterns to include",
  "excludePatterns": "array (optional) - File patterns to exclude"
}

Gap Types:

  • adr_to_code: File referenced in ADR doesn't exist
  • code_to_adr: Technology/pattern in code without ADR coverage

Response Format:

# Gap Analysis Report

## Summary

- **Files Scanned:** 150
- **ADRs Checked:** 5
- **Total Gaps Found:** 3
  - Errors: 1
  - Warnings: 2

## ADR-to-Code Gaps (1)

### ❌ Missing referenced file: src/auth/oauth.ts

- **ADR:** docs/adrs/003-auth-strategy.md
- **Description:** ADR references file that doesn't exist

## Code-to-ADR Gaps (2)

### ⚠️ Undocumented technology: redis

- **Pattern Type:** ioredis usage
- **Suggested ADR Title:** "Caching Strategy with Redis"

get_gaps​

Purpose: Get current gaps from ADR Aggregator

Tier: Free

Parameters:

{
  "projectPath": "string (optional) - Project path",
  "includeDismissed": "boolean (optional) - Include dismissed gaps",
  "includeResolved": "boolean (optional) - Include resolved gaps"
}

📚 Additional Resources​

Deprecated tools​

The following eight host-native tools are deprecated under ADR-023. They still work today — they remain registered and dispatched — but they duplicate capabilities the MCP host already provides natively and will be removed in a later, retirement-gated step. Prefer the host-provided replacement in each row.

  • read_file — DEPRECATED host-native, ADR-023. Replaced by the MCP host's own file-read capability.
  • write_file — DEPRECATED host-native, ADR-023. Replaced by the MCP host's own file-write capability.
  • list_directory — DEPRECATED host-native, ADR-023. Replaced by the MCP host's own directory-listing capability.
  • read_directory — DEPRECATED host-native, ADR-023. Replaced by the MCP host's own directory-read capability.
  • list_roots — DEPRECATED host-native, ADR-023. Replaced by the MCP host's native roots capability (roots/list).
  • search_tools — DEPRECATED host-native, ADR-023. Replaced by MCP progressive tool discovery (native tools/list pagination).
  • load_prompt — DEPRECATED host-native, ADR-023. Replaced by the MCP host's native prompts capability (prompts/list and prompts/get).
  • get_current_datetime — DEPRECATED host-native, ADR-023. Replaced by the host environment's own date/time capability.

Last updated: September 2026 | Version 2.14.12