### Example: Full Analysis with LLM Setup

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/llm-parameter-generation.md

This bash script demonstrates setting the OpenAI API key as a prerequisite for running a full analysis with LLM-based parameter generation.

```bash
# Set API key
export OPENAI_API_KEY="sk-..."

```

--------------------------------

### Clone Repository and Setup Environment

Source: https://github.com/destilabs/mcp-doctor/blob/main/CONTRIBUTING.md

Clone your fork of the repository and set up the development environment using a virtual environment and installing dependencies.

```bash
git clone https://github.com/YOUR_USERNAME/mcp-doctor.git
cd mcp-doctor
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"
```

--------------------------------

### Install and Run Semgrep for Code Analysis

Source: https://github.com/destilabs/mcp-doctor/blob/main/SECURITY_ANALYSIS_REPORT.md

Installs Semgrep, a static analysis tool, and runs it with an auto-detected configuration on the 'src/' directory.

```bash
pip install semgrep
semgrep --config=auto src/
```

--------------------------------

### Complete Workflow Example

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/tool-call-cache.md

This example demonstrates a full workflow: running an analysis with caching enabled, viewing cached statistics, extracting successful parameters, and using those parameters for manual testing.

```bash
# 1. Run analysis with caching
export OPENAI_API_KEY="sk-..."
mcp-doctor analyze \
  --target "https://mcp.explorium.ai/sse" \
  --oauth \
  --check token_efficiency \
  --show-tool-outputs

# Output shows:
# ⚙️  Using LLM to fix parameters for match-business
# ✅ LLM correction successful! (~421 tokens)
# 💾 Cached 12 successful tool calls to ~/.mcp-analyzer/tool-call-cache/...

# 2. View what was cached
mcp-doctor cache-stats --server "https://mcp.explorium.ai/sse"

# 3. Extract successful parameters
cat ~/.mcp-analyzer/tool-call-cache/*/match-business/*_llm_corrected_*.json | \
  jq '.input_params' | head -1 > match-business-params.json

# 4. Use for manual testing
mcp-doctor analyze \
  --target "..." \
  --check token_efficiency \
  --overrides match-business-params.json
```

--------------------------------

### Install and Run Pip-Audit for Dependency Scanning

Source: https://github.com/destilabs/mcp-doctor/blob/main/SECURITY_ANALYSIS_REPORT.md

Installs the pip-audit tool for scanning project dependencies for known vulnerabilities and then executes the audit.

```bash
pip install pip-audit
pip-audit
```

--------------------------------

### Handle Sample Values Gracefully in Tools

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/troubleshooting-token-efficiency.md

Tools should be designed to handle sample or placeholder values, such as example URLs, without failing.

```python
def scrape_url(url: str):
    if url == "https://example.com":
        return {"content": "Sample content for testing"}
    # ... actual scraping logic
```

--------------------------------

### Example Overrides JSON for MCP Doctor

Source: https://github.com/destilabs/mcp-doctor/blob/main/README.md

An example JSON file demonstrating how to specify tool overrides for token efficiency checks.

```json
{
  "tools": {
    "analyse-video": { "videoId": "68d52f0c18ca9db9c9db6bb0", "type": "summary" },
    "analyze-video": { "videoId": "68d52f0c18ca9db9c9db6bb0", "type": "summary" },
    "search-docs": { "query": "sample query", "limit": 10 }
  }
}
```

--------------------------------

### Example of a Valid Tool Schema

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/troubleshooting-token-efficiency.md

Ensure your tools have correctly defined parameter schemas, including 'type' and 'required' fields, to be properly analyzed.

```json
{
  "name": "my_tool",
  "parameters": {
    "properties": {
      "required_param": {"type": "string"}
    },
    "required": ["required_param"]
  }
}
```

--------------------------------

### Install and Run Bandit for Static Analysis

Source: https://github.com/destilabs/mcp-doctor/blob/main/SECURITY_ANALYSIS_REPORT.md

Installs the Bandit security linter and runs it recursively on the 'src/' directory to identify security issues in Python code.

```bash
pip install bandit
bandit -r src/
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/destilabs/mcp-doctor/blob/main/README.md

Install the necessary development dependencies for MCP Doctor using pip.

```bash
pip install -e ".[dev]"
```

--------------------------------

### Install and Use MCP Doctor CLI

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/README.md

Install MCP Doctor using pip and run basic analysis commands. Use the --check flag to specify analysis types like token_efficiency or all.

```bash
pip install mcp-doctor

mcp-doctor analyze --target "npx your-mcp-server"

mcp-doctor analyze --target "npx your-mcp-server" --check token_efficiency

mcp-doctor analyze --target "npx your-mcp-server" --check all
```

--------------------------------

### Initialize and use MCPClient for HTTP, NPX, and authenticated servers

Source: https://context7.com/destilabs/mcp-doctor/llms.txt

Demonstrates initializing `MCPClient` for different server types including HTTP, NPX, and servers requiring authentication. It shows how to get server info, list tools, call a tool, and handle potential errors.

```python
import asyncio
from mcp_analyzer.mcp_client import MCPClient, MCPClientError

async def diagnose():
    # HTTP server
    client = MCPClient("http://localhost:8000/mcp", timeout=30)

    # NPX server with API key
    client = MCPClient(
        "npx firecrawl-mcp",
        timeout=60,
        env_vars={"FIRECRAWL_API_KEY": "abc123"},
        working_dir="/tmp",
    )

    # HTTP server with bearer token header
    client = MCPClient(
        "https://api.example.com/mcp",
        headers={"Authorization": "Bearer mytoken"},
    )

    try:
        # Initialize connection / launch NPX process
        info = await client.get_server_info()
        print(f"Server: {info.server_name} v{info.server_version}")
        print(f"Protocol: {info.protocol_version}")
        print(f"Capabilities: {info.capabilities}")

        # List all tools
        tools = await client.get_tools()
        for tool in tools:
            print(f"  - {tool.name}: {tool.description}")

        # Execute a tool call
        result = await client.call_tool("search_docs", {"query": "hello world", "limit": 5})
        print(result)

        # Get resolved server URL (useful after NPX launch)
        print(client.get_server_url())  # e.g., "http://localhost:3001"

    except MCPClientError as e:
        print(f"Connection failed: {e}")
    finally:
        await client.close()  # stops NPX process if launched

asyncio.run(diagnose())
```

--------------------------------

### Install LLM Dependencies

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/llm-parameter-generation.md

Install the necessary Python packages for LLM integration, including OpenAI and Anthropic libraries.

```bash
pip install -e ".[llm]"
```

--------------------------------

### Example of Initial Parameter Attempt

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/llm-parameter-generation.md

This JSON represents an initial, potentially failing, parameter attempt for a tool call. It shows empty arrays where elements might be required.

```json
{
  "prospect_ids": [],
  "enrichments": []
}
```

--------------------------------

### Example of a Good Tool Response

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/troubleshooting-token-efficiency.md

A good tool response should contain meaningful data and metadata, contributing to accurate token counting.

```json
// Good response
{
  "result": "This is actual content with data...",
  "metadata": {"items": 42}
}
```

--------------------------------

### Example of a Bad Tool Response

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/troubleshooting-token-efficiency.md

This response format, while indicating success, lacks meaningful data and will result in 0 tokens being counted.

```json
// Bad response (will show 0 tokens)
{
  "success": true
}
```

--------------------------------

### Conventional Commit Message Example

Source: https://github.com/destilabs/mcp-doctor/blob/main/CONTRIBUTING.md

Examples of commit messages following the conventional commit format, specifying type, scope, and a description for different kinds of changes.

```git
type(scope): description

feat(checker): add new diagnostic for parameter validation
fix(client): handle connection timeout gracefully
docs(readme): update installation instructions
```

--------------------------------

### Get Detailed Diagnostic Output

Source: https://github.com/destilabs/mcp-doctor/blob/main/README.md

Run an analysis on an HTTP MCP server with verbose output enabled. This provides more detailed diagnostic information for troubleshooting.

```bash
mcp-doctor analyze --target http://localhost:8000/mcp --verbose
```

--------------------------------

### Well-Designed Tool Schema for Document Search

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/token-efficiency-arguments.md

An example of a well-designed tool schema for 'search_documents' that leverages recognized parameter naming and pagination conventions for optimal test argument generation.

```json
{
  "name": "search_documents",
  "description": "Search through document database with pagination",
  "parameters": {
    "properties": {
      "search_query": {
        "type": "string",
        "description": "Text to search for in documents"
      },
      "limit": {
        "type": "integer", 
        "description": "Maximum number of results (1-1000)",
        "minimum": 1,
        "maximum": 1000
      },
      "include_content": {
        "type": "boolean",
        "description": "Whether to include full document content"
      }
    },
    "required": ["search_query"]
  }
}
```

--------------------------------

### MCP Doctor Server Diagnosis Report

Source: https://github.com/destilabs/mcp-doctor/blob/main/README.md

This is an example output from the MCP Doctor's server diagnosis, detailing the health of NPX tools. It includes counts and percentages of healthy tools, warnings, critical issues, and recommendations.

```text
🩺 MCP Doctor - Server Diagnosis
NPX Command: export FIRECRAWL_API_KEY=abc123 && npx firecrawl-mcp

✅ NPX server launched at http://localhost:3001
✅ Connected! Found 12 tools

📝 Tool Description Analysis
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Diagnostic Result            ┃    Count ┃ Percentage ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━┩
│ ✅ Healthy Tools             │        8 │      66.7% │
│ ⚠️  Warnings                 │        3 │      25.0% │
│ 🚨 Critical Issues           │        1 │       8.3% │
│ ℹ️  Recommendations          │        5 │      41.7% │
└──────────────────────────────┴──────────┴────────────┘

🎯 Treatment Recommendations:
   1. Add descriptions to 1 tool missing documentation
   2. Improve parameter naming for 3 tools with generic names
   3. Add usage context to 2 tools for better agent understanding
   4. Simplify technical jargon in 2 tool descriptions
```

--------------------------------

### MCP Doctor CLI: Generate Dataset - NPX Command Target

Source: https://github.com/destilabs/mcp-doctor/blob/main/README.md

Example of using the `generate-dataset` command with an NPX command as the target. This requires setting the OPENAI_API_KEY and specifies the NPX command, number of tasks, and output file.

```bash
# Generate 8 tasks using tools from an NPX command
export OPENAI_API_KEY=sk-open-example
mcp-doctor generate-dataset --target "npx firecrawl-mcp" --num-tasks 8 --output dataset.json
```

--------------------------------

### MCP Doctor Token Efficiency Analysis Report

Source: https://github.com/destilabs/mcp-doctor/blob/main/README.md

This example output from MCP Doctor's token efficiency analysis highlights potential issues with response sizes and tool complexity. It provides a breakdown of metrics, status, and specific recommendations for improvement.

```text
🩺 MCP Doctor - Server Diagnosis
NPX Command: npx firecrawl-mcp

✅ NPX server launched at http://localhost:3001
✅ Connected! Found 8 tools

🔢 Token Efficiency Analysis
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Metric                       ┃ Value         ┃ Status                    ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Average Response Size        │ 3,250 tokens  │ ✅ Efficient             │
│ Largest Response             │ 28,500 tokens │ 🚨 Oversized             │
│ Tools Over 25k Tokens        │ 1             │ 🚨 1                     │
│ Tools Successfully Analyzed  │ 8/8           │ ✅ Complete              │
└──────────────────────────────┴───────────────┴───────────────────────────┘

🚨 Token Efficiency Issues Found:
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Tool                         ┃ Severity ┃ Issue                                                                        ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ scrape_url                   │ ⚠️       │ Response contains 28,500 tokens (>25,000 recommended)                       │
│ scrape_url                   │ ℹ️       │ Tool would benefit from filtering capabilities to reduce response size       │
│ list_crawl_jobs              │ ℹ️       │ Tool likely returns collections but doesn't support pagination              │
│ get_crawl_status             │ ℹ️       │ Responses contain verbose technical identifiers (UUIDs, hashes)             │
└──────────────────────────────┴──────────┴──────────────────────────────────────────────────────────────────────────┘

🎯 Token Efficiency Recommendations:
   1. Implement response size limits for 1 tool with oversized responses (>25k tokens)
   2. Add pagination support to 1 tool that returns collections
   3. Add filtering capabilities to 1 tool to reduce response size
   4. Replace verbose technical identifiers with semantic ones in 1 tool
```

--------------------------------

### MCP Doctor CLI: Generate Dataset - Server Target

Source: https://github.com/destilabs/mcp-doctor/blob/main/README.md

Example of using the `generate-dataset` command to create synthetic datasets from a running MCP server. This requires setting the ANTHROPIC_API_KEY and specifies the server target, number of tasks, and LLM timeout.

```bash
# Generate 8 tasks using tools fetched from a running server
export ANTHROPIC_API_KEY=sk-ant-example
mcp-doctor generate-dataset --target http://localhost:8000/mcp --num-tasks 8 --llm-timeout 90 --output dataset.json
```

--------------------------------

### MCP Doctor CLI: Generate Dataset - Local JSON Definition

Source: https://github.com/destilabs/mcp-doctor/blob/main/README.md

Example of using the `generate-dataset` command to create tasks from a local JSON file defining tools. This requires setting the OPENAI_API_KEY and specifies the tools file and number of tasks.

```bash
# Generate tasks from a local JSON definition using OpenAI
export OPENAI_API_KEY=sk-open-example
mcp-doctor generate-dataset --tools-file tools.json --num-tasks 5
```

--------------------------------

### MCPClient: Low-level async client for MCP servers

Source: https://context7.com/destilabs/mcp-doctor/llms.txt

Demonstrates how to initialize and use the MCPClient to connect to MCP servers (HTTP, NPX), retrieve server info, list tools, and call tools.

```APIDOC
## Python API: `MCPClient`

Low-level async client for connecting to MCP servers. Automatically detects transport type (HTTP, SSE, or STDIO). Supports NPX process management, custom headers, and environment variable injection.

```python
import asyncio
from mcp_analyzer.mcp_client import MCPClient, MCPClientError

async def diagnose():
    # HTTP server
    client = MCPClient("http://localhost:8000/mcp", timeout=30)

    # NPX server with API key
    client = MCPClient(
        "npx firecrawl-mcp",
        timeout=60,
        env_vars={"FIRECRAWL_API_KEY": "abc123"},
        working_dir="/tmp",
    )

    # HTTP server with bearer token header
    client = MCPClient(
        "https://api.example.com/mcp",
        headers={"Authorization": "Bearer mytoken"},
    )

    try:
        # Initialize connection / launch NPX process
        info = await client.get_server_info()
        print(f"Server: {info.server_name} v{info.server_version}")
        print(f"Protocol: {info.protocol_version}")
        print(f"Capabilities: {info.capabilities}")

        # List all tools
        tools = await client.get_tools()
        for tool in tools:
            print(f"  - {tool.name}: {tool.description}")

        # Execute a tool call
        result = await client.call_tool("search_docs", {"query": "hello world", "limit": 5})
        print(result)

        # Get resolved server URL (useful after NPX launch)
        print(client.get_server_url())  # e.g., "http://localhost:3001"

    except MCPClientError as e:
        print(f"Connection failed: {e}")
    finally:
        await client.close()  # stops NPX process if launched

asyncio.run(diagnose())
```
```

--------------------------------

### Run Individual Linting Tools

Source: https://github.com/destilabs/mcp-doctor/blob/main/README.md

Execute individual code quality and formatting tools.

```bash
black src/ tests/
isort src/ tests/
mypy src/
```

--------------------------------

### Analyze tool descriptions for AI-agent friendliness using DescriptionChecker

Source: https://context7.com/destilabs/mcp-doctor/llms.txt

This Python code demonstrates how to use `DescriptionChecker` to evaluate `MCPTool` descriptions for clarity, completeness, and adherence to AI-agent friendly standards. It highlights issues like vague names, short descriptions, and ambiguous parameters.

```python
from mcp_analyzer.checkers.descriptions import (
    DescriptionChecker,
    IssueType,
    Severity,
)
from mcp_analyzer.mcp_client import MCPTool

checker = DescriptionChecker()

# Build sample tools
tools = [
    MCPTool(
        name="scrape_url",
        description="Fetches and extracts text content from a web page. Use this when you need to retrieve information from a URL.",
        input_schema={
            "properties": {
                "url": {"type": "string", "description": "The URL to scrape"},
                "limit": {"type": "integer", "description": "Max content length"},
            },
            "required": ["url"],
        },
    ),
    MCPTool(
        name="do_stuff",  # vague name with poor description
        description="handle data",
        input_schema={
            "properties": {
                "id": {"type": "string"},   # ambiguous parameter
                "data": {"type": "object"}, # ambiguous parameter
            }
        },
    ),
]

results = checker.analyze_tool_descriptions(tools)

# results structure:
# {
#   "issues": [DescriptionIssue, ...],
#   "statistics": {
#     "total_tools": 2,
#     "tools_with_issues": 1,
#     "errors": 0, "warnings": 2, "info": 1,
#     "tools_passed": 1
#   },
#   "recommendations": ["Rename 2 ambiguous parameters...", ...]
# }

stats = results["statistics"]
print(f"Passed: {stats['tools_passed']}/{stats['total_tools']}")

for issue in results["issues"]:
    print(f"[{issue.severity}] {issue.tool_name} ({issue.field}): {issue.message}")
    print(f"  → {issue.suggestion}")

# Output:
# [warning] do_stuff (description): Description is too short (11 chars)
#   → Expand description to include purpose, usage context, and expected outcomes
# [warning] do_stuff (parameter.id): Parameter 'id' has ambiguous name
#   → Use a more descriptive name like 'user_id', 'account_data', etc.
# [info] do_stuff (description): Contains technical jargon: ...

```

--------------------------------

### Set OpenAI API Key

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/llm-parameter-generation.md

Configure your environment with the OpenAI API key for authentication. This is recommended for cost efficiency.

```bash
export OPENAI_API_KEY="sk-..."
```

--------------------------------

### Handle Sample Data in Python

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/troubleshooting-token-efficiency.md

Implement graceful handling of sample queries within your tool's Python function. This ensures that MCP Doctor's test queries return predictable results.

```python
def search_documents(query: str, limit: int = 10):
    # Handle test queries gracefully
    if query == "sample query":
        return {
            "results": [
                {"title": "Sample Document", "content": "Sample content..."}
                # ... generate sample results
            ],
            "total": limit
        }
    
    # Real implementation
    return perform_actual_search(query, limit)
```

--------------------------------

### Analyze with Description Check

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/troubleshooting-token-efficiency.md

Use this command to perform static analysis when HTTP transport is not supported for token efficiency. This bypasses the need for tool execution capabilities.

```bash
mcp-doctor analyze --target http://your-server --check descriptions
```

--------------------------------

### Validate Tool Parameter Type Handling

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/troubleshooting-token-efficiency.md

Ensure your tool functions correctly handle expected data types. This Python example shows a tool expecting an integer but receiving a string, which could cause errors.

```python
# If your tool expects an integer but gets a string
def my_tool(limit: int):  # MCP Doctor generates limit=10
    return f"Processing {limit} items"
```

--------------------------------

### DescriptionChecker: Rule-based checker for tool descriptions

Source: https://context7.com/destilabs/mcp-doctor/llms.txt

Explains how to use the DescriptionChecker to evaluate tool descriptions for AI-agent friendliness, checking for issues like vague names, short descriptions, and ambiguous parameters.

```APIDOC
## Python API: `DescriptionChecker`

Rule-based checker that evaluates tool descriptions for AI-agent friendliness. Checks for missing/short descriptions, vague purpose statements, technical jargon, missing usage context, and ambiguous/generic parameter names.

```python
from mcp_analyzer.checkers.descriptions import (
    DescriptionChecker,
    IssueType,
    Severity,
)
from mcp_analyzer.mcp_client import MCPTool

checker = DescriptionChecker()

# Build sample tools
tools = [
    MCPTool(
        name="scrape_url",
        description="Fetches and extracts text content from a web page. Use this when you need to retrieve information from a URL.",
        input_schema={
            "properties": {
                "url": {"type": "string", "description": "The URL to scrape"},
                "limit": {"type": "integer", "description": "Max content length"},
            },
            "required": ["url"],
        },
    ),
    MCPTool(
        name="do_stuff",  # vague name with poor description
        description="handle data",
        input_schema={
            "properties": {
                "id": {"type": "string"},   # ambiguous parameter
                "data": {"type": "object"}, # ambiguous parameter
            }
        },
    ),
]

results = checker.analyze_tool_descriptions(tools)

# results structure:
# {
#   "issues": [DescriptionIssue, ...],
#   "statistics": {
#     "total_tools": 2,
#     "tools_with_issues": 1,
#     "errors": 0, "warnings": 2, "info": 1,
#     "tools_passed": 1
#   },
#   "recommendations": ["Rename 2 ambiguous parameters...", ...]
# }

stats = results["statistics"]
print(f"Passed: {stats['tools_passed']}/{stats['total_tools']}")

for issue in results["issues"]:
    print(f"[{issue.severity}] {issue.tool_name} ({issue.field}): {issue.message}")
    print(f"  → {issue.suggestion}")

# Output:
# [warning] do_stuff (description): Description is too short (11 chars)
#   → Expand description to include purpose, usage context, and expected outcomes
# [warning] do_stuff (parameter.id): Parameter 'id' has ambiguous name
#   → Use a more descriptive name like 'user_id', 'account_data', etc.
# [info] do_stuff (description): Contains technical jargon: ...
```
```

--------------------------------

### Auto-format Code

Source: https://github.com/destilabs/mcp-doctor/blob/main/README.md

Automatically format the project's code using black and isort.

```bash
./scripts/format.sh
```

--------------------------------

### Generate HTML Coverage Report

Source: https://github.com/destilabs/mcp-doctor/blob/main/README.md

Generate a detailed HTML coverage report and open it in the browser.

```bash
pytest --cov-report=html
open htmlcov/index.html  # View coverage report
```

--------------------------------

### Initialize TokenEfficiencyChecker

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/token-efficiency-architecture.md

Initializes the main orchestrator for token efficiency analysis, setting configuration parameters and detection patterns.

```python
class TokenEfficiencyChecker:
    def __init__(self):
        self.max_recommended_tokens = 25000  # Anthropic's guideline
        self.sample_requests_per_tool = 3    # Test scenarios per tool
        
        # Detection patterns
        self.verbose_id_patterns = [...]     # UUID, hash patterns
        self.pagination_params = [...]       # Pagination indicators
        self.filtering_params = [...]        # Filtering indicators
```

--------------------------------

### Extract Parameters for Manual Overrides

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/tool-call-cache.md

Uses cache statistics and `jq` to extract successful input parameters from cached tool calls for creating manual override files.

```bash
# View cache
mcp-doctor cache-stats --server "https://mcp.explorium.ai/sse"

# Find cached files
ls ~/.mcp-analyzer/tool-call-cache/*/match-business/

# Extract successful parameters
cat ~/.mcp-analyzer/tool-call-cache/*/match-business/minimal_llm_corrected_*.json | \
  jq '.input_params' > overrides.json

```

--------------------------------

### Generate and Upload Dataset to LangSmith

Source: https://github.com/destilabs/mcp-doctor/blob/main/README.md

Use this command to generate tasks and upload them to LangSmith. Ensure LANGSMITH_API_KEY is set. You can also set ANTHROPIC_API_KEY or OPENAI_API_KEY. Use --llm-timeout to extend model response wait times. Add --push-to-langsmith to stream data directly to LangSmith. Customize dataset name, project, description, and endpoint as needed. Use --env-file for file-based secrets.

```bash
export LANGSMITH_API_KEY=ls-example
mcp-doctor generate-dataset --target http://localhost:8000/mcp --num-tasks 5 \
  --push-to-langsmith --langsmith-project "MCP Evaluation" \
  --langsmith-dataset-name "MCP Doctor Synthetic"
```

--------------------------------

### Analyze Token Efficiency with Verbose Output

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/troubleshooting-token-efficiency.md

Run the analysis in verbose mode to see detailed information about generated arguments, which can help diagnose issues with tool execution.

```bash
# Run with verbose mode to see what arguments are being generated
mcp-doctor analyze --target "npx your-mcp-server" --check token_efficiency --verbose
```

--------------------------------

### Cache Directory Layout

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/tool-call-cache.md

Illustrates the file structure for storing cached tool calls, including metadata and individual tool call records.

```bash
~/.mcp-analyzer/tool-call-cache/
└── a1b2c3d4e5f6g7h8/              # Server URL hash
    ├── _metadata.json              # Server information
    ├── match-business/             # Tool directory
    │   ├── _index.json            # Tool statistics
    │   ├── minimal_20251003_120000_123456.json
    │   ├── minimal_llm_corrected_20251003_120005_789012.json
    │   └── typical_20251003_120010_345678.json
    └── enrich-prospects/
        ├── _index.json
        └── minimal_llm_corrected_20251003_120015_901234.json

```

--------------------------------

### Token Efficiency Checker Configuration

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/token-efficiency-architecture.md

Initializes configuration parameters for the TokenEfficiencyChecker, including token limits and detection patterns.

```python
class TokenEfficiencyChecker:
    def __init__(self):
        # Token limits (based on Anthropic guidelines)
        self.max_recommended_tokens = 25000
        
        # Test scenarios
        self.sample_requests_per_tool = 3
        
        # Detection patterns (customizable)
        self.pagination_params = [
            "limit", "offset", "page", "page_size", "per_page",
            "cursor", "next_token", "continuation_token"
        ]
        
        self.filtering_params = [
            "filter", "where", "query", "search", "include", "exclude",
            "fields", "select", "only", "except", "type", "status"
        ]
```

--------------------------------

### Implement Pagination in Python

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/troubleshooting-token-efficiency.md

Support pagination parameters like 'limit' and 'offset' in your Python functions. This is crucial for MCP Doctor's testing of large datasets.

```python
def list_items(limit: int = 10, offset: int = 0):
    # Support the pagination parameters that MCP Doctor tests
    items = get_items_from_database(limit=limit, offset=offset)
    return {
        "items": items,
        "total": get_total_count(),
        "limit": limit,
        "offset": offset
    }
```

--------------------------------

### Python: Generate Sample Value for Parameter

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/token-efficiency-arguments.md

This method creates contextually appropriate values for parameters based on their names and types. It handles common types like string, integer, and boolean, with specific logic for URLs, emails, queries, and IDs within strings.

```python
def _generate_sample_value(self, param_name: str, param_schema: Dict[str, Any]) -> Any:
    param_type = param_schema.get("type", "string")
    
    if param_type == "string":
        param_lower = param_name.lower()
        
        # URL parameters
        if any(word in param_lower for word in ["url", "link", "href"]):
            return "https://example.com"
        
        # Email parameters
        elif any(word in param_lower for word in ["email", "mail"]):
            return "test@example.com"
        
        # Search/query parameters
        elif any(word in param_lower for word in ["query", "search", "term"]):
            return "sample query"
        
        # ID parameters
        elif any(word in param_lower for word in ["id", "key"]):
            return "sample_id"
        
        # Generic string
        else:
            return "sample_value"
    
    elif param_type == "integer":
        return 1
    elif param_type == "boolean":
        return True
    # ... and so on
```

--------------------------------

### Minimal Scenario Test Call

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/token-efficiency-arguments.md

A minimal JSON payload for testing the 'search_users' tool with only the required 'query' parameter.

```json
{"query": "sample query"}
```

--------------------------------

### Run Token Efficiency Check

Source: https://github.com/destilabs/mcp-doctor/blob/main/README.md

Perform a token efficiency analysis on an NPX-launched MCP server. This check helps optimize the server's token usage.

```bash
mcp-doctor analyze --target "npx firecrawl-mcp" --check token_efficiency
```

--------------------------------

### Troubleshooting Cache Directory Issues

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/tool-call-cache.md

If you cannot find the cache directory, use the 'mcp-doctor cache-stats' command to list all cache locations.

```bash
mcp-doctor cache-stats  # Shows all cache locations
```

--------------------------------

### Analyze Token Efficiency with STDIO Transport

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/troubleshooting-token-efficiency.md

This command initiates token efficiency analysis, assuming your MCP server uses STDIO transport, which is common for NPX-based servers.

```bash
mcp-doctor analyze --target "npx your-mcp-server" --check token_efficiency
```

--------------------------------

### Run Tests with Coverage

Source: https://github.com/destilabs/mcp-doctor/blob/main/CONTRIBUTING.md

Measure test coverage by running tests with coverage and then generating a report.

```bash
coverage run -m pytest tests/
coverage report -m
```

--------------------------------

### Typical Scenario Test Call

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/token-efficiency-arguments.md

A typical JSON payload for testing the 'search_users' tool, including 'query', 'page', and 'per_page' parameters.

```json
{
  "query": "sample query",
  "page": 1,
  "per_page": 10
}
```

--------------------------------

### Test Changes and Check Formatting

Source: https://github.com/destilabs/mcp-doctor/blob/main/CONTRIBUTING.md

Run tests and check code formatting using pytest, Black, and isort as part of the pull request preparation.

```bash
python -m pytest tests/ -v
black --check src/ tests/
isort --check-only src/ tests/
```

--------------------------------

### Verify MCP Server Tool Support

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/troubleshooting-token-efficiency.md

Use this curl command to check if your MCP server supports the 'tools/list' method, which is necessary for tool calling.

```bash
# Verify your server supports tools/call method
curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
```

--------------------------------

### Initialize ToolCallCache with Custom Directory

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/tool-call-cache.md

Specify a custom directory for the tool call cache during initialization using the 'cache_dir' argument.

```python
from pathlib import Path
from mcp_analyzer.checkers.tool_call_cache import ToolCallCache

custom_dir = Path("/custom/cache/location")
cache = ToolCallCache("https://server.com", cache_dir=custom_dir)
```

--------------------------------

### Token Efficiency Analysis Pipeline

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/token-efficiency-architecture.md

Orchestrates static and dynamic analysis of tools to identify token efficiency issues. Requires a list of tools and an MCP client for dynamic testing.

```python
async def analyze_token_efficiency(self, tools, mcp_client):
    for tool in tools:
        # Static analysis (no tool execution)
        static_issues = self._analyze_tool_schema(tool)
        
        # Dynamic analysis (actual tool calls)
        metrics = await self._measure_response_sizes(tool, mcp_client)
        dynamic_issues = self._analyze_response_metrics(metrics)
```

--------------------------------

### Check Code Quality

Source: https://github.com/destilabs/mcp-doctor/blob/main/README.md

Perform code quality checks using black, isort, and mypy.

```bash
./scripts/lint.sh
```

--------------------------------

### Format Code with Black and isort

Source: https://github.com/destilabs/mcp-doctor/blob/main/CONTRIBUTING.md

Apply code formatting using Black for general code style and isort for import sorting across specified directories.

```bash
black src/ tests/
isort src/ tests/
```

--------------------------------

### Diagnose HTTP Server using Python MCP Client

Source: https://github.com/destilabs/mcp-doctor/blob/main/README.md

Use the MCPClient to connect to an HTTP server, retrieve tools, and analyze their descriptions using DescriptionChecker. Ensure to close the client in a finally block.

```python
import asyncio
from mcp_analyzer.mcp_client import MCPClient
from mcp_analyzer.checkers.descriptions import DescriptionChecker

async def diagnose_http_server():
    client = MCPClient("http://localhost:8000/mcp")
    
    try:
        tools = await client.get_tools()
        
        checker = DescriptionChecker()
        results = checker.analyze_tool_descriptions(tools)
        
        return results
    finally:
        await client.close()

# Run diagnosis
results = asyncio.run(diagnose_http_server())
print(f"Found {len(results['issues'])} issues")
```

--------------------------------

### Measure Response Sizes for Dynamic Analysis

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/token-efficiency-architecture.md

Measures response sizes by generating test scenarios, executing tool calls via an MCP client, and estimating token counts. This is part of the dynamic analysis phase.

```python
async def _measure_response_sizes(self, tool, mcp_client):
    # Generate 3 test scenarios
    scenarios = self._generate_test_scenarios(tool)
    
    for scenario in scenarios:
        # Execute actual tool call
        response = await mcp_client.call_tool(tool.name, scenario.params)
        
        # Measure and analyze
        token_count = self._estimate_token_count(response)
        # ... collect metrics
```

--------------------------------

### Run Specific Test File

Source: https://github.com/destilabs/mcp-doctor/blob/main/CONTRIBUTING.md

Execute tests from a specific file, such as test_descriptions.py, using pytest with verbose output.

```bash
python -m pytest tests/test_descriptions.py -v
```

--------------------------------

### Analyze Performance Trends

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/tool-call-cache.md

Runs analysis checks and then uses `find` and `jq` to extract and format performance metrics (tool name, timestamp, token count, response time) from all cached JSON files for trend analysis.

```bash
# Run checks over time
mcp-doctor analyze --target "..." --check token_efficiency

# Analyze trends
find ~/.mcp-analyzer/tool-call-cache -name "*.json" -not -name "_*" | \
  xargs jq -r '[.tool_name, .timestamp, .metrics.token_count, .metrics.response_time_seconds] | @csv'

```

--------------------------------

### Basic Analysis with Default GPT-4o-mini

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/llm-parameter-generation.md

Run mcp-doctor analysis using the default GPT-4o-mini model for automatic parameter correction. The tool will retry calls if validation fails.

```bash
mcp-doctor analyze \
  --target "https://mcp.explorium.ai/sse" \
  --oauth \
  --check token_efficiency \
  --show-tool-outputs
```

--------------------------------

### Run All Tests

Source: https://github.com/destilabs/mcp-doctor/blob/main/CONTRIBUTING.md

Execute all tests in the project using pytest. Use the -v flag for verbose output.

```bash
python -m pytest tests/ -v
```

--------------------------------

### Generate Test Scenarios for Tool Evaluation

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/token-efficiency-architecture.md

Generates exactly 3 test scenarios (minimal, typical, large) for a given tool based on its input schema to test token usage under different conditions.

```python
def _generate_test_scenarios(self, tool) -> List[EvaluationScenario]:
    """
    Generates exactly 3 scenarios for comprehensive testing:
    1. Minimal - required params only
    2. Typical - required + common optional params  
    3. Large - required + params that might cause oversized responses
    """
    
    scenarios = []
    schema = tool.input_schema
    properties = schema.get("properties", {})
    required = schema.get("required", [])
    
    # Scenario 1: Minimal
    minimal_params = {}
    for param in required:
        minimal_params[param] = self._generate_sample_value(param, properties[param])
    
    # Scenario 2: Typical (add small pagination)
    typical_params = minimal_params.copy()
    for pagination_param in self.pagination_params:
        if pagination_param in properties:
            if pagination_param in ["limit", "count", "per_page"]:
                typical_params[pagination_param] = 10  # Small limit
            break
    
    # Scenario 3: Large (add large pagination)
    large_params = minimal_params.copy()
    for pagination_param in self.pagination_params:
        if pagination_param in properties:
            if pagination_param in ["limit", "count", "per_page"]:
                large_params[pagination_param] = 1000  # Large limit
            break
    
    return [
        EvaluationScenario("minimal", minimal_params, "Required params only"),
        EvaluationScenario("typical", typical_params, "Normal usage"),
        EvaluationScenario("large", large_params, "Test size limits")
    ]
```

--------------------------------

### Troubleshooting Cache Size Issues

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/tool-call-cache.md

To manage cache size, first check the current disk usage with 'du -sh' and then clear old caches using 'mcp-doctor cache-clear'.

```bash
du -sh ~/.mcp-analyzer/tool-call-cache/
mcp-doctor cache-clear  # Clear old caches
```

--------------------------------

### Detect Pagination Support

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/token-efficiency-architecture.md

Checks if a tool supports pagination by looking for common pagination parameters in its input schema. If pagination is not supported but the tool likely returns collections, an informational issue is raised.

```python
def _check_pagination_support(self, tool) -> List[TokenEfficiencyIssue]:
    input_schema = tool.input_schema
    properties = input_schema.get("properties", {})
    
    # Check for pagination parameter presence
    has_pagination = any(
        param_name.lower() in [p.lower() for p in self.pagination_params]
        for param_name in properties.keys()
    )
    
    # Check if tool likely returns collections
    if not has_pagination and self._likely_returns_collections(tool):
        return [TokenEfficiencyIssue(
            tool_name=tool.name,
            issue_type=IssueType.NO_PAGINATION,
            severity=Severity.INFO,
            message="Tool likely returns collections but doesn't support pagination",
            suggestion="Consider adding pagination parameters (limit, offset, page)"
        )]
```

--------------------------------

### Export Cache for Sharing

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/tool-call-cache.md

Compresses the cache directory for a specific server into a tar.gz archive for sharing with team members.

```bash
# Export cache for a server
tar -czf mcp-cache.tar.gz ~/.mcp-analyzer/tool-call-cache/a1b2c3d4e5f6g7h8/

# Share with team

```

--------------------------------

### View Cache Statistics

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/tool-call-cache.md

Displays statistics about the tool call cache, either for all servers or a specific server.

```bash
mcp-doctor cache-stats

```

```bash
mcp-doctor cache-stats --server "https://mcp.explorium.ai/sse"

```

--------------------------------

### Manual Overrides Configuration

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/llm-parameter-generation.md

This JSON file defines manual overrides for specific tools, allowing you to specify exact test data that takes precedence over LLM generation.

```json
{
  "enrich-business": {
    "business_ids": ["real_business_id_123"],
    "parameters": ["revenue", "employee_count"]
  }
}
```

--------------------------------

### Run All Available Checks

Source: https://github.com/destilabs/mcp-doctor/blob/main/README.md

Execute all diagnostic checks available for an NPX-launched MCP server. This provides a comprehensive overview of the server's health.

```bash
mcp-doctor analyze --target "npx firecrawl-mcp" --check all
```

--------------------------------

### Analyze NPX-Launched MCP Server

Source: https://github.com/destilabs/mcp-doctor/blob/main/README.md

Diagnose an MCP server launched via NPX. The target should be the command used to launch the server.

```bash
mcp-doctor analyze --target "npx firecrawl-mcp"
```

--------------------------------

### Check Code Formatting

Source: https://github.com/destilabs/mcp-doctor/blob/main/CONTRIBUTING.md

Verify code formatting without making changes using Black's --check and --diff options, and isort's --check-only and --diff options.

```bash
black --check --diff src/ tests/
isort --check-only --diff src/ tests/
```

--------------------------------

### Inspect NPX Server for Risky Tools

Source: https://github.com/destilabs/mcp-doctor/blob/main/README.md

Inspect an NPX-launched MCP server specifically for risky tools. This is part of the security audit and helps identify potentially harmful tool configurations.

```bash
mcp-doctor analyze --target "npx firecrawl-mcp" --check security
```

--------------------------------

### Integrate MCP Token Efficiency Test in GitHub Actions

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/llm-parameter-generation.md

Configure a GitHub Actions workflow to automatically test MCP token efficiency. This snippet shows how to set up the environment variables, including the OpenAI API key, and run the mcp-doctor analyze command with a specified LLM model.

```yaml
# .github/workflows/test.yml
- name: Test MCP Token Efficiency
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
  run: |
    mcp-doctor analyze \
      --target "$MCP_SERVER_URL" \
      --check token_efficiency \
      --llm-model gpt-4o-mini
```

--------------------------------

### Run Tests with Coverage

Source: https://github.com/destilabs/mcp-doctor/blob/main/README.md

Run tests and generate HTML and terminal coverage reports using pytest-cov.

```bash
pytest --cov=src/mcp_analyzer --cov-report=html --cov-report=term
```

--------------------------------

### Set Anthropic API Key

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/llm-parameter-generation.md

Configure your environment with the Anthropic API key for authentication when using Claude models.

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
```

--------------------------------

### Diagnose NPX Server using Python MCP Client

Source: https://github.com/destilabs/mcp-doctor/blob/main/README.md

Diagnose an NPX server using MCPClient. Supports setting environment variables directly in the command or via kwargs. The client automatically launches and stops the NPX server.

```python
import asyncio
from mcp_analyzer.mcp_client import MCPClient
from mcp_analyzer.checkers.descriptions import DescriptionChecker

async def diagnose_npx_server():
    # Method 1: Environment variables in command
    client = MCPClient("export FIRECRAWL_API_KEY=abc123 && npx firecrawl-mcp")
    
    # Method 2: Environment variables via kwargs
    # client = MCPClient("npx firecrawl-mcp", env_vars={"FIRECRAWL_API_KEY": "abc123"})
    
    try:
        # Server will be launched automatically
        server_info = await client.get_server_info()
        tools = await client.get_tools()
        
        checker = DescriptionChecker()
        results = checker.analyze_tool_descriptions(tools)
        
        print(f"Diagnosed NPX server at: {client.get_server_url()}")
        return results
        
    finally:
        # This will automatically stop the NPX server
        await client.close()
```

--------------------------------

### Create Feature Branch

Source: https://github.com/destilabs/mcp-doctor/blob/main/CONTRIBUTING.md

Create a new branch for feature development, branching off the main branch.

```bash
git checkout -b feature/your-feature-name
```

--------------------------------

### Project Structure Overview

Source: https://github.com/destilabs/mcp-doctor/blob/main/CONTRIBUTING.md

An overview of the mcp-doctor project's directory structure, highlighting the main package, tests, documentation, and scripts.

```tree
mcp-doctor/
├── src/mcp_analyzer/          # Main package
│   ├── checkers/              # Diagnostic checkers
│   ├── cli.py                 # Command-line interface
│   ├── mcp_client.py         # MCP client implementations
│   └── reports.py            # Report generation
├── tests/                     # Test suite
├── docs/                      # Documentation
└── scripts/                   # Development scripts
```

--------------------------------

### Database Query Tool Schema

Source: https://github.com/destilabs/mcp-doctor/blob/main/docs/token-efficiency-arguments.md

Schema for a 'search_users' tool, defining parameters for querying users with pagination.

```json
{
  "name": "search_users",
  "description": "Search for users in the database",
  "parameters": {
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query"
      },
      "page": {
        "type": "integer", 
        "description": "Page number"
      },
      "per_page": {
        "type": "integer",
        "description": "Results per page"
      }
    },
    "required": ["query"]
  }
}
```

--------------------------------

### Analyze HTTP Server with MCP Doctor

Source: https://github.com/destilabs/mcp-doctor/blob/main/README.md

Use the 'analyze' command with the --target flag to point to an HTTP MCP server endpoint.

```bash
mcp-doctor analyze --target http://localhost:8000/mcp
```

```bash
mcp-doctor analyze --target https://api.example.com/mcp
```