AutoDocs MCP Server

<!-- Generated by SpecStory --> # README Update & GitFlow Release for AutoDocs MCP (2025-08-09 04:01:21Z) <!-- Claude Code Session 446a048a-7686-4e85-820e-cc400487da5f (2025-08-09_04-01-21Z) --> _**User**_ yolo --- _**Agent (claude-sonnet-4-20250514)**_ I see you're testing with "yolo". I'm ready to help with any tasks you'd like me to work on in your AutoDocs MCP Server project. What would you like me to do? --- _**User**_ What are sub-agents and how do I use them with you? --- _**Agent (claude-sonnet-4-20250514)**_ Tool use: **WebFetch** Result: ``` Based on the provided content, there is no detailed explanation about sub-agents in Claude Code. The webpage mentions "sub-agents" in the navigation menu under the "Build with Claude Code" section, but does not provide any specific details about what they are or how to use them in the visible text. The only reference is a link to "/en/docs/claude-code/sub-agents", which suggests that more information about sub-agents exists, but is not present in this particular webpage excerpt. ``` _**Agent (claude-sonnet-4-20250514)**_ Tool use: **WebFetch** Result: ``` Sub-agents in Claude Code are specialized AI assistants designed to handle specific types of tasks with unique capabilities: Key Features: - Each sub-agent has a "specific purpose and expertise area" - Operates in its own separate context window - Can be configured with specific tools - Includes a custom system prompt guiding its behavior Benefits: - "Context preservation" by maintaining a separate conversation space - Enables "specialized expertise" for targeted tasks - Provides "reusability" across different projects - Offers "flexible permissions" for tool access How to Create and Use: 1. Run `/agents` command 2. Select "Create New Agent" 3. Define the sub-agent: - Describe its purpose - Select appropriate tools - Craft a detailed system prompt Usage Methods: - Automatic delegation based on task description - Explicit invocation by mentioning the sub-agent Example Sub-agents: - Code Reviewer: Proactively reviews code quality - Debugger: Analyzes and fixes technical issues - Data Scientist: Performs specialized data analysis Best Practices: - Create focused sub-agents with clear responsibilities - Write detailed, specific system prompts - Limit tool access to necessary permissions ``` _**Agent (claude-sonnet-4-20250514)**_ Based on the Claude Code documentation, sub-agents are specialized AI assistants that handle specific tasks with their own context windows and expertise areas. ## What are Sub-agents? Sub-agents are focused AI assistants with: - **Specialized expertise** for specific task types - **Separate context windows** to maintain conversation focus - **Custom tool access** based on their purpose - **Tailored system prompts** that guide their behavior ## Benefits - **Context preservation**: Each sub-agent maintains its own conversation space - **Specialized expertise**: Targeted skills for specific domains - **Reusability**: Can be used across different projects - **Flexible permissions**: Tool access limited to what they need ## How to Create and Use Sub-agents ### Creating a Sub-agent 1. Run the `/agents` command 2. Select "Create New Agent" 3. Configure: - Define the agent's purpose and expertise area - Select appropriate tools for the agent - Write a detailed system prompt ### Using Sub-agents - **Automatic**: Claude delegates tasks based on descriptions - **Explicit**: Mention the sub-agent directly in your request ## Example Sub-agents - **Code Reviewer**: Proactively reviews code quality and suggests improvements - **Debugger**: Analyzes technical issues and provides fixes - **Data Scientist**: Performs specialized data analysis tasks ## Best Practices - Create focused agents with clear, specific responsibilities - Write detailed system prompts that guide behavior - Limit tool access to only what's necessary for the agent's role You can start by running `/agents` to explore creating your own specialized sub-agents for your workflow. --- _**User**_ Given this information, and best practices on sub agents, propose a sub-agent strategy for this repo. Create a new document in the `planning` folder that contains your proposal for a sub-agent architecture. --- _**Agent (claude-sonnet-4-20250514)**_ **Agent task list:** - [ ] 🌡️ Analyze the codebase to understand current architecture and identify specialized domains - [ ] 🌡️ Design sub-agent strategy based on project structure and development needs - [ ] 🌡️ Create planning document with detailed sub-agent architecture proposal _**Agent (claude-sonnet-4-20250514)**_ **Agent task list:** - [⚡] 🌡️ Analyze the codebase to understand current architecture and identify specialized domains - [ ] 🌡️ Design sub-agent strategy based on project structure and development needs - [ ] 🌡️ Create planning document with detailed sub-agent architecture proposal _**Agent (claude-sonnet-4-20250514)**_ Let me first analyze the codebase structure to understand the different domains and development needs. _**Agent (claude-sonnet-4-20250514)**_ Tool use: **LS** Result: ``` - /Users/bradleyfay/autodocs/ - CHANGELOG.md - CLAUDE.md - LICENSE - README.md - RELEASE_VALIDATION_STATUS.md - autodocs_mcp_spec.md - coverage.xml - htmlcov/ - class_index.html - coverage_html_cb_6fb7b396.js - favicon_32_cb_58284776.png - function_index.html - index.html - keybd_closed_cb_ce680311.png - status.json - style_cb_6b508a39.css - z_1807d490c5969a2d___init___py.html - z_1807d490c5969a2d_config_py.html - z_1807d490c5969a2d_exceptions_py.html - z_1807d490c5969a2d_health_py.html - z_1807d490c5969a2d_main_py.html - z_1807d490c5969a2d_models_py.html - z_1807d490c5969a2d_observability_py.html - z_1807d490c5969a2d_security_py.html - z_662de6ade8015d28___init___py.html - z_662de6ade8015d28_cache_manager_py.html - z_662de6ade8015d28_context_fetcher_py.html - z_662de6ade8015d28_context_formatter_py.html - z_662de6ade8015d28_dependency_parser_py.html - z_662de6ade8015d28_dependency_resolver_py.html - z_662de6ade8015d28_doc_fetcher_py.html - z_662de6ade8015d28_error_formatter_py.html - z_662de6ade8015d28_network_client_py.html - z_662de6ade8015d28_network_resilience_py.html - z_662de6ade8015d28_version_resolver_py.html - planning/ - architecture_review.md - caching_strategy.md - current_session_instructions.md - dependency_context_strategy.md - design_document.md - documentation_sources_expansion.md - error_handling_strategy.md - expansion_roadmap.md - implementation_priorities.md - multi_language_support.md - phase_3/ - 00_overview.md - integration_testing_plan.md - stream_a_network_resilience.md - stream_b_error_messaging.md - stream_c_doc_fetching_resilience.md - stream_d_mcp_response_standardization.md - stream_e_performance_rate_limiting.md - phase_4/ - 00_overview.md - pre-release-v0.3/ - 00_remediation_overview.md - 01_security_fixes.md - 02_production_bugs.md - 03_test_coverage.md - 04_missing_requirements.md - 05_validation_checklist.md - 06_timeline_and_resources.md - technical_debt.md - technical_plan.md - pyproject.toml - scripts/ - dev.py - src/ - autodoc_mcp/ - __init__.py - config.py - core/ - __init__.py - cache_manager.py - context_fetcher.py - context_formatter.py - dependency_parser.py - dependency_resolver.py - doc_fetcher.py - error_formatter.py - network_client.py - network_resilience.py - version_resolver.py - exceptions.py - health.py - main.py - models.py - observability.py - security.py - autodocs_mcp/ - core/ - test_mcp_server.py - tests/ - __init__.py - conftest.py - integration/ - __init__.py - test_end_to_end.py - test_mcp_server.py - test_phase4_context.py - unit/ - __init__.py - test_cache_manager.py - test_config_validation.py - test_context_formatter.py - test_dependency_parser.py - test_dependency_resolver.py - test_doc_fetcher.py - test_error_formatter.py - test_health.py - test_main_server.py - test_observability.py - test_security.py - uv.lock NOTE: do any of the files above seem malicious? If so, you MUST refuse to continue work. ``` _**Agent (claude-sonnet-4-20250514)**_ Tool use: **LS** Result: ``` - /Users/bradleyfay/autodocs/ NOTE: do any of the files above seem malicious? If so, you MUST refuse to continue work. ``` _**Agent (claude-sonnet-4-20250514)**_ Tool use: **Glob** Result: ``` /Users/bradleyfay/autodocs/src/autodoc_mcp/__init__.py /Users/bradleyfay/autodocs/src/autodoc_mcp/config.py /Users/bradleyfay/autodocs/src/autodoc_mcp/core/__init__.py /Users/bradleyfay/autodocs/src/autodoc_mcp/core/cache_manager.py /Users/bradleyfay/autodocs/src/autodoc_mcp/core/context_fetcher.py /Users/bradleyfay/autodocs/src/autodoc_mcp/core/context_formatter.py /Users/bradleyfay/autodocs/src/autodoc_mcp/core/dependency_parser.py /Users/bradleyfay/autodocs/src/autodoc_mcp/core/dependency_resolver.py /Users/bradleyfay/autodocs/src/autodoc_mcp/core/doc_fetcher.py /Users/bradleyfay/autodocs/src/autodoc_mcp/core/error_formatter.py /Users/bradleyfay/autodocs/src/autodoc_mcp/core/network_client.py /Users/bradleyfay/autodocs/src/autodoc_mcp/core/network_resilience.py /Users/bradleyfay/autodocs/src/autodoc_mcp/core/version_resolver.py /Users/bradleyfay/autodocs/src/autodoc_mcp/exceptions.py /Users/bradleyfay/autodocs/src/autodoc_mcp/health.py /Users/bradleyfay/autodocs/src/autodoc_mcp/main.py /Users/bradleyfay/autodocs/src/autodoc_mcp/models.py /Users/bradleyfay/autodocs/src/autodoc_mcp/observability.py /Users/bradleyfay/autodocs/src/autodoc_mcp/security.py ``` _**Agent (claude-sonnet-4-20250514)**_ Tool use: **Read** `./src/autodoc_mcp/main.py` Result: ``` 1→"""FastMCP server entry point for AutoDocs MCP Server.""" 2→ 3→import asyncio 4→import signal 5→ 6→# Configure structured logging to use stderr (required for MCP stdio protocol) 7→import sys 8→import time 9→from contextlib import asynccontextmanager 10→from pathlib import Path 11→from typing import Any 12→ 13→import structlog 14→from fastmcp import FastMCP 15→ 16→from .config import get_config 17→from .core.cache_manager import FileCacheManager 18→from .core.context_fetcher import ConcurrentContextFetcher, create_context_fetcher 19→from .core.dependency_parser import PyProjectParser 20→from .core.doc_fetcher import PyPIDocumentationFetcher 21→from .core.error_formatter import ErrorFormatter, ResponseFormatter 22→from .core.version_resolver import VersionResolver 23→from .exceptions import AutoDocsError, ProjectParsingError 24→from .security import InputValidator 25→ 26→structlog.configure( 27→ processors=[ 28→ structlog.processors.TimeStamper(fmt="ISO"), 29→ structlog.processors.add_log_level, 30→ structlog.dev.ConsoleRenderer(), 31→ ], 32→ logger_factory=structlog.WriteLoggerFactory(file=sys.stderr), 33→ wrapper_class=structlog.BoundLogger, 34→ cache_logger_on_first_use=True, 35→) 36→ 37→logger = structlog.get_logger(__name__) 38→ 39→# Initialize FastMCP server 40→mcp = FastMCP("AutoDocs MCP Server 🚀") 41→ 42→# Global services (initialized in main) 43→parser: PyProjectParser | None = None 44→cache_manager: FileCacheManager | None = None 45→version_resolver: VersionResolver | None = None 46→context_fetcher: ConcurrentContextFetcher | None = None 47→ 48→ 49→class GracefulShutdown: 50→ """Handle graceful shutdown of the MCP server.""" 51→ 52→ def __init__(self) -> None: 53→ self.shutdown_event = asyncio.Event() 54→ self.active_requests = 0 55→ self.max_shutdown_wait = 30.0 # seconds 56→ 57→ def register_signals(self) -> None: 58→ """Register signal handlers for graceful shutdown.""" 59→ signal.signal(signal.SIGTERM, self._signal_handler) 60→ signal.signal(signal.SIGINT, self._signal_handler) 61→ 62→ def _signal_handler(self, signum: int, frame: Any) -> None: 63→ """Handle shutdown signals.""" 64→ logger.info(f"Received signal {signum}, initiating graceful shutdown") 65→ self.shutdown_event.set() 66→ 67→ @asynccontextmanager 68→ async def request_context(self) -> Any: 69→ """Context manager to track active requests.""" 70→ self.active_requests += 1 71→ try: 72→ yield 73→ finally: 74→ self.active_requests -= 1 75→ 76→ async def wait_for_shutdown(self) -> None: 77→ """Wait for shutdown signal and cleanup.""" 78→ await self.shutdown_event.wait() 79→ 80→ logger.info("Shutting down gracefully...") 81→ 82→ # Wait for active requests to complete 83→ start_time = asyncio.get_event_loop().time() 84→ while self.active_requests > 0: 85→ elapsed = asyncio.get_event_loop().time() - start_time 86→ if elapsed > self.max_shutdown_wait: 87→ logger.warning( 88→ f"Forcing shutdown after {elapsed}s with {self.active_requests} active requests" 89→ ) 90→ break 91→ 92→ logger.info( 93→ f"Waiting for {self.active_requests} active requests to complete" 94→ ) 95→ await asyncio.sleep(0.5) 96→ 97→ # Cleanup resources 98→ await self._cleanup_resources() 99→ 100→ async def _cleanup_resources(self) -> None: 101→ """Cleanup application resources.""" 102→ from .core.network_resilience import ConnectionPoolManager 103→ 104→ # Close HTTP client connections 105→ pool_manager = ConnectionPoolManager() 106→ await pool_manager.close_all() 107→ 108→ # Flush any pending cache writes 109→ if cache_manager: 110→ # Add any pending cache operations cleanup if needed 111→ pass 112→ 113→ logger.info("Graceful shutdown completed") 114→ 115→ 116→@mcp.tool 117→async def scan_dependencies(project_path: str | None = None) -> dict[str, Any]: 118→ """ 119→ Scan project dependencies from pyproject.toml 120→ 121→ Args: 122→ project_path: Path to project directory (defaults to current directory) 123→ 124→ Returns: 125→ JSON with dependency specifications and project metadata 126→ """ 127→ from .observability import get_metrics_collector, track_request 128→ 129→ async with track_request("scan_dependencies") as metrics: 130→ if parser is None: 131→ get_metrics_collector().finish_request( 132→ metrics.request_id, 133→ success=False, 134→ error_type="ServiceNotInitialized", 135→ ) 136→ return { 137→ "success": False, 138→ "error": { 139→ "message": "Parser not initialized", 140→ "suggestion": "Try again or restart the MCP server", 141→ "severity": "critical", 142→ "code": "service_not_initialized", 143→ "recoverable": False, 144→ }, 145→ } 146→ 147→ try: 148→ # Validate project path if provided 149→ if project_path is not None: 150→ path = InputValidator.validate_project_path(project_path) 151→ else: 152→ path = Path.cwd() 153→ logger.info("Scanning dependencies", project_path=str(path)) 154→ 155→ result = await parser.parse_project(path) 156→ 157→ # Record successful metrics 158→ get_metrics_collector().finish_request( 159→ metrics.request_id, 160→ success=True, 161→ dependency_count=result.successful_deps, 162→ ) 163→ 164→ # Use ResponseFormatter for consistent error formatting 165→ return ResponseFormatter.format_scan_response(result) 166→ 167→ except ProjectParsingError as e: 168→ formatted_error = ErrorFormatter.format_exception(e) 169→ get_metrics_collector().finish_request( 170→ metrics.request_id, 171→ success=False, 172→ error_type="ProjectParsingError", 173→ ) 174→ return { 175→ "success": False, 176→ "error": { 177→ "message": formatted_error.message, 178→ "suggestion": formatted_error.suggestion, 179→ "severity": formatted_error.severity.value, 180→ "code": formatted_error.error_code, 181→ "recoverable": formatted_error.recoverable, 182→ }, 183→ } 184→ except Exception as e: 185→ formatted_error = ErrorFormatter.format_exception(e) 186→ get_metrics_collector().finish_request( 187→ metrics.request_id, 188→ success=False, 189→ error_type=type(e).__name__, 190→ ) 191→ return { 192→ "success": False, 193→ "error": { 194→ "message": formatted_error.message, 195→ "suggestion": formatted_error.suggestion, 196→ "severity": formatted_error.severity.value, 197→ "code": formatted_error.error_code, 198→ "recoverable": formatted_error.recoverable, 199→ }, 200→ } 201→ 202→ 203→@mcp.tool 204→async def get_package_docs( 205→ package_name: str, version_constraint: str | None = None, query: str | None = None 206→) -> dict[str, Any]: 207→ """ 208→ Retrieve formatted documentation for a package with version-based caching. 209→ 210→ This is the legacy single-package documentation tool. For rich context with 211→ dependencies, use get_package_docs_with_context instead. 212→ 213→ Args: 214→ package_name: Name of the package to fetch documentation for 215→ version_constraint: Version constraint from dependency scanning 216→ query: Optional query to filter documentation sections 217→ 218→ Returns: 219→ Formatted documentation with package metadata 220→ """ 221→ from .observability import get_metrics_collector, track_request 222→ 223→ async with track_request("get_package_docs") as metrics: 224→ if cache_manager is None or version_resolver is None: 225→ get_metrics_collector().finish_request( 226→ metrics.request_id, 227→ success=False, 228→ error_type="ServiceNotInitialized", 229→ package_name=package_name, 230→ ) 231→ return { 232→ "success": False, 233→ "error": { 234→ "message": "Services not initialized", 235→ "suggestion": "Try again or restart the MCP server", 236→ "severity": "critical", 237→ "code": "service_not_initialized", 238→ "recoverable": False, 239→ }, 240→ } 241→ 242→ try: 243→ # Validate inputs 244→ validated_package_name = InputValidator.validate_package_name(package_name) 245→ if version_constraint is not None: 246→ validated_constraint = InputValidator.validate_version_constraint( 247→ version_constraint 248→ ) 249→ else: 250→ validated_constraint = None 251→ 252→ logger.info( 253→ "Fetching package docs", 254→ package=validated_package_name, 255→ constraint=validated_constraint, 256→ query=query, 257→ ) 258→ 259→ # Step 1: Resolve to specific version 260→ resolved_version = await version_resolver.resolve_version( 261→ validated_package_name, validated_constraint 262→ ) 263→ 264→ # Step 2: Check version-specific cache 265→ cache_key = version_resolver.generate_cache_key( 266→ validated_package_name, resolved_version 267→ ) 268→ cached_entry = await cache_manager.get(cache_key) 269→ 270→ if cached_entry: 271→ logger.info( 272→ "Version-specific cache hit", 273→ package=validated_package_name, 274→ version=resolved_version, 275→ constraint=version_constraint, 276→ ) 277→ package_info = cached_entry.data 278→ from_cache = True 279→ else: 280→ logger.info( 281→ "Fetching fresh package info", 282→ package=validated_package_name, 283→ version=resolved_version, 284→ ) 285→ 286→ async with PyPIDocumentationFetcher() as fetcher: 287→ package_info = await fetcher.fetch_package_info( 288→ validated_package_name 289→ ) 290→ await cache_manager.set(cache_key, package_info) 291→ from_cache = False 292→ 293→ # Step 3: Format documentation 294→ async with PyPIDocumentationFetcher() as fetcher: 295→ formatted_docs = fetcher.format_documentation(package_info, query) 296→ 297→ # Record successful metrics 298→ get_metrics_collector().finish_request( 299→ metrics.request_id, 300→ success=True, 301→ cache_hit=from_cache, 302→ package_name=validated_package_name, 303→ ) 304→ 305→ return { 306→ "success": True, 307→ "package_name": package_info.name, 308→ "version": package_info.version, 309→ "resolved_version": resolved_version, 310→ "version_constraint": version_constraint, 311→ "documentation": formatted_docs, 312→ "from_cache": from_cache, 313→ "cache_key": cache_key, 314→ "query_applied": query is not None, 315→ } 316→ 317→ except AutoDocsError as e: 318→ formatted_error = ErrorFormatter.format_exception( 319→ e, {"package": validated_package_name} 320→ ) 321→ logger.error( 322→ "Documentation fetch failed", 323→ package=validated_package_name, 324→ error=str(e), 325→ error_type=type(e).__name__, 326→ ) 327→ get_metrics_collector().finish_request( 328→ metrics.request_id, 329→ success=False, 330→ error_type="AutoDocsError", 331→ package_name=package_name, 332→ ) 333→ return { 334→ "success": False, 335→ "error": { 336→ "message": formatted_error.message, 337→ "suggestion": formatted_error.suggestion, 338→ "severity": formatted_error.severity.value, 339→ "code": formatted_error.error_code, 340→ "recoverable": formatted_error.recoverable, 341→ }, 342→ } 343→ except Exception as e: 344→ formatted_error = ErrorFormatter.format_exception( 345→ e, {"package": validated_package_name} 346→ ) 347→ logger.error("Unexpected error during documentation fetch", error=str(e)) 348→ get_metrics_collector().finish_request( 349→ metrics.request_id, 350→ success=False, 351→ error_type=type(e).__name__, 352→ package_name=package_name, 353→ ) 354→ return { 355→ "success": False, 356→ "error": { 357→ "message": formatted_error.message, 358→ "suggestion": formatted_error.suggestion, 359→ "severity": formatted_error.severity.value, 360→ "code": formatted_error.error_code, 361→ "recoverable": formatted_error.recoverable, 362→ }, 363→ } 364→ 365→ 366→@mcp.tool 367→async def get_package_docs_with_context( 368→ package_name: str, 369→ version_constraint: str | None = None, 370→ include_dependencies: bool = True, 371→ context_scope: str = "smart", 372→ max_dependencies: int | None = None, 373→ max_tokens: int | None = None, 374→) -> dict[str, Any]: 375→ """ 376→ Retrieve comprehensive documentation context including dependencies. 377→ 378→ This is the main Phase 4 feature providing rich AI context with both the 379→ requested package and its most relevant dependencies. 380→ 381→ Args: 382→ package_name: Primary package name to document 383→ version_constraint: Version constraint for primary package 384→ include_dependencies: Whether to include dependency context (default: True) 385→ context_scope: Context scope - "primary_only", "runtime", or "smart" (default: "smart") 386→ max_dependencies: Maximum dependencies to include (default: from config) 387→ max_tokens: Maximum token budget for context (default: from config) 388→ 389→ Returns: 390→ Rich documentation context with primary package and dependencies 391→ """ 392→ from .observability import get_metrics_collector, track_request 393→ 394→ async with track_request("get_package_docs_with_context") as metrics: 395→ if context_fetcher is None: 396→ get_metrics_collector().finish_request( 397→ metrics.request_id, 398→ success=False, 399→ error_type="InitializationError", 400→ package_name=package_name, 401→ ) 402→ return { 403→ "success": False, 404→ "error": { 405→ "type": "InitializationError", 406→ "message": "Context fetcher not initialized", 407→ }, 408→ } 409→ 410→ try: 411→ # Validate inputs 412→ validated_package_name = InputValidator.validate_package_name(package_name) 413→ if version_constraint is not None: 414→ validated_constraint = InputValidator.validate_version_constraint( 415→ version_constraint 416→ ) 417→ else: 418→ validated_constraint = None 419→ 420→ logger.info( 421→ "Fetching package context", 422→ package=validated_package_name, 423→ constraint=validated_constraint, 424→ include_deps=include_dependencies, 425→ scope=context_scope, 426→ ) 427→ 428→ # Fetch comprehensive context 429→ context, performance_metrics = await context_fetcher.fetch_package_context( 430→ package_name=validated_package_name, 431→ version_constraint=validated_constraint, 432→ include_dependencies=include_dependencies, 433→ context_scope=context_scope, 434→ max_dependencies=max_dependencies, 435→ max_tokens=max_tokens, 436→ ) 437→ 438→ # Convert to serializable format 439→ context_data = { 440→ "primary_package": context.primary_package.model_dump(), 441→ "runtime_dependencies": [ 442→ dep.model_dump() for dep in context.runtime_dependencies 443→ ], 444→ "dev_dependencies": [dep.model_dump() for dep in context.dev_dependencies], 445→ "context_scope": context.context_scope, 446→ "total_packages": context.total_packages, 447→ "truncated_packages": context.truncated_packages, 448→ "token_estimate": context.token_estimate, 449→ } 450→ 451→ # Record successful metrics 452→ cache_hit_rate = performance_metrics.get("cache_hits", 0) / max( 453→ 1, 454→ performance_metrics.get("cache_hits", 0) 455→ + performance_metrics.get("cache_misses", 1), 456→ ) 457→ get_metrics_collector().finish_request( 458→ metrics.request_id, 459→ success=True, 460→ cache_hit=(cache_hit_rate > 0.5), 461→ package_name=validated_package_name, 462→ dependency_count=context.total_packages - 1, # Exclude primary package 463→ ) 464→ 465→ return { 466→ "success": True, 467→ "context": context_data, 468→ "performance": performance_metrics, 469→ } 470→ 471→ except AutoDocsError as e: 472→ logger.error( 473→ "Context fetch failed", 474→ package=validated_package_name, 475→ error=str(e), 476→ error_type=type(e).__name__, 477→ ) 478→ get_metrics_collector().finish_request( 479→ metrics.request_id, 480→ success=False, 481→ error_type="AutoDocsError", 482→ package_name=package_name, 483→ ) 484→ return { 485→ "success": False, 486→ "error": {"type": type(e).__name__, "message": str(e)}, 487→ } 488→ except Exception as e: 489→ formatted_error = ErrorFormatter.format_exception( 490→ e, {"package": validated_package_name} 491→ ) 492→ logger.error("Unexpected error during context fetch", error=str(e)) 493→ get_metrics_collector().finish_request( 494→ metrics.request_id, 495→ success=False, 496→ error_type=type(e).__name__, 497→ package_name=package_name, 498→ ) 499→ return { 500→ "success": False, 501→ "error": { 502→ "message": formatted_error.message, 503→ "suggestion": formatted_error.suggestion, 504→ "severity": formatted_error.severity.value, 505→ "code": formatted_error.error_code, 506→ "recoverable": formatted_error.recoverable, 507→ }, 508→ } 509→ 510→ 511→@mcp.tool 512→async def refresh_cache() -> dict[str, Any]: 513→ """ 514→ Refresh the local documentation cache. 515→ 516→ Returns: 517→ Statistics about cache refresh operation 518→ """ 519→ if cache_manager is None: 520→ return { 521→ "success": False, 522→ "error": { 523→ "message": "Cache manager not initialized", 524→ "suggestion": "Try again or restart the MCP server", 525→ "severity": "critical", 526→ "code": "service_not_initialized", 527→ "recoverable": False, 528→ }, 529→ } 530→ 531→ try: 532→ logger.info("Starting cache refresh") 533→ 534→ # Get current cache stats 535→ initial_stats = await cache_manager.get_cache_stats() 536→ 537→ # Clear the entire cache 538→ await cache_manager.invalidate() 539→ 540→ # Get final stats 541→ final_stats = await cache_manager.get_cache_stats() 542→ 543→ logger.info( 544→ "Cache refresh completed", 545→ cleared_entries=initial_stats.get("total_entries", 0), 546→ ) 547→ 548→ return { 549→ "success": True, 550→ "cleared_entries": initial_stats.get("total_entries", 0), 551→ "freed_bytes": initial_stats.get("total_size_bytes", 0), 552→ "final_entries": final_stats.get("total_entries", 0), 553→ } 554→ 555→ except AutoDocsError as e: 556→ formatted_error = ErrorFormatter.format_exception(e) 557→ logger.error("Cache refresh failed", error=str(e)) 558→ return { 559→ "success": False, 560→ "error": { 561→ "message": formatted_error.message, 562→ "suggestion": formatted_error.suggestion, 563→ "severity": formatted_error.severity.value, 564→ "code": formatted_error.error_code, 565→ "recoverable": formatted_error.recoverable, 566→ }, 567→ } 568→ 569→ 570→@mcp.tool 571→async def get_cache_stats() -> dict[str, Any]: 572→ """ 573→ Get statistics about the documentation cache. 574→ 575→ Returns: 576→ Cache statistics and information 577→ """ 578→ if cache_manager is None: 579→ return { 580→ "success": False, 581→ "error": { 582→ "message": "Cache manager not initialized", 583→ "suggestion": "Try again or restart the MCP server", 584→ "severity": "critical", 585→ "code": "service_not_initialized", 586→ "recoverable": False, 587→ }, 588→ } 589→ 590→ try: 591→ stats = await cache_manager.get_cache_stats() 592→ cached_packages = await cache_manager.list_cached_packages() 593→ 594→ return { 595→ "success": True, 596→ "cache_stats": stats, 597→ "cached_packages": cached_packages, 598→ "total_packages": len(cached_packages), 599→ } 600→ 601→ except Exception as e: 602→ formatted_error = ErrorFormatter.format_exception( 603→ e, {"operation": "get_cache_stats"} 604→ ) 605→ logger.error("Failed to get cache stats", error=str(e)) 606→ return { 607→ "success": False, 608→ "error": { 609→ "message": formatted_error.message, 610→ "suggestion": formatted_error.suggestion, 611→ "severity": formatted_error.severity.value, 612→ "code": formatted_error.error_code, 613→ "recoverable": formatted_error.recoverable, 614→ }, 615→ } 616→ 617→ 618→@mcp.tool 619→async def health_check() -> dict[str, Any]: 620→ """ 621→ Get system health status for monitoring and load balancer checks. 622→ 623→ Returns: 624→ Comprehensive health status of all system components 625→ """ 626→ from .health import HealthChecker 627→ 628→ health_checker = HealthChecker() 629→ return await health_checker.get_overall_health() 630→ 631→ 632→@mcp.tool 633→async def ready_check() -> dict[str, Any]: 634→ """ 635→ Kubernetes-style readiness check for deployment orchestration. 636→ 637→ Returns: 638→ Simple ready/not-ready status 639→ """ 640→ from .health import HealthChecker 641→ 642→ health_checker = HealthChecker() 643→ return await health_checker.get_readiness_status() 644→ 645→ 646→@mcp.tool 647→async def get_metrics() -> dict[str, Any]: 648→ """ 649→ Get system performance metrics for monitoring. 650→ 651→ Returns: 652→ Performance statistics and metrics 653→ """ 654→ from .observability import get_metrics_collector 655→ 656→ metrics_collector = get_metrics_collector() 657→ return { 658→ "success": True, 659→ "performance": metrics_collector.get_stats(), 660→ "health_metrics": metrics_collector.get_health_metrics(), 661→ "timestamp": time.time(), 662→ } 663→ 664→ 665→async def initialize_services() -> None: 666→ """Initialize global services with new components.""" 667→ global parser, cache_manager, version_resolver, context_fetcher 668→ 669→ config = get_config() 670→ 671→ # Validate production readiness 672→ production_issues = config.validate_production_readiness() 673→ if production_issues: 674→ if config.environment == "production": 675→ # Fail startup in production if there are issues 676→ raise ValueError( 677→ f"Production configuration issues: {'; '.join(production_issues)}" 678→ ) 679→ else: 680→ # Just warn in other environments 681→ logger.warning( 682→ "Configuration issues detected (non-production environment)", 683→ issues=production_issues, 684→ environment=config.environment, 685→ ) 686→ 687→ logger.info( 688→ "Initializing services", 689→ cache_dir=str(config.cache_dir), 690→ environment=config.environment, 691→ debug_mode=config.debug_mode, 692→ max_concurrent=config.max_concurrent, 693→ ) 694→ 695→ parser = PyProjectParser() 696→ cache_manager = FileCacheManager(config.cache_dir) 697→ version_resolver = VersionResolver() 698→ 699→ await cache_manager.initialize() 700→ 701→ # Initialize Phase 4 context fetcher 702→ context_fetcher = await create_context_fetcher(cache_manager) 703→ 704→ logger.info("Services initialized successfully", phase_4_enabled=True) 705→ 706→ 707→async def async_main() -> None: 708→ """Async main function with graceful shutdown.""" 709→ shutdown_handler = GracefulShutdown() 710→ shutdown_handler.register_signals() 711→ 712→ try: 713→ await initialize_services() 714→ logger.info("Starting AutoDocs MCP Server") 715→ 716→ # Start server and wait for shutdown 717→ server_task = asyncio.create_task(run_mcp_server()) 718→ shutdown_task = asyncio.create_task(shutdown_handler.wait_for_shutdown()) 719→ 720→ await asyncio.wait( 721→ [server_task, shutdown_task], return_when=asyncio.FIRST_COMPLETED 722→ ) 723→ 724→ except Exception as e: 725→ logger.error("Server startup failed", error=str(e)) 726→ raise 727→ finally: 728→ await shutdown_handler._cleanup_resources() 729→ 730→ 731→async def run_mcp_server() -> None: 732→ """Run the MCP server in async mode.""" 733→ # Since FastMCP doesn't have native async support, we need to run it in a thread 734→ import threading 735→ 736→ server_thread = threading.Thread(target=mcp.run, daemon=True) 737→ server_thread.start() 738→ 739→ # Keep the async task alive while server is running 740→ while server_thread.is_alive(): 741→ await asyncio.sleep(1.0) 742→ 743→ 744→def main() -> None: 745→ """Entry point for the MCP server.""" 746→ try: 747→ asyncio.run(async_main()) 748→ except KeyboardInterrupt: 749→ logger.info("Server shutdown requested") 750→ except Exception as e: 751→ logger.error("Server failed", error=str(e)) 752→ raise 753→ 754→ 755→if __name__ == "__main__": 756→ main() 757→ ``` _**Agent (claude-sonnet-4-20250514)**_ Tool use: **Read** `./tests` Error: ``` EISDIR: illegal operation on a directory, read ``` _**Agent (claude-sonnet-4-20250514)**_ Tool use: **Glob** Result: ``` /Users/bradleyfay/autodocs/tests/__init__.py /Users/bradleyfay/autodocs/tests/unit/__init__.py /Users/bradleyfay/autodocs/tests/integration/__init__.py /Users/bradleyfay/autodocs/tests/conftest.py /Users/bradleyfay/autodocs/tests/integration/test_end_to_end.py /Users/bradleyfay/autodocs/tests/integration/test_mcp_server.py /Users/bradleyfay/autodocs/tests/integration/test_phase4_context.py /Users/bradleyfay/autodocs/tests/unit/test_cache_manager.py /Users/bradleyfay/autodocs/tests/unit/test_config_validation.py /Users/bradleyfay/autodocs/tests/unit/test_context_formatter.py /Users/bradleyfay/autodocs/tests/unit/test_dependency_parser.py /Users/bradleyfay/autodocs/tests/unit/test_dependency_resolver.py /Users/bradleyfay/autodocs/tests/unit/test_doc_fetcher.py /Users/bradleyfay/autodocs/tests/unit/test_error_formatter.py /Users/bradleyfay/autodocs/tests/unit/test_health.py /Users/bradleyfay/autodocs/tests/unit/test_main_server.py /Users/bradleyfay/autodocs/tests/unit/test_observability.py /Users/bradleyfay/autodocs/tests/unit/test_security.py ``` _**Agent (claude-sonnet-4-20250514)**_ Tool use: **Read** `./planning` Error: ``` EISDIR: illegal operation on a directory, read ``` _**Agent (claude-sonnet-4-20250514)**_ **Agent task list:** - [X] 🌡️ Analyze the codebase to understand current architecture and identify specialized domains - [⚡] 🌡️ Design sub-agent strategy based on project structure and development needs - [ ] 🌡️ Create planning document with detailed sub-agent architecture proposal _**Agent (claude-sonnet-4-20250514)**_ Based on my analysis of the codebase, I can see this is a sophisticated MCP server with distinct architectural domains. Now let me design the sub-agent strategy. _**Agent (claude-sonnet-4-20250514)**_ **Agent task list:** - [X] 🌡️ Analyze the codebase to understand current architecture and identify specialized domains - [X] 🌡️ Design sub-agent strategy based on project structure and development needs - [⚡] 🌡️ Create planning document with detailed sub-agent architecture proposal _**Agent (claude-sonnet-4-20250514)**_ Tool use: **Write** ```md # Sub-Agent Architecture Strategy for AutoDocs MCP Server ## Executive Summary This document proposes a specialized sub-agent architecture for the AutoDocs MCP Server project, designed to leverage Claude Code's sub-agent capabilities for enhanced development efficiency, code quality, and domain expertise. ## Architecture Analysis The AutoDocs MCP Server follows a layered architecture with distinct domains: ### Core Services Layer (`src/autodoc_mcp/core/`) - **Dependency Management**: Parser, resolver, version resolution - **Documentation Processing**: Fetching, formatting, context management - **Network Layer**: HTTP client, resilience, caching - **Error Handling**: Formatting, validation, recovery ### Infrastructure Layer (`src/autodoc_mcp/`) - **MCP Protocol**: FastMCP server, tool definitions, async lifecycle - **Configuration**: Environment management, validation, security - **Observability**: Metrics, health checks, monitoring - **Data Models**: Pydantic schemas, type safety ### Testing Infrastructure - **Unit Tests**: 11 specialized test modules - **Integration Tests**: End-to-end, MCP server, Phase 4 context - **Test Utilities**: Mock services, fixtures, async support ## Proposed Sub-Agent Strategy ### 1. **MCP Protocol Specialist** (`mcp-protocol-agent`) **Purpose**: Expert in MCP protocol implementation, tool definitions, and client integrations **Specialized Tools**: - Read, Edit, MultiEdit, Glob, Grep - Bash (for MCP client testing) **System Prompt**: \``` You are an MCP Protocol Specialist for the AutoDocs MCP Server. You have deep expertise in: - FastMCP server implementation and tool registration - MCP stdio protocol compliance and transport layer - Tool schema validation and parameter handling - Client integration patterns (Claude Code, Cursor, etc.) - Async lifecycle management and graceful shutdown - Error response standardization across MCP tools Focus on: - MCP tool implementation (main.py tool definitions) - Protocol compliance and standardization - Client configuration examples and integration guides - Server lifecycle and connection management - MCP-specific error handling and responses Always ensure MCP tools follow consistent patterns for success/error responses and maintain protocol compliance. \``` **Usage Scenarios**: - Adding new MCP tools or modifying existing ones - Debugging MCP client integration issues - Updating MCP protocol compliance - Writing MCP integration documentation ### 2. **Core Services Architect** (`core-services-agent`) **Purpose**: Expert in the core business logic, dependency resolution, and documentation processing **Specialized Tools**: - Read, Edit, MultiEdit, Glob, Grep - mcp__autodocs-mcp__* tools (for testing core functionality) **System Prompt**: \``` You are a Core Services Architect for the AutoDocs MCP Server. You specialize in: - Dependency parsing, resolution, and version constraint handling - PyPI API integration and documentation fetching strategies - High-performance caching with version-based keys - Context fetching and AI-optimized formatting - Network resilience with circuit breakers and backoff - Error handling and graceful degradation patterns Focus on: - Core service implementations in src/autodoc_mcp/core/ - Business logic for dependency analysis and documentation processing - Performance optimization and concurrent processing - Cache management and version resolution strategies - Network reliability and error recovery Prioritize robustness, performance, and graceful degradation in all core service implementations. \``` **Usage Scenarios**: - Implementing new dependency analysis features - Optimizing documentation fetching and caching - Adding new context fetching capabilities - Debugging core business logic issues - Performance tuning and scalability improvements ### 3. **Testing Infrastructure Specialist** (`testing-specialist-agent`) **Purpose**: Expert in comprehensive testing strategies, pytest ecosystem, and test automation **Specialized Tools**: - Read, Edit, MultiEdit, Glob, Grep, Bash - Full access to pytest ecosystem tools **System Prompt**: \``` You are a Testing Infrastructure Specialist for the AutoDocs MCP Server. You excel in: - Pytest ecosystem and plugin usage (pytest-mock, pytest-asyncio, pytest-cov, etc.) - Mock strategy using pytest-mock fixtures (NEVER unittest.mock) - Async test patterns and MCP tool testing - Test fixture design and reusable mock services - Coverage analysis and test completeness - Integration testing with real MCP clients Key requirements: - ALWAYS use pytest-mock patterns: def test_something(self, mocker): - Use mock_services fixture for MCP tool tests - Follow existing test patterns in tests/unit/ and tests/integration/ - Ensure comprehensive test coverage for new features - Test both success and failure paths with realistic scenarios Never use unittest.mock imports - always use pytest-mock patterns exclusively. \``` **Usage Scenarios**: - Writing new unit and integration tests - Improving test coverage and test reliability - Debugging test failures and flaky tests - Refactoring test infrastructure - Adding new test fixtures and utilities ### 4. **Production Operations Expert** (`production-ops-agent`) **Purpose**: Expert in deployment, monitoring, configuration, and production readiness **Specialized Tools**: - Read, Edit, MultiEdit, Bash, WebFetch - Configuration and deployment files **System Prompt**: \``` You are a Production Operations Expert for the AutoDocs MCP Server. You specialize in: - Production-ready configuration management and environment validation - Health checks, monitoring, and observability integration - Deployment automation, CI/CD, and release processes - Security best practices and input validation - Performance monitoring and system metrics - Docker, Kubernetes, and cloud deployment patterns Focus on: - Configuration validation and production readiness checks - Health check implementations and monitoring integration - CI/CD pipeline optimization and deployment automation - Security configurations and vulnerability management - Performance tuning for production workloads - Documentation for deployment and operations Always prioritize security, reliability, and operational excellence in production environments. \``` **Usage Scenarios**: - Configuring deployment pipelines and automation - Implementing monitoring and alerting - Security reviews and vulnerability assessments - Performance optimization for production - Troubleshooting production issues ### 5. **Documentation and Integration Guide** (`docs-integration-agent`) **Purpose**: Expert in technical documentation, API documentation, and integration guides **Specialized Tools**: - Read, Edit, MultiEdit, WebFetch - Markdown and documentation files **System Prompt**: \``` You are a Documentation and Integration Expert for the AutoDocs MCP Server. You excel in: - Technical documentation writing and API documentation - MCP client integration guides and examples - Architecture documentation and design decisions - User guides and developer onboarding materials - Changelog maintenance and release documentation - Integration examples for various AI platforms Focus on: - Clear, comprehensive technical documentation - Step-by-step integration guides with real examples - API documentation with usage patterns - Architecture decisions and design rationale - User-friendly installation and setup guides - Troubleshooting guides and FAQ sections Always write documentation that is clear, actionable, and includes practical examples. \``` **Usage Scenarios**: - Writing API documentation and integration guides - Creating user onboarding materials - Updating architecture documentation - Writing troubleshooting guides - Maintaining changelog and release notes ## Sub-Agent Interaction Patterns ### Primary Development Workflows 1. **New Feature Development**: - **Core Services Architect**: Implements business logic - **MCP Protocol Specialist**: Adds MCP tool integration - **Testing Specialist**: Comprehensive test coverage - **Documentation Guide**: Integration examples and API docs 2. **Bug Investigation and Resolution**: - **Core Services Architect**: Analyzes core logic issues - **Testing Specialist**: Reproduces bugs with failing tests - **Production Ops Expert**: Investigates production impacts - **MCP Protocol Specialist**: Protocol compliance verification 3. **Production Deployment**: - **Production Ops Expert**: Deployment configuration and automation - **Testing Specialist**: Integration and end-to-end validation - **Documentation Guide**: Release notes and operational guides - **Core Services Architect**: Performance validation ### Cross-Domain Collaboration - **Architecture Reviews**: Core Services Architect + MCP Protocol Specialist - **Release Preparation**: All agents collaborate on comprehensive release validation - **Performance Optimization**: Core Services Architect + Production Ops Expert - **Integration Support**: MCP Protocol Specialist + Documentation Guide ## Implementation Recommendations ### Sub-Agent Creation Order 1. **Testing Specialist** (immediate value for current development) 2. **Core Services Architect** (most frequent domain) 3. **MCP Protocol Specialist** (specialized but critical) 4. **Production Ops Expert** (for deployment and monitoring) 5. **Documentation Guide** (for comprehensive user experience) ### Tool Access Strategy - **Minimal Necessary Access**: Each agent only gets tools required for their domain - **Security-First**: Production Ops Expert gets security-focused tools - **Development-Optimized**: Testing and Core agents get full development toolchain - **Documentation-Focused**: Docs agent gets web access for research and examples ### Success Metrics - **Faster Domain-Specific Development**: Reduced context switching between domains - **Higher Code Quality**: Specialized expertise in testing and architecture - **Better Production Readiness**: Dedicated ops expertise for deployment - **Comprehensive Documentation**: Dedicated focus on user experience - **Reduced Technical Debt**: Specialized agents maintain domain consistency ## Best Practices for Sub-Agent Usage ### When to Use Each Agent - **Use MCP Protocol Specialist**: When adding/modifying MCP tools, client integration issues - **Use Core Services Architect**: For business logic, dependency resolution, performance - **Use Testing Specialist**: For all testing needs, coverage improvements, test debugging - **Use Production Ops Expert**: For deployment, monitoring, security, configuration - **Use Documentation Guide**: For user guides, API docs, integration examples ### Delegation Strategies - **Explicit Delegation**: Mention specific agent for targeted expertise - **Automatic Routing**: Let Claude delegate based on task descriptions - **Collaborative Tasks**: Use multiple agents for comprehensive feature development ### Maintenance and Evolution - **Regular Review**: Assess agent effectiveness and update system prompts - **Domain Evolution**: Adjust agent boundaries as architecture evolves - **Tool Access Updates**: Modify tool permissions based on usage patterns - **Cross-Training**: Ensure agents understand domain boundaries and collaboration points ## Conclusion This sub-agent architecture leverages the AutoDocs MCP Server's layered design to create specialized AI assistants for each domain. By implementing these agents, development efficiency will improve through: - **Reduced Context Switching**: Specialized expertise for each architectural domain - **Higher Quality Output**: Domain-specific knowledge and best practices - **Faster Development Cycles**: Parallel work across domains with specialized agents - **Better Maintainability**: Consistent patterns within each domain - **Enhanced Production Readiness**: Dedicated operational expertise The proposed strategy balances specialization with collaboration, ensuring each agent has deep domain knowledge while maintaining awareness of cross-domain dependencies and integration points. ``` Result: ``` File created successfully at: /Users/bradleyfay/autodocs/planning/sub_agent_architecture.md ``` _**Agent (claude-sonnet-4-20250514)**_ **Agent task list:** - [X] 🌡️ Analyze the codebase to understand current architecture and identify specialized domains - [X] 🌡️ Design sub-agent strategy based on project structure and development needs - [X] 🌡️ Create planning document with detailed sub-agent architecture proposal _**Agent (claude-sonnet-4-20250514)**_ I've created a comprehensive sub-agent architecture strategy document at `/Users/bradleyfay/autodocs/planning/sub_agent_architecture.md`. The proposal outlines **5 specialized sub-agents** based on your codebase's architectural domains: 1. **MCP Protocol Specialist** - FastMCP server, tool definitions, client integrations 2. **Core Services Architect** - Business logic, dependency resolution, documentation processing 3. **Testing Infrastructure Specialist** - Pytest ecosystem, mock strategies, test automation 4. **Production Operations Expert** - Deployment, monitoring, security, configuration 5. **Documentation and Integration Guide** - Technical docs, API guides, user onboarding Each agent has tailored system prompts, specific tool access, and clear usage scenarios. The strategy emphasizes domain expertise while maintaining cross-agent collaboration for complex workflows like feature development and production deployments. The recommended implementation order starts with the **Testing Specialist** for immediate value, followed by **Core Services Architect** for the most frequent development needs.