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 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:

   cd node-mcp-bnf
   npm install
   

3. Build the project:

   npm run build
   

Usage

Local Development

Option 1: HTTP Server (Recommended for Development)

Run the server on a local HTTP port for testing:

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:

npm run dev

Claude Desktop Configuration

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

{
  "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:

{
  "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:

   {
     "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:

   vercel deploy
   

4. Configure Cursor/Claude Desktop to use HTTP endpoint:

   {
     "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:

{
  "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:

{
  "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:

{
  "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:

   {
     "topic": "Impressionnisme en France",
     "page_count": 4,
     "source_count": 10,
     "include_graphics": true
   }
   

2. Search sources:

   {
     "search_sources": true
   }
   

3. Create bibliography:

   {
     "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:

   {
     "section_number": 2,
     "total_sections": 8,
     "title": "Introduction",
     "content": "...",
     "sources_used": [1, 2],
     "next_section_needed": true
   }
   

5. Complete report:

   {
     "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

npm run build

Testing

npm test

Development Mode

npm run dev

Documentation

• Python Architecture Analysis - Analysis of the original Python server
• Gallica API Notes - Detailed API documentation
• Node.js Architecture - 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
• Uses the Model Context Protocol SDK
• Built for the Gallica digital library of the Bibliothèque nationale de France