MCP Academic RAG Server

An experimental MCP server for academic document OCR and RAG. The maintained console entry is servers.mcp_server_sdk:cli_main. All five console aliases use that implementation. Source variants under servers/ remain in the repository; they are not separate production releases.

Python 3.10 or newer is required. The installation contract uses MCP SDK v1 (mcp>=1,<2) and Haystack 2 (haystack-ai>=2,<3). Package version, author and license metadata remain in pyproject.toml.

Install and start

From this checkout, use an isolated environment:

python -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/mcp-academic-rag-server --help

--help works without credentials or loading optional RAG backends. Set OPENAI_API_KEY securely before using the stdio server. The current entry checks the configured key's shape; this does not verify the key with an external service.

.venv/bin/mcp-academic-rag-server --validate-only
.venv/bin/mcp-academic-rag-server

The second command waits for an MCP client on stdin/stdout. It does not start an HTTP dashboard. --validate-only checks the environment and creates DATA_PATH (default ./data), without making a model request. Missing or malformed keys produce a nonzero exit status. This entry accepts --help and --validate-only; logging is controlled by LOG_LEVEL.

On macOS, normal CLI startup replaces its Python process once before serving stdio, selecting the installed Torch OpenMP library for Torch, FAISS and scikit-learn. It preserves arguments and standard streams and requires KMP_DUPLICATE_LIB_OK=FALSE. Help and validation-only commands do not need this native startup. Embedded SDK consumers must supply utils.native_runtime.native_subprocess_environment() when launching Python; changing these variables after Python starts is insufficient. SDK imports never replace their host process. See native startup for the embedding contract and checks.

Configure an MCP client with the absolute path of the installed executable and provide credentials through its environment configuration. Do not put a live key in the repository. Document processing and queries also require the applicable processor, model and storage configuration; use config/config.json.example as a source reference rather than treating an environment check as full setup.

Optional Windows Web development uses the standalone libmagic wheel declared by the web/dev extras. Install into an isolated environment; older python-magic/python-magic-bin distributions must not share that environment. The maintained Windows adapter uses only the wheel's owned native DLL and database and reports unavailable validation explicitly. Other platforms retain their existing libmagic setup.

Current MCP tools

The tool list is defined in servers/mcp_server_sdk.py.

OCR uses the Mistral file upload, signed URL and OCR contracts in connectors/api_connector.py. Empty text, partial file results and service errors do not count as successful extraction. Local verification uses controlled fixture text and vectors; no paper extraction, research finding or model answer quality is claimed from those fixtures.

Markdown-to-PDF conversion requires local Chromium (python -m playwright install chromium). It disables scripts and local/remote resource fetching; self-contained data images are supported. Missing browsers and unsupported legacy PDF options are explicit errors.

Develop and verify

The Docker image runs this same installed MCP stdio entry:

docker build --target runtime-validation -t academic-rag:dependencies .
docker build -t academic-rag:local .
python scripts/check_container.py academic-rag:local --dependency-image academic-rag:dependencies
docker run --rm -i --network none -e OPENAI_API_KEY academic-rag:local

Connect the container through an MCP stdio client. It has no HTTP listener or port 8000 health endpoint. The container checker verifies actual dependencies, installer removal, the installed entry and real protocol with a fixture key and networking disabled. The CPU image uses the official PyTorch CPU wheels. Optional PDF rendering requires installing Chromium and its system dependencies in a derived image; missing browsers fail explicitly. The historical docker-compose.yml infrastructure is not the maintained MCP client entry; its optional Nginx configuration is absent.

AGENTS.md defines maintenance boundaries. docs/maintenance.md contains the repeatable installation, cleanup, behavior and documentation checks. pyproject.toml owns package metadata and dependencies, pytest.ini owns test selection, and .flake8 owns lint settings. Do not duplicate these configurations in another file.

.venv/bin/python -m pip install -e '.[dev,monitoring]'
.venv/bin/python -m pytest

Default discovery includes unit, contract, integration, component, E2E and performance tests. Browser tests require the normal Chromium installation:

.venv/bin/python -m playwright install chromium
.venv/bin/python -m pytest tests/e2e

Manual scripts that can request live models or services are outside default collection. Review their inputs and service requirements before running them. The existing CI workflows retain formatting, typing, security, documentation and behavior checks. Read the actual run result and failing command before claiming that the complete project passes.

Status and scope

Installation/protocol checks, offline behavior, remote CI, user acceptance and production release are separate evidence. This repair does not establish live OCR accuracy, answer quality, deployment readiness, performance targets or whole-project coverage. Existing Markdown guides under docs/ provide implementation context; use the maintained entry and checks above for current execution.

The project declares MIT license metadata. A repository LICENSE file is absent; this repair preserves the declaration and does not create a new license grant.

Acknowledgments

• Model Context Protocol for the protocol
• Haystack for RAG components
• FAISS for local vector search
• OpenAI for model integration
• OpenTelemetry for observability components