AutoDocs MCP Server

Instructions

Implementation Reference

• src/autodoc_mcp/main.py:203-364 (handler)

  The core handler function for the 'get_package_docs' MCP tool. Decorated with @mcp.tool for automatic registration and schema inference from type hints and docstring. Implements version resolution, caching, documentation fetching from PyPI, formatting, and comprehensive error handling.
  @mcp.tool async def get_package_docs( package_name: str, version_constraint: str | None = None, query: str | None = None ) -> dict[str, Any]: """ Retrieve formatted documentation for a package with version-based caching. This is the legacy single-package documentation tool. For rich context with dependencies, use get_package_docs_with_context instead. Args: package_name: Name of the package to fetch documentation for version_constraint: Version constraint from dependency scanning query: Optional query to filter documentation sections Returns: Formatted documentation with package metadata """ from .observability import get_metrics_collector, track_request async with track_request("get_package_docs") as metrics: if cache_manager is None or version_resolver is None: get_metrics_collector().finish_request( metrics.request_id, success=False, error_type="ServiceNotInitialized", package_name=package_name, ) return { "success": False, "error": { "message": "Services not initialized", "suggestion": "Try again or restart the MCP server", "severity": "critical", "code": "service_not_initialized", "recoverable": False, }, } try: # Validate inputs validated_package_name = InputValidator.validate_package_name(package_name) if version_constraint is not None: validated_constraint = InputValidator.validate_version_constraint( version_constraint ) else: validated_constraint = None logger.info( "Fetching package docs", package=validated_package_name, constraint=validated_constraint, query=query, ) # Step 1: Resolve to specific version resolved_version = await version_resolver.resolve_version( validated_package_name, validated_constraint ) # Step 2: Check version-specific cache cache_key = version_resolver.generate_cache_key( validated_package_name, resolved_version ) cached_entry = await cache_manager.get(cache_key) if cached_entry: logger.info( "Version-specific cache hit", package=validated_package_name, version=resolved_version, constraint=version_constraint, ) package_info = cached_entry.data from_cache = True else: logger.info( "Fetching fresh package info", package=validated_package_name, version=resolved_version, ) async with PyPIDocumentationFetcher() as fetcher: package_info = await fetcher.fetch_package_info( validated_package_name ) await cache_manager.set(cache_key, package_info) from_cache = False # Step 3: Format documentation async with PyPIDocumentationFetcher() as fetcher: formatted_docs = fetcher.format_documentation(package_info, query) # Record successful metrics get_metrics_collector().finish_request( metrics.request_id, success=True, cache_hit=from_cache, package_name=validated_package_name, ) return { "success": True, "package_name": package_info.name, "version": package_info.version, "resolved_version": resolved_version, "version_constraint": version_constraint, "documentation": formatted_docs, "from_cache": from_cache, "cache_key": cache_key, "query_applied": query is not None, } except AutoDocsError as e: formatted_error = ErrorFormatter.format_exception( e, {"package": validated_package_name} ) logger.error( "Documentation fetch failed", package=validated_package_name, error=str(e), error_type=type(e).__name__, ) get_metrics_collector().finish_request( metrics.request_id, success=False, error_type="AutoDocsError", package_name=package_name, ) return { "success": False, "error": { "message": formatted_error.message, "suggestion": formatted_error.suggestion, "severity": formatted_error.severity.value, "code": formatted_error.error_code, "recoverable": formatted_error.recoverable, }, } except Exception as e: formatted_error = ErrorFormatter.format_exception( e, {"package": validated_package_name} ) logger.error("Unexpected error during documentation fetch", error=str(e)) get_metrics_collector().finish_request( metrics.request_id, success=False, error_type=type(e).__name__, package_name=package_name, ) return { "success": False, "error": { "message": formatted_error.message, "suggestion": formatted_error.suggestion, "severity": formatted_error.severity.value, "code": formatted_error.error_code, "recoverable": formatted_error.recoverable, }, }