Troubleshooting Guide¶

This guide helps you diagnose and resolve common issues with the AutoDocs MCP Server. Each section includes symptoms, diagnosis steps, and solutions.

Quick Diagnostic Commands¶

Before diving into specific issues, run these commands to gather diagnostic information:

# Check if AutoDocs is installed
autodoc-mcp --version

# Test manual startup
autodoc-mcp

# Check environment configuration
env | grep -E "(CACHE_DIR|LOG_LEVEL|MAX_)"

# Test network connectivity to PyPI
curl -s https://pypi.org/pypi/requests/json | head -n 10

Installation Issues¶

"Command not found: autodoc-mcp"¶

Symptoms: - autodoc-mcp: command not found error - MCP client cannot start the server

Diagnosis:

# Check if package is installed
pip show autodoc-mcp
pip list | grep autodoc

# Check PATH
echo $PATH
which python
which pip

Solutions:

Using uv (Recommended)Using pipFix PATH Issues

# Install with uv tool
uv tool install autodoc-mcp

# Verify installation
autodoc-mcp --version

# Install globally
pip install autodoc-mcp

# Or install for user only
pip install --user autodoc-mcp

# Add to PATH if needed
export PATH="$HOME/.local/bin:$PATH"

# Add to shell profile (.bashrc, .zshrc, etc.)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

"Permission denied" during installation¶

Symptoms: - Permission errors during pip install - Cannot write to system directories

Solutions:

# Use user installation
pip install --user autodoc-mcp

# Or use virtual environment
python -m venv autodoc-env
source autodoc-env/bin/activate  # Windows: autodoc-env\Scripts\activate
pip install autodoc-mcp

"Package not found" from PyPI¶

Symptoms: - No matching distribution found error - Package cannot be downloaded

Solutions:

# Update pip
pip install --upgrade pip

# Clear pip cache
pip cache purge

# Use specific index URL
pip install -i https://pypi.org/simple/ autodoc-mcp

# For corporate networks, configure proxy
pip install --proxy http://proxy.company.com:8080 autodoc-mcp

MCP Client Connection Issues¶

MCP client cannot connect to server¶

Symptoms: - "Failed to connect to MCP server" in AI client - Server not responding to MCP protocol

Diagnosis:

# Test server startup manually
autodoc-mcp

# Expected output should show:
# [INFO] Starting AutoDocs MCP Server v0.x.x
# [INFO] FastMCP server initialized with 8 tools
# [INFO] Ready for MCP connections

Solutions:

Fix Command PathEnable Debug LoggingUse Python Module

Update MCP client configuration:

{
  "mcpServers": {
    "autodoc-mcp": {
      "command": "autodoc-mcp",  // Use full path if needed: "/usr/local/bin/autodoc-mcp"
      "env": {
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

{
  "mcpServers": {
    "autodoc-mcp": {
      "command": "autodoc-mcp",
      "env": {
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

{
  "mcpServers": {
    "autodoc-mcp": {
      "command": "python",
      "args": ["-m", "autodocs_mcp.main"],
      "env": {
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

"Tools not available" in AI client¶

Symptoms: - AI assistant says tools are not available - No AutoDocs tools visible in MCP client

Diagnosis:

# Check server logs for initialization errors
export LOG_LEVEL=DEBUG
autodoc-mcp

# Look for errors during tool registration

Solutions:

Restart MCP client after configuration changes
Verify JSON syntax in MCP client configuration
Check server startup for error messages
Test tool availability by asking AI assistant: "What MCP tools are available?"

Network and PyPI Issues¶

"Failed to connect to PyPI" errors¶

Symptoms: - Network timeouts when fetching package documentation - "Unable to reach PyPI" error messages

Diagnosis:

# Test PyPI connectivity
curl -I https://pypi.org/pypi/requests/json

# Check DNS resolution
nslookup pypi.org

# Test with verbose output
export LOG_LEVEL=DEBUG
# Then use AutoDocs and check logs

Solutions:

Corporate Firewall/ProxyNetwork TimeoutsAlternative PyPI Index

# Set proxy environment variables
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.local

# Configure in MCP client
{
  "env": {
    "HTTP_PROXY": "http://proxy.company.com:8080",
    "HTTPS_PROXY": "http://proxy.company.com:8080"
  }
}

# Increase timeout and reduce concurrency
export REQUEST_TIMEOUT=30
export MAX_CONCURRENT=3
export RETRY_ATTEMPTS=5

# Use mirror or alternative index
export PYPI_BASE_URL=https://pypi.python.org/pypi

Slow response times¶

Symptoms: - Long delays before getting documentation - "Request timed out" errors

Diagnosis:

# Check cache status
# Ask AI assistant: "What's the status of the AutoDocs cache?"

# Monitor network performance
ping pypi.org
curl -w "@curl-format.txt" -s https://pypi.org/pypi/requests/json

Solutions:

First-time cache miss: Initial requests are slower as documentation is fetched and cached
Reduce concurrency: Lower MAX_CONCURRENT for unstable networks
Increase timeout: Set REQUEST_TIMEOUT=30 for slow networks
Pre-populate cache: Use development scripts to cache common packages

Cache Issues¶

"Context fetcher not initialized" error¶

Symptoms: - Error when using get_package_docs_with_context - Service fails to start properly

Diagnosis:

# Check cache directory permissions
ls -la ~/.cache/autodoc-mcp/

# Test cache write access
touch ~/.cache/autodoc-mcp/test-file
rm ~/.cache/autodoc-mcp/test-file

Solutions:

Fix Cache DirectoryClear Corrupted Cache

# Create cache directory
mkdir -p ~/.cache/autodoc-mcp
chmod 755 ~/.cache/autodoc-mcp

# Or use alternative location
export CACHE_DIR="/tmp/autodoc-cache"

# Clear cache completely
rm -rf ~/.cache/autodoc-mcp/*

# Or use MCP tool
# Ask AI assistant: "Clear the AutoDocs cache"

"Cache write error" messages¶

Symptoms: - Cannot save documentation to cache - Repeated network requests for same packages

Diagnosis:

# Check disk space
df -h ~/.cache/
du -sh ~/.cache/autodoc-mcp/

# Check permissions
ls -la ~/.cache/autodoc-mcp/

Solutions:

Free disk space: Remove old files or increase available storage
Fix permissions: chmod -R 755 ~/.cache/autodoc-mcp/
Change cache location: Set CACHE_DIR to writable location
Clear cache: Remove corrupted cache files

Cache corruption issues¶

Symptoms: - Inconsistent or incomplete documentation responses - JSON parsing errors in cached files

Diagnosis:

# Check for corrupted cache files
find ~/.cache/autodoc-mcp/ -name "*.json" -exec python -m json.tool {} \; > /dev/null

# View cache statistics
# Ask AI assistant: "Show me cache performance statistics"

Solutions:

# Clear specific package cache
rm ~/.cache/autodoc-mcp/fastapi-*.json

# Clear entire cache
# Ask AI assistant: "Clear the AutoDocs cache"

# Prevent corruption with proper shutdown
# Always stop server gracefully (Ctrl+C, not kill -9)

Package-Specific Issues¶

"No dependencies found" for known packages¶

Symptoms: - Packages with dependencies show empty dependency lists - Missing expected framework dependencies

Diagnosis:

# Check package metadata manually
curl -s https://pypi.org/pypi/fastapi/json | jq '.info.requires_dist'

# Test with different context scopes
# Ask AI: "Get FastAPI docs with context_scope='runtime'"

Solutions:

Try different context scope: Use "runtime" or "smart" scope
Some packages have optional-only dependencies: This is normal behavior
Check package version: Some versions have different dependencies
Verify package exists: Ensure package name is spelled correctly

"Package not found" for valid packages¶

Symptoms: - PyPI returns 404 for valid package names - Inconsistent package availability

Diagnosis:

# Verify package exists on PyPI
curl -I https://pypi.org/pypi/PACKAGE_NAME/json

# Check for case sensitivity
curl -I https://pypi.org/pypi/package_name/json

Solutions:

Check spelling: Package names are case-sensitive
Use canonical name: Some packages have different canonical names
Try alternative names: Some packages have aliases or have been renamed
Check package status: Package may be yanked or delisted

Performance Issues¶

High memory usage¶

Symptoms: - AutoDocs consuming excessive memory - System running out of memory

Diagnosis:

# Monitor memory usage
ps aux | grep autodoc
top -p $(pgrep -f autodoc)

# Check cache size
du -sh ~/.cache/autodoc-mcp/

Solutions:

Reduce Memory UsageClean Up Cache

# Limit context size
export MAX_DEPENDENCY_CONTEXT=3
export MAX_CONTEXT_TOKENS=15000

# Reduce cache size
export MAX_CACHE_SIZE_MB=200

# Clear cache periodically
# Ask AI assistant: "Clear the AutoDocs cache"

# Implement automatic cleanup
export CACHE_CLEANUP_INTERVAL=1800

Excessive network requests¶

Symptoms: - High network usage - Rate limiting errors from PyPI

Diagnosis:

# Monitor network requests
export LOG_LEVEL=DEBUG
# Check logs for request patterns

# Check cache hit rate
# Ask AI assistant: "Show me cache performance statistics"

Solutions:

# Reduce concurrent requests
export MAX_CONCURRENT=3

# Increase cache retention
export MAX_CACHE_SIZE_MB=1000

# Use longer timeouts with fewer retries
export REQUEST_TIMEOUT=20
export RETRY_ATTEMPTS=2

Development and Testing Issues¶

Tests failing in development¶

Symptoms: - pytest failures during development - Import errors in tests

Diagnosis:

# Run tests with verbose output
uv run pytest -v

# Check test environment
uv run python -c "import autodocs_mcp; print(autodocs_mcp.__version__)"

# Run specific test
uv run pytest tests/test_specific.py::test_function -v

Solutions:

# Install development dependencies
uv sync --all-extras

# Run pre-commit hooks
uv run pre-commit run --all-files

# Clear Python cache
find . -name "*.pyc" -delete
find . -name "__pycache__" -type d -exec rm -rf {} +

# Reinstall in development mode
uv sync --reinstall

Pre-commit hooks failing¶

Symptoms: - Git commits being rejected - Linting or formatting errors

Solutions:

# Install pre-commit hooks
uv run pre-commit install

# Run all hooks manually
uv run pre-commit run --all-files

# Fix specific issues
uv run ruff check --fix
uv run ruff format
uv run mypy src

Advanced Troubleshooting¶

Enable comprehensive debugging¶

# Maximum debug information
export LOG_LEVEL=DEBUG
export REQUEST_TIMEOUT=60
export RETRY_ATTEMPTS=1

# Start server manually
autodoc-mcp

# Monitor all activity
tail -f ~/.cache/autodoc-mcp/debug.log  # if logging to file

Collect diagnostic information¶

# System information
uname -a
python --version
pip --version

# Package information
pip show autodoc-mcp
pip list | grep -E "(fastmcp|pydantic|httpx)"

# Environment
env | grep -E "(CACHE|LOG|MAX|PYPI)"

# Network test
curl -w "@curl-format.txt" -s https://pypi.org/pypi/requests/json > /dev/null

Performance profiling¶

# Use development scripts for profiling
uv run python scripts/dev.py test-docs fastapi --profile

# Monitor resource usage
htop
iotop
netstat -an | grep :80

Getting Help¶

Log Analysis¶

When reporting issues, include relevant log entries:

# Enable debug logging
export LOG_LEVEL=DEBUG

# Reproduce the issue
# Then share the relevant log output

Health Check Information¶

# Get comprehensive health status
# Ask AI assistant: "Check the health status of AutoDocs"

# Get performance metrics
# Ask AI assistant: "Show me AutoDocs performance metrics"

# Get cache statistics
# Ask AI assistant: "What's the status of the AutoDocs cache?"

Issue Report Template¶

When reporting issues, include:

AutoDocs version: autodoc-mcp --version
Python version: python --version
Operating system: uname -a (Unix) or system info (Windows)
MCP client: Claude Desktop, Cursor, etc.
Configuration: Relevant environment variables
Error messages: Complete error messages and stack traces
Reproduction steps: Minimal steps to reproduce the issue
Logs: Relevant log entries with LOG_LEVEL=DEBUG

Prevention Best Practices¶

Regular Maintenance¶

# Monthly cache cleanup
# Ask AI assistant: "Clear the AutoDocs cache"

# Check system health
# Ask AI assistant: "Check the health status of AutoDocs"

# Update to latest version
pip install --upgrade autodoc-mcp

Monitoring¶

# Set up basic monitoring
# Check cache size: du -sh ~/.cache/autodoc-mcp/
# Check memory usage: ps aux | grep autodoc
# Test connectivity: curl -I https://pypi.org/

Backup and Recovery¶

# Backup cache (optional - will regenerate automatically)
tar -czf autodoc-cache-backup.tar.gz ~/.cache/autodoc-mcp/

# Quick recovery
rm -rf ~/.cache/autodoc-mcp/
# Cache will regenerate on next use

If issues persist after trying these solutions, consider:

Updating to the latest version: pip install --upgrade autodoc-mcp
Checking the GitHub Issues page
Filing a new issue with diagnostic information
Consulting the Configuration Reference for advanced settings