LCSH MCP Server

# cataloger mcp server A Model Context Protocol (MCP) server that provides access to the Library of Congress Subject Headings (LCSH) through a simple API interface. ## Overview This MCP server allows AI assistants to search the Library of Congress Subject Headings (LCSH) using the public suggest2 API. It provides a clean interface for querying LCSH data and handling the various response formats from the API. ## Features - **MCP Tool Integration**: Exposes a `search_lcsh` tool that can be used by AI assistants - **MCP Tool Integration**: Exposes `search_lcsh` (default left-anchored), `search_lcsh_keyword` (keyword-based), and `search_name_authority` tools that can be used by AI assistants - **Resource Endpoints**: Provides resource endpoints at `lcsh://search/{query}` and `lcnaf://search/{query}` - **Robust Error Handling**: Gracefully handles API errors, connection issues, and unexpected response formats - **Multiple Response Formats**: Supports both dictionary (hits) and list response formats from the LCSH API - **Dual Operation Modes**: - **stdio mode**: For direct integration with AI assistants like Claude Desktop - **HTTP/SSE mode**: For network-based connections on a specified port ## Requirements - Python 3.12 or higher - Dependencies: - `mcp[cli]>=1.6.0`: Model Context Protocol Python SDK - `requests>=2.32.3`: HTTP library for API requests ## Installation ```bash # Clone the repository git clone <repository-url> cd lcsh-mcp # Set up a virtual environment python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate # Install dependencies using uv uv pip install -e . ``` ## Usage ### Running in stdio Mode (Default) This mode is ideal for direct integration with AI assistants like Claude Desktop: ```bash python server.py ``` ### Running in HTTP/SSE Mode This mode allows network-based connections on the specified port: ```bash python server.py 6274 ``` The server will start on port 6274 (or any port you specify) and be accessible at `http://localhost:6274`. ## API Reference ### Tool: `search_lcsh` Searches the Library of Congress Subject Headings using the public suggest2 API. **Parameters:** - `query` (string): The search term to look for in LCSH **Returns:** A dictionary with the following structure: ```json { "results": [ { "label": "Subject Heading Label", "uri": "http://id.loc.gov/authorities/subjects/..." }, ... ] } ``` Or in case of an error: ```json { "error": "Error message", "type": "ErrorType", "traceback": "..." } ``` ### Resource: `lcsh://search/{query}` A resource endpoint that returns the same data as the `search_lcsh` tool. ### Tool: `search_lcsh_keyword` Searches the Library of Congress Subject Headings (LCSH) using the public suggest2 API with a keyword search type. This allows for more flexible matching compared to the default left-anchored search of `search_lcsh`. **Parameters:** - `query` (string): The search term to look for in LCSH. **API Behavior:** - Uses `searchtype: "keyword"` in the API request. - Requests up to `count: 50` results from the API. **Returns:** A dictionary with the following structure (same as `search_lcsh`): ```json { "results": [ { "label": "Subject Heading Label", "uri": "http://id.loc.gov/authorities/subjects/..." }, ... ] } ``` Or in case of an error (same as `search_lcsh`): ```json { "error": "Error message", "type": "ErrorType", "traceback": "..." } ``` ### Tool: `search_name_authority` Searches the Library of Congress Name Authorities (LCNAF) for Personal Names using the public suggest2 API. **Parameters:** - `query` (string): The search term to look for in LCNAF (Personal Names) **Returns:** A dictionary with the following structure (same as `search_lcsh`): ```json { "results": [ { "label": "Name Authority Label", "uri": "http://id.loc.gov/authorities/names/..." }, ... ] } ``` Or in case of an error (same as `search_lcsh`): ```json { "error": "Error message", "type": "ErrorType", "traceback": "..." } ``` ### Resource: `lcnaf://search/{query}` A resource endpoint that returns the same data as the `search_name_authority` tool. ## Testing The server includes a comprehensive test suite that can be run with pytest: ```bash python -m pytest test_server.py -v ``` Tests cover basic functionality, empty queries, no results, and API errors. ## Integration with Claude Desktop To use this MCP server with Claude Desktop: 1. Start the server in stdio mode: `python server.py` 2. In Claude Desktop, go to Settings > MCP Servers 3. Add a new MCP server with the following configuration: - Name: cataloger mcp Search - Command: `python /path/to/cataloger mcp/server.py` 4. Enable the server and start using the cataloger mcp search capabilities in your conversations ## License [Specify your license here] ## Contributing [Add contribution guidelines if applicable] ## Testing with MCP Inspector The MCP Inspector is a visual testing tool specifically designed for MCP servers. Here's how to use it with your cataloger mcp server: ### Step 1: Install MCP Inspector First, you need to install the MCP Inspector. You can use npm to install it globally: ```bash npm install -g @modelcontextprotocol/inspector ``` Or you can use it directly with npx without installing: ```bash npx @modelcontextprotocol/inspector ``` ### Step 2: Start Your cataloger mcp server You need to have your cataloger mcp server running in HTTP/SSE mode for testing with the Inspector: ```bash python server.py 6274 ``` This will start your server on port 6274 (or you can choose another port). ### Step 3: Connect MCP Inspector to Your Server Now you can connect the MCP Inspector to your running server. There are two ways to do this: #### Option 1: Using the CLI ```bash npx @modelcontextprotocol/inspector --cli http://localhost:6274 ``` This will connect to your server in CLI mode and allow you to interact with it through the command line. #### Option 2: Using the Web Interface ```bash npx @modelcontextprotocol/inspector ``` This will start the MCP Inspector web interface. By default, it runs on port 3000, so you can access it at http://localhost:3000 in your browser. Once the interface loads: 1. Click on "Add Server" 2. Enter a name for your server (e.g., "cataloger mcp server") 3. Enter the URL: `http://localhost:6274` 4. Click "Save" ### Step 4: Test Your Server's Tools and Resources Once connected, you can: #### List Available Tools CLI: ```bash npx @modelcontextprotocol/inspector --cli http://localhost:6274 --method tools/list ``` Web Interface: - Click on your server in the sidebar - Go to the "Tools" tab to see all available tools #### Test the `search_lcsh` Tool CLI: ```bash npx @modelcontextprotocol/inspector --cli http://localhost:6274 --method tools/call --tool-name search_lcsh --tool-arg query=history ``` Web Interface: - Click on the "search_lcsh" tool #### Test the `search_lcsh_keyword` Tool CLI: ```bash npx @modelcontextprotocol/inspector --cli http://localhost:6274 --method tools/call --tool-name search_lcsh_keyword --tool-arg query="artificial intelligence policy" ``` Web Interface: - Click on the "search_lcsh_keyword" tool - Enter "artificial intelligence policy" (or any search term) in the query field - Click "Execute" - View the results in the response panel #### Test the `search_name_authority` Tool CLI: ```bash npx @modelcontextprotocol/inspector --cli http://localhost:6274 --method tools/call --tool-name search_name_authority --tool-arg query="Smith, John" ``` Web Interface: - Click on the "search_name_authority" tool - Enter "history" (or any search term) in the query field - Click "Execute" - View the results in the response panel #### Test the Resource Endpoint CLI: ```bash npx @modelcontextprotocol/inspector --cli http://localhost:6274 --method resources/list ``` Web Interface: - Go to the "Resources" tab - You should see the `lcsh://search/{query}` resource - You can test it by entering a query parameter ### Step 5: Debugging and Monitoring The MCP Inspector provides detailed information about: - Request and response payloads - Execution times - Any errors that occur This makes it an excellent tool for debugging your MCP server and ensuring it's working correctly.