Skip to content

MCP Tools Reference

The AutoDocs MCP Server provides 8 production-ready MCP tools organized into three functional categories. Each tool follows MCP protocol standards and provides structured JSON responses.

Tool Categories Overview

Category Tools Purpose
Core Documentation scan_dependencies, get_package_docs, get_package_docs_with_context Parse projects and fetch documentation
Cache Management refresh_cache, get_cache_stats Manage documentation cache
System Health health_check, ready_check, get_metrics Monitor system status

Core Documentation Tools

scan_dependencies

Purpose: Parse Python project dependencies from pyproject.toml files with graceful error handling.

Parameters

Parameter Type Required Default Description
project_path string No Current directory Path to project directory containing pyproject.toml

Response Structure

{
  "success": true,
  "project_name": "my-fastapi-app",
  "total_dependencies": 12,
  "successfully_parsed": 10,
  "failed_to_parse": 2,
  "dependencies": [
    {
      "name": "fastapi",
      "version_constraint": ">=0.100.0",
      "category": "main"
    },
    {
      "name": "pytest",
      "version_constraint": "^7.0.0",
      "category": "dev"
    }
  ],
  "parsing_errors": [
    {
      "raw_spec": "invalid-package==",
      "error": "Invalid version constraint"
    }
  ],
  "metadata": {
    "python_requires": ">=3.8",
    "description": "My FastAPI application"
  }
}

Use Cases

  • Project Discovery: Understand what packages a project uses
  • Dependency Analysis: Get structured dependency information
  • Version Constraint Validation: Identify malformed dependency specifications
  • Development Setup: Prepare environment for new projects

Example Usage

AI assistants can use this tool when users ask questions like: - "What packages does this project use?" - "Show me the project dependencies" - "What version of FastAPI is required?"

get_package_docs_with_context ⭐

Purpose: Retrieve comprehensive documentation context including the requested package and its most relevant dependencies with smart scoping. This is the primary Phase 4 tool for rich AI context.

Parameters

Parameter Type Required Default Description
package_name string Yes - Primary package name to document
version_constraint string No Latest Version constraint for primary package
include_dependencies boolean No true Whether to include dependency context
context_scope string No "smart" Context scope: "primary_only", "runtime", or "smart"
max_dependencies integer No 8 Maximum number of dependencies to include
max_tokens integer No 30000 Maximum token budget for context

Context Scope Options

  • "primary_only": Only the requested package, no dependencies
  • "runtime": Include all runtime dependencies (excludes dev/test dependencies)
  • "smart": Intelligent selection of most relevant dependencies based on framework awareness

Response Structure

{
  "success": true,
  "context": {
    "primary_package": {
      "name": "fastapi",
      "version": "0.104.1",
      "summary": "FastAPI framework, high performance, easy to learn, fast to code, ready for production",
      "key_features": [
        "Automatic interactive API documentation",
        "Based on standard Python type hints",
        "High performance, on par with NodeJS and Go"
      ],
      "main_classes": ["FastAPI", "APIRouter", "Depends", "HTTPException"],
      "key_functions": ["Depends", "HTTPException", "status"],
      "usage_examples": "from fastapi import FastAPI\n\napp = FastAPI()\n\n@app.get('/')\ndef read_root():\n    return {'Hello': 'World'}",
      "documentation_url": "https://fastapi.tiangolo.com/"
    },
    "runtime_dependencies": [
      {
        "name": "pydantic",
        "version": "2.5.1",
        "why_included": "Required by fastapi for data validation",
        "relevance_score": 0.95,
        "summary": "Data validation using Python type hints",
        "key_features": [
          "Data validation and settings management",
          "JSON serialization/deserialization"
        ],
        "main_classes": ["BaseModel", "Field", "validator"]
      },
      {
        "name": "starlette",
        "version": "0.27.0",
        "why_included": "Required by fastapi as ASGI foundation",
        "relevance_score": 0.90,
        "summary": "Lightweight ASGI framework/toolkit",
        "key_features": [
          "ASGI framework foundation",
          "Routing and middleware support"
        ],
        "main_classes": ["Request", "Response", "Middleware"]
      }
    ],
    "context_metadata": {
      "total_packages": 3,
      "context_scope": "smart (2 runtime deps)",
      "token_estimate": 15420,
      "truncated": false,
      "framework_detected": "FastAPI"
    }
  },
  "performance": {
    "total_time_seconds": 0.89,
    "cache_hits": 1,
    "cache_misses": 2,
    "network_requests": 2,
    "concurrent_fetches": 2
  }
}

Smart Framework Detection

The tool includes special handling for major frameworks:

Framework Enhanced Dependencies Priority Boost
FastAPI pydantic, starlette, uvicorn +0.3 relevance
Django django-rest-framework, psycopg2 +0.2 relevance
Flask werkzeug, jinja2, flask-sqlalchemy +0.2 relevance
SQLAlchemy alembic, psycopg2, pymysql +0.2 relevance

Use Cases

  • AI Code Generation: Provide comprehensive context for accurate code suggestions
  • Framework Learning: Understand how packages work together in ecosystems
  • API Integration: Get complete context for API libraries and their dependencies
  • Troubleshooting: Understand package relationships when debugging issues

Example Usage

AI assistants use this tool when users ask questions like: - "Help me build a FastAPI application with user authentication" - "Show me how to use SQLAlchemy with async support" - "What are the key features of the requests library?"

get_package_docs (Legacy)

Purpose: Retrieve basic documentation for a single package without dependency context. This is the legacy tool - prefer get_package_docs_with_context for rich AI contexts.

Parameters

Parameter Type Required Default Description
package_name string Yes - Package name to document
version_constraint string No Latest Version constraint for the package
query string No None Filter documentation sections by keyword

Response Structure

{
  "success": true,
  "package": {
    "name": "requests",
    "version": "2.31.0",
    "summary": "Python HTTP for Humans",
    "key_features": [
      "Simple HTTP library for Python",
      "Built-in JSON decoder",
      "Automatic decompression"
    ],
    "main_classes": ["Session", "Request", "Response"],
    "usage_examples": "import requests\n\nr = requests.get('https://api.github.com')\nprint(r.json())"
  },
  "performance": {
    "fetch_time_seconds": 0.12,
    "cache_hit": true
  }
}

Use Cases

  • Simple Package Lookup: Quick documentation for single packages
  • Legacy Integration: Existing code that depends on the simpler interface
  • Minimal Context: When you specifically don't want dependency information

Cache Management Tools

refresh_cache

Purpose: Clear the local documentation cache to force fresh fetches from PyPI.

Parameters

None - this tool takes no parameters.

Response Structure

{
  "success": true,
  "cache_cleared": true,
  "statistics": {
    "files_removed": 45,
    "space_freed_mb": 12.3,
    "cache_directory": "/Users/user/.cache/autodoc-mcp"
  },
  "message": "Cache successfully cleared"
}

Use Cases

  • Force Refresh: Clear stale cache entries
  • Debugging: Eliminate cache-related issues
  • Development: Test with fresh documentation fetches
  • Maintenance: Regular cache cleanup

Example Usage

AI assistants use this when users ask: - "Clear the AutoDocs cache" - "Refresh the documentation cache" - "Remove cached documentation"

get_cache_stats

Purpose: View statistics about the documentation cache including cached packages and performance metrics.

Parameters

None - this tool takes no parameters.

Response Structure

{
  "success": true,
  "cache_info": {
    "total_entries": 127,
    "total_size_mb": 45.2,
    "cache_directory": "/Users/user/.cache/autodoc-mcp",
    "oldest_entry": "2024-01-15T10:30:00Z",
    "newest_entry": "2024-08-10T14:25:00Z"
  },
  "performance_stats": {
    "total_requests": 1543,
    "cache_hits": 1205,
    "cache_misses": 338,
    "hit_rate_percent": 78.1,
    "average_response_time_ms": 45
  },
  "cached_packages": [
    {
      "name": "fastapi",
      "version": "0.104.1",
      "cached_at": "2024-08-10T14:25:00Z",
      "size_kb": 234
    },
    {
      "name": "pydantic",
      "version": "2.5.1",
      "cached_at": "2024-08-10T14:24:00Z",
      "size_kb": 189
    }
  ]
}

Use Cases

  • Cache Monitoring: Understand cache performance and usage
  • Storage Management: Monitor disk space usage
  • Performance Analysis: Analyze hit rates and response times
  • Debugging: Verify which packages are cached

Example Usage

AI assistants use this when users ask: - "What's the status of the AutoDocs cache?" - "How much space is the documentation cache using?" - "Show me cache performance statistics"

System Health & Monitoring Tools

health_check

Purpose: Comprehensive health status check for monitoring systems and load balancers.

Parameters

None - this tool takes no parameters.

Response Structure

{
  "success": true,
  "overall_status": "healthy",
  "timestamp": "2024-08-10T14:30:00Z",
  "components": {
    "cache_system": {
      "status": "healthy",
      "details": {
        "cache_directory_accessible": true,
        "cache_write_test": "passed",
        "cache_read_test": "passed"
      }
    },
    "network_connectivity": {
      "status": "healthy",
      "details": {
        "pypi_reachable": true,
        "dns_resolution": "working",
        "last_successful_request": "2024-08-10T14:29:45Z"
      }
    },
    "core_services": {
      "status": "healthy",
      "details": {
        "dependency_parser": "initialized",
        "context_fetcher": "initialized",
        "doc_fetcher": "initialized"
      }
    }
  },
  "system_info": {
    "version": "0.4.2",
    "uptime_seconds": 3600,
    "python_version": "3.11.5",
    "memory_usage_mb": 128.5
  }
}

Health Status Values

  • "healthy": All systems operational
  • "degraded": Some non-critical issues present
  • "unhealthy": Critical systems failing

Use Cases

  • Load Balancer Checks: Determine if instance can handle traffic
  • Monitoring Systems: Automated health monitoring
  • Debugging: Diagnose system-level issues
  • Operations: Pre-deployment health verification

ready_check

Purpose: Kubernetes-style readiness check for deployment orchestration.

Parameters

None - this tool takes no parameters.

Response Structure

{
  "success": true,
  "ready": true,
  "timestamp": "2024-08-10T14:30:00Z",
  "checks": {
    "services_initialized": true,
    "cache_accessible": true,
    "network_available": true
  },
  "message": "Service ready to handle requests"
}

Ready States

  • ready: true: Service can handle MCP requests
  • ready: false: Service is initializing or has critical issues

Use Cases

  • Container Orchestration: Kubernetes readiness probes
  • Deployment Automation: Wait for service readiness
  • Load Balancing: Route traffic only to ready instances
  • CI/CD Pipelines: Verify deployment success

get_metrics

Purpose: Detailed system performance metrics for monitoring and analysis.

Parameters

None - this tool takes no parameters.

Response Structure

{
  "success": true,
  "timestamp": "2024-08-10T14:30:00Z",
  "performance_metrics": {
    "request_stats": {
      "total_requests": 1543,
      "successful_requests": 1498,
      "failed_requests": 45,
      "success_rate_percent": 97.1,
      "average_response_time_ms": 245,
      "p95_response_time_ms": 850,
      "p99_response_time_ms": 1200
    },
    "cache_metrics": {
      "cache_hits": 1205,
      "cache_misses": 338,
      "hit_rate_percent": 78.1,
      "total_cached_packages": 127,
      "cache_size_mb": 45.2
    },
    "network_metrics": {
      "pypi_requests": 892,
      "successful_fetches": 847,
      "failed_fetches": 45,
      "average_fetch_time_ms": 180,
      "concurrent_request_count": 3
    },
    "system_metrics": {
      "memory_usage_mb": 128.5,
      "cpu_usage_percent": 12.3,
      "uptime_seconds": 3600,
      "active_connections": 5
    }
  },
  "error_summary": {
    "network_errors": 23,
    "parsing_errors": 12,
    "cache_errors": 8,
    "other_errors": 2
  }
}

Metric Categories

  • Request Stats: MCP tool invocation performance
  • Cache Metrics: Documentation cache performance
  • Network Metrics: PyPI API interaction performance
  • System Metrics: Resource usage and system health
  • Error Summary: Error counts by category

Use Cases

  • Performance Monitoring: Track system performance over time
  • Capacity Planning: Understand resource usage patterns
  • SLA Monitoring: Verify response time commitments
  • Optimization: Identify performance bottlenecks

Tool Selection Guide

For AI Assistants

Primary Tool: Use get_package_docs_with_context for most documentation requests.

When to use each tool:

User Request Recommended Tool Reason
"Help me with FastAPI" get_package_docs_with_context Provides FastAPI + pydantic + starlette context
"What packages does this project use?" scan_dependencies Analyzes local project structure
"Clear the documentation cache" refresh_cache Direct cache management
"Is AutoDocs working properly?" health_check Comprehensive status check

For Monitoring Systems

Use Case Tool Integration Pattern
Load Balancer Health health_check HTTP 200 if healthy
Kubernetes Readiness ready_check Pod readiness probe
Performance Monitoring get_metrics Periodic metric collection
Cache Monitoring get_cache_stats Storage and performance tracking

Error Handling

All tools return consistent error structures:

{
  "success": false,
  "error": {
    "type": "NetworkError",
    "message": "Failed to connect to PyPI",
    "details": {
      "url": "https://pypi.org/pypi/fastapi/json",
      "timeout_seconds": 15
    },
    "suggestion": "Check network connectivity and try again"
  }
}

Common error types: - NetworkError: PyPI connectivity issues - ValidationError: Invalid parameters - CacheError: Cache system issues - ParsingError: Package metadata parsing failures - RateLimitError: PyPI rate limiting

Each error includes actionable suggestions for resolution.