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

This is cataloger-mcp-server, a Model Context Protocol (MCP) server that provides access to Library of Congress Subject Headings (LCSH) and Name Authorities (LCNAF) through a simple API interface. It allows AI assistants to search authoritative library cataloging data using the public suggest2 API.

Development Commands

Installation and Setup

# Install in development mode
pip install -e .

# Install dependencies using uv (preferred)
uv pip install -e .

# Or install from PyPI
pip install cataloger-mcp-server

Running the Server

# Run in stdio mode (default, for Claude Desktop integration)
cataloger-mcp-server

# Run with explicit CLI module
python -m cataloger_mcp_server.cli

# Run in HTTP/SSE mode on port 6274 (for testing/debugging)
cataloger-mcp-server --port 6274

Testing

# Run all tests
python -m pytest test_server.py -v

# Run specific test
python -m pytest test_server.py::test_search_lcsh_basic -v

# Run tests with coverage (if installed)
python -m pytest --cov=cataloger_mcp_server test_server.py

Testing with MCP Inspector

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Start server in HTTP mode first
cataloger-mcp-server --port 6274

# Test with inspector (in separate terminal)
npx @modelcontextprotocol/inspector http://localhost:6274

Architecture

Core Components

• src/cataloger_mcp_server/server.py - Main MCP server implementation using FastMCP
• src/cataloger_mcp_server/cli.py - Command-line interface entry point
• test_server.py - pytest test suite (root level, not in tests/ directory)

MCP Tools Available

1. search_lcsh(query) - Left-anchored search in LCSH (default search type)
2. search_lcsh_keyword(query) - Keyword search in LCSH (more flexible matching)
3. search_name_authority(query) - Search LCNAF for Personal Names