@nulib/dc-api-mcp 2.10.2 → 2.10.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +70 -46
  2. package/dist/apps/mcp/lambda.js +30 -30
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -1,90 +1,114 @@
1
1
  # dc-api-mcp
2
2
 
3
- A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes Northwestern University Library's [Digital Collections API](https://api.dc.library.northwestern.edu/api/v2) as tools for AI assistants.
3
+ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes Northwestern University Library's [Digital Collections](https://dc.library.northwestern.edu/) as tools for AI assistants. It provides tools for searching, browsing, and retrieving metadata and IIIF manifests for digitized library materials.
4
4
 
5
- ## Requirements
5
+ ## Available Tools
6
+
7
+ | Tool | Description |
8
+ | --------------------- | ------------------------------------------------------------------ |
9
+ | `search` | Search for works using field-based and/or natural language queries |
10
+ | `similarity-search` | Find works visually or semantically similar to a given work |
11
+ | `get-work` | Retrieve full metadata for a single work by ID |
12
+ | `view-work` | View a work's IIIF manifest for display in compatible viewers |
13
+ | `list-collections` | List available digital collections |
14
+ | `view-collection` | Browse a specific collection's IIIF manifest |
15
+ | `view-search-results` | Retrieve results from a previous search |
16
+ | `view-similar-works` | Retrieve results from a previous similarity search |
17
+
18
+ ## Using the Remote Endpoint
19
+
20
+ The server is available as a hosted remote at:
21
+
22
+ ```
23
+ https://api.dc.library.northwestern.edu/api/v2/mcp
24
+ ```
25
+
26
+ No local installation is required. Configure your MCP client to connect to this URL using the streamable HTTP transport.
27
+
28
+ ### Claude Desktop
29
+
30
+ Add the following to your Claude Desktop configuration file.
31
+
32
+ **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
33
+ **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
34
+
35
+ ```json
36
+ {
37
+ "mcpServers": {
38
+ "dc-api": {
39
+ "type": "http",
40
+ "url": "https://api.dc.library.northwestern.edu/api/v2/mcp"
41
+ }
42
+ }
43
+ }
44
+ ```
45
+
46
+ ### Claude Code
47
+
48
+ ```bash
49
+ claude mcp add --transport http dc-api https://api.dc.library.northwestern.edu/api/v2/mcp
50
+ ```
51
+
52
+ ---
53
+
54
+ ## Development
55
+
56
+ ### Requirements
6
57
 
7
58
  - Node.js 24+ (see [.tool-versions](.tool-versions))
8
59
  - [mise](https://mise.jdx.dev/) (used by `bin/run.sh` to activate the correct runtime)
9
60
 
10
- ## Setup
61
+ ### Setup
11
62
 
12
63
  ```bash
13
64
  npm install
14
65
  ```
15
66
 
16
- ## Configuration
67
+ ### Configuration
17
68
 
18
69
  The server reads the following environment variables:
19
70
 
20
- | Variable | Default | Description |
21
- | -------------- | ------------------------------------------------- | -------------------------------------------------------------------- |
22
- | `DC_API_BASE` | `https://api.dc.library.northwestern.edu/api/v2` | Base URL for the Digital Collections API |
23
- | `DC_IIIF_BASE` | `https://iiif.dc.library.northwestern.edu/iiif/3` | Base URL for the Digital Collections API |
24
- | `SECRETS_PATH` | _(none)_ | The base secrets path to load configuration from AWS Secrets Manager |
71
+ | Variable | Default | Description |
72
+ | -------------- | ------------------------------------------------- | ---------------------------------------- |
73
+ | `DC_API_BASE` | `https://api.dc.library.northwestern.edu/api/v2` | Base URL for the Digital Collections API |
74
+ | `DC_IIIF_BASE` | `https://iiif.dc.library.northwestern.edu/iiif/3` | Base URL for the IIIF server |
75
+ | `SECRETS_PATH` | _(none)_ | Base path for AWS Secrets Manager config |
25
76
 
26
- ## Running locally
77
+ ### Running locally
27
78
 
28
- ### stdio (for Claude Desktop / Claude Code)
79
+ #### stdio (for Claude Desktop / Claude Code)
29
80
 
30
81
  ```bash
31
- cd src
32
82
  npm run stdio
33
83
  ```
34
84
 
35
- Or via the wrapper script:
85
+ Or via the wrapper script (activates the correct Node.js version via mise):
36
86
 
37
87
  ```bash
38
88
  bin/run.sh
39
89
  ```
40
90
 
41
- ### HTTP (Streamable HTTP transport, port 3000)
91
+ #### HTTP (Streamable HTTP transport, port 3000)
42
92
 
43
93
  ```bash
44
- cd src
45
94
  npm run http
46
95
  ```
47
96
 
48
- ## Configuring Claude Desktop
49
-
50
- Add the following entry to your Claude Desktop configuration file.
51
-
52
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
53
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
97
+ ### Configuring Claude Desktop (local build)
54
98
 
55
99
  ```json
56
100
  {
57
101
  "mcpServers": {
58
102
  "dc-api": {
59
- "command": "/path/to/dc-api/mcp/bin/run.sh"
103
+ "command": "/path/to/dc-api-v2/mcp/bin/run.sh"
60
104
  }
61
105
  }
62
106
  }
63
107
  ```
64
108
 
65
- Replace `/path/to/dc-api/mcp` with the absolute path to this directory on your machine.
66
-
67
- If you need to override the API base URL or supply a semantic search model ID, pass them as environment variables:
68
-
69
- ```json
70
- {
71
- "mcpServers": {
72
- "dc-api": {
73
- "command": "/path/to/dc-api/mcp/bin/run.sh",
74
- "env": {
75
- "DC_API_BASE": "https://api.dc.library.northwestern.edu/api/v2",
76
- "DC_IIIF_BASE": "https://iiif.dc.library.northwestern.edu/iiif/3"
77
- }
78
- }
79
- }
80
- }
81
- ```
82
-
83
- After editing the file, restart Claude Desktop for the changes to take effect. You should see the `dc-api` server listed under the MCP tools panel.
84
-
85
- ## Tests
109
+ Replace `/path/to/dc-api-v2/mcp` with the absolute path to this directory. Restart Claude Desktop after editing.
86
110
 
87
- There are several ways to invoke the test suite:
111
+ ### Tests
88
112
 
89
113
  | Command | Result |
90
114
  | ------------------- | ------------------------------------------------------------ |
@@ -93,5 +117,5 @@ There are several ways to invoke the test suite:
93
117
  | `npm test:coverage` | Run the test suite and calculate coverage |
94
118
  | `npm test:record` | Run the test suite against live data and record new fixtures |
95
119
 
96
- - By default, the test suite uses pre-recorded HTTP fixtures. You can set `MSW_MODE=live` to run against live data.
97
- - `npm test:record` will record new test fixtures (requires `mitmproxy`, which can be installed with `pip install mitmproxy`).
120
+ - By default, the test suite uses pre-recorded HTTP fixtures. Set `MSW_MODE=live` to run against live data.
121
+ - `npm test:record` records new fixtures (requires `mitmproxy`: `pip install mitmproxy`).