Metadata-Version: 2.4
Name: cordra-mcp
Version: 1.2.2
Summary: MCP server for Cordra digital object repository
Project-URL: Homepage, https://github.com/dnlbauer/cordra-mcp
Project-URL: Repository, https://github.com/dnlbauer/cordra-mcp
Author-email: Daniel Bauer <github@dbauer.me>
License: MIT
License-File: LICENSE
Keywords: MCP,agent-coding,ai,cordra,digital-repository,model-context-protocol
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: mcp[cli]>=1.2.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: requests>=2.25.0
Provides-Extra: dev
Requires-Dist: loguru>=0.7.0; extra == 'dev'
Requires-Dist: mypy>=1.6.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: production
Description-Content-Type: text/markdown

# Cordra MCP Server

Cordra is a configurable digital object repository system that stores digital objects as JSON documents
with associated metadata and optional binary payloads.
This Model Context Protocol (MCP) server provides AI assistants with read-only
access to explore and understand Cordra repositories.
This allows AI systems to quickly understand the data model and schema structure
of a Cordra repository and to explore digital objects and their relationships.

![Example](example.gif)

## Features

- **Read-Only Access**: All operations are strictly read-only,
ensuring safe exploration without risk of data modification or corruption.
- **Schema Discovery**: Discover and retrieve schema definitions for each type in the repository.
- **Individual Object Retrieval**: Retrieve specific digital objects by their handle identifier with complete metadata.

## MCP Architecture

### Resources

- `cordra://objects/{prefix}/{suffix}` - Retrieve a specific object by its handle identifier
- `cordra://schemas/{schema_name}` - Schema definition for a specific type.
- `cordra://design` - Design document containing the overall structure and configuration of the Cordra repository.

### Tools

- `search_objects` - Search for digital objects using a query string with pagination support.
  - `query` - Lucene/Solr compatible search query
  - `type` - Optional filter by object type  
  - `limit` - Number of results per page (default: 1)
  - `page_num` - Page number to retrieve, 0-based (default: 0)
- `count_objects` - Count the total number of objects matching a query.
  - `query` - Lucene/Solr compatible search query
  - `type` - Optional filter by object type  

## Configuration

The MCP server can be configured using environment variables:

- `CORDRA_BASE_URL` - Cordra server URL (default: `https://localhost:8443`)
- `CORDRA_USERNAME` - Username for authentication (optional)
- `CORDRA_PASSWORD` - Password for authentication (optional)
- `CORDRA_VERIFY_SSL` - SSL certificate verification (default: `true`)
- `CORDRA_TIMEOUT` - Request timeout in seconds (default: `30`)
- `LOGLEVEL` - Logging level (default: `INFO`, options: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`)

## Usage

Run the MCP server:

```bash
uv run mcp-cordra
```

### Claude Code

You can add this MCP to Claude Code by registering it in the settings
of your project or creating a `.mcp.json` file in your workdir:

Example using the docker build:

```json
{
  "mcpServers": {
    "cordra": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "CORDRA_BASE_URL",
        "ghcr.io/dnlbauer/cordra-mcp:latest"
      ],
      "env": {
        "CORDRA_BASE_URL": "https://cordra.example.de"
      }
    }
  }
}
```

Example using the python package with `uvx`:

```json
{
  "mcpServers": {
    "cordra": {
      "command": "uvx",
      "args": [
        "cordra-mcp"
      ],
      "env": {
        "CORDRA_BASE_URL": "https://cordra.example.de"
      }
    }
  }
}
```
