Software Requirements Specification¶

This section is the Software Requirements Specification (SRS) for PriorisMCP. It is both user-readable documentation and the working design reference for implementation — requirements land here before code, and this section is expected to evolve alongside the server as new source providers and capabilities are added.

Purpose¶

PriorisMCP is a Model Context Protocol (MCP) server that gives an MCP client (e.g. Claude) a single, uniform way to browse, search, fetch, and parse prior art from external sources — starting with research publications, with patents and other prior-art domains anticipated as future work.

Scope¶

v1¶

• One provider domain: research publications.
• Three providers within that domain:
  • arXiv — open-access, no authentication required.
  • Europe PMC — open-access, no authentication required, biomedical/life-sciences literature.
  • Local filesystem — not a network source at all: parses a caller-supplied PDF the caller already has (e.g. a paywalled paper downloaded through the user's own, out-of-band authenticated access), sent to the server as base64-encoded content rather than a server-side path, so "local" means local to the caller regardless of transport. Deliberately narrower than the other two — see Architecture → Local filesystem source for why it implements only fetch_full_text/parse_full_text, not the full capability set.
• Capabilities exposed per provider (exact availability is provider-dependent — not every provider necessarily supports every capability):
  • Search by keyword/query.
  • List top-N items by category (arXiv subject classification only — see Out of scope for v1 for why Europe PMC doesn't get this capability in v1).
  • Fetch metadata for a given item — a distinct, lightweight operation, separate from full-text retrieval.
  • Fetch full text for a given item — a separate, heavier operation than metadata fetch; the returned format depends on what the provider/item offers (e.g. arXiv exposes both PDF and HTML full text; other providers may differ). For the local filesystem source, this decodes and validates caller-sent content rather than performing network I/O.
  • Parse full text — convert previously-fetched full text into Markdown, operating on already-persisted content rather than re-fetching it.
• Resolve identifier — a grouping-level capability, not per-provider: convert an item identifier (e.g. DOI, arXiv ID) into a fetchable URL, parameterised by the desired target format (e.g. HTML, PDF). Self-identifying identifier schemes (an arXiv ID) route directly to their provider; DOIs resolve via the DOI system first, then route to whichever v1 provider (if any) the redirect lands on. The local filesystem source has no identifiers to route — it is invoked directly, never through this tool.
• List/delete fetched content — also grouping-level, not per-provider: enumerate or remove previously-persisted (provider, identifier, format, artefact) entries from the storage abstraction, across any v1 provider, so a caller can correct a mistaken fetch (e.g. the wrong arXiv ID) without needing filesystem-level access to the storage backend. See Functional requirements → Storage management tools.
• Fetched full text is persisted through a storage abstraction, with a local filesystem backend as the default.
• Repeated identical requests are served through the server's existing response-caching middleware rather than a separate, provider-specific caching layer.
• Served over both stdio and streamable-http/http MCP transports (PRIORIS_MCP_TRANSPORT, see src/prioris_mcp/__init__.py); an agent invoking PriorisMCP via stdio is the primary expected path, but v1 doesn't restrict to it. The HTTP transport's ingress security posture is covered in Security.

Two open-access, unauthenticated network providers are deliberately chosen for v1 so that the provider interface (see Architecture) is validated against two genuinely different APIs and content shapes, rather than being modelled after a single source and assumed to generalise. The local filesystem source is a third, non-network addition to the same grouping, validating the interface's other direction: that a source implementing only a subset of the capability set is expressible without distorting the interface itself (see Architecture → Provider groupings).

Out of scope for v1¶

• Patents. Anticipated as a separate provider grouping (PatentProvider) once the research-publication providers have exercised the shared abstractions. Patent records differ enough (claims, legal/family status, citation graphs) that they are not expected to fit the same interface as research publications without changes.
• Authenticated sources (e.g. Semantic Scholar, or any source requiring an API key or OAuth). v1 targets unauthenticated, open-access sources only; authenticated sources are future work once credential handling and per-source rate/quota policies are designed.
• Fetching arbitrary URLs directly (as opposed to caller-sent content) for the local filesystem source. This was considered specifically so that content already retrieved through the user's own out-of-band authentication (e.g. a paywalled paper downloaded through a subscription) could still be parsed — but a tool that fetches a caller-supplied URL is the same SSRF shape already rejected for DOI routing (see Security → Untrusted identifiers): it would let a caller direct PriorisMCP's own network egress at an arbitrary host, including internal/private addresses, with no allowlist possible since the whole point is supporting arbitrary publisher domains. Deferred, not silently dropped — see Security → URL-based fetching is explicitly deferred.
• S3 (or other remote/object) storage backend. The storage abstraction is designed for it from the start (see Storage), but v1 implements the local filesystem backend only.
• arXiv's OAI-PMH interface (oaipmh.arxiv.org/oai), a separate bulk/incremental metadata-harvesting protocol distinct from the export API v1 uses. It is not tied to any v1 capability — its intended purpose is "copying and synchronization of a complete set of arXiv metadata," not per-item lookup — but its arXiv metadata format does expose per-article license information the export API does not, which may make it useful later (e.g. to enrich fetch_metadata). Deferred until that use case is settled, not because of any technical blocker.
• Europe PMC's Annotations API (www.ebi.ac.uk/europepmc/annotations_api), which provides text-mined entity annotations per article (genes, chemicals, diseases, and similar, tagged to external ontologies). This would be a genuinely new, Europe-PMC-only capability with no arXiv equivalent, not a variant of anything in Architecture. Deferred until its licensing/attribution terms for annotation data (separate from the underlying article's own licensing) are confirmed, and until there's a concrete use case for PriorisMCP.
• list_top_n for Europe PMC. Unlike arXiv, Europe PMC has no single subject-classification field to list top items by — instead it exposes several parallel, multi-valued tagging/labelling schemes: KEYWORD/KW (free-text keywords), GOTERM/GOTERM_ID (Gene Ontology terms), DISEASE/DISEASE_ID, ORGANISM/ORGANISM_ID, EXPERIMENTAL_METHOD/EXPERIMENTAL_METHOD_ID, and PUB_TYPE (publication type). None of these is a like-for-like match for arXiv's single primary category, so v1 does not implement list_top_n for Europe PMC at all rather than force a mismatched mapping onto one of these fields. Revisit if a concrete use case emerges for listing by one of these tag axes (e.g. "top N by DISEASE").
• Storage retention/eviction. v1 persists fetched full text and parsed Markdown indefinitely (see Storage); there is no size- or time-based eviction. A size-based cap with LRU eviction (evicting least-recently-read entries once a configured disk quota is hit) is the intended future direction — see Storage → Future — since storage keys are content-addressed and immutable, so the problem is disk growth, not staleness. Deferred until there's a concrete need, not because of a technical blocker.
• Redistribution-policy-aware persistence. Distinct from retention above: whether persisted content may ever be shared beyond the MCP client that originally fetched it depends on each article's own licence, which v1 does not currently have full visibility into — Europe PMC's metadata already exposes a license field, but arXiv's Export API (what v1 uses) exposes no per-article licence at all; only the already-deferred OAI-PMH arXiv metadata format does (see above). Aligning persistence/redistribution behaviour with each source's stated terms is future work that depends on that OAI-PMH decision for arXiv, and could start sooner for Europe PMC given its existing license field.
• Persistent, cross-call adaptive rate-limit spacing. The provider request queue's backoff (see Non-functional requirements → Rate-limit breaches) resets to the base spacing at the start of every tool call rather than persisting a widened spacing across calls that gradually decays back down over a sustained run of successes. The simpler per-call reset was chosen as sufficient for v1 — it satisfies this SRS's rate-limiting requirements without introducing unverified cross-call state. A persistent, gradually-decaying queue-wide spacing remains a future consideration if repeated 429s across many calls in a short window turn out to need a more conservative, longer-memory response than per-call reset provides.
• Additional/alternative full-text parsing backends. The parser-backend interface (see Architecture → parse_full_text) is designed for pluggable, swappable backends per format from the start, but v1 ships exactly one backend per format. A slower, more sophisticated general-purpose document-parsing backend for PDF — trading speed for higher-fidelity structure recovery on complex layouts than v1's backend targets — and a boilerplate-removal-oriented backend for parsing arbitrary/messier HTML once a future non-arXiv source needs it (v1's HTML backend is chosen for arXiv's already-clean, structured HTML specifically, not general web content) are both named future options this abstraction is designed for. Deferred until either is a concrete need, not because of a technical blocker.

v2¶

The first capability built on top of v1's storage redesign rather than a v1 amendment — tracked as issue #13:

• NotesBackend. Server-side, single-user, document-level user-authored notes storage — a new abstraction, sibling to StorageBackend/SearchIndex rather than an extension of either. See Architecture → NotesBackend and Notes storage. Five new tools (research_notes_create/read/update/delete/search) and one resource (notes://{note_id}/export) — see Functional requirements → Notes tools.
• Out of scope for v2, tracked as future work beyond it: multi-user/hosted deployment of NotesBackend (a user_id dimension, a client-server backend implementation); migration of the prioris client plugin's existing .prioris/discussions/ local files (tracked in anirbanbasu/prioris#1, a separate repository); span-level note anchoring, rejected in favour of document-level identity — see Architecture → Anchoring for why; filtering/searching by metadata keys, or a general boolean query language over tags beyond must-have-all/must-have-any/must-have-none — see Notes storage → Data model; manual cross-document note relations — a note declaring a relationship to documents beyond its own primary one — see Notes storage → Future: cross-document notes and relations.

v3¶

• Discovery. research_discovery — embedding-based candidate discovery over external, not-yet-fetched research-publication metadata (OpenAlex search.semantic), plus a fetch ladder for routing/surfacing full text once a candidate is chosen. See Discovery.
• VectorSearchBackend. Embedding-based semantic search, layered on top of SearchIndex/NotesBackend — see Search → Vector search.

Assumptions and dependencies¶

• Provider availability. PriorisMCP depends on arXiv's and Europe PMC's APIs remaining available and stable in shape; an outage or breaking API change in either is an external dependency, not something this SRS specifies behaviour for beyond the error semantics already described per-capability (see Functional requirements).
• Consent for heavier operations rests with the MCP client. PriorisMCP assumes the calling MCP client (the LLM, or the human behind it) is the point where consent for a heavier operation is decided — e.g. parse_full_text failing explicitly rather than silently triggering fetch_full_text (see Architecture → parse_full_text) exists specifically so that decision point remains with the caller, not PriorisMCP.
• Content licensing is separate from rate-limit terms of use. The rate limits documented in References govern how often PriorisMCP may call arXiv/Europe PMC; they say nothing about the licensing terms attached to the content itself once fetched. arXiv and Europe PMC articles carry their own (often per-article) licences — some permissive, some not — governing redistribution of full text. v1 persists fetched full text indefinitely via the storage abstraction as a caching/de-duplication mechanism for the same MCP client that already fetched it; this SRS does not currently address longer-term redistribution of persisted content beyond that use — see Out of scope for v1 → Redistribution-policy-aware persistence — and this should be revisited before any feature that shares persisted content beyond the fetching client is considered.

Definitions and acronyms¶

References¶

• arXiv API user manual and its terms of use (rate limits apply).
• Europe PMC RESTful Web Service.

Document structure¶

• Architecture — provider groupings and the ResearchPublicationProvider interface; NotesBackend (v2).
• Storage — StorageBackend/NotesBackend, the two persistence abstractions, split into:
  • Document storage — the StorageBackend abstraction and its local-filesystem and (future) S3 implementations.
  • Notes storage — the NotesBackend abstraction, its data model, and its storage layout (v2).
• Discovery — embedding-based candidate discovery beyond arXiv/Europe PMC keyword search, and the fetch ladder for results that land outside them (v3).
• Search — the retrieval mechanisms over content already fetched into storage, split into:
  • Full-text search — SearchIndex, literal/lexical keyword matching (v1).
  • Vector search — VectorSearchBackend, embedding-based semantic search (v3).
• Functional requirements — the concrete tools/resources exposed for arXiv and Europe PMC in v1, and notes tools/the export resource in v2, in behavioural terms.
• Non-functional requirements — cross-cutting qualities, currently concurrency.
• Security — untrusted-identifier and untrusted-content requirements.
• Interface specification — exact MCP wire-level input/output schemas for every v1 and v2 tool/resource, grounded in the arXiv and Europe PMC APIs where applicable.
• Test specification — verification/acceptance criteria per capability, grounded in the interface specification's schemas.
• Architecture Decision Records — settled decisions with named rejected alternatives, extracted out of the chapters above so they stay lean; linked from wherever the underlying decision is used.