# Homosaurus MCP

An experimental MCP (Model Context Protocol) server connecting Claude to the Homosaurus V4 LGBTQ+ linked data vocabulary, developed to investigate the potential of large language models in subject analysis and authority control.

---

## What This Server Does

Homosaurus MCP connects Claude Desktop to the Homosaurus vocabulary via two live APIs, allowing you to search and retrieve Homosaurus authority data directly within your AI-assisted cataloging workflow.

Once installed, you can ask Claude things like:

- *"Search the Homosaurus for terms related to bisexuality"*
- *"Find the Homosaurus term for queer families"*
- *"What are the broader and narrower terms for 'Transgender people'?"*
- *"Retrieve the full record for this Homosaurus URI"*

The server handles all the API calls, parses the responses, and returns structured data Claude can reason about.

---

## Who This Is For

- **Catalogers** using Claude Desktop who want AI-assisted subject heading work grounded in real Homosaurus authority data
- **Library and archives staff** building or evaluating AI-assisted cataloging tools and workflows for LGBTQ+ materials
- **Developers** integrating Homosaurus vocabulary lookups into MCP-based systems

---

## Tools

| Tool | Description |
|------|-------------|
| `search_homosaurus` | Search by string match, returns top 10 candidates with relevance scores. |
| `search_homosaurus_broad` | Same search with a higher limit, returns top 25 candidates. |
| `get_homosaurus_term` | Full term record by URI — preferred label, alt labels, scope note, broader/narrower/related terms. |

---

## Notes on Search Behaviour

**Search** is handled by the [NDE Termennetwerk](https://netwerkdigitaalerfgoed.nl/activiteiten/termennetwerk/)
Reconciliation Service API (W3C CG spec v0.2), which searches the
Homosaurus vocabulary hosted by IHLIA. Results are scored by relevance
and sorted in descending order. The `match` flag in results indicates
whether the service considers a candidate a high-confidence exact match.

**`search_homosaurus_broad`** uses the same underlying search but
requests 25 candidates instead of 10. Use it when exploring a concept
area or when the standard search returns too few results.

**Full record retrieval** via `get_homosaurus_term` fetches the
individual term JSON-LD directly from homosaurus.org. Broader, narrower,
and related terms are returned as URI lists — pass each URI back to
`get_homosaurus_term` to resolve labels if needed.

**No local data is cached.** Every tool call is a live network request.
Search depends on `termennetwerk-api.netwerkdigitaalerfgoed.nl`;
full record retrieval depends on `homosaurus.org`.

---

## Installation

### Requirements

- Python 3.11 or later
- Claude Desktop (or another MCP-compatible host)

### Install from GitHub

**Mac:**

```bash
pip3 install git+https://github.com/msuicaut/homosaurus-mcp-server.git
```

**Windows (Anaconda Prompt):**

```
pip install git+https://github.com/msuicaut/homosaurus-mcp-server.git
```

### Install from a local clone

```bash
git clone https://github.com/msuicaut/homosaurus-mcp-server.git
cd homosaurus-mcp-server
pip install -e .
```

On Windows with Anaconda, use Anaconda Prompt and add
`--break-system-packages` if prompted.

---

## Claude Desktop Configuration

After installation, add the server to your `claude_desktop_config.json`.
Claude Desktop uses a restricted PATH that does not include the Python
bin directory, so the full path to the command is required.

To find your exact path, run the following in Terminal (Mac) or
Anaconda Prompt (Windows):

- **Mac:** `which homosaurus-mcp`
- **Windows:** `where homosaurus-mcp`

The examples below are illustrative only — your actual path will differ
depending on your Python version and installation method.

**Mac (example):**
```json
{
  "mcpServers": {
    "homosaurus": {
      "command": "/Library/Frameworks/Python.framework/Versions/3.13/bin/homosaurus-mcp"
    }
  }
}
```

**Windows/Anaconda (example):**
```json
{
  "mcpServers": {
    "homosaurus": {
      "command": "C:\\Users\\username\\anaconda3\\Scripts\\homosaurus-mcp.exe"
    }
  }
}
```

Always replace the path with the actual output of the `which` or `where`
command on your machine.

**Finding your config file:**

- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

After editing the config, quit Claude Desktop completely and reopen it.
The Homosaurus tools will be available in your next conversation.

### Verifying the installation

Once Claude Desktop is open, ask: *"What Homosaurus tools do you have
available?"* — you should see all three tools listed.

---

## Updating

**Mac:**

```bash
pip3 install --upgrade git+https://github.com/msuicaut/homosaurus-mcp-server.git
```

**Windows (Anaconda Prompt):**

```
pip install --upgrade git+https://github.com/msuicaut/homosaurus-mcp-server.git
```

After updating, restart Claude Desktop fully.

---

## Troubleshooting

**Tools not appearing in Claude Desktop**

- Confirm the package installed without errors: `pip show homosaurus-mcp-server`
- Confirm the command is available: `homosaurus-mcp --help` (should start the server, not throw an error)
- Check that the config file path is correct for your OS
- Quit Claude Desktop fully (not just close the window) before reopening

**Search returns an error**

The search tool depends on the NDE Termennetwerk API. If the API is
unavailable, tool calls will return a descriptive error message. Check
your network connection and try again.

**`get_homosaurus_term` returns an error**

Confirm the URI is a valid `homosaurus.org` URI returned by a search
tool. URIs from other vocabularies will be rejected.

**Changes to server.py not taking effect**

Python caches compiled bytecode in `__pycache__` folders. After editing
`server.py`, delete any `__pycache__` folders in the package directory
and restart Claude Desktop fully.

---

## License

GPLv3. See [LICENSE](LICENSE).

---

## Development Note

The code in this project was developed in collaboration with Claude, Anthropic's AI assistant. The design decisions — including tool selection, API choice, and the application of cataloging practice to the server's behaviour — reflect the author's professional cataloging expertise. Claude handled the implementation of those decisions in Python.

---

## Acknowledgement

This project makes use of the Homosaurus vocabulary provided by the
[Digital Transgender Archive](https://www.digitaltransgenderarchive.net/)
and maintained at [homosaurus.org](https://homosaurus.org/). Search is
provided by the [NDE Termennetwerk](https://netwerkdigitaalerfgoed.nl/activiteiten/termennetwerk/),
a service of the Dutch Digital Heritage Network (Netwerk Digitaal Erfgoed).

The project was inspired by and adapted from KL Tang's
[cataloger-mcp](https://github.com/kltng/cataloger-mcp), extended here
to apply to Homosaurus vocabulary lookup.