prioris-mcp 0.1.0__tar.gz

prioris_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PriorisMCP project contributors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

prioris_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: prioris-mcp
+Version: 0.1.0
+Summary: A model context protocol (MCP) server to facilitate looking up prior art.
+Keywords: python3,prior-art,research,literature-review,model-context-protocol-server,mcp-server
+Author: Anirban Basu
+Author-email: Anirban Basu <anirbanbasu@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: anyio>=4.14.2
+Requires-Dist: defusedxml>=0.7.1
+Requires-Dist: environs>=15.0.1
+Requires-Dist: fastmcp>=3.4.4
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: liteparse>=2.9.0
+Requires-Dist: lxml>=6.1.1
+Requires-Dist: markdownify>=1.2.3
+Requires-Python: >=3.13
+Project-URL: Repository, https://github.com/anirbanbasu/prioris-mcp
+Project-URL: Issues, https://github.com/anirbanbasu/prioris-mcp/issues
+Project-URL: Download, https://pypi.org/project/prioris-mcp/
+Description-Content-Type: text/markdown
+
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue?logo=python&logoColor=3776ab&labelColor=e4e4e4)](https://www.python.org/downloads/release/python-3130/) [![Documentation](https://github.com/anirbanbasu/prioris-mcp/actions/workflows/docs.yml/badge.svg)](https://github.com/anirbanbasu/prioris-mcp/actions/workflows/docs.yml) [![pytest](https://github.com/anirbanbasu/prioris-mcp/actions/workflows/uv-pytest-coverage.yml/badge.svg)](https://github.com/anirbanbasu/prioris-mcp/actions/workflows/uv-pytest-coverage.yml) [![PyPI](https://img.shields.io/pypi/v/prioris-mcp?label=pypi%20package)](https://pypi.org/project/prioris-mcp/#history) ![GitHub commits since latest release](https://img.shields.io/github/commits-since/anirbanbasu/prioris-mcp/latest) [![CodeQL Advanced](https://github.com/anirbanbasu/prioris-mcp/actions/workflows/codeql.yml/badge.svg)](https://github.com/anirbanbasu/prioris-mcp/actions/workflows/codeql.yml) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/anirbanbasu/prioris-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/anirbanbasu/prioris-mcp) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+# Prioris MCP
+
+A model context protocol (MCP) server to facilitate looking up prior art.
+
+Full documentation, including installation, configuration, and how to connect this server to Claude, is published at **[the documentation site](https://docs-prioris-mcp.anirbanbasu.com)**.
+
+# Contributing
+
+See the [Contributing guide](CONTRIBUTING.md).
+
+# License
+
+[MIT](https://choosealicense.com/licenses/mit/).

prioris_mcp-0.1.0/README.md

@@ -0,0 +1,15 @@
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue?logo=python&logoColor=3776ab&labelColor=e4e4e4)](https://www.python.org/downloads/release/python-3130/) [![Documentation](https://github.com/anirbanbasu/prioris-mcp/actions/workflows/docs.yml/badge.svg)](https://github.com/anirbanbasu/prioris-mcp/actions/workflows/docs.yml) [![pytest](https://github.com/anirbanbasu/prioris-mcp/actions/workflows/uv-pytest-coverage.yml/badge.svg)](https://github.com/anirbanbasu/prioris-mcp/actions/workflows/uv-pytest-coverage.yml) [![PyPI](https://img.shields.io/pypi/v/prioris-mcp?label=pypi%20package)](https://pypi.org/project/prioris-mcp/#history) ![GitHub commits since latest release](https://img.shields.io/github/commits-since/anirbanbasu/prioris-mcp/latest) [![CodeQL Advanced](https://github.com/anirbanbasu/prioris-mcp/actions/workflows/codeql.yml/badge.svg)](https://github.com/anirbanbasu/prioris-mcp/actions/workflows/codeql.yml) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/anirbanbasu/prioris-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/anirbanbasu/prioris-mcp) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+# Prioris MCP
+
+A model context protocol (MCP) server to facilitate looking up prior art.
+
+Full documentation, including installation, configuration, and how to connect this server to Claude, is published at **[the documentation site](https://docs-prioris-mcp.anirbanbasu.com)**.
+
+# Contributing
+
+See the [Contributing guide](CONTRIBUTING.md).
+
+# License
+
+[MIT](https://choosealicense.com/licenses/mit/).

prioris_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,137 @@
+[project]
+name = "prioris-mcp"
+version = "0.1.0"
+description = "A model context protocol (MCP) server to facilitate looking up prior art."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+authors = [
+    { name = "Anirban Basu", email = "anirbanbasu@users.noreply.github.com" }
+]
+keywords = ["python3", "prior-art", "research", "literature-review", "model-context-protocol-server", "mcp-server"]
+requires-python = ">=3.13"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "anyio>=4.14.2",
+    "defusedxml>=0.7.1",
+    "environs>=15.0.1",
+    "fastmcp>=3.4.4",
+    "httpx>=0.28.1",
+    "liteparse>=2.9.0",
+    "lxml>=6.1.1",
+    "markdownify>=1.2.3",
+]
+
+[project.scripts]
+prioris-mcp = "prioris_mcp.server:main"
+
+[project.urls]
+Repository = "https://github.com/anirbanbasu/prioris-mcp"
+Issues = "https://github.com/anirbanbasu/prioris-mcp/issues"
+Download = "https://pypi.org/project/prioris-mcp/"
+
+[build-system]
+requires = ["uv_build>=0.11.29,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "icecream>=2.1.8",
+    "ty>=0.0.1a29",
+]
+docs = [
+    "zensical>=0.0.51",
+]
+test = [
+    "coverage>=7.9.1",
+    "pytest>=8.4.1",
+]
+
+[tool.ty.rules]
+possibly-unresolved-reference = "warn"
+# Keyword argument expansion is not supported by ty yet? https://github.com/astral-sh/ty/issues/247
+invalid-argument-type = "ignore"
+
+[tool.ty.environment]
+python-version = "3.13"
+
+[tool.ruff]
+line-length = 120
+target-version = "py313"
+include = [
+    "src/prioris_mcp/**/*.py",
+    "tests/**/*.py",
+    "docs/**/*.py",
+]
+
+[tool.ruff.lint]
+extend-select = [
+    "Q",
+    "RUF100",
+    "RUF018", # https://docs.astral.sh/ruff/rules/assignment-in-assert/
+    "C90",
+    "UP",
+    "I",
+    "D",
+    "TID251",
+]
+# flake8-quotes = { inline-quotes = "single", multiline-quotes = "double" }
+mccabe = { max-complexity = 15 }
+ignore = [
+    "D100", # ignore missing docstring in module
+    "D102", # ignore missing docstring in public method
+    "D104", # ignore missing docstring in public package
+    "D105", # ignore missing docstring in magic methods
+    "D107", # ignore missing docstring in __init__ methods
+]
+
+[tool.ruff.lint.isort]
+combine-as-imports = true
+known-first-party = ["prioris-mcp"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+# don't format python in docstrings, pytest-examples takes care of it
+docstring-code-format = false
+# quote-style = "single"
+
+[tool.coverage.run]
+omit = [
+    "tests/*", # Excludes all files and subdirectories within a 'tests' directory at the project root
+]
+
+[tool.coverage.report]
+fail_under = 100
+skip_covered = true
+show_missing = true
+ignore_errors = true
+precision = 2
+exclude_lines = [
+    # `# pragma: no cover` is standard marker for code that's not covered, this will error if code is covered
+    'pragma: no cover',
+    # use `# pragma: lax no cover` if you want to ignore cases where (some of) the code is covered
+    'pragma: lax no cover',
+    'raise NotImplementedError',
+    'if TYPE_CHECKING:',
+    'if typing.TYPE_CHECKING:',
+    '@overload',
+    '@deprecated',
+    '@typing.overload',
+    '@abstractmethod',
+    '\(Protocol\):$',
+    'typing.assert_never',
+    '$\s*assert_never\(',
+    'if __name__ == .__main__.:',
+    'except ImportError as _import_error:',
+    '$\s*pass$',
+    'assert False',
+]

prioris_mcp-0.1.0/src/prioris_mcp/__init__.py

@@ -0,0 +1,89 @@
+import logging
+import os
+from pathlib import Path
+
+from environs import Env
+from marshmallow.validate import OneOf, Range
+from rich.logging import RichHandler
+
+PACKAGE_NAME = "prioris-mcp"
+env = Env()
+env.read_env()
+
+
+class EnvVars:
+    """Environment variables for Prioris MCP configuration."""
+
+    PRIORIS_MCP_ASGI_CORS_ALLOWED_ORIGINS = env.list(
+        "PRIORIS_MCP_ASGI_CORS_ALLOWED_ORIGINS",
+        # Default is restricted to localhost, not a wildcard: a wildcard origin lets any webpage's
+        # JavaScript read this server's responses, not just tools actually served from localhost.
+        # Override explicitly (e.g. to "*") for tools that need it, such as the MCP Inspector.
+        default=["http://localhost", "http://127.0.0.1"],
+    )
+
+    PRIORIS_MCP_HOST = env.str("PRIORIS_MCP_HOST", default="localhost")
+    PRIORIS_MCP_PORT = env.int(
+        "PRIORIS_MCP_PORT", default=8000, validate=Range(min=1024, max=49151)
+    )  # Valid port range is 1024-49151 for non-privileged ports
+
+    PRIORIS_MCP_LOG_LEVEL = env.str(
+        "PRIORIS_MCP_LOG_LEVEL",
+        default="INFO",
+        validate=OneOf(["NOTSET", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]),
+    ).upper()
+
+    PRIORIS_MCP_TRANSPORT: str = env.str(
+        name="PRIORIS_MCP_TRANSPORT",
+        default="stdio",
+        validate=OneOf(["stdio", "streamable-http", "http"]),
+    )
+
+    PRIORIS_MCP_RESPONSE_CACHE_TTL: int = env.int(
+        name="PRIORIS_MCP_RESPONSE_CACHE_TTL",
+        default=30,  # in seconds
+        validate=Range(min=0, max=86400),  # 0 seconds to 1 day where 0 means caching is disabled
+    )
+
+    PRIORIS_MCP_UNVERIFIED_HTTPS: bool = env.bool(
+        name="PRIORIS_MCP_UNVERIFIED_HTTPS",
+        default=False,  # By default, HTTPS requests are verified; override in development for testing
+    )
+
+    _default_data_home = Path(os.environ.get("XDG_DATA_HOME") or (Path.home() / ".local" / "share"))
+
+    PRIORIS_MCP_STORAGE_DIR = env.path(
+        "PRIORIS_MCP_STORAGE_DIR",
+        # Data, not configuration, hence XDG_DATA_HOME (not XDG_CONFIG_HOME) - see
+        # docs/requirement-specification/02-storage.md.
+        default=_default_data_home / "prioris-mcp" / "downloads",
+    )
+
+    PRIORIS_MCP_RATE_LIMIT_BACKOFF_BUDGET_SECONDS = env.float(
+        "PRIORIS_MCP_RATE_LIMIT_BACKOFF_BUDGET_SECONDS",
+        # Total time a single tool call's rate-limit backoff may spend retrying before giving up
+        # with `rate_limited` - see docs/requirement-specification/04-non-functional-requirements.md.
+        default=60.0,
+        validate=Range(min=0, max=3600),
+    )
+
+    # Clamped to the host's CPU count even if the environment variable requests more: this bounds
+    # concurrently-*executing* JATS transforms (not just concurrently-awaited ones) against
+    # unbounded resource use from abandoned, still-running transforms - see
+    # docs/requirement-specification/05-security.md#a-bounded-per-call-failure-is-not-sufficient-on-its-own.
+    PRIORIS_MCP_JATS_MAX_CONCURRENT_TRANSFORMS = min(
+        env.int(
+            "PRIORIS_MCP_JATS_MAX_CONCURRENT_TRANSFORMS",
+            default=min(4, os.cpu_count() or 4),
+            validate=Range(min=1),
+        ),
+        os.cpu_count() or 4,
+    )
+
+
+logging.basicConfig(
+    level=EnvVars.PRIORIS_MCP_LOG_LEVEL,
+    format="%(message)s",
+    datefmt="[%X]",
+    handlers=[RichHandler(rich_tracebacks=False, markup=True, show_path=False, show_time=False)],
+)

prioris_mcp-0.1.0/src/prioris_mcp/errors.py

@@ -0,0 +1,75 @@
+"""Shared error types and the tool-level `{"error": ..., "message": ...}` envelope.
+
+See docs/requirement-specification/06-interface-specification.md#conventions for the envelope
+shape and the codes below - every `research_*` tool method returns this envelope on failure
+instead of letting an exception cross the MCP protocol boundary as a raw error.
+"""
+
+from collections.abc import Awaitable
+from typing import Any
+
+from prioris_mcp.rate_limit import ProviderUnavailableError, RateLimitedError
+
+
+class NotFoundError(Exception):
+    """Identifier not recognised by the provider, or requested format not yet persisted.
+
+    Maps to the `not_found` error code.
+    """
+
+
+class FormatUnavailableError(Exception):
+    """Identifier is valid but does not offer the requested format.
+
+    Maps to the `format_unavailable` error code.
+    """
+
+
+class UnsupportedProviderError(Exception):
+    """A DOI resolved to a domain outside the v1 provider allowlist.
+
+    Maps to the `unsupported_provider` error code.
+    """
+
+
+class InvalidRequestError(Exception):
+    """Caller-supplied arguments fail a provider's own validation before any outbound call.
+
+    Maps to the `invalid_request` error code.
+    """
+
+
+_ERROR_CODES: dict[type[Exception], str] = {
+    NotFoundError: "not_found",
+    FormatUnavailableError: "format_unavailable",
+    UnsupportedProviderError: "unsupported_provider",
+    InvalidRequestError: "invalid_request",
+    RateLimitedError: "rate_limited",
+    ProviderUnavailableError: "provider_unavailable",
+}
+
+
+def to_error_envelope(exc: Exception) -> dict[str, str]:
+    """Convert one of the mapped exception types into the tool-level error envelope.
+
+    Raises:
+        TypeError: `exc` isn't one of the mapped types - an unmapped exception is a bug in the
+            calling tool method (it should not have been caught), not a case to paper over with
+            a generic error code.
+    """
+    for exc_type, code in _ERROR_CODES.items():
+        if isinstance(exc, exc_type):
+            return {"error": code, "message": str(exc)}
+    raise TypeError(f"No error code mapped for exception type {type(exc).__name__}")
+
+
+async def call_returning_envelope(coro: Awaitable[dict[str, Any]]) -> dict[str, Any]:
+    """Await `coro`, converting any mapped exception into the error envelope instead of raising.
+
+    Every `research_*` tool method on `PriorisMCP` wraps its provider call with this, so the
+    try/except-to-envelope translation is written once, not once per tool.
+    """
+    try:
+        return await coro
+    except tuple(_ERROR_CODES.keys()) as exc:
+        return to_error_envelope(exc)

prioris_mcp-0.1.0/src/prioris_mcp/middleware.py

@@ -0,0 +1,82 @@
+import logging
+import time
+from importlib.metadata import PackageMetadata, metadata as importlib_metadata
+from typing import ClassVar
+
+from fastmcp.server.middleware import Middleware
+
+from prioris_mcp import PACKAGE_NAME
+
+logger = logging.getLogger(__name__)
+
+
+class StripUnknownArgumentsMiddleware(Middleware):
+    """Middleware to strip unknown arguments from MCP feature invocations."""
+
+    async def on_call_tool(self, context, call_next):
+        """Filter out unknown arguments from tool calls."""
+        try:
+            # Only proceed if this is a tool call with non-zero arguments
+            if context.fastmcp_context and context.message.arguments and len(context.message.arguments) > 0:
+                tool = await context.fastmcp_context.fastmcp.get_tool(context.message.name)
+                tool_args = tool.parameters.get("properties", None)
+                expected_args_names = set(tool_args.keys()) if tool_args else set()
+                filtered_args = {k: v for k, v in context.message.arguments.items() if k in expected_args_names}
+                unknown_args = set(context.message.arguments.keys()).difference(expected_args_names)
+                if unknown_args:
+                    logger.info(f"Unknown arguments for tool '{context.message.name}': {list(unknown_args)}")
+                context.message.arguments = filtered_args  # modify in place
+        except Exception:  # pragma: no cover
+            logger.exception(
+                f"Error in {StripUnknownArgumentsMiddleware.__name__}.on_call_tool",
+                stack_info=True,
+            )
+        return await call_next(context)
+
+
+class ResponseMetadataMiddleware(Middleware):
+    """Middleware to add metadata to MCP responses."""
+
+    _package_metadata: ClassVar[PackageMetadata] = importlib_metadata(PACKAGE_NAME)
+    PACKAGE_METADATA_KEY: ClassVar[str] = "_package_metadata"
+    TIMING_METADATA_KEY: ClassVar[str] = "_timing_metadata"
+
+    async def _time_operation(self, context, call_next, operation_name: str):
+        """Helper method to time any operation."""
+        # Based on: https://github.com/jlowin/fastmcp/blob/ee6340526216c7796000c69ef3b9001a1a6f31a3/src/fastmcp/server/middleware/timing.py#L91C5-L109C18
+        start_time = time.perf_counter()
+        try:
+            result = await call_next(context)
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            logger.debug(f"{operation_name} completed in {duration_ms:.2f}ms")
+            return result, duration_ms
+        except Exception as e:
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            logger.warning(
+                f"{operation_name} failed after {duration_ms:.2f}ms: {e}",
+            )
+            raise
+
+    async def on_call_tool(self, context, call_next):
+        """Add metadata to tool responses."""
+        # There is no support for top-level metadata for prompts or resources yet.
+        # Do not encapsulate this in a try-except; let errors propagate
+        feature_name = getattr(context.message, "name", "unknown")
+        result, duration_ms = await self._time_operation(context, call_next, f"Tool '{feature_name}'")
+
+        if result is None:  # pragma: no cover
+            # Isn't this an impossible scenario?
+            return result
+        if getattr(result, "meta", None) is None:
+            result.meta = {}  # pragma: no cover
+        result.meta[ResponseMetadataMiddleware.PACKAGE_METADATA_KEY] = {
+            "name": ResponseMetadataMiddleware._package_metadata["name"],
+            "version": ResponseMetadataMiddleware._package_metadata["version"],
+        }
+        result.meta[ResponseMetadataMiddleware.TIMING_METADATA_KEY] = {
+            "tool_response_time_ms": duration_ms,
+        }
+        logger.debug(
+            f"Added package metadata to tool response: {result.meta[ResponseMetadataMiddleware.PACKAGE_METADATA_KEY]}"
+        )
+        return result

prioris_mcp-0.1.0/src/prioris_mcp/mixin.py

@@ -0,0 +1,71 @@
+import copy
+import logging
+from typing import Any, ClassVar
+
+from fastmcp import FastMCP
+from fastmcp.tools import ToolResult
+
+logger = logging.getLogger(__name__)
+
+
+class MCPMixin:
+    """A mixin class to register tools, resources, and prompts with a FastMCP instance."""
+
+    # Each entry is a dict, must include "fn" (method name),
+    # rest is arbitrary metadata relevant to FastMCP.
+    tools: ClassVar[list[dict[str, Any]]] = []
+    # Each entry is a dict, must include "fn" (method name) and "uri",
+    # rest is arbitrary metadata relevant to FastMCP.
+    resources: ClassVar[list[dict[str, Any]]] = []
+    # Each entry is a dict, must include "fn" (method name),
+    # rest is arbitrary metadata relevant to FastMCP.
+    prompts: ClassVar[list[dict[str, Any]]] = []
+
+    def register_features(self, mcp: FastMCP) -> FastMCP:
+        """Register tools, resources, and prompts with the given FastMCP instance.
+
+        Args:
+            mcp (FastMCP): The FastMCP instance to register features with.
+
+        Returns:
+            FastMCP: The FastMCP instance with registered features.
+        """
+        # Register tools
+        for tool in self.tools:
+            assert "fn" in tool, "Tool metadata must include the 'fn' key."
+            tool_copy = copy.deepcopy(tool)
+            fn_name = tool_copy.pop("fn")
+            fn = getattr(self, fn_name)
+            mcp.tool(**tool_copy)(fn)  # pass remaining metadata as kwargs
+        # Register resources
+        for res in self.resources:  # pragma: no cover
+            assert "fn" in res and "uri" in res, "Resource metadata must include 'fn' and 'uri' keys."
+            res_copy = copy.deepcopy(res)
+            fn_name = res_copy.pop("fn")
+            uri = res_copy.pop("uri")
+            fn = getattr(self, fn_name)
+            mcp.resource(uri, **res_copy)(fn)
+        # Register prompts
+        for pr in self.prompts:  # pragma: no cover
+            assert "fn" in pr, "Prompt metadata must include the 'fn' key."
+            pr_copy = copy.deepcopy(pr)
+            fn_name = pr_copy.pop("fn")
+            fn = getattr(self, fn_name)
+            mcp.prompt(**pr_copy)(fn)
+
+        return mcp
+
+    def get_tool_result(self, result: Any, metadata: dict[str, Any] | None = None) -> ToolResult:  # pragma: no cover
+        """Create a ToolResult object with the given result and metadata, including package metadata.
+
+        Args:
+            result (Any): The result to include in the ToolResult.
+            metadata (Dict[str, Any] | None, optional): Additional metadata to include. Defaults to None.
+
+        Returns:
+            ToolResult: The ToolResult object containing the result and metadata.
+        """
+        return ToolResult(
+            structured_content={"result": result} if not isinstance(result, dict) else result,
+            meta=metadata if metadata is not None else None,
+        )

prioris_mcp-0.1.0/src/prioris_mcp/parsers/base.py

@@ -0,0 +1,30 @@
+"""Pluggable parser-backend interface: converts persisted full text into Markdown.
+
+See docs/requirement-specification/01-architecture.md#parse_full_text - one backend per source
+format, swappable by configuration without changing this interface, mirroring
+`StorageBackend`'s interface-plus-swappable-implementation shape.
+"""
+
+from abc import ABC, abstractmethod
+
+
+class ParseError(Exception):
+    """A source document could not be converted to Markdown.
+
+    Covers both malformed input and a backend-enforced resource bound being exceeded - see
+    docs/requirement-specification/05-security.md#fetched-content-is-untrusted-input-to-parse_full_text.
+    Callers treat both the same way: a bounded, typed failure, not a crash or a hang.
+    """
+
+
+class ParserBackend(ABC):
+    """Converts one source format's raw bytes into a Markdown string."""
+
+    @abstractmethod
+    async def to_markdown(self, content: bytes) -> str:
+        """Convert `content` to Markdown.
+
+        Raises:
+            ParseError: the content is malformed, or parsing exceeded this backend's own
+                resource bound (size/time).
+        """