Research Deposition MCP

A safety-first Model Context Protocol (MCP) server for preparing scholarly deposits from agentic research workflows. Zenodo is the first repository adapter; the core model is intentionally repository-independent.

Project status: v0.2 in progress / early development. Use Zenodo Sandbox for testing. Package identity and signed human approval are implemented; full remote-draft/file attestation remains planned in #10.

Why this exists

Repository APIs make programmatic deposition possible, but a raw API wrapper is not enough for trustworthy agentic publishing. Research Deposition MCP separates three responsibilities:

1. Agent/LLM — interpret researcher intent and assemble candidate metadata.

2. Deterministic deposition layer — validate, canonicalize, hash, transform, upload, and report inconsistencies.

3. Human/operator — authorize publication of a specific immutable package using a signing key kept outside the MCP/agent environment.

The design principle is simple: agents may help prepare a deposit, but they should not silently invent scientific metadata or obtain implicit authority to publish it.

Related MCP server: io.github.xngg1021/academic-research-kernel

Current scope

Implemented:

• repository-independent research-deposit model;

• deterministic schema validation with warnings;

• deterministic file selection with explicit include/exclude rules;

• repository-independent file manifest with POSIX/NFC-normalized source/deposit paths, byte size, and SHA-256;

• canonical byte-stable file-manifest serialization;

• canonical scientific metadata serialization;

• versioned publication package combining metadata + manifest;

• SHA-256 package digest with domain separation;

• strict rejection of symlinks/path traversal for manifest construction;

• Zenodo adapter and Zenodo Sandbox default;

• draft creation, retrieval, metadata update, and local file upload;

• publication review that emits the exact approval request;

• Ed25519 operator-signed, short-lived approval receipts;

• pre-publication package digest recomputation;

• approval binding to package digest, repository adapter, endpoint, draft ID, and policy version;

• publication disabled by default at process level.

Still planned include wiring the append-only audit event log (#9) into the MCP tool handlers, full Zenodo remote-package verification and Sandbox E2E coverage (#10), RO-Crate/CITATION.cff/ISA/ORW importers, identifier validation, and additional repository adapters. See ROADMAP.md and BACKLOG.md.

MCP tools

See docs/file-manifest.md, docs/package-identity.md, and docs/approval.md.

Safety defaults

ZENODO_BASE_URL=https://sandbox.zenodo.org
ZENODO_ALLOW_PUBLISH=false
DEPOSITION_PUBLICATION_POLICY_VERSION=1
DEPOSITION_APPROVAL_MAX_AGE_SECONDS=900

A valid approval receipt does not enable publication by itself. Final publication requires both:

1. deliberate process configuration (ZENODO_ALLOW_PUBLISH=true); and

2. a valid operator-signed receipt matching the freshly recomputed package and exact target.

The private approval key is intentionally not used by the MCP server. See docs/safety-model.md.

Requirements

• Node.js 20+

• npm

• a Zenodo Sandbox personal access token for writable tests

Install

git clone https://github.com/dhuzard/Research-Deposition-MCP.git
cd Research-Deposition-MCP
npm install
npm test

Create a Zenodo Sandbox token and start the MCP server:

export ZENODO_API_KEY="..."
npm start

Do not commit tokens or put them into MCP configuration files that will be version-controlled.

Local CLI

research-deposition is a local, read-only operator CLI. It validates a package config and its selected files and computes the deterministic package digest; it never talks to a repository and never writes anything.

research-deposition status [--json]
research-deposition package check <config.json> [--json]
research-deposition package digest <config.json> [--json]

A package config is JSON with schemaVersion: "1", repository-independent metadata, and an explicit files list of { "sourcePath": "...", "depositName": "..." } entries. sourcePath is resolved relative to the directory containing the config file (the implicit root) and is treated as a literal file path, not a glob. --json emits exactly one JSON document to stdout, including on validation failure; without it, output is human-readable. Exit codes: 0 for a valid (or warning-only) result, 1 for an invalid config/metadata/file or a runtime safety rejection, 2 for usage errors. Tokens are never accepted as CLI flags and are never logged; status only reports whether one is configured via ZENODO_API_KEY.

MCP client example

{
  "mcpServers": {
    "research-deposition": {
      "command": "node",
      "args": ["/absolute/path/Research-Deposition-MCP/build/src/index.js"],
      "env": {
        "ZENODO_API_KEY": "YOUR_SANDBOX_TOKEN",
        "ZENODO_BASE_URL": "https://sandbox.zenodo.org",
        "DEPOSITION_APPROVAL_PUBLIC_KEY_FILE": "/safe/path/operator-public.pem"
      }
    }
  }
}

Only the public approval key belongs in the MCP process.

Repository-independent metadata

{
  "title": "Home-cage behavioral dataset",
  "description": "Behavioral and experimental metadata for ...",
  "resourceType": "dataset",
  "creators": [
    {
      "name": "Huzard, Damien",
      "orcid": "0000-0000-0000-0000",
      "affiliation": "..."
    }
  ],
  "keywords": ["FAIR", "home-cage monitoring"],
  "license": "cc-by-4.0",
  "version": "1.0.0",
  "relatedIdentifiers": []
}

The common model deliberately avoids Zenodo field names. Repository-specific transformations live in adapters.

File manifest

{
  "rootDir": "/path/to/project",
  "include": ["data/**", "README.md"],
  "exclude": ["data/intermediate/**"],
  "destinations": {
    "README.md": "documentation/README.md"
  }
}

build_file_manifest returns a canonical manifest containing only repository-independent relative paths and content identity. Absolute local paths are not serialized. Symlinks and .. traversal are rejected.

Publication package and digest

build_publication_package combines canonical metadata with the canonical file manifest. The resulting digest has the form:

sha256:<64 lowercase hex characters>

The digest is over a versioned canonical JSON representation with explicit domain separation. Creator order is significant. Keywords and related identifiers are canonicalized as unordered sets. Unknown operational metadata fields and machine-local root paths do not affect the digest.

The full contract and golden test fixture are documented in docs/package-identity.md.

Human approval workflow

Generate an operator key pair outside the agent workspace:

npm run build
research-deposition-approve keygen \
  --private-key ~/.config/research-deposition/operator-private.pem \
  --public-key ~/.config/research-deposition/operator-public.pem

Configure the MCP process with only the public key:

export DEPOSITION_APPROVAL_PUBLIC_KEY_FILE="$HOME/.config/research-deposition/operator-public.pem"

Call publication_review with the draft ID, metadata, root directory, and file-selection rules. It returns an approvalRequest containing the package digest and exact publication target.

Save that request as JSON and sign it interactively:

research-deposition-approve sign \
  --request approval-request.json \
  --private-key ~/.config/research-deposition/operator-private.pem \
  --receipt approval-receipt.json

The signing command requires a TTY and an exact human-entered confirmation phrase. There is intentionally no non-interactive bypass flag.

publish_draft then requires the receipt plus the metadata/file-selection inputs. It re-reads the selected files and recomputes the package digest immediately before verifying the receipt and publishing.

Any change to metadata, selected file content, selected filenames, repository endpoint, draft ID, or configured policy version invalidates the authorization.

See docs/approval.md for the complete protocol and its current limitations.

Audit event log

src/audit.ts defines a repository-independent, append-only audit event schema (v1) with a domain-separated SHA-256 hash chain, plus an AuditFileSink NDJSON persistence layer (src/audit-sinks.ts) that validates any existing log and refuses to resume a tampered one. It records operation-level activity — validation, manifest/digest generation, draft and file operations, approval lifecycle, publication — without repository tokens, the approval private key, or arbitrary payloads.

The chain is tamper-evident, not tamper-proof; see docs/audit.md for its guarantees and limits (in particular, detecting tail truncation requires an externally held checkpoint hash). This module is not yet wired into the MCP tool handlers.

Architecture

Agentic client
     │ MCP
     ▼
Research Deposition MCP
 ├─ deterministic validation / policy
 ├─ common research-deposit model
 ├─ deterministic file-manifest layer
 ├─ canonical publication-package identity
 ├─ operator public-key receipt verification
 └─ repository adapters
       ├─ Zenodo
       ├─ InvenioRDM (planned)
       └─ Dataverse (planned)

Human/operator side
 └─ private Ed25519 key + interactive approval CLI

Metadata-source adapters will eventually map structures such as ISA, RO-Crate, CITATION.cff, and Open Research Workspace (ORW) metadata into the common model without coupling those standards to Zenodo.

More detail: docs/architecture.md.

Environment variables

Current integrity boundary

The signed receipt authorizes the declared local publication package and exact repository target. The server recomputes that local package immediately before publication.

Full proof that the current remote Zenodo draft contains exactly the same file set is not yet implemented; that is part of #10. Direct upload_file operations therefore remain a known gap before this should be treated as production-grade remote package attestation.

Development

npm install
npm run build
npm test

Source code lives under src/; repository-specific code belongs under src/adapters/. Tests use Node's built-in test runner.

Before adding any new write capability, read AGENTS.md, CONTRIBUTING.md, and docs/safety-model.md.

Contributing

Issues and pull requests are welcome. For substantial features, open an issue first so the data model, safety boundary, and repository semantics can be discussed before implementation. See CONTRIBUTING.md.

For security-sensitive problems, do not open a public issue; follow SECURITY.md.

License

MIT — see LICENSE.