mcp-fetch: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

mcp-fetch is a Model Context Protocol (MCP) server that provides web content fetching capabilities for AI assistants. It converts HTML pages to clean markdown using Mozilla Readability and optionally processes images using Sharp.

Development Commands

# Build TypeScript to JavaScript
npm run build

# Type checking only (recommended before commits)
npm run typecheck

# Run all quality checks (biome linting + typecheck)
npm test

# Format code using Biome
npm run format

# Lint code using Biome
npm run lint

# Build and run the server
npm run dev

# Run the compiled server
npm start

Architecture

Single-File Design

• Core logic: All functionality is in index.ts (606 lines)
• Type definitions: External module types in types.d.ts
• This is intentional - the tool has focused scope and benefits from centralized logic

Key Components

• MCP Server: Uses @modelcontextprotocol/sdk for protocol implementation
• Content Pipeline: HTML → Readability → Markdown → Pagination
• Image Pipeline: Fetch → JPEG conversion → Vertical merging → File saving → Optional Base64 encoding
• Parameter Validation: Zod schemas with automatic type conversion from string/number unions

Dependencies Architecture

• Content Processing: @mozilla/readability + jsdom + turndown chain
• Image Processing: sharp for high-performance image operations
• HTTP: node-fetch for web requests
• Compliance: robots-parser for robots.txt checking

Code Patterns

Parameter Handling

Parameters use union types (string | number) with Zod validation for automatic type conversion:

url: z.string(),
maxLength: z.union([z.string(), z.number()]).transform(Number).default(20000),
enableFetchImages: z.union([z.string(), z.boolean()]).transform(toBool).default(false)

Error Handling

Network operations include comprehensive error handling with specific error types for different failure scenarios.