Documentation Search MCP Server - Tutorial

Complete guide to using the documentation-search-enhanced MCP server for documentation search, security scanning, and project generation.

Table of Contents

1. What is MCP?
2. Installation & Setup
3. Available Tools
4. Documentation Search
5. Security Scanning
6. Project Generation
7. Learning & Examples
8. Advanced Usage
9. Troubleshooting

What is MCP?

Model Context Protocol (MCP) is a standard for connecting AI assistants to external tools and data sources. Think of it as a plugin system that lets Claude, Cursor, and other AI assistants use specialized tools.

How it works:

1. You install an MCP server (like documentation-search-enhanced)
2. Configure your AI client (Claude Desktop, Codex CLI, Cursor, etc.)
3. The AI can now call tools from the server to answer your questions

Example workflow:

You: "Search FastAPI docs for authentication examples"
  ↓
Claude Desktop sees you need documentation
  ↓
Claude calls the semantic_search tool from documentation-search-enhanced
  ↓
Tool fetches and searches FastAPI documentation
  ↓
Claude receives results and explains them to you

Installation & Setup

Prerequisites

• Python 3.12+ (3.13 supported for core features)
• uv package manager: https://docs.astral.sh/uv
• One of: Claude Desktop, Codex CLI, Cursor, or another MCP client

Step 1: Install uv

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with Homebrew
brew install uv

# Verify installation
which uvx
# Expected: /Users/yourusername/.local/bin/uvx

Step 2: Test the Package

# This will download and cache the package
uvx documentation-search-enhanced@1.6.3
# You'll see JSON-RPC errors - this is normal (server needs a client)
# Press Ctrl+C to exit

Step 3: Configure Your MCP Client

Option A: Claude Desktop

1. Find your uvx path:

which uvx
# Copy this path

2. Edit Claude Desktop config:

# macOS
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Linux
nano ~/.config/Claude/claude_desktop_config.json

3. Add this configuration (replace paths with your actual paths):

{
  "mcpServers": {
    "documentation-search-enhanced": {
      "command": "/Users/yourusername/.local/bin/uvx",
      "args": ["documentation-search-enhanced@1.6.3"],
      "env": {
        "SERPER_API_KEY": "your_api_key_here_or_leave_empty"
      }
    }
  }
}

4. Restart Claude Desktop

5. Look for the 🔌 icon in Claude Desktop - it shows connected MCP servers

Option B: Codex CLI

# Get your uvx path
which uvx

# Add the MCP server (with SERPER API key)
codex mcp add documentation-search-enhanced \
  --env SERPER_API_KEY=your_key_here \
  -- /Users/yourusername/.local/bin/uvx documentation-search-enhanced@1.6.3

# Or without SERPER API key (uses prebuilt index)
codex mcp add documentation-search-enhanced \
  -- /Users/yourusername/.local/bin/uvx documentation-search-enhanced@1.6.3

# Verify
codex mcp list

# Start interactive session
codex

Option C: Cursor

In Cursor settings, add to MCP configuration:

{
  "mcpServers": {
    "documentation-search-enhanced": {
      "command": "/Users/yourusername/.local/bin/uvx",
      "args": ["documentation-search-enhanced@1.6.3"]
    }
  }
}

Optional: Enable Semantic Search

For AI-powered semantic search (adds ~600MB, Python 3.12 only):

# Create a virtual environment
python3.12 -m venv ~/.venv-doc-search
source ~/.venv-doc-search/bin/activate

# Install with vector search
pip install documentation-search-enhanced[vector]==1.6.3

# Update your MCP config to use this Python instead of uvx
# Replace "command" with: "/Users/yourusername/.venv-doc-search/bin/python"
# Replace "args" with: ["-m", "documentation_search_enhanced.main"]

Available Tools

Core Tools

Documentation Search

Basic Search

Example 1: Simple Documentation Query

You: "How do I set up authentication in FastAPI?"

What happens:
- Claude calls semantic_search(query="FastAPI authentication", libraries=["fastapi"])
- Tool searches FastAPI documentation
- Returns relevant sections about OAuth2, JWT, security
- Claude explains the concepts and provides code examples

Example 2: Multi-Library Search

You: "Compare authentication approaches in FastAPI vs Flask"

What happens:
- Claude calls semantic_search(query="authentication", libraries=["fastapi", "flask"])
- Tool searches both documentation sets
- Returns authentication docs from both frameworks
- Claude provides comparative analysis

Example 3: Specific Topic Search

You: "Show me React hooks documentation for useEffect"

What happens:
- Claude calls semantic_search(query="useEffect hook lifecycle", libraries=["react"])
- Tool finds React docs on useEffect
- Claude explains usage patterns and common pitfalls

Advanced Search Features

Version-Specific Documentation:

You: "How does async/await work in Python 3.11?"

What happens:
- Claude calls semantic_search(query="async await", libraries=["python"], version="3.11")
- Tool fetches Python 3.11 specific documentation
- Returns version-specific syntax and features

With Vector Search (if installed):

You: "Find documentation about database connection pooling"

What happens:
- Claude calls semantic_search(query="...", use_vector_rerank=True)
- Tool uses semantic embeddings for better relevance
- Results ranked by: 50% semantic similarity + 30% keywords + 20% source authority
- More contextually relevant results than keyword-only search

Supported Documentation Sources

Web Frameworks:

• FastAPI, Flask, Django, Express.js, NestJS, Spring Boot

Frontend:

• React, Vue, Angular, Svelte, Next.js, Nuxt

Data Science:

• NumPy, Pandas, Scikit-learn, TensorFlow, PyTorch

Cloud & DevOps:

• AWS, Azure, GCP, Docker, Kubernetes, Terraform

Languages:

• Python, JavaScript, TypeScript, Go, Rust, Java

And 70+ more sources

Security Scanning

Scan Local Project

Example 1: Quick Vulnerability Check

You: "Scan my project for vulnerabilities"
You: "The project is at /Users/me/myapp"

What happens:
- Claude calls scan_project_dependencies(project_path="/Users/me/myapp")
- Tool detects package manager (requirements.txt, package.json, etc.)
- Scans with Safety, pip-audit, and OSV
- Returns list of vulnerabilities with CVSS scores
- Claude summarizes critical issues and suggests fixes

Example output:

Found 3 vulnerabilities:

CRITICAL (CVSS 9.8):
- Package: requests==2.25.1
- CVE-2023-32681: Unintended leak of Proxy-Authorization header
- Fix: Upgrade to requests>=2.31.0

HIGH (CVSS 7.5):
- Package: flask==1.1.2
- CVE-2023-30861: Cookie parsing vulnerability
- Fix: Upgrade to flask>=2.3.2

MEDIUM (CVSS 5.3):
- Package: pyyaml==5.3.1
- CVE-2020-14343: Arbitrary code execution
- Fix: Upgrade to pyyaml>=5.4

Example 2: Detailed Snyk Analysis

You: "Run a detailed security audit on my project"

What happens:
- Claude calls snyk_scan_project(project_path="/Users/me/myapp")
- Snyk performs deep dependency tree analysis
- Checks for outdated packages, licensing issues, and security vulnerabilities
- Returns detailed remediation advice

Example 3: Security Report Generation

You: "Generate a security report for my project and save it to a file"

What happens:
- Claude scans your project
- Formats results as markdown or JSON
- Uses Write tool to save report
- You get a shareable security audit document

Compare Library Security

Example: Choosing Between Libraries

You: "Should I use requests or httpx? Which is more secure?"

What happens:
- Claude calls compare_library_security(libraries=["requests", "httpx"])
- Tool fetches CVE data for both packages
- Compares vulnerability counts, severity, and patching history
- Claude provides recommendation based on security posture

Example output:

Security Comparison: requests vs httpx

requests:
- 12 known CVEs (5 critical, 4 high, 3 medium)
- Last critical CVE: 6 months ago (patched)
- Active maintenance: Yes
- Security score: 7.5/10

httpx:
- 2 known CVEs (0 critical, 1 high, 1 medium)
- Last critical CVE: Never
- Active maintenance: Yes
- Security score: 9.0/10

Recommendation: httpx has a better security track record

Project Generation

Generate Project Starters

Example 1: FastAPI Project

You: "Create a new FastAPI project called 'my-api'"

What happens:
- Claude calls generate_project_starter(
    project_type="fastapi",
    project_name="my-api"
  )
- Tool generates:
  - Project structure (app/, tests/, config/)
  - main.py with example endpoints
  - requirements.txt with dependencies
  - .env.example for configuration
  - README.md with setup instructions
  - Dockerfile and docker-compose.yml

Generated structure:

my-api/
├── app/
│   ├── __init__.py
│   ├── main.py           # FastAPI app with example routes
│   ├── models.py         # Pydantic models
│   ├── database.py       # Database connection
│   └── routers/
│       ├── __init__.py
│       └── users.py      # Example user routes
├── tests/
│   ├── __init__.py
│   └── test_main.py      # Example tests
├── requirements.txt      # Dependencies
├── .env.example          # Environment variables template
├── Dockerfile           # Production-ready container
├── docker-compose.yml   # Local development setup
└── README.md            # Setup and usage instructions

Example 2: React Project

You: "Generate a React project with TypeScript"

What happens:
- Claude calls generate_project_starter(
    project_type="react",
    project_name="my-react-app",
    options={"typescript": true}
  )
- Tool generates:
  - Vite-based React setup
  - TypeScript configuration
  - Example components
  - Routing setup (React Router)
  - State management boilerplate
  - Testing setup (Vitest)

Example 3: Full-Stack Project

You: "Create a full-stack app with FastAPI backend and React frontend"

What happens:
- Claude generates both projects
- Creates shared docker-compose.yml
- Sets up API proxy configuration
- Configures CORS
- Provides unified development workflow

Development Environment Setup

Example: Docker Compose Generation

You: "Set up a development environment with PostgreSQL, Redis, and my FastAPI app"

What happens:
- Claude calls manage_dev_environment(
    services=["postgresql", "redis", "fastapi"],
    project_path="/Users/me/myapp"
  )
- Tool generates docker-compose.yml:

version: '3.8'
services:
  db:
    image: postgres:15
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  app:
    build: .
    ports:
      - "8000:8000"
    depends_on:
      - db
      - redis
    environment:
      DATABASE_URL: postgresql://user:password@db:5432/myapp
      REDIS_URL: redis://redis:6379

volumes:
  postgres_data:

To use:

docker-compose up -d

Learning & Examples

Get Learning Path

Example 1: Learning New Framework

You: "I want to learn FastAPI. Create a learning roadmap"

What happens:
- Claude calls get_learning_path(
    technology="fastapi",
    skill_level="beginner",
    goals=["Build REST API", "Deploy to production"]
  )
- Tool generates structured learning path

Example output:

FastAPI Learning Path (Beginner → Intermediate)

Week 1: Fundamentals
✓ Python basics (async/await, type hints)
✓ HTTP protocols and REST APIs
✓ Install FastAPI and Uvicorn
✓ First "Hello World" API
  Resources: FastAPI Tutorial - First Steps

Week 2: Core Concepts
✓ Path parameters and query parameters
✓ Request body with Pydantic models
✓ Response models and status codes
✓ Data validation
  Resources: FastAPI Tutorial - Request Body

Week 3: Database Integration
✓ SQLAlchemy basics
✓ Database models and relationships
✓ CRUD operations
✓ Async database queries
  Resources: FastAPI SQL Databases

Week 4: Authentication & Security
✓ OAuth2 with Password flow
✓ JWT tokens
✓ Password hashing
✓ Dependency injection
  Resources: FastAPI Security

Week 5: Advanced Features
✓ Background tasks
✓ WebSockets
✓ File uploads
✓ Testing with pytest
  Resources: FastAPI Advanced User Guide

Week 6: Deployment
✓ Docker containerization
✓ Environment configuration
✓ Logging and monitoring
✓ Deploy to AWS/Railway/Render
  Resources: FastAPI Deployment

Example 2: Code Examples

You: "Show me examples of JWT authentication in FastAPI"

What happens:
- Claude calls get_code_examples(
    topic="JWT authentication",
    language="python",
    framework="fastapi"
  )
- Tool finds relevant code snippets
- Claude explains and adapts to your needs

Example output:

# JWT Authentication in FastAPI

from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
from jose import JWTError, jwt
from passlib.context import CryptContext
from datetime import datetime, timedelta

# Configuration
SECRET_KEY = "your-secret-key-here"
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

app = FastAPI()

def verify_password(plain_password, hashed_password):
    return pwd_context.verify(plain_password, hashed_password)

def create_access_token(data: dict):
    to_encode = data.copy()
    expire = datetime.utcnow() + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
    to_encode.update({"exp": expire})
    encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
    return encoded_jwt

async def get_current_user(token: str = Depends(oauth2_scheme)):
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        username: str = payload.get("sub")
        if username is None:
            raise HTTPException(status_code=401, detail="Invalid token")
    except JWTError:
        raise HTTPException(status_code=401, detail="Invalid token")
    return username

@app.post("/token")
async def login(form_data: OAuth2PasswordRequestForm = Depends()):
    # Verify user credentials (check database)
    user = authenticate_user(form_data.username, form_data.password)
    if not user:
        raise HTTPException(status_code=401, detail="Incorrect credentials")

    access_token = create_access_token(data={"sub": user.username})
    return {"access_token": access_token, "token_type": "bearer"}

@app.get("/users/me")
async def read_users_me(current_user: str = Depends(get_current_user)):
    return {"username": current_user}

Advanced Usage

Combining Multiple Tools

Example: Complete Project Setup Workflow

You: "I'm starting a new FastAPI project with authentication. Set up everything for me."

What happens (multi-step workflow):
1. Claude generates FastAPI starter
2. Searches FastAPI auth docs
3. Adds authentication code
4. Generates docker-compose with PostgreSQL
5. Scans dependencies for vulnerabilities
6. Provides setup instructions

Example: Security-First Development

You: "I need to choose between Flask, FastAPI, and Django for a new API. Consider security."

What happens:
1. Claude compares security records of all three
2. Searches current best practices for each
3. Provides recommendation based on your requirements
4. Generates starter for chosen framework
5. Pre-configures security best practices

Customizing Search

Disable vector search for faster results:

# Claude will use: use_vector_rerank=False
# Results in <100ms response time vs ~500ms with vector search

Search specific versions:

You: "Find Python 3.12 specific features for asyncio"

# Claude searches: version="3.12" parameter

Filter by source type:

You: "Search only official documentation, no blog posts"

# Claude filters for official doc sources

Troubleshooting

MCP Server Won't Start

Error: MCP startup failed: No such file or directory (os error 2)

Solution:

# 1. Find your actual uvx path
which uvx

# 2. Update config with FULL path (not just "uvx")
# Wrong: "command": "uvx"
# Right: "command": "/Users/yourusername/.local/bin/uvx"

JSON-RPC Errors When Testing

Error: Invalid JSON: EOF while parsing a value

This is normal! MCP servers need a client (Claude Desktop, Codex). You can't run them directly. Just test with your MCP client instead.

Vector Search Not Working

Symptoms: Search results seem basic, no semantic ranking

Causes:

1. Vector dependencies not installed (Python 3.13 or missing [vector] extra)
2. First run is building index (takes a few seconds)

Solutions:

# Check if vector search is available
python3.12 -m pip show sentence-transformers

# If not installed, install with vector extra (Python 3.12 only)
pip install documentation-search-enhanced[vector]==1.6.3

Slow Performance

If searches take >5 seconds:

1. Check SERPER_API_KEY: Without it, the tool crawls documentation in real-time (slower)
2. Prebuilt index: The tool downloads a prebuilt index from GitHub Releases automatically
3. Vector search: Adds ~200-500ms. Disable with use_vector_rerank=False if not needed

Speed comparison:

• With SERPER + prebuilt index: 100-200ms
• With prebuilt index only: 500-1000ms
• Live crawling (no index): 3-10 seconds
• Vector search enabled: +200-500ms

Package Installation Fails

Error: Could not find a version that satisfies the requirement

Solution:

# 1. Check Python version
python --version  # Need 3.12+

# 2. Use uvx (recommended) instead of pip
uvx documentation-search-enhanced@1.6.3

# 3. If using pip, upgrade pip first
pip install --upgrade pip

Can't Find Documentation

If search returns no results:

1. Check spelling of library name
2. Try broader search terms
3. Check if source is supported (see Available Tools section)
4. Use get_docs with direct URL if you know the doc location

Real-World Workflows

Workflow 1: Secure API Development

1. Generate FastAPI starter
   You: "Create a FastAPI project called 'secure-api'"

2. Add authentication
   You: "Add JWT authentication to this project"

3. Security scan
   You: "Scan this project for vulnerabilities"

4. Fix issues
   Claude: "Found 2 vulnerabilities in dependencies"
   You: "Update the requirements.txt with secure versions"

5. Set up development environment
   You: "Add PostgreSQL and Redis to docker-compose"

6. Deploy
   You: "How do I deploy this to AWS?"

Workflow 2: Learning New Technology

1. Get learning path
   You: "I want to learn React. Create a learning roadmap"

2. Start with basics
   You: "Explain React hooks with examples"

3. Build project
   You: "Generate a React project with routing and state management"

4. Find specific examples
   You: "Show me examples of useEffect for data fetching"

5. Add features
   You: "How do I add authentication to this React app?"

Workflow 3: Library Selection

1. Compare options
   You: "Compare FastAPI, Flask, and Django for building REST APIs"

2. Check security
   You: "Which has the best security track record?"

3. Review documentation
   You: "Search each framework's docs for authentication"

4. Generate starter
   You: "Create a starter project with the recommended framework"

5. Verify setup
   You: "Scan the generated project for vulnerabilities"

Tips & Best Practices

Writing Effective Queries

Good queries:

• "Search FastAPI docs for database migrations with Alembic"
• "Find React documentation about performance optimization"
• "Show me examples of async/await in Python"

Less effective queries:

• "docs" (too vague)
• "help" (unclear what you need)
• "fix my code" (AI can't access your code without you sharing it)

Security Scanning Best Practices

1. Scan regularly: Before each deployment
2. Fix critical issues immediately: CVSS 9.0+ vulnerabilities
3. Keep dependencies updated: Use pip list --outdated
4. Document exceptions: If you can't update, document why

Project Generation Tips

1. Customize after generation: Templates are starting points
2. Review generated code: Understand what it does
3. Update dependencies: Check for newer versions
4. Follow the README: Generated projects include setup instructions

Getting Help

Check Logs

Claude Desktop logs:

# macOS
tail -f ~/Library/Logs/Claude/mcp*.log

# Look for errors from documentation-search-enhanced

Codex CLI:

codex --verbose
# Enables detailed logging

Common Issues

Report Issues

GitHub Issues: https://github.com/anton-prosterity/documentation-search-mcp/issues

Include:

• Python version (python --version)
• Package version (uvx documentation-search-enhanced@1.6.3 --version)
• MCP client (Claude Desktop / Codex / Cursor)
• Error messages or logs

What's Next?

Explore more:

• Try semantic search with the [vector] extra
• Generate different project types (React, Django, NestJS)
• Set up security scanning in CI/CD
• Create custom learning paths
• Compare libraries before choosing dependencies

Advanced topics:

• Custom documentation sources (coming soon)
• Private repository scanning
• Team collaboration features
• CI/CD integration examples

Quick Reference

Most Common Commands

Search documentation:

"Search [framework] docs for [topic]"
"Find examples of [feature] in [language]"

Security scanning:

"Scan my project for vulnerabilities"
"Compare security of [library1] vs [library2]"

Project generation:

"Create a [framework] project called [name]"
"Generate docker-compose with [services]"

Learning:

"Create a learning path for [technology]"
"Show me examples of [concept]"

Environment Variables

Supported Project Types

• fastapi - FastAPI REST API
• react - React frontend app
• django - Django web application
• flask - Flask API
• nextjs - Next.js full-stack app
• vue - Vue.js frontend app

Supported Scan Tools

• Safety: Python CVE database
• pip-audit: PyPI advisory database
• OSV: Google's Open Source Vulnerabilities DB
• Snyk: Commercial-grade security scanning

Happy coding with documentation-search-enhanced! 🚀