# Node.js MCP Server for Gallica/BnF

A high-quality TypeScript/Node.js MCP (Model Context Protocol) server for accessing the Gallica digital library of the Bibliothèque nationale de France (BnF). This server faithfully reproduces all functionality from the [Python MCP server](https://github.com/Kryzo/mcp-bibliotheque_nationale_de_France) and extends it with additional features for IIIF images, OCR text, and item metadata.

## Features

### Core Search Tools (8 tools - matching Python)
- **search_by_title** - Search documents by title with exact match option
- **search_by_author** - Search documents by author with exact match option
- **search_by_subject** - Search documents by subject with exact match option
- **search_by_date** - Search documents by date (YYYY, YYYY-MM, or YYYY-MM-DD)
- **search_by_document_type** - Search by document type (monographie, periodique, image, etc.)
- **advanced_search** - Custom CQL query syntax for complex searches
- **natural_language_search** - Natural language search across all fields
- **sequential_reporting** - Multi-step sequential report generation with source management

### Extended Tools (4 new tools)
- **get_item_details** - Get full metadata for an item by ARK identifier
- **get_item_pages** - Enumerate pages of a document with IIIF URLs
- **get_page_image** - Generate IIIF image URLs for specific pages
- **get_page_text** - Retrieve OCR/text content (ALTO, plain text)

## Installation

### Prerequisites
- Node.js 18.0 or higher
- npm or yarn

### Steps

1. **Clone or download this repository**

2. **Install dependencies:**
   ```bash
   cd node-mcp-bnf
   npm install
   ```

3. **Build the project:**
   ```bash
   npm run build
   ```

## Usage

### Local Development

#### Option 1: HTTP Server (Recommended for Development)

Run the server on a local HTTP port for testing:

```bash
npm run dev:http
```

This starts the server on `http://localhost:3000` (or the port specified in `PORT` environment variable).

The server will:
- Listen on the specified port
- Accept MCP requests via HTTP/SSE
- Log all activity to the console

You can test it by connecting an MCP client to `http://localhost:3000/message`.

#### Option 2: STDIO Mode (For MCP Clients)

The server can be used locally with Claude Desktop or Cursor MCP via STDIO.

**Run in STDIO mode:**
```bash
npm run dev
```

#### Claude Desktop Configuration

Add to your Claude Desktop configuration file (usually `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "gallica-bnf": {
      "command": "node",
      "args": ["/path/to/node-mcp-bnf/dist/index.js"],
      "cwd": "/path/to/node-mcp-bnf"
    }
  }
}
```

#### Cursor MCP Configuration

Add to your Cursor MCP settings:

```json
{
  "mcpServers": {
    "gallica-bnf": {
      "command": "node",
      "args": ["/path/to/node-mcp-bnf/dist/index.js"]
    }
  }
}
```

### Development Scripts

- `npm run dev` - Run in STDIO mode (for MCP clients like Cursor/Claude Desktop)
- `npm run dev:http` - Run HTTP server on local port (default: 3000)
- `npm start` - Run compiled STDIO version
- `npm run start:http` - Run compiled HTTP server version

**Environment Variables for HTTP Server:**
- `PORT` - Port to listen on (default: 3000)
- `LOG_LEVEL` - Logging level (error, warn, info, debug)

## Deployment on Vercel

### Prerequisites
- Vercel account
- Vercel CLI installed (`npm i -g vercel`)

### Steps

1. **Create `vercel.json` in project root:**
   ```json
   {
     "functions": {
       "src/httpServer.ts": {
         "runtime": "nodejs18.x"
       }
     },
     "routes": [
       {
         "src": "/(.*)",
         "dest": "src/httpServer.ts"
       }
     ]
   }
   ```

2. **Set environment variables in Vercel dashboard:**
   - `GALLICA_BASE_URL` (optional, default: `https://gallica.bnf.fr`)
   - `GALLICA_SRU_URL` (optional, default: `https://gallica.bnf.fr/SRU`)
   - `LOG_LEVEL` (optional, default: `info`)
   - `MCP_ICON_URL` (optional, absolute URL to icon - defaults to `/icon.svg` relative to server URL)

3. **Deploy:**
   ```bash
   vercel deploy
   ```

4. **Configure Cursor/Claude Desktop to use HTTP endpoint:**
   ```json
   {
     "mcpServers": {
       "gallica-bnf": {
         "url": "https://your-vercel-app.vercel.app"
       }
     }
   }
   ```

## API Documentation

### Search Tools

#### search_by_title
Search for documents by title.

**Parameters:**
- `title` (string, required): The title to search for
- `exact_match` (boolean, optional): If true, search for exact title
- `max_results` (number, optional, default: 10): Maximum results (1-50)
- `start_record` (number, optional, default: 1): Starting record for pagination

**Example:**
```json
{
  "title": "Les Misérables",
  "exact_match": false,
  "max_results": 10
}
```

#### search_by_author
Search for documents by author.

**Parameters:**
- `author` (string, required): The author name
- `exact_match` (boolean, optional): If true, search for exact author name
- `max_results` (number, optional, default: 10)
- `start_record` (number, optional, default: 1)

#### search_by_subject
Search for documents by subject/keywords.

**Parameters:**
- `subject` (string, required): The subject to search for
- `exact_match` (boolean, optional)
- `max_results` (number, optional, default: 10)
- `start_record` (number, optional, default: 1)

#### search_by_date
Search for documents by publication date.

**Parameters:**
- `date` (string, required): Date in format YYYY, YYYY-MM, or YYYY-MM-DD
- `max_results` (number, optional, default: 10)
- `start_record` (number, optional, default: 1)

**Example:**
```json
{
  "date": "1862",
  "max_results": 20
}
```

#### search_by_document_type
Search for documents by type.

**Parameters:**
- `doc_type` (string, required): Document type (monographie, periodique, image, manuscrit, carte, musique, etc.)
- `max_results` (number, optional, default: 10)
- `start_record` (number, optional, default: 1)

#### advanced_search
Perform advanced search with custom CQL query.

**Parameters:**
- `query` (string, required): CQL query string
- `max_results` (number, optional, default: 10)
- `start_record` (number, optional, default: 1)

**Example:**
```json
{
  "query": "dc.creator all \"Victor Hugo\" and dc.type all \"monographie\""
}
```

#### natural_language_search
Natural language search across all fields.

**Parameters:**
- `query` (string, required): Natural language search query
- `max_results` (number, optional, default: 10)
- `start_record` (number, optional, default: 1)

### Extended Tools

#### get_item_details
Get full metadata for an item.

**Parameters:**
- `ark` (string, required): ARK identifier (e.g., "ark:/12148/bpt6k123456" or "bpt6k123456")

**Returns:**
- Bibliographic data (title, creator, date, etc.)
- Available formats (iiif, image, text, alto)
- IIIF manifest URL
- Gallica URL

#### get_item_pages
Enumerate pages of a document.

**Parameters:**
- `ark` (string, required): ARK identifier
- `page` (number, optional): Get specific page number
- `page_size` (number, optional): Get first N pages
- `page_range` (array, optional): Get pages in range [start, end]

**Returns:**
- Array of page info with:
  - Page number
  - Label
  - IIIF image URL
  - Text availability flag
  - Thumbnail URL

#### get_page_image
Get IIIF image URL for a specific page.

**Parameters:**
- `ark` (string, required): ARK identifier
- `page` (number, required): Page number
- `size` (string, optional): Image size (e.g., "full", "200,", "500,500")
- `region` (string, optional): Image region (e.g., "full", "x,y,w,h")

**Returns:**
- IIIF image URL
- Thumbnail URL

#### get_page_text
Retrieve OCR/text content for a page.

**Parameters:**
- `ark` (string, required): ARK identifier
- `page` (number, required): Page number
- `format` (string, optional): Text format ("plain", "alto", "tei")

**Returns:**
- Text content (or null if not available)
- Availability flag

### Sequential Reporting Tool

#### sequential_reporting
Generate research reports in a sequential, step-by-step manner.

**Workflow:**

1. **Initialize:**
   ```json
   {
     "topic": "Impressionnisme en France",
     "page_count": 4,
     "source_count": 10,
     "include_graphics": true
   }
   ```

2. **Search sources:**
   ```json
   {
     "search_sources": true
   }
   ```

3. **Create bibliography:**
   ```json
   {
     "section_number": 1,
     "total_sections": 8,
     "title": "Bibliography",
     "content": "...",
     "is_bibliography": true,
     "sources_used": [1, 2, 3],
     "next_section_needed": true
   }
   ```

4. **Write sections sequentially:**
   ```json
   {
     "section_number": 2,
     "total_sections": 8,
     "title": "Introduction",
     "content": "...",
     "sources_used": [1, 2],
     "next_section_needed": true
   }
   ```

5. **Complete report:**
   ```json
   {
     "section_number": 8,
     "total_sections": 8,
     "title": "Conclusion",
     "content": "...",
     "sources_used": [5, 6],
     "next_section_needed": false
   }
   ```

## Configuration

### Environment Variables

- `GALLICA_BASE_URL` - Base URL for Gallica API (default: `https://gallica.bnf.fr`)
- `GALLICA_SRU_URL` - SRU search endpoint (default: `https://gallica.bnf.fr/SRU`)
- `LOG_LEVEL` - Logging level: `error`, `warn`, `info`, `debug` (default: `info`)
- `HTTP_TIMEOUT` - HTTP request timeout in milliseconds (default: 30000)
- `HTTP_RETRIES` - Maximum number of retry attempts (default: 3)
- `DEFAULT_MAX_RECORDS` - Default maximum search results (default: 10)
- `DEFAULT_START_RECORD` - Default starting record for pagination (default: 1)

## Development

### Project Structure

```
node-mcp-bnf/
├── src/
│   ├── index.ts              # STDIO entry point
│   ├── httpServer.ts        # HTTP entry point
│   ├── mcpServer.ts         # MCP server setup
│   ├── config.ts            # Configuration
│   ├── logging.ts           # Logging utility
│   ├── tools/               # MCP tools
│   └── gallica/             # Gallica API clients
├── docs/                     # Documentation
├── tests/                    # Unit tests
└── package.json
```

### Building

```bash
npm run build
```

### Testing

```bash
npm test
```

### Development Mode

```bash
npm run dev
```

## Documentation

- [Python Architecture Analysis](docs/ARCHITECTURE-python.md) - Analysis of the original Python server
- [Gallica API Notes](docs/GALLICA-API-NOTES.md) - Detailed API documentation
- [Node.js Architecture](docs/ARCHITECTURE-node.md) - Architecture and design of this server

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Acknowledgments

- Based on the Python MCP server by [Kryzo](https://github.com/Kryzo/mcp-bibliotheque_nationale_de_France)
- Uses the [Model Context Protocol](https://modelcontextprotocol.io/) SDK
- Built for the [Gallica digital library](https://gallica.bnf.fr/) of the Bibliothèque nationale de France