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,
                  },
              }