MARE 0.4.8 — Remote MCP Hardening and Evaluation

MARE 0.4.8

MARE 0.4.8 is the Remote MCP Hardening and Evaluation release.

This patch release secures MARE's remote MCP document-access paths, adds continuous integration across supported Python versions, and expands retrieval evaluation with rank-aware and latency metrics.

Security

• Reject URL ingestion targets that resolve to private, loopback, link-local, or reserved network addresses.
• Revalidate redirected URL targets before accepting downloaded content.
• Reject credential-bearing URLs.
• Apply a 20-second download timeout and a 25 MiB size limit.
• Verify downloaded content has a PDF signature before writing it.
• Restrict remote MCP local-file access to the server working directory.
• Use path-aware containment checks when serving proof assets.

Evaluation

• Added Recall@k and mean reciprocal rank to evaluation summaries and stack comparisons.
• Added first-relevant-rank and reciprocal-rank details per query.
• Added average retrieval latency reporting.
• Included rank-aware evidence metrics in stack recommendations.

Reliability

• Added GitHub Actions CI for Python 3.9 through 3.13.
• Added package build, metadata validation, and wheel installation smoke tests on every push and pull request.

MARE 0.4.7 — Superseded by 0.4.8

MARE 0.4.7

Superseded by MARE 0.4.8. Use 0.4.8 or newer. The follow-up release includes everything in 0.4.7 plus remote MCP hardening, CI, and expanded evaluation.

MARE 0.4.7 is the Evidence Quality and Provenance release.

This release makes MARE's agent-facing evidence easier to evaluate, reference, and audit. Evidence Briefs now expose explicit quality checks, and retrieved evidence carries stable identifiers and provenance metadata that survive structured workflow and agent handoffs.

Highlights

• Added structured evidence_quality signals to Evidence Briefs.
• Added checks for support strength, source diversity, proof availability, citation completeness, and table-grounding precision.
• Added compact evidence-quality output to mare workflow, mare chat, mare ui, and evaluation reports.
• Added quality-aware rescue behavior so alternate retrieval attempts are accepted only when they improve the evidence assessment.
• Added stable evidence_id values derived from source and evidence provenance rather than result rank.
• Added structured provenance metadata to serialized evidence results.
• Added top_provenance to Evidence Briefs for fast agent inspection.
• Propagated provenance through workflow payloads, reviews, MCP tools, and integration adapters.
• Expanded regression coverage for evidence quality, provenance stability, and cross-surface payload consistency.

Why It Matters

Agentic retrieval needs more than a relevance score. An agent must know whether evidence is sufficiently supported, whether proof is inspectable, and whether the same evidence can be referenced reliably across retries and downstream actions.

With evidence-quality checks and stable provenance IDs, MARE clients can:

• inspect why an evidence set is considered strong or weak
• decide whether to answer, retrieve again, or request another source
• preserve evidence references when result ordering changes
• attach audit-friendly provenance to agent decisions
• evaluate retrieval improvements using the same trust signals exposed to users

This keeps MARE focused on its core role: the inspectable document-evidence layer beneath agents and grounded document workflows.

MARE 0.4.6

MARE 0.4.6

MARE 0.4.6 is the Agentic Evidence Planning release.

The market is moving from single-shot RAG toward agentic, multi-step retrieval that can prove what it found, decide when evidence is insufficient, and keep an audit trail of follow-up searches. This release moves MARE in that direction while keeping the base package lightweight and deterministic.

Highlights

• Added research_plan to Evidence Brief payloads.
• Research plans include:
  • a status such as ready, needs_evidence, needs_stronger_support, needs_source_check, or needs_conflict_check
  • a short rationale
  • concrete next retrieval steps with action names, queries, and reasons
• Added attempt-level audit trails to workflow evidence rescue.
• Evidence rescue now records each alternate query, support assessment, result count, top citation, top score, and whether that attempt improved support.
• Added top-level agent_contract payloads for Python, MCP query tools, and workflow JSON.
• Agent contracts include may_answer, recommended_action, stop_reasons, support/source/research statuses, and the research plan.
• Added mare workflow --task contract for a compact terminal action-contract view.
• Added :contract to mare chat.
• Surfaced research-plan status and steps in mare workflow --task brief.
• Surfaced agent actions and research-plan status in workflow review/answer views and mare chat.
• Surfaced research-plan status and steps in the Streamlit playground Evidence Brief panel.
• Added an Agent Contract panel to the Streamlit playground.

Why It Matters

MARE already explains the trust shape of retrieved evidence. The next useful step is telling a human or agent what to do with that trust signal.

With research plans and audited rescue attempts, agent clients can now:

• answer when evidence is ready
• retrieve stronger support when evidence is weak
• compare sources when coverage is narrow
• resolve conflict signals before acting
• inspect exactly which rescue searches were attempted
• read one compact action contract before deciding whether to answer or continue retrieval

That keeps MARE focused on grounded document work rather than generic chat behavior.

MARE 0.4.5

MARE 0.4.5

MARE 0.4.5 is the Evidence Brief release.

This release sharpens MARE's public position as a grounded document evidence layer for agents and developers. Instead of only returning a best match, MARE can now explain the trust shape of a retrieval result: source coverage, support strength, conflict hints, proof assets, evidence gaps, and next questions.

Highlights

• Added Evidence Brief payloads with:
  • support status and message
  • source coverage status and message
  • source count and source documents
  • available proof assets such as snippet, citation, page image, and highlight
  • deterministic conflict hints for obvious language mismatches such as required vs optional
  • evidence gaps
  • next evidence-seeking questions
• Added mare workflow --task brief.
• Added evidence rescue in workflow and chat: weak or missing initial support now triggers deterministic alternate evidence-seeking queries, and the payload/history records whether stronger proof was found.
• Added optional FastEmbed semantic retrieval as a lighter ONNX-based first-stage retriever, with smart defaults and the Streamlit selector able to use it when mare-retrieval[fastembed] is installed.
• Added fastembed to mare-eval --stack so teams can compare built-in, FastEmbed, hybrid, and sentence-transformers retrieval on their own cases.
• Added eval comparison recommendations that rank stacks and name the best retrieval choice for the current eval set.
• Added experimental ColPali/ColQwen visual page retrieval behind mare-retrieval[colpali], with Streamlit and eval-stack selection for rendered PDF page images.
• Added --retriever selection to mare workflow and mare chat for smart, built-in, FastEmbed, hybrid, sentence-transformers, and experimental ColPali visual retrieval stacks.
• Added a clear ColPali visual-retrieval setup message when a corpus has no rendered PDF page images.
• Added :brief to mare chat.
• Added an Evidence Brief section to the Streamlit playground.
• Added examples/evidence_brief_demo.py.
• Added AGENT_INTEGRATIONS.md with OpenClaw, Hermes Agent, shell-tool, MCP, and Python wrapper recipes.
• Updated mare start to lead with the trust-first Evidence Brief flow.
• Updated README and package metadata around the document evidence layer positioning.
• Added LAUNCH_PLAN.md for public launch messaging and channel planning.

Trust-First Demo

From a repo checkout:

mare workflow --folder ./examples/mixed_docs --query "show me the onboarding steps" --task brief

Or:

PYTHONPATH=src python3 examples/evidence_brief_demo.py

Why It Matters

Agentic document workflows need more than confident answers. They need inspectable evidence before an agent, developer, or user trusts the result.

Evidence Briefs make that explicit:

• What supports this answer?
• How strong is the support?
• Is the evidence concentrated in one source or spread across sources?
• Are there obvious conflict-language signals?
• Which proof assets exist?
• What is missing?
• What should I ask next?

That keeps MARE centered on grounded usefulness rather than generic document chat.

v0.4.4: Guided Onboarding and Grounded Review Workflows

MARE v0.4.4

MARE v0.4.4 focuses on adoption and lightweight document work.

This release makes the product easier to start and more useful once users are inside:

• better first-run guidance across CLI and UI
• a new mare start entrypoint
• grounded extraction workflows for actions, requirements, risks, and deadlines

Highlights

• Added a new guided first-run command:
  • mare start
  • mare start ./examples/mixed_docs
  • mare start ./docs
• Improved top-level CLI help so MARE is presented as a mixed-document, folder-first product instead of a PDF-only workflow.
• Improved the Streamlit playground first-run experience with:
  • a clearer “Start Here” panel
  • stronger empty-state guidance
  • better starter prompts for real document work
• Added grounded extraction payloads for:
  • actions
  • requirements
  • risks
  • deadlines
• Added new mare chat commands:
  • :actions
  • :requirements
  • :risks
  • :deadlines
• Added new mare workflow --task ... views:
  • --task actions
  • --task requirements
  • --task risks
  • --task deadlines
  • plus --task compare and --task summary for cleaner terminal evaluation

Why this release matters

Earlier releases made MARE’s evidence engine broader and more honest.

v0.4.4 turns that engine into something users can adopt faster:

• new users can understand the first run in seconds
• operators can ask for actions instead of only retrieval
• policy and compliance reviews can surface deadlines, risks, and requirement language with citations
• the same evidence can now be consumed as human-readable task views or structured payloads

The product shape stays consistent:

documents -> grounded retrieval -> proof -> concrete document-work output

Example commands

Start here:

mare start
mare start ./examples/mixed_docs

Chat:

mare chat --folder ./docs
:actions onboarding tasks
:requirements vendor obligations
:risks battery safety warnings
:deadlines renewal dates

Workflow:

mare workflow --folder ./docs --query "vendor obligations" --task requirements
mare workflow --folder ./docs --query "training deadlines" --task deadlines

Notes

• JSON evidence payloads now include a findings block with grounded extractions.
• This release continues to prefer inspectable proof over free-form unsupported generation.
• PDFs still provide the strongest visual proof flow, while mixed-document extraction now feels more productized across terminal and UI surfaces.

MARE v0.4.3

MARE v0.4.3

MARE v0.4.3 builds on the product cleanup in v0.4.2 and makes the public package match the repo's newer document and agent workflows more honestly.

This release is about tightening the real product story:

• grounded retrieval across more than just PDFs
• better mixed-document local workflows
• stronger agent-facing proof delivery over MCP
• cleaner public examples and release packaging

Highlights

• Expanded first-pass local document support beyond PDFs:
  • pdf
  • md / markdown
  • txt
  • docx
• Added mixed-document local workflows:
  • mare chat --folder ./examples/mixed_docs
  • mare workflow --folder ./examples/mixed_docs --query "..."
  • examples/mixed_docs_workflow.py
• Added public mixed-document sample content in examples/mixed_docs/ for repeatable demos and tests.
• Improved local folder discovery for mare chat and mare workflow so mixed document trees work more naturally.
• Expanded object extraction and evidence handling for markdown, text, and docx-backed corpora.
• Improved Streamlit UI stability and public-facing copy:
  • safer missing-image handling
  • clearer document upload story
  • cleaner developer playground notebook examples
• Improved MCP evidence delivery for agents and remote app clients:
  • ingest_document
  • query_document
  • best_evidence
  • proof_assets
  • primary_proof_asset
  • proof_links
  • public page/highlight asset URLs when mare mcp is started with a public base URL
• Cleaned the public repo boundary:
  • better separation of local artifacts vs public examples
  • packaging now includes the shipped example scripts and mixed-document samples

Why this release matters

v0.4.2 made MARE feel more like one product.

v0.4.3 makes that product story more truthful:

• MARE is no longer only a PDF-shaped local workflow
• the repo now ships runnable mixed-document examples
• the MCP layer is better suited to agent workflows that need grounded proof, not just snippets

The core model stays the same:

user or agent -> MARE -> citation + snippet + proof

What changed is the breadth and polish of the surfaces around that loop.

Install

pip install mare-retrieval

UI:

pip install "mare-retrieval[ui]"
mare ui

MCP:

pip install "mare-retrieval[mcp]"
mare mcp

Mixed-document example:

mare chat --folder ./examples/mixed_docs

Notes

• Python import remains import mare
• GitHub repo remains MARE
• PyPI distribution name remains mare-retrieval
• PDFs still provide the strongest visual proof experience
• markdown, text, and docx are now part of the public local workflow story
• mare mcp remains the main protocol-facing integration surface for agents and app platforms

Docs

• GitHub: https://github.com/mare-retrieval/MARE
• PyPI: https://pypi.org/project/mare-retrieval/

v0.4.2

MARE v0.4.2

MARE v0.4.2 turns the project into a more cohesive product surface.

This release is about making MARE easier to understand, easier to try, and easier to treat like one system instead of a set of disconnected entrypoints.

Highlights

• Added a unified product CLI:
  • mare --help
  • mare ui
  • mare chat
  • mare ask
  • mare workflow
  • mare ingest
  • mare eval
  • mare mcp
• Added a simple document-agent experience:
  • mare chat --folder ./docs
  • ask questions over a folder of PDFs
  • get source file, page, snippet, highlight path, and retrieval reason
• Made the visual playground easier to launch:
  • mare ui
  • no need to remember the raw Streamlit command
• Improved first-run onboarding and landing-page clarity:
  • one-product README structure
  • visual-first quickstart
  • clearer “which interface should I use?” guidance
  • clearer generated evidence file locations
• Improved MCP/Create App readiness:
  • remote MCP transport support
  • compatibility with older FastMCP SDK signatures
  • host/origin allowlist support for tunneled testing
  • URL-based PDF MCP tools:
    • ingest_pdf_url
    • query_pdf_url

Why this release matters

Earlier releases made MARE technically stronger.

v0.4.2 makes MARE feel more like a product:

• one front door
• one mental model
• multiple usage modes on top of the same evidence-first engine

The intended shape is now much clearer:

mare
  -> ui
  -> chat
  -> workflow
  -> mcp

That means new users can understand MARE faster, while developers and agent builders still get the deeper integration layers underneath.

Install

pip install mare-retrieval

Visual playground:

pip install "mare-retrieval[ui]"
mare ui

Simple document-agent loop:

mare chat --folder ./docs

Notes

• Python import remains import mare
• GitHub repo remains MARE
• PyPI distribution name remains mare-retrieval
• mare ui and mare chat are now the clearest first-use entrypoints
• mare mcp remains the protocol-facing integration path for agent platforms and remote app workflows

Docs

• GitHub: https://github.com/mare-retrieval/MARE
• PyPI: https://pypi.org/project/mare-retrieval/

v0.4.1

MARE v0.4.1

MARE v0.4.1 is a focused follow-up release that tightens the agent and app integration story introduced in v0.4.0.

The goal of this release is simple:

• make MCP usage clearer for developers
• make remote MCP deployment more practical
• make ChatGPT/Create App style integrations less brittle
• keep the human-facing and agent-facing entrypoints easier to evaluate

Highlights

• Added a human-friendly workflow CLI:
  • mare-workflow
  • supports single-PDF, corpus, and multi-PDF evaluation
  • supports pretty terminal output and structured JSON payloads
• Improved mare-mcp usability:
  • clearer guidance when run interactively
  • safer stdio messaging
  • remote MCP transport support
• Added compatibility fixes for older FastMCP SDK versions:
  • older run() signatures
  • older streamable HTTP transport behavior
• Added remote host/origin allowlist support for tunneling and remote MCP testing
  • useful for ngrok and similar workflows
• Added URL-based MCP PDF tools for remote app platforms:
  • ingest_pdf_url
  • query_pdf_url
  • lets the MARE server fetch PDFs over HTTP(S) instead of depending on local file paths from another runtime
• Improved MCP and publishing docs:
  • clearer interface guidance for mare-ui, mare-workflow, and mare-mcp
  • clearer PyPI trusted publisher setup guidance

Why this release matters

v0.4.0 established MARE as a stronger PDF evidence layer for developers and agents.

v0.4.1 makes that layer easier to:

• test locally
• expose remotely
• connect to app platforms
• evaluate in a more enterprise-friendly way

The core idea stays the same:

user question -> agent/app -> MARE -> page + snippet + highlight + proof

This release improves the operational path around that architecture.

Install

pip install mare-retrieval

Useful extras:

pip install "mare-retrieval[ui]"
pip install "mare-retrieval[mcp]"

Notes

• Python import remains import mare
• GitHub repo remains MARE
• PyPI distribution name remains mare-retrieval
• mare-workflow is now the recommended terminal entrypoint for human and enterprise evaluation
• mare-mcp remains the protocol-facing entrypoint for MCP-capable clients and remote app integrations

Docs

• GitHub: https://github.com/mare-retrieval/MARE
• PyPI: https://pypi.org/project/mare-retrieval/

v0.4.0

MARE v0.4.0

MARE is an evidence-first PDF retrieval library for developers and agents.

This release is the point where MARE starts to feel like a real PDF evidence layer rather than only a single-document retrieval demo. The core built-in path is stronger, the agent story is much clearer, and the library can now work across multiple PDFs while preserving grounded page/snippet/highlight output.

Highlights

• Sharpened product positioning around:
  • evidence-first PDF retrieval
  • page, snippet, highlight, and visual proof
  • developer and agent workflows
• Added a first MCP server layer for agents
  • mare-mcp
  • ingest_pdf
  • query_pdf
  • query_corpus
  • query_corpora
  • page_objects
  • describe_corpus
  • search_objects
• Added agent-oriented workflow examples
  • examples/agent_workflow.py
  • examples/multi_pdf_workflow.py
  • examples/mcp_stdio_config.json
• Added hybrid semantic retrieval that preserves MARE's lexical/object-aware evidence behavior
• Added object-level semantic matching inside the hybrid retriever
• Improved semantic retrieval so it preserves MARE evidence outputs such as:
  • snippet
  • object type
  • highlight
• Added corpus introspection and object browsing
  • app.describe_corpus()
  • app.search_objects(...)
• Added multi-PDF retrieval support
  • MAREApp.from_corpora(...)
  • load_corpora(...)
  • MCP query_corpora
• Upgraded the Streamlit playground
  • recommended default stack messaging
  • advanced stack visibility
  • stale-result protection
  • multi-PDF upload and retrieval
• Improved object highlight precision
  • line-aware region metadata for built-in extraction
  • bbox-aware highlighting when richer parsers provide coordinates
  • better region fallback behavior for figures, tables, and sections
• Added stack comparison mode to the eval harness
• Added real benchmark examples for:
  • manuals
  • Apple support docs
  • research papers

Why this release matters

MARE is now much closer to the intended architecture:

user question -> agent/app -> MARE -> page + snippet + highlight + proof

The built-in stack remains the recommended default, while advanced integrations now fit more cleanly as optional infrastructure around the evidence-first core.

Install

pip install mare-retrieval

Useful extras:

pip install "mare-retrieval[ui]"
pip install "mare-retrieval[mcp]"
pip install "mare-retrieval[sentence-transformers]"
pip install "mare-retrieval[faiss]"
pip install "mare-retrieval[integrations]"

Notes

• Python import remains import mare
• GitHub repo remains MARE
• PyPI distribution name remains mare-retrieval
• the built-in retrieval path is still the recommended default for most users

Docs

• GitHub: https://github.com/mare-retrieval/MARE
• PyPI: https://pypi.org/project/mare-retrieval/

v0.3.0

MARE v0.3.0

MARE is a Python library for evidence-first PDF retrieval.

This release is a meaningful upgrade over the initial PyPI baseline. It moves MARE from a simple page-retrieval package toward a more extensible retrieval foundation for documents and developer workflows.

Highlights

• Added highlighted evidence images for retrieved results
• Added object-aware retrieval for procedures, sections, figures, and tables
• Improved manual-oriented procedure retrieval with heading-aware grouping
• Added stronger figure and table extraction foundations
• Added region-level fallback highlighting for non-text objects
• Added a more polished Streamlit demo experience
• Added developer extension points via MAREConfig
• Added pluggable parser, retriever, and reranker interfaces
• Added open-source integrations:
  • DoclingParser
  • UnstructuredParser
  • FastEmbedReranker
  • QdrantHybridRetriever
• Added an advanced-stack example in examples/advanced_stack.py

Install

pip install mare-retrieval

Optional extras:

pip install "mare-retrieval[ui]"
pip install "mare-retrieval[docling]"
pip install "mare-retrieval[unstructured]"
pip install "mare-retrieval[fastembed]"
pip install "mare-retrieval[integrations]"

Notes

• Python import remains import mare
• GitHub repo remains MARE
• PyPI distribution name remains mare-retrieval

Docs

• GitHub: https://github.com/SaiSandeepKantareddy/MARE
• PyPI: https://pypi.org/project/mare-retrieval/