Northwestern University Libraries Digital Collections API MCP server

dc-api-v2

Local development setup

env.json

The env.json file contains environment variable values for the lambda functions defined in the API for use in local development. You can create an env.json file containing the values to run the API against your dev data by running:

make env.json

If the file already exists, it will not be overwritten unless you include -B in the make command.

Running the API locally

To start the API in development mode, first make sure you have the correct version of the AWS SAM command line utility installed:

asdf install aws-sam-cli

Then run the following command:

make serve

The API will be available at:

• https://USER_PREFIX.dev.rdc.library.northwestern.edu:3002
• Don't forget to open port 3002 if you want to access it remotely

⚠️ Note the above URLs (which point to your local OpenSearch instance) need full endpoints to resolve. For example:

• https://USER_PREFIX.dev.rdc.library.northwestern.edu:3002/search
• https://USER_PREFIX.dev.rdc.library.northwestern.edu:3002/collections

View supported endpoints Questions? View the production API documentation

Chaos middleware

The API supports simulated network effects (errors and delays) for local testing via the CHAOS_CONFIG environment variable. If the variable is absent the middleware is disabled entirely.

Set it to an inline JSON array:

export CHAOS_CONFIG='[
  { "pattern": "/works/:id", "effect": "error", "status": 500, "chance": 0.3 },
  { "pattern": "/auth/whoami", "effect": "delay", "ms": 500 },
  { "pattern": "/file-sets/*", "effect": "delay", "ms": [100, 800] }
]'

Or set it to the path of a JSON file containing the same array:

export CHAOS_CONFIG=/path/to/chaos.json

Each rule has a pattern (matched against the request path) and an effect:

All matching rules are evaluated in order. Delay rules accumulate; an error rule short-circuits the request only when it fires — otherwise evaluation continues to the next rule.

Example workflows

Meadow

View and edit information about a specific Work in the Index.

1. Open a local Meadow instance.
2. Find an id of a Work you'd like to inspect in the API.
3. View JSON response at https://USERPREFIX.dev.rdc.library.northwestern.edu:3002/works/[WORKID]
4. View IIIF Manifest JSON response at https://USERPREFIX.dev.rdc.library.northwestern.edu:3002/works/[WORKID]?as=iiif

IIIF content search

IIIF Presentation responses expose IIIF Content Search 2.0 services for transcription annotations:

• Work manifests include a SearchService2 entry for https://USERPREFIX.dev.rdc.library.northwestern.edu:3002/works/[WORKID]/search?as=iiif
• File set canvases include a SearchService2 entry for https://USERPREFIX.dev.rdc.library.northwestern.edu:3002/file-sets/[FILESET_ID]/search?as=iiif

To search transcription text, include a non-empty q parameter:

Shortened. The full README is on GitHub.