@ildunari/jina-mcp-advanced/CLAUDE.md

Pure MCP Server for Jina.AI Advanced web scraping

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Commands

### Development Commands
```bash
# Install dependencies
npm install

# Run the MCP server
npm start
# or
JINA_API_KEY=YOUR_API_KEY node index.js

# Run tests (requires server to be running)
npm test
# or
node test.js YOUR_API_KEY

# Build/publish package
npm publish
```

### CLI Usage
```bash
# Global installation
npm install -g @ildunari/jina-mcp-advanced
JINA_API_KEY=YOUR_API_KEY jina-mcp

# Direct execution via npx
JINA_API_KEY=YOUR_API_KEY npx @ildunari/jina-mcp-advanced
```

## Architecture Overview

This is a pure MCP (Model Context Protocol) server for Jina.AI's advanced web scraping capabilities:

- **MCP Server Mode** (`index.js`) - Pure Model Context Protocol integration
  - Uses stdio transport for Claude Desktop integration
  - Exposes `read_webpage` tool to Claude
  - Implements MCP SDK request handlers

### Key Implementation Details

- **API Key Handling**: Required for all Jina API calls via environment variable:
  - Environment variable: `JINA_API_KEY=your_key_here`
  
- **Jina Reader Parameters**: Supports all Jina Reader parameters including:
  - `return_format`: markdown, html, text, screenshot, pageshot
  - `engine`: default or browser (for JS-heavy sites)
  - Advanced options: selectors, timeouts, caching, image handling

- **Error Handling**: Comprehensive error handling with proper MCP error responses

- **Pure MCP**: No HTTP server or dual-mode architecture - this is MCP-only
  - stdout: JSON-RPC messages only (MCP protocol)
  - stderr: debug/logging output

### Tool Available

- `read_webpage`: Fetch and extract content from URLs using Jina Reader Advanced