dev_commands.md

Development Commands

🚀 Quick Start Commands

1. Install Dependencies

uv sync

2. Setup Environment

# Create .env file from template
cp .env.example .env

# Edit .env file and add your Anthropic API key
ANTHROPIC_API_KEY=your_actual_api_key_here

3. Run FastAPI Server

# Standard uvicorn command with auto-reload
uvicorn main:app --reload

# Or with custom host/port
uvicorn main:app --reload --host 0.0.0.0 --port 8000

4. Install MCP Server

# Install the MCP server for Claude Desktop
uv run mcp install mcp_main.py

# Or install from current directory
uv run mcp install .

5. Test MCP Server Locally

# Test the MCP server directly
python mcp_main.py

# Or using uv
uv run mcp_main.py

📊 API Testing

Test FastAPI Endpoints

# Health check
curl http://localhost:8000/health

# Upload PDF
curl -X POST "http://localhost:8000/upload-pdf/" -F "file=@sample.pdf"

# List documents
curl http://localhost:8000/documents/

# Get document status
curl http://localhost:8000/status/{file_id}

🔧 Claude Desktop Configuration

Manual Configuration

1. Open Claude Desktop configuration:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux: ~/.config/claude/claude_desktop_config.json

2. Add the server configuration:

{
  "mcpServers": {
    "pdf-parser": {
      "command": "uv",
      "args": ["--directory", "C:\\path\\to\\your\\pdf-parser", "run", "mcp_main.py"],
      "cwd": "C:\\path\\to\\your\\pdf-parser"
    }
  }
}

3. Restart Claude Desktop

🛠️ Development Tools

Code Quality

# Format code
uv run ruff format .

# Lint code
uv run ruff check .

# Type checking
uv run mypy .

Testing

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=. --cov-report=html

🐛 Debugging

Check Dependencies

python -c "import fitz, tiktoken, anthropic, fastapi, uvicorn, mcp; print('All dependencies OK')"

Verbose Logging

# Run FastAPI with debug logging
uvicorn main:app --reload --log-level debug

# Run MCP server with debug
python mcp_main.py --verbose

Environment Variables

# Check environment variables
python -c "import os; print('ANTHROPIC_API_KEY:', 'SET' if os.getenv('ANTHROPIC_API_KEY') else 'NOT SET')"

🔄 Common Workflows

Development Workflow

1. uv sync - Install dependencies
2. cp .env.example .env - Setup environment
3. uvicorn main:app --reload - Start FastAPI server
4. uv run mcp install mcp_main.py - Install MCP server
5. Configure Claude Desktop
6. Test with PDF uploads

Production Deployment

1. uv sync --frozen - Install exact dependencies
2. uvicorn main:app --host 0.0.0.0 --port 8000 - Start production server
3. Configure reverse proxy (nginx/apache)
4. Setup SSL certificates
5. Configure Claude Desktop for production

📁 File Structure

pdf-parser/
├── main.py                 # FastAPI server (uvicorn main:app)
├── mcp_main.py            # MCP server entry point (uv run mcp install)
├── mcp_server.py          # MCP server implementation
├── pdf_processor.py       # PDF processing logic
├── anthropic_client.py    # Anthropic API client
├── pyproject.toml         # Project configuration
├── .env.example          # Environment template
├── dev_commands.md       # This file
└── README.md             # Documentation