Skip to main content

MCP Tools API Reference

DocuMCP provides a comprehensive set of tools via the Model Context Protocol (MCP). These tools enable intelligent documentation deployment through repository analysis, SSG recommendations, and automated GitHub Pages setup.

Implementation Details​

DocuMCP implements the MCP protocol using the low-level Server class from @modelcontextprotocol/sdk/server/index.js with StdioServerTransport for process-based communication. Tools are registered manually using setRequestHandler with CallToolRequestSchema and ListToolsRequestSchema, providing full control over tool execution and response formatting.

Core Documentation Tools​

analyze_repository​

Description: Analyze repository structure, dependencies, and documentation needs

Parameters:

  • path (string, required): Path to the repository to analyze
  • depth (enum, optional): Analysis depth level
    • "quick": Fast overview focusing on basic structure
    • "standard": Comprehensive analysis (default)
    • "deep": Detailed analysis with advanced insights

Returns: Analysis object containing:

  • id: Unique analysis identifier for use in other tools
  • timestamp: Analysis execution time
  • structure: File counts, languages, and project features
  • dependencies: Package ecosystem and dependency analysis
  • documentation: Existing documentation assessment
  • recommendations: Project classification and team size estimates

Example:

{
  "path": "/path/to/repository",
  "depth": "standard"
}

recommend_ssg​

Description: Recommend the best static site generator based on project analysis

Parameters:

  • analysisId (string, required): ID from previous repository analysis
  • preferences (object, optional):
    • priority: "simplicity", "features", or "performance"
    • ecosystem: "javascript", "python", "ruby", "go", or "any"

Returns: Recommendation object with weighted scoring and justifications

Example:

{
  "analysisId": "analysis_abc123",
  "preferences": {
    "priority": "simplicity",
    "ecosystem": "javascript"
  }
}

generate_config​

Description: Generate configuration files for the selected static site generator

Parameters:

  • ssg (enum, required): "jekyll", "hugo", "docusaurus", "mkdocs", or "eleventy"
  • projectName (string, required): Name of the project
  • projectDescription (string, optional): Brief description
  • outputPath (string, required): Where to generate config files

Returns: Generated configuration files and setup instructions

Example:

{
  "ssg": "hugo",
  "projectName": "My Documentation Site",
  "outputPath": "./docs"
}

setup_structure​

Description: Create Diataxis-compliant documentation structure

Parameters:

  • path (string, required): Root path for documentation
  • ssg (enum, required): Static site generator type
  • includeExamples (boolean, optional, default: true): Include example content

Returns: Created directory structure following Diataxis framework:

  • tutorials/: Learning-oriented guides for skill acquisition (study context)
  • how-to/: Problem-solving guides for specific tasks (work context)
  • reference/: Information-oriented content for lookup and verification (information context)
  • explanation/: Understanding-oriented content for context and background (understanding context)

Example:

{
  "path": "./docs",
  "ssg": "mkdocs",
  "includeExamples": true
}

deploy_pages​

Description: Set up GitHub Pages deployment workflow

Parameters:

  • repository (string, required): Repository path or URL
  • ssg (enum, required): Static site generator type
  • branch (string, optional, default: "gh-pages"): Deployment branch
  • customDomain (string, optional): Custom domain name

Returns: GitHub Actions workflow files for automated deployment

Example:

{
  "repository": "username/repository",
  "ssg": "docusaurus",
  "customDomain": "docs.example.com"
}

verify_deployment​

Description: Verify and troubleshoot GitHub Pages deployment

Parameters:

  • repository (string, required): Repository path or URL
  • url (string, optional): Expected deployment URL

Returns: Deployment status and troubleshooting recommendations

Example:

{
  "repository": "username/repository",
  "url": "https://username.github.io/repository"
}

Content Management Tools​

populate_diataxis_content​

Description: Intelligently populate Diataxis documentation with project-specific content

Parameters:

  • analysisId (string, required): Repository analysis ID
  • docsPath (string, required): Path to documentation directory
  • populationLevel (enum, optional, default: "comprehensive"): Content generation level
  • includeProjectSpecific (boolean, optional, default: true): Include project-specific content
  • preserveExisting (boolean, optional, default: true): Preserve existing content
  • technologyFocus (array of strings, optional): Specific technologies to emphasize

Returns: Populated content metrics and file creation summary

update_existing_documentation​

Description: Intelligently analyze and update existing documentation using memory insights

Parameters:

  • analysisId (string, required): Repository analysis ID
  • docsPath (string, required): Path to existing documentation directory
  • compareMode (enum, optional, default: "comprehensive"): Comparison mode
  • updateStrategy (enum, optional, default: "moderate"): Update aggressiveness
  • preserveStyle (boolean, optional, default: true): Preserve existing style
  • focusAreas (array of strings, optional): Specific areas to focus on

Returns: Update recommendations and gap analysis

detect_documentation_gaps​

Description: Analyze repository and existing documentation to identify missing content

Parameters:

  • repositoryPath (string, required): Path to the repository
  • documentationPath (string, optional): Path to existing documentation
  • analysisId (string, optional): Optional existing analysis ID to reuse
  • depth (enum, optional, default: "standard"): Analysis depth

Returns: Identified gaps and recommendations for improvement

Validation Tools​

validate_diataxis_content​

Description: Validate the accuracy, completeness, and compliance of generated Diataxis documentation

Parameters:

  • contentPath (string, required): Path to documentation directory to validate
  • analysisId (string, optional): Repository analysis ID for context
  • validationType (enum, optional, default: "all"): Type of validation
  • includeCodeValidation (boolean, optional, default: true): Validate code examples
  • confidence (enum, optional, default: "moderate"): Validation confidence level

Returns: Validation results with issues, recommendations, and confidence scores

validate_content​

Description: Validate general content quality including links and code syntax

Parameters:

  • contentPath (string, required): Path to content directory
  • validationType (string, optional, default: "all"): Validation type
  • includeCodeValidation (boolean, optional, default: true): Validate code blocks
  • followExternalLinks (boolean, optional, default: false): Check external URLs

Returns: Content validation results with broken links and code errors

Description: Comprehensive link checking for documentation deployment

Parameters:

  • documentation_path (string, optional, default: "./docs"): Documentation directory
  • check_external_links (boolean, optional, default: true): Validate external URLs
  • check_internal_links (boolean, optional, default: true): Validate internal references
  • check_anchor_links (boolean, optional, default: true): Validate anchor links
  • timeout_ms (number, optional, default: 5000): Request timeout
  • max_concurrent_checks (number, optional, default: 5): Concurrent check limit

Returns: Comprehensive link validation report

Testing and Deployment Tools​

test_local_deployment​

Description: Test documentation build and local server before deploying to GitHub Pages

Parameters:

  • repositoryPath (string, required): Path to the repository
  • ssg (enum, required): Static site generator type
  • port (number, optional, default: 3000): Local server port
  • timeout (number, optional, default: 60): Build timeout in seconds
  • skipBuild (boolean, optional, default: false): Skip build step

Returns: Local testing results and server status

README Management Tools​

evaluate_readme_health​

Description: Evaluate README files for community health and onboarding effectiveness

Parameters:

  • readme_path (string, required): Path to README file
  • project_type (enum, optional, default: "community_library"): Project type
  • repository_path (string, optional): Repository path for context

Returns: Health evaluation with scores and recommendations

readme_best_practices​

Description: Analyze README files against best practices checklist

Parameters:

  • readme_path (string, required): Path to README file
  • project_type (enum, optional, default: "library"): Project type
  • generate_template (boolean, optional, default: false): Generate templates
  • target_audience (enum, optional, default: "mixed"): Target audience

Returns: Best practices analysis and improvement recommendations

generate_readme_template​

Description: Generate standardized README templates for different project types

Parameters:

  • projectName (string, required): Name of the project
  • description (string, required): Brief project description
  • templateType (enum, required): Project template type
  • author (string, optional): Project author/organization
  • license (string, optional, default: "MIT"): Project license
  • outputPath (string, optional): Output file path

Returns: Generated README template content

validate_readme_checklist​

Description: Validate README files against community best practices checklist

Parameters:

  • readmePath (string, required): Path to README file
  • projectPath (string, optional): Project directory for context
  • strict (boolean, optional, default: false): Use strict validation
  • outputFormat (enum, optional, default: "console"): Output format

Returns: Validation report with detailed scoring

analyze_readme​

Description: Comprehensive README analysis with length assessment and optimization opportunities

Parameters:

  • project_path (string, required): Path to project directory
  • target_audience (enum, optional, default: "community_contributors"): Target audience
  • optimization_level (enum, optional, default: "moderate"): Optimization level
  • max_length_target (number, optional, default: 300): Target max length

Returns: README analysis with optimization recommendations

optimize_readme​

Description: Optimize README content by restructuring and condensing

Parameters:

  • readme_path (string, required): Path to README file
  • strategy (enum, optional, default: "community_focused"): Optimization strategy
  • max_length (number, optional, default: 300): Target maximum length
  • include_tldr (boolean, optional, default: true): Include TL;DR section
  • create_docs_directory (boolean, optional, default: true): Create docs directory

Returns: Optimized README content and extracted documentation

Documentation Freshness Tracking Tools​

DocuMCP includes comprehensive tools for tracking and managing documentation freshness, ensuring your documentation stays up-to-date and identifying files that need attention.

track_documentation_freshness​

Description: Scan documentation directory for staleness markers and identify files needing updates based on configurable time thresholds (minutes, hours, days)

Parameters:

  • docsPath (string, required): Path to documentation directory
  • projectPath (string, optional): Path to project root (for knowledge graph tracking)
  • warningThreshold (object, optional): Warning threshold (yellow flag)
    • value (number, positive): Threshold value
    • unit (enum): "minutes", "hours", or "days"
  • staleThreshold (object, optional): Stale threshold (orange flag)
    • value (number, positive): Threshold value
    • unit (enum): "minutes", "hours", or "days"
  • criticalThreshold (object, optional): Critical threshold (red flag)
    • value (number, positive): Threshold value
    • unit (enum): "minutes", "hours", or "days"
  • preset (enum, optional): Use predefined threshold preset
    • Options: "realtime", "active", "recent", "weekly", "monthly", "quarterly"
  • includeFileList (boolean, optional, default: true): Include detailed file list in response
  • sortBy (enum, optional, default: "staleness"): Sort order for file list
    • Options: "age", "path", "staleness"
  • storeInKG (boolean, optional, default: true): Store tracking event in knowledge graph for historical analysis

Returns: Freshness report with:

  • Summary statistics (total files, fresh, warning, stale, critical)
  • Detailed file list with staleness levels
  • Age information for each file
  • Recommendations for action

Example:

{
  "docsPath": "/path/to/docs",
  "preset": "monthly",
  "includeFileList": true
}

Default Thresholds:

  • Warning: 7 days
  • Stale: 30 days
  • Critical: 90 days

validate_documentation_freshness​

Description: Validate documentation freshness, initialize metadata for files without it, and update timestamps based on code changes

Parameters:

  • docsPath (string, required): Path to documentation directory
  • projectPath (string, required): Path to project root (for git integration)
  • initializeMissing (boolean, optional, default: true): Initialize metadata for files without it
  • updateExisting (boolean, optional, default: false): Update last_validated timestamp for all files
  • updateFrequency (enum, optional, default: "monthly"): Default update frequency for new metadata
    • Options: "realtime", "active", "recent", "weekly", "monthly", "quarterly"
  • validateAgainstGit (boolean, optional, default: true): Validate against current git commit

Returns: Validation report with:

  • Files initialized (new metadata created)
  • Files updated (existing metadata refreshed)
  • Metadata structure for each file
  • Recommendations for next steps

Example:

{
  "docsPath": "/path/to/docs",
  "projectPath": "/path/to/project",
  "initializeMissing": true,
  "validateAgainstGit": true
}

Use Cases:

  • First-time setup: Initialize freshness metadata for all documentation files
  • Regular maintenance: Update validation timestamps
  • After code changes: Sync documentation freshness with git history

Sitemap Management Tools​

manage_sitemap​

Description: Generate, validate, and manage sitemap.xml as the source of truth for documentation links. Sitemap.xml is used for SEO, search engine submission, and deployment tracking.

Parameters:

  • action (enum, required): Action to perform
    • "generate": Create new sitemap.xml
    • "validate": Check sitemap structure
    • "update": Sync sitemap with documentation
    • "list": Show all URLs in sitemap
  • docsPath (string, required): Path to documentation root directory
  • baseUrl (string, required for generate/update): Base URL for the site (e.g., https://user.github.io/repo)
  • includePatterns (array, optional): File patterns to include
    • Default: ["**/*.md", "**/*.html", "**/*.mdx"]
  • excludePatterns (array, optional): File patterns to exclude
    • Default: ["node_modules", ".git", "dist", "build", ".documcp"]
  • updateFrequency (enum, optional): Default change frequency for pages
    • Options: "always", "hourly", "daily", "weekly", "monthly", "yearly", "never"
  • useGitHistory (boolean, optional, default: true): Use git history for last modified dates
  • sitemapPath (string, optional): Custom path for sitemap.xml (default: docsPath/sitemap.xml)

Returns: Sitemap operation result with:

  • Generated/validated sitemap structure
  • URL count and statistics
  • Validation errors (if any)
  • Recommendations for SEO optimization

Example:

{
  "action": "generate",
  "docsPath": "/path/to/docs",
  "baseUrl": "https://example.com/docs"
}

Use Cases:

  • SEO optimization: Generate sitemap for search engines
  • Link validation: Ensure all documentation pages are discoverable
  • Deployment tracking: Monitor documentation changes over time

User Preferences & Analytics Tools​

manage_preferences​

Description: Manage user preferences for personalized recommendations

Parameters:

  • action (enum, required): Action to perform
    • "get": Retrieve current preferences
    • "update": Update preferences
    • "reset": Reset to defaults
    • "export": Export preferences as JSON
    • "import": Import preferences from JSON
    • "recommendations": Get SSG recommendations based on preferences
  • userId (string, optional, default: "default"): User ID for multi-user setups
  • preferences (object, optional): Preference updates (for update action)
    • preferredSSGs (array, optional): List of preferred static site generators
    • documentationStyle (enum, optional): "minimal", "comprehensive", or "tutorial-heavy"
    • expertiseLevel (enum, optional): "beginner", "intermediate", or "advanced"
    • preferredTechnologies (array, optional): Preferred technologies and frameworks
    • preferredDiataxisCategories (array, optional): Preferred documentation categories
    • autoApplyPreferences (boolean, optional): Automatically apply preferences to recommendations
  • json (string, optional): JSON string for import action

Returns: Preference data or operation result

Example:

{
  "action": "get",
  "userId": "user123"
}

analyze_deployments​

Description: Analyze deployment patterns and generate insights

Parameters:

  • analysisType (enum, optional, default: "full_report"): Type of analysis
    • "full_report": Comprehensive analysis
    • "ssg_stats": Per-SSG statistics
    • "compare": Compare multiple SSGs
    • "health": Deployment health score
    • "trends": Temporal analysis
  • ssg (string, optional): SSG name for ssg_stats analysis
  • ssgs (array, optional): Array of SSG names for comparison
  • periodDays (number, optional, default: 30): Period in days for trend analysis

Returns: Analytics report with deployment insights

Example:

{
  "analysisType": "full_report"
}

Memory System Tools​

The memory system provides intelligent learning and pattern recognition across documentation projects.

memory_recall​

Description: Recall memories about a project or topic

Parameters:

  • query (string, required): Search query or project ID
  • type (enum, optional): Memory type to recall
  • limit (number, optional, default: 10): Maximum results

memory_insights​

Description: Get insights and patterns from memory

Parameters:

  • projectId (string, optional): Project ID to analyze
  • timeRange (object, optional): Time range for analysis

memory_similar​

Description: Find similar projects from memory

Parameters:

  • analysisId (string, required): Analysis ID to find similar projects for
  • limit (number, optional, default: 5): Maximum similar projects

memory_export​

Description: Export memories to JSON or CSV

Parameters:

  • filter (object, optional): Filter memories to export
  • format (enum, optional, default: "json"): Export format

memory_cleanup​

Description: Clean up old memories

Parameters:

  • daysToKeep (number, optional, default: 30): Number of days to retain
  • dryRun (boolean, optional, default: false): Preview without deleting

Tool Chaining and Workflows​

DocuMCP tools are designed to work together in workflows:

  1. Analysis → Recommendation → Implementation:

    analyze_repository → recommend_ssg → generate_config → setup_structure → deploy_pages

  2. Content Management:

    analyze_repository → populate_diataxis_content → validate_diataxis_content

  3. Documentation Maintenance:

    detect_documentation_gaps → update_existing_documentation → validate_content

  4. Freshness Tracking:

    validate_documentation_freshness → track_documentation_freshness → (update files as needed)

  5. SEO and Sitemap Management:

    manage_sitemap (generate) → deploy_pages → manage_sitemap (validate)

Error Handling​

All tools return structured responses with error information when failures occur:

{
  "content": [
    {
      "type": "text",
      "text": "Error executing tool_name: error_message"
    }
  ],
  "isError": true
}

Resource Storage​

Tool results are automatically stored as MCP resources with URIs like:

  • documcp://analysis/{id}: Analysis results
  • documcp://config/{ssg}/{id}: Configuration files
  • documcp://deployment/{id}: Deployment workflows

These resources can be accessed later for reference or further processing.

Version Information​

Current DocuMCP version: 0.5.2

For the latest updates and detailed changelog, see the project repository.

Recent Additions (v0.5.2)​

Documentation Freshness Tracking​

  • track_documentation_freshness: Monitor documentation staleness with configurable thresholds
  • validate_documentation_freshness: Initialize and update freshness metadata

Sitemap Management​

  • manage_sitemap: Generate, validate, and manage sitemap.xml for SEO and deployment tracking

These tools integrate with the knowledge graph system to provide historical analysis and intelligent recommendations.