The DSpace MCP Server lets AI assistants search, authenticate, and manage items, files, and submissions in a DSpace 7+ repository via the REST API.
Authenticate (JWT or username/password), check auth status, and logout.
Search items, communities, and collections with full-text queries, filters, facets, scoping, and pagination.
Retrieve item metadata by UUID and browse communities/collections.
Create archived items directly (admin, bypasses workflow), update metadata via JSON Patch, and permanently delete items.
Upload local files as bitstreams/attachments to items (admin), auto-creating bundles.
Retrieve extracted full text or download original bitstream content.
Manage submissions: create, update, and list workspace items through the standard workflow.
Run via stdio (local) or HTTP (AWS Lambda) with OAuth 2.1 per-user auth on HTTP and env-based auth on stdio.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@DSpace MCP Server search DSpace for articles about open access publishing"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server for DSpace 7+ digital repository platform.
Provides AI assistants with tools to search, authenticate, create and update items in DSpace repositories via the REST API.
Search — Full-text search with filters, facets, and pagination
Authentication — OAuth 2.1 per-user auth on the HTTP transport (each caller acts as their own DSpace user, credentials never reach the model), or JWT/username-password from the environment for local stdio; CSRF-aware
Item Management (Admin) — Create archived items directly (bypasses workflow) and delete items
Item Updates — Patch metadata using JSON Patch (RFC 6902)
File Uploads (Admin) — Attach files (bitstreams) to items, auto-creating the target bundle
Content Retrieval — Read a document's extracted full text (TEXT bundle) or download the original file
Submissions — Create workspace items through the standard submission flow
Browse — List communities and collections
Related MCP server: Alfresco MCP Chat
Runs as:
Local Node.js — stdio transport for Claude Desktop, Cursor, etc.
AWS Lambda — HTTP transport via Lambda Web Adapter + API Gateway
npm install
npm run build
# Configure in Claude Desktop / Cursor (stdio auth comes from env):
# {
# "mcpServers": {
# "dspace": {
# "command": "node",
# "args": ["dist/transports/stdio.js"],
# "env": {
# "DSPACE_BASE_URL": "https://sandbox.dspace.org/server",
# "DSPACE_USER": "you@example.org",
# "DSPACE_PASSWORD": "secret"
# // or, instead of user/password: "DSPACE_TOKEN": "<dspace-jwt>"
# }
# }
# }
# }The HTTP transport always runs with OAuth 2.1 enabled (see Authentication).
DSPACE_BASE_URL=https://sandbox.dspace.org/server \
DSPACE_MCP_PUBLIC_URL=http://127.0.0.1:8080 \
npm run dev:http
# MCP endpoint: POST http://localhost:8080/mcp (requires a bearer token)npm run build
docker build -t dspace-mcp .
# Push to ECR, deploy with API Gateway HTTP API v2Variable | Default | Description |
|
| DSpace REST API base URL |
|
| HTTP server port (Lambda/dev) |
| (none) | stdio auth: a pre-existing DSpace JWT to authenticate the session at startup. Takes precedence over user/password |
| (none) | stdio auth: DSpace username/email (used with |
| (none) | stdio auth: DSpace password (used with |
|
| HTTP transport: externally reachable base URL of this MCP server. Used as OAuth issuer, resource identifier, and to build the metadata/authorize/token URLs. Must be the public URL (behind Lambda/ALB), not |
|
| Also enable the non-browser |
|
| Opaque access-token lifetime, seconds (10 min) |
|
| Refresh-token lifetime, seconds (20 min) |
|
| Authorization-code lifetime, seconds (5 min) |
Token lifetimes. These form a hierarchy: access token (10 min) < refresh token (20 min) < DSpace JWT (DSpace default ~30 min). A refresh renews the underlying DSpace JWT via DSpace's native mechanism, which only works while that JWT is still valid — so the refresh token is kept shorter than the DSpace JWT. If your DSpace uses a different JWT lifetime, adjust these accordingly (keep both below the DSpace JWT).
The OAuth variables affect the HTTP transport only. The stdio transport ignores them and authenticates from
DSPACE_TOKEN(orDSPACE_USER/DSPACE_PASSWORD) at startup, as the MCP spec recommends for stdio.
There are two authentication models, one per transport.
The local process holds a single DSpace session, authenticated from the environment at startup (the model the MCP spec recommends for stdio: credentials come from the local environment, not over the network and not through tool calls). Set either:
DSPACE_TOKEN — a pre-existing DSpace JWT (takes precedence), or
DSPACE_USER + DSPACE_PASSWORD — a DSpace username/email and password.
// Claude Desktop / Cursor
{
"mcpServers": {
"dspace": {
"command": "node",
"args": ["dist/transports/stdio.js"],
"env": {
"DSPACE_BASE_URL": "https://sandbox.dspace.org/server",
"DSPACE_USER": "dspacedemo+admin@gmail.com",
"DSPACE_PASSWORD": "dspace"
// or, instead of user/password:
// "DSPACE_TOKEN": "<dspace-jwt>"
}
}
}
}The session established at startup persists for the process lifetime and is
reused for every tool call. If no credentials are set, the server starts
unauthenticated and only public/anonymous DSpace operations work. There is no
login/logout tool: credentials never pass through the model, and for security
the JWT is never returned in any tool response (error messages are scrubbed of
anything resembling a token). Use dspace_auth_status to check the session.
The HTTP transport always runs with OAuth 2.1: the server acts as both an OAuth 2.1 authorization server and a resource server, using DSpace itself as the identity backend — no external OIDC/IdP is required. Each caller authenticates with their own DSpace credentials, so every DSpace call runs as that user rather than as a shared service account.
Key property: the DSpace JWT stays server-side. The MCP server mints its own
opaque access/refresh tokens and hands only those to the client; the client
sends them as Authorization: Bearer … at the transport layer. The DSpace JWT
therefore never enters a tool argument, a tool result, or the model's context.
Standards implemented (per the MCP authorization spec):
RFC 9728 Protected Resource Metadata — GET /.well-known/oauth-protected-resource/mcp
RFC 8414 Authorization Server Metadata — GET /.well-known/oauth-authorization-server
RFC 7591 Dynamic Client Registration — POST /register
POST /mcp requires a valid bearer; a missing/invalid token returns 401 with
a WWW-Authenticate header pointing at the resource metadata, which is what
triggers the OAuth flow in MCP clients. Once authenticated, every DSpace call
runs as that user, using their DSpace JWT.
The MCP client discovers the metadata, registers, and opens /authorize.
The server serves a small login page; the user types their DSpace credentials in the browser. They go straight to DSpace and are never seen by the MCP client or the model.
On success the server logs in to DSpace, issues a single-use authorization code, and redirects back to the client.
The client exchanges the code (with its PKCE code_verifier) at /token for
an opaque access token + refresh token.
Refreshing rotates the tokens and also refreshes the backing DSpace JWT, so long sessions stay alive transparently.
Enable with DSPACE_MCP_HEADLESS_FALLBACK=true. The /token endpoint then also
accepts the OAuth 2.1 password grant (discouraged by the spec — use only when
a browser is unavailable). It has two modes:
Login — username + password are DSpace credentials. The server logs in
to DSpace and stores the freshly minted JWT. That token is created inside the
server from the credentials and is never returned to the client or the model.
curl -X POST http://127.0.0.1:8080/token \
-d grant_type=password \
-d client_id=headless \
-d username='dspacedemo+admin@gmail.com' \
-d password='dspace'JWT passthrough — set username=jwt-token and put an existing DSpace JWT in
the password field. The server verifies the token against DSpace
(/api/authn/status) and, if valid, stores it as-is.
curl -X POST http://127.0.0.1:8080/token \
-d grant_type=password \
-d client_id=headless \
-d username=jwt-token \
-d password='<existing-dspace-jwt>'Both return a standard OAuth response with an opaque access_token (and
refresh_token); use the opaque token as the bearer on /mcp.
Security note. A JWT supplied via passthrough has, by definition, already been handled by the client (and possibly the model context). The server does not attempt to invalidate it: DSpace's refresh only rotates the token and leaves the previous one valid until its own expiry, so refreshing cannot revoke a leaked token. The only true revocation is a DSpace logout, which destroys the whole session (new token included) and is therefore not done here. A passed-in JWT stays valid until its natural expiry; supply it knowingly. The
password-login mode does not have this exposure, since the token is born server-side — prefer it, and prefer the Authorization Code flow over both whenever a browser is available.
Because this grant routes credentials/tokens through the MCP client, it is off by default.
The token store is in-memory by default, which is per-process. That is fine
for a long-lived local/HTTP server, but the Lambda HTTP transport is stateless
(a fresh process per invocation), so opaque tokens minted in one invocation will
not be found in the next. For Lambda, provide a persistent TokenStore
implementation (e.g. DynamoDB or Redis) — the code is written against the
TokenStore interface in src/auth/token-store.ts specifically to make that
swap without touching the provider.
There is no
dspace_login/dspace_logouttool. Authentication is handled by the transport — OAuth on HTTP, environment credentials on stdio — never through the model. On the HTTP transport every/mcprequest requires a valid bearer. Usedspace_auth_statusto check the current session.
Tool | Description |
| Check current authentication status |
| Search items, communities, collections |
| Get item by UUID with full metadata |
| List top-level communities |
| List collections (optionally filtered by community) |
| Create an archived item (admin, bypasses workflow) |
| Patch item metadata (JSON Patch) |
| Permanently delete an item by UUID (admin) |
| Upload a local file as a bitstream (attachment) to an item (admin) |
| Get an item's file text — extracted text (TEXT bundle) or a textual original |
| Download a bitstream by UUID — save to a local file ( |
| Create a submission workspace item |
| Update workspace item metadata |
| List current user's workspace items |
Copyright © 2026 4Science Spa
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.
See the LICENSE file for the full license text.
dspace-mcp is independent software that communicates with a DSpace instance only through its public REST API, over the network. It is not a derivative work of DSpace, does not link against DSpace code, and does not embed or redistribute any part of DSpace.
For this reason, using dspace-mcp has no licensing impact on the DSpace instance it connects to. The AGPL-3.0 covers dspace-mcp itself only, and running or integrating it does not require you to release the connected DSpace instance — or its customizations, configuration, or infrastructure — under the AGPL-3.0 or any other license. Interacting with DSpace through its REST API is ordinary client/server communication and does not combine the two into a single program.
4Science Spa, as the copyright owner, also offers dspace-mcp under separate commercial terms for organizations that cannot comply with the AGPL-3.0 (for example, those integrating it into closed-source or SaaS products without releasing their source). Contact 4Science for commercial licensing options.
Contributions are welcome. Please read CONTRIBUTING.md.
All contributions are subject to a Contributor License Agreement, which allows 4Science to distribute the project under the AGPL-3.0 and under commercial licenses (dual licensing):
Individuals: CLA.md
Companies / organizations: CLA-ENTITY.md
Check the current authentication status with the DSpace instance.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does not disclose what the status comprises (logged-in user, token validity, expiry), whether it requires a prior login, or whether it is a safe read-only call, leaving the agent to infer all of this.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler. Nothing is wasted and the purpose is stated immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-annotation tool with no output schema, the description is minimal but leaves the agent guessing what the status result actually contains and whether any prerequisite state is required. Adequate, but a sentence on the expected outcome would close the gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate. The baseline of 4 applies since no parameter-level semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: check the current authentication status with the DSpace instance. This is clearly distinguishable from siblings dspace_login and dspace_logout, though it doesn't explicitly name those siblings as the contrasting alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent can infer this is a read-only probe used to determine whether it needs to call dspace_login. There is no explicit statement of when to call it (e.g., before authenticated operations) or when it is unnecessary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an archived item directly in DSpace (admin only, bypasses submission workflow). The item is immediately visible in the repository.
| Name | Required | Description | Default |
|---|---|---|---|
| metadata | Yes | Item metadata as key-value pairs. Keys are Dublin Core fields (e.g. "dc.title", "dc.contributor.author"). Values can be a string or array of strings for multi-valued fields. | |
| discoverable | No | Whether the item is discoverable via search (default: true) | |
| owningCollectionUuid | Yes | UUID of the collection to create the item in |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does disclose two meaningful traits: it requires admin privileges and the item is immediately visible in the repository (no staged/draft state). It omits failure behavior, metadata validation requirements, and what the call returns, but the permission and visibility disclosures are exactly the non-obvious facts an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, zero filler, with the purpose front-loaded and the admin/visibility constraints following immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description covers the essentials: what it does, who can do it, and the immediate-visibility side effect. The notable remaining gap is the return value (e.g. the new item's UUID) and any required-metadata constraints, which the agent must learn from elsewhere.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (owningCollectionUuid, metadata, discoverable are all documented in the schema, including Dublin Core key format and multi-value handling). The description adds nothing beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Create an archived item") plus the scope qualifier ("directly in DSpace"), and the phrase "bypasses submission workflow" implicitly distinguishes it from the workspace/submission siblings like dspace_create_workspace_item. An agent can tell it apart from the other create-path tools without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"admin only, bypasses submission workflow" gives clear context for when this tool applies and a precondition for calling it. It stops short of naming the alternative explicitly (e.g. use dspace_create_workspace_item for the normal submission path), so no exclusions or routing guidance are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new workspace item (submission) in DSpace. This starts the standard deposit workflow. After creation, use dspace_update_workspace_item to add metadata, then submit for review.
| Name | Required | Description | Default |
|---|---|---|---|
| metadata | No | Initial metadata as key-value pairs (e.g. {"dc.title": "My Paper", "dc.contributor.author": ["Author 1", "Author 2"]}) | |
| owningCollectionUuid | No | UUID of the target collection (defaults to first submittable collection) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that this is the entry point to a multi-step deposit workflow and that metadata is not added here, but it omits auth requirements (there is a dspace_login sibling), whether the item is reversible/deletable before submission, and what identifier the caller receives for the next step.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the core action and followed by the workflow sequence. Every sentence earns its place by establishing either what the tool does or what the caller must do next.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description covers the workflow position but leaves gaps: it does not say what the return value contains (presumably the workspace item handle/UUID needed by the next call), nor the authentication precondition. Adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (metadata and owningCollectionUuid) are already documented with examples and defaults in the schema. The description adds no parameter-level detail beyond that, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Create a new workspace item (submission) in DSpace.' The parenthetical clarifies that this is the workspace/submission model rather than a published item, which is meaningful given the sibling dspace_create_item. It stops short of explicitly contrasting itself with that sibling, so an agent must infer the distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear workflow context: creation starts the deposit workflow, then route to dspace_update_workspace_item to add metadata and submit for review. It names the next tool explicitly. It does not, however, state when to prefer this over dspace_create_item or what prerequisites (e.g., being logged in) apply.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete an item from DSpace by UUID (admin only). This is irreversible: the item and its bundles/bitstreams are removed from the repository.
| Name | Required | Description | Default |
|---|---|---|---|
| uuid | Yes | UUID of the item to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does well: it declares the operation irreversible, discloses the cascade (bundles/bitstreams removed), and states the admin-only authorization requirement. It omits error/response behavior, but the destructive and auth semantics are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action and identifier, followed immediately by the critical irreversibility warning. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, single-parameter mutation tool with no output schema and no annotations, the description supplies the essential context: destructiveness, cascade scope, and auth requirement. Response/error behavior is unaddressed, but no output schema exists to defer to.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single 'uuid' parameter, so the schema already documents it; the description only restates 'by UUID'. Per the baseline rule for high coverage, a 3 is appropriate with no added syntax or format detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Permanently delete'), resource ('an item from DSpace'), and identifier ('by UUID'), which cleanly distinguishes it from read/update siblings like dspace_get_item and dspace_update_item_metadata. An agent can identify the operation without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The '(admin only)' qualifier gives a clear precondition for use, effectively telling the agent when this tool is applicable. It does not name alternatives (e.g., 'use dspace_update_item_metadata to modify instead of delete') or state explicit when-not conditions, so it falls short of the top band.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a DSpace item by UUID, including all metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| uuid | Yes | Item UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and delivers little: it does not state auth requirements, error behavior for a bad/unknown UUID, or whether metadata is complete vs. partial. 'Including all metadata' is the only behavioral hint offered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence, front-loaded with verb and resource, with zero filler. Well-sized for a single-parameter lookup tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a trivial single-param read with no output schema, the description is minimally adequate but silent on return shape and auth context. Since no output schema exists, it could usefully describe what the item payload looks like.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single uuid parameter is documented as 'Item UUID' in the schema, so the description's 'by UUID' adds essentially nothing. Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Get) and resource (DSpace item) scoped by UUID, and notes it returns all metadata. It does not explicitly differentiate from read-side siblings like dspace_search, but the resource+identifier combination is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no mention of prerequisites (e.g. whether login is required), and no pointer to alternatives such as dspace_search when the UUID is unknown. The agent must infer context entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List collections, optionally filtered to a specific community.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (0-based) | |
| size | No | Results per page | |
| communityUuid | No | UUID of parent community (omit for all collections) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. "List" implies a read, but the description discloses nothing about permissions, ordering, pagination beyond what the schema shows, or return format, leaving significant gaps for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no wasted words that conveys the tool's action and its one notable option.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with complete schema coverage and no output schema, the description is minimally adequate. It omits any note of default ordering or that results are paginated, but the essential action is conveyed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents page, size, and communityUuid. The description restates the community filter without adding format or defaulting detail beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (collections) with the optional community scoping, which is clear. However, it does not explicitly differentiate itself from the sibling dspace_list_communities, leaving the agent to infer the distinction from the names alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Optionally filtered to a specific community" implies when the communityUuid parameter is useful, but there is no explicit when-to-use guidance, no mention of alternatives like dspace_list_communities, and no exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List top-level communities in the DSpace repository.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (0-based) | |
| size | No | Results per page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing beyond the fact that it is a read: no auth/permission requirements, no pagination default behavior, no indication of whether results are limited or how many are returned. For a repo-listing call with zero annotation coverage this is a real gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short, front-loaded sentence with no filler. It says exactly what the tool is and nothing more, which is structurally ideal for a simple list operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a trivial paginated list with a fully documented input schema and no output schema, the description is minimally sufficient. It stops short of telling the agent anything about result shape, ordering, or how it differs from sibling listing tools, which leaves the definition merely adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters (page, size) have 100% schema description coverage and the description adds no format or default-value detail beyond them. With the schema doing all the work and no parameters required, the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (List) and resource (communities) with the scope qualifier 'top-level', so the operation itself is unambiguous. However, it never distinguishes itself from the close sibling dspace_list_collections or dspace_list_workspace_items, which an agent could easily confuse with it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use, when-not-to-use, or alternative-tool guidance. The agent is left to infer that this is a browsing/entry-point call rather than a search, and must guess how it relates to dspace_search and dspace_list_collections.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List workspace items (submissions in progress) for the current user.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (0-based) | |
| size | No | Results per page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. 'List' safely implies a read operation, but it does not disclose the authentication requirement (only implies it via 'current user'), pagination behavior or defaults, or what an empty result means. It adds little beyond restating the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single tight sentence with the resource front-loaded and the parenthetical clarification placed exactly where comprehension needs it. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter, no-output-schema list tool this is minimally adequate: the read scope and subject are clear and the schema handles pagination. It falls short on prerequisites (auth/session state) and any indication of result shape beyond 'items', which matters because a workspace list is user-scoped.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both 'page' (0-based) and 'size' (1-100) are fully documented in the schema, including bounds. The description adds no additional meaning such as default values or ordering, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (workspace items) with scope (for the current user), and clarifies the domain jargon by equating workspace items with in-progress submissions. It does not explicitly distinguish itself from siblings like dspace_search or dspace_get_item, but the resource is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance: no mention of when to prefer this over dspace_search, dspace_list_collections, or how it relates to dspace_create_workspace_item / dspace_update_workspace_item. The phrase 'for the current user' implies a logged-in context but stops short of stating a prerequisite.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Authenticate with a DSpace instance. Provide EITHER a JWT token directly, OR username + password for password-based login. The session persists for subsequent tool calls.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Email/username for password login | ||
| token | No | Pre-existing JWT token to use directly | |
| password | No | Password for password login |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses that the session persists across subsequent tool calls, but says nothing about token lifetime, what happens on failure, whether credentials are stored, or how to re-authenticate after expiry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, zero filler, with the core purpose front-loaded and the two login modes immediately following. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-param tool with no output schema and no annotations, the description covers the essentials: purpose, the two modes, and session persistence. Missing failure/expiry behavior keeps it short of a 5, but nothing critical blocks correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, and the description adds meaning beyond the schema by stating the either/or constraint: token OR email+password. That mutual exclusivity is not expressible in the flat schema and is the key semantic an agent needs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Authenticate with a DSpace instance') and is clearly distinguishable from siblings like dspace_auth_status and dspace_logout. An agent can immediately tell this establishes a session rather than checking or ending one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lays out the two mutually exclusive entry paths (JWT token OR username+password), which is real usage guidance for how to call it. It does not, however, say when to prefer this over dspace_auth_status or when to call it again if a session already exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Logout from the DSpace instance, invalidating the current JWT token.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the key side effect: the current JWT token is invalidated, which tells the agent the session becomes unusable. It omits other relevant traits such as whether an already-logged-out or invalid token errors, and whether invalidation is server-side only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that names the action first and the effect second, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description covers all an agent needs to call it: the action and its effect on the token. Only minor edge-case behavior (already-invalid sessions, authentication prerequisites) is unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters and the description correctly introduces none. Baseline of 4 applies for a parameterless tool; there is simply nothing further to document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (logout) and resource (the DSpace instance), and adds the concrete effect ('invalidating the current JWT token'). This cleanly distinguishes it from its direct sibling dspace_login and from dspace_auth_status, which reads session state instead of ending it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the verb and by the presence of dspace_login/dspace_auth_status as siblings, but the description never explicitly says when to call it (e.g. at end of a session, before switching accounts) or what happens if no session exists. Adequate but no routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search DSpace for items, communities, or collections. Supports full-text queries, type filtering, scoping to a container, and advanced filters.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (0-based) | |
| size | No | Results per page (default 20) | |
| sort | No | Sort field and direction, e.g. "dc.date.issued,desc" | |
| query | No | Search query string (Solr/Lucene syntax) | |
| scope | No | UUID of a community/collection to scope the search | |
| dsoType | No | Filter by object type | |
| filters | No | Advanced filters as key-value pairs, e.g. {"author": "Smith,equals"} |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It identifies a search operation but does not state read-only safety, authentication requirements, pagination behavior, rate limits, or result format; the schema supplies parameter details but not behavioral guarantees.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with the purpose followed by supported capabilities. There is no filler, and every sentence contributes to a quick understanding of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter search tool with no annotations, no output schema, and many sibling tools, the description omits when to use this versus list/get tools and provides no behavioral or authentication context. The rich schema helps with invocation mechanics but not selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all 7 parameters already documented in detail (Solr/Lucene syntax, UUID scope, enum type, filter key-value examples). The description restates parameter categories without adding syntax, defaults, or examples beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Search') and resource (DSpace items, communities, collections), making the core action clear. However, it does not explicitly differentiate this tool from sibling list/get tools such as dspace_list_communities or dspace_get_item, so an agent must infer when search is preferred.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. The description lists capabilities (full-text queries, type filtering, scoping, advanced filters) but never names alternatives or the conditions under which this tool should be chosen over sibling list/get tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update metadata on an existing DSpace item using JSON Patch (RFC 6902). Supports add, remove, replace, and move operations on metadata fields.
| Name | Required | Description | Default |
|---|---|---|---|
| uuid | Yes | UUID of the item to update | |
| operations | Yes | Array of JSON Patch operations |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses the mutation mechanism and the supported ops, which is useful, but says nothing about permission/auth requirements, whether 'remove' is irreversible, whether operations are atomic or can partially fail, or what the response looks like — all critical for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with no filler, front-loading the core action and then the supported operation set. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description need not explain return values, and the schema is rich enough to cover parameters. However, for a mutation tool with no annotations, the description omits auth/permission expectations and the consequences or reversibility of operations — a meaningful gap for an agent about to modify live metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the nested operations schema already documents op, path, from, and value with examples, so the schema does the heavy lifting. The description adds only the RFC 6902 reference and the op enumeration, which are marginal gains beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Update metadata on an existing DSpace item') and names the mechanism (JSON Patch / RFC 6902) plus the supported operations, so the agent knows exactly what the tool does. It does not, however, explicitly differentiate itself from the sibling dspace_update_workspace_item, leaving that distinction to the agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites (e.g. authentication or required permissions), and no mention of when to prefer this over dspace_update_workspace_item or dspace_create_item. The agent must infer all routing decisions from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update metadata on a workspace item (submission in progress) using JSON Patch.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Workspace item ID | |
| operations | Yes | JSON Patch operations |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses only the patch mechanism (JSON Patch), which is meaningful, but says nothing about mutation semantics such as whether remove operations are destructive, whether the item must be unlocked, auth requirements, or error behavior on invalid paths, leaving a write tool substantially under-documented.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with the verb+resource first and the mechanism last; nothing is wasted. It is arguably too terse to address a JSON Patch write tool, but as a sentence it is well structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema is fully documented and the description names the resource and patch mechanism, so an agent can call it correctly. For a mutation tool with no annotations and no output schema, though, missing guidance on permissions, item state, and patch failure behavior leaves real gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the schema documents the required id and the operations array with op/path/from/value semantics and a concrete JSON Pointer example. The description adds only the mechanism name and no extra parameter guidance, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (update) and resource (metadata on a workspace item) and helpfully glosses 'workspace item' as a submission in progress, which disambiguates the resource. It does not, however, distinguish itself from the sibling dspace_update_item_metadata, leaving the agent to infer that one targets in-progress submissions and the other archived items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The parenthetical '(submission in progress)' implies the usage context, so an agent can roughly infer when this tool applies. However, it never states when to use this instead of dspace_update_item_metadata or dspace_create_workspace_item, nor any preconditions such as required submission state or permissions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a local file as a bitstream (attachment) to a DSpace item (admin only). The file is added to the item's bundle (default "ORIGINAL", where DSpace stores primary files); the bundle is created automatically if it does not exist.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Bitstream name shown in DSpace (defaults to the file name) | |
| filePath | Yes | Absolute path to the local file to upload | |
| itemUuid | Yes | UUID of the item to attach the file to | |
| mimeType | No | MIME type of the file (auto-detected from the extension if omitted) | |
| bundleName | No | Target bundle name (default: "ORIGINAL"). Use "LICENSE" or "THUMBNAIL" for special bundles. | |
| description | No | Optional description stored as dc.description on the bitstream |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden: it usefully discloses the admin-only auth requirement, the default ORIGINAL bundle, and that the bundle is auto-created as a side effect. However, it omits return value, overwrite/duplicate-name behavior, and size limits, which matter for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste, purpose front-loaded followed by the bundle behavior. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, auth gate, and bundle side effects for a 6-parameter mutation tool with no annotations or output schema. It is nearly complete, but the absence of return-value and overwrite/error semantics leaves a modest gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description only reinforces the bundleName default and ORIGINAL semantics that the schema already states, adding no new parameter-level detail such as name collisions or path constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Upload a local file as a bitstream ... to a DSpace item') and scopes it clearly against siblings like dspace_create_item and dspace_update_item_metadata. An agent can identify the operation without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides the key usage constraint '(admin only)' and implies the item must already exist as the attachment target, which gives real context. It does not explicitly name when to prefer this over alternatives, but no sibling competes for the same bitstream-upload job.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0dspace_auth_statusdspace_create_itemdspace_create_workspace_itemdspace_delete_itemdspace_get_itemdspace_list_collectionsdspace_list_communitiesdspace_list_workspace_itemsdspace_logindspace_logoutdspace_searchdspace_update_item_metadatadspace_update_workspace_itemdspace_upload_bitstreamScored across 14 tools
Each tool has a clearly distinct target and action: auth tools (status/login/logout), hierarchy (list_communities, list_collections), retrieval (search, get_item), and mutation tools. The only potentially confusable pair — create_item vs create_workspace_item and update_item_metadata vs update_workspace_item — is explicitly disambiguated by the archived-vs-workspace distinction in the descriptions.
All 14 tools use a uniform snake_case convention with a consistent dspace_ prefix, and verbs (list/get/create/update/delete/upload/login/logout/search) are used predictably across resource nouns. No camelCase or mixed styles appear anywhere.
14 tools is well within the ideal 3-15 range and each one maps to a distinct capability (auth lifecycle, hierarchy browsing, item CRUD, bitstream upload, workspace workflow). Nothing feels redundant or padded.
Item CRUD plus bitstream upload and a read side (communities/collections/search) are covered, but the workspace workflow is a dead end: create_workspace_item's own description says to 'submit for review' yet no submit tool exists, and delete_workspace_item, bitstream download, and community/collection management are absent. These gaps will force agents to abandon the documented deposit flow.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Query, browse, and automate OmegaAI workspaces from any MCP client. Streamable HTTP with OAuth 2.0.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
