Skip to main content
Glama
02Mahmoudhamam

ResearchMind MCP

by 02Mahmoudhamam
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Local

ResearchMind MCP

An AI research assistant for working with a personal corpus of academic papers, exposed both as a REST API and as a Model Context Protocol (MCP) server.

IMPORTANT

Development status: pre-alpha. The system does not yet run. This repository is an architectural foundation with an approved delivery plan. Most capabilities described below are not implemented. The Development Status section is exact about what exists. Nothing here is production-ready or safe to expose to a network.

What It Does

The goal is a research assistant for an individual academic or a small research group. A researcher uploads papers, and the system makes their own corpus answerable:

  • Semantic search across everything they have uploaded.

  • Grounded answers to research questions, drawn only from their documents and returned with citations that resolve to a real page and section.

  • Document-scoped analysis — summarise a paper, compare several.

MCP is the integration seam. The same capabilities are reachable from the project's own web client and from an external MCP host such as Claude Desktop, because both are thin adapters over one service core.

What it is not. Not a literature search engine — it works on documents you supply. Not multi-tenant SaaS. Not a chatbot with general knowledge: if the answer is not in your corpus, the correct response is "no relevant sources", and the system is built to say so rather than to improvise.

Related MCP server: Athena

Architecture

A modular monolith. REST and MCP are sibling adapters over a shared Service Core; neither calls the other.

┌──────────────────┐            ┌────────────────────────┐
│  Next.js client  │            │  MCP host              │
│  (browser)       │            │  (e.g. Claude Desktop) │
└────────┬─────────┘            └───────────┬────────────┘
         │ HTTPS + Bearer JWT               │ stdio subprocess
┌────────▼─────────────────┐   ┌────────────▼─────────────┐
│  REST ADAPTER            │   │  MCP ADAPTER             │
│  backend/api/            │   │  mcp_server/             │
│  routers · schemas       │   │  tool registry+dispatch  │
│         └────────────────┼───┼──► one identity resolver │
└────────┬─────────────────┘   └────────────┬─────────────┘
         └───────────────┬──────────────────┘
┌────────────────────────▼───────────────────────────────┐
│  SERVICE CORE — backend/services/                      │
│  Auth · Document · Ingestion · Search · Research       │
│  every method takes an authenticated Principal         │
└──┬──────────┬───────────┬───────────┬──────────────┬───┘
   ▼          ▼           ▼           ▼              ▼
┌──────┐ ┌─────────┐ ┌────────┐ ┌──────────┐ ┌────────────┐
│Repos │ │ Object  │ │Embed   │ │ Vector   │ │ LLM        │
│      │ │ storage │ │Provider│ │ Index    │ │ Provider   │
└──┬───┘ └────┬────┘ └───┬────┘ └────┬─────┘ └─────┬──────┘
   ▼          ▼          ▼           ▼             ▼
PostgreSQL  volume    FastEmbed   Qdrant       Anthropic
(SOURCE OF  (content- (local,     (INDEX       (Claude)
 TRUTH)     addressed) 384-d)      ONLY)
                          ▲
                     ┌────┴─────┐
                     │  Redis   │ ARQ job queue + rate limits
                     └──────────┘

Storage responsibilities

Store

Owns

Never

PostgreSQL

Sole authority for what exists and who owns it

Vectors

Qdrant

An index: vectors + user_id/document_id payload

A source of truth

Redis

ARQ job queue, job status, rate-limit counters

Anything whose loss is unrecoverable

Object storage

Original uploaded bytes, content-addressed

Anything derivable

Isolation invariant. Retrieval filters on user_id in Qdrant (fast path) and re-validates every chunk against PostgreSQL ownership before any content reaches a prompt (correct path). If the two ever disagree, the system returns fewer results — never another user's document.

Rationale for every structural choice is in docs/adr/.

Technology Stack

Layer

Technology

Language / runtime

Python 3.12 · Poetry

API

FastAPI · Uvicorn · Pydantic v2 · pydantic-settings

System of record

PostgreSQL 16 · SQLAlchemy 2 (async) · asyncpg · Alembic

Vector index

Qdrant (cosine)

Jobs & cache

Redis 7 · ARQ

LLM

Anthropic Claude (claude-sonnet-4) via the anthropic SDK

Embeddings

FastEmbed · BAAI/bge-small-en-v1.5 (384-d, local)

Document parsing

PyMuPDF (block mode, thread-offloaded)

MCP

mcp Python SDK, stdio transport

Auth

JWT (python-jose, algorithm pinned) · passlib/bcrypt

Frontend

Next.js 14 (App Router) · React 18 · TypeScript · Tailwind · TanStack Query · Zustand · axios

Testing

pytest · pytest-asyncio · testcontainers · httpx · gitleaks

Quality

ruff · black · mypy (strict)

Infrastructure

Docker · Docker Compose · GitHub Actions · Dependabot

Embeddings run locally, so a full stack needs exactly one secret: ANTHROPIC_API_KEY. See ADR-0004.

Repository Structure

Path

Contents

backend/

REST adapter (api/) and the Service Core (services/), config, security

mcp/

MCP adapter — server, tools, resources, prompts (renamed to mcp_server/ at M0)

agents/

Agent layer (collapsed to a single ResearchAgent at M5)

shared/

Domain models, interfaces (ABCs), utilities — the layer everything depends on

document_processing/

RAG ingestion: parse → chunk → embed

vector_db/

Qdrant adapter

memory_system/

Redis adapter

frontend/

Next.js web client

tests/

unit/, integration/, e2e/

infra/

Dockerfiles and infrastructure configuration

scripts/

Developer and CI helper scripts

docs/

Architecture, ADRs, roadmap, development, security

Development Status

Verified by execution, not by assumption. The full evidence base is in docs/architecture/AUDIT-2026-09.md.

What genuinely works

Component

State

Domain models (shared/models/)

✅ Complete — 12 Pydantic v2 models

Interfaces (shared/interfaces/)

✅ Complete — 4 ABCs

API schemas (backend/api/schemas/)

✅ Complete — 9 DTOs

Settings (backend/config/settings.py)

✅ Complete

FastAPI app construction

✅ Builds and mounts routers

Repository foundation

✅ Docs, ADRs, CI hygiene, workflow

What does not work

Area

State

All 12 REST endpoints

❌ Signatures only — every body is ...

Authentication

❌ Fails open. Any non-empty bearer token is accepted

MCP layer

❌ Cannot be imported — local mcp/ shadows the SDK

RAG pipeline

❌ 1 of 17 stages implemented

Persistence

❌ No relational database exists

Agents

❌ Return success=True without calling an LLM

Container builds

❌ All three fail

Test suite

❌ 1 failing, 1 uncollectable

Roughly 10% complete — concentrated in declarations rather than behaviour.

Prerequisites

  • Python 3.12 · Poetry 1.8+

  • Node.js 20+ · npm

  • Docker + Docker Compose v2

  • An Anthropic API key

  • Git

Local Development

WARNING

No runnable workflow exists yet. docker compose up fails: poetry check rejects pyproject.toml, and the frontend has no next.config.js. Making these commands work is Milestone M0, the next unit of work.

What works today

git clone <repository-url>
cd researchmind-mcp

cp .env.example .env                    # then set ANTHROPIC_API_KEY
cd frontend && cp .env.example .env.local && cd ..

./scripts/check-hygiene.sh              # repository hygiene checks

After Milestone M0 (not yet available)

docker compose up --build               # full stack
poetry install && poetry run python main.py   # backend only

This section is updated as each milestone makes a workflow genuinely functional. Commands are not documented here before they work.

Testing

poetry run pytest                       # ⚠️ does not yet collect cleanly
./scripts/check-hygiene.sh              # ✅ works today

Strategy, test levels and the blocking release-gate suites are in docs/development/testing.md.

Git Workflow

main (protected, validated states only) ← milestone/* ← sprint/*. Conventional Commits. Tags mark validated milestones, never aspirational ones.

Full detail: docs/development/workflow.md.

Roadmap

Milestone

Outcome

M0

Build integrity — images build, imports resolve, CI green

M1

System of record — Postgres, repositories, migrations

M2

Fail-closed authentication

M3

Document ingestion — PDF to owned, section-aware chunks

M4

Tenant-isolated retrieval

M5

Grounded answering — first working end-to-end flow

M6

MCP adapter

M7

RAG evaluation harness

M8

Web client

M9

Hardening and observability

M10

Release validation

docs/roadmap/MILESTONES.md · docs/roadmap/COMPLETION_PLAN.md

Security

Authentication currently fails open and the system must not be exposed to a network. Principles and invariants: docs/security/principles.md. To report a vulnerability, see SECURITY.md — please report privately.

Contributing

See CONTRIBUTING.md.

License

Apache License 2.0.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

No tool schema history has been recorded yet.

This server cannot be installed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Personal Research Assistant

    chakri01
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables semantic search and conversational querying across a personal research library of PDFs, DOCX, and other documents using a vector database. It provides tools for document summarization, finding related papers, and high-accuracy retrieval for AI clients like Claude Desktop.
    -

  • Athena

    Vis-3
    F
    license
    Not graded
    quality
    D
    maintenance
    A local academic research assistant that indexes PDFs into a searchable vector library and exposes MCP tools for semantic search, claim extraction, contradiction detection, and multi-step research synthesis.
    -

  • arxivsub-mcp

    arxivsub
    A
    license
    A
    quality
    B
    maintenance
    Enables searching arXiv and top AI conferences, finding related papers, generating research insights, and managing a personal library via MCP tools.
    5
    51
    MIT

  • research-mcp

    lduda79
    F
    license
    A
    quality
    B
    maintenance
    Enables semantic search across personal PDF paper collections with page-level citations, allowing users to query their library from any MCP-capable client.
    9
    -

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/02Mahmoudhamam/researchmind-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server