# Project Memory MCP

Project Memory MCP is a small, local-first backend for semantic search over a software
project's Markdown and text documentation. It indexes document chunks in Qdrant and exposes
retrieval through a CLI and MCP tools. The server does not call an LLM; the MCP host uses the
retrieved context to formulate its answer.

## Architecture

HTTP, MCP, and CLI modules are thin entry adapters. The application services orchestrate
document loading, chunking, embeddings, and vector storage through typed domain ports.
Sentence Transformers and Qdrant remain isolated in infrastructure adapters.

```text
Documentation
     ↓
Chunking
     ↓
Embeddings
     ↓
Qdrant
     ↑
MCP Search Tool
     ↑
AI Host
```

Markdown files are first split by their heading hierarchy and then by character count.
Text files use character-based recursive splitting directly. Each chunk receives a stable
SHA-256 ID and keeps its relative source path and Markdown section.

## Requirements

- Python 3.12
- Docker with Docker Compose

## Installation

Create and activate a virtual environment:

```bash
python -m venv .venv
```

Linux and macOS:

```bash
source .venv/bin/activate
```

Windows PowerShell:

```powershell
.venv\Scripts\Activate.ps1
```

Install the direct runtime and development dependencies:

```bash
pip install -r requirements.txt
```

Copy the example configuration:

Linux and macOS:

```bash
cp .env.example .env
```

Windows PowerShell:

```powershell
Copy-Item .env.example .env
```

## Run Qdrant

```bash
docker compose up -d qdrant
```

Qdrant exposes HTTP on port `6333` and gRPC on port `6334`. Its data is stored in the
named `qdrant_storage` volume.

## Index sample documentation

The first run downloads the configured Sentence Transformers model.

```bash
python -m scripts.index_docs --path ./docs_sample
```

The command reports discovered files, created chunks, indexed files, and skipped files.
Re-indexing replaces points for each processed path without deleting the whole collection.

## Search from the CLI

```bash
python -m scripts.search_docs "Where are JWT tokens validated?" --top-k 5
```

Each result includes its cosine score, relative path, Markdown section, stable chunk ID,
and text.

## Run FastAPI

```bash
uvicorn app.api.main:app --reload
```

The current HTTP surface intentionally contains only:

```http
GET /health
```

## Run the MCP server

Open the server with MCP Inspector:

```bash
mcp dev mcp_server.py
```

The root module exports an MCP Python SDK v2 `MCPServer` named `Project Memory MCP` and
uses stdio safely: application logging is sent to stderr.

Available tools:

- `search_project_docs(query, top_k=5)` searches the current project's indexed
  documentation and returns structured chunks. `top_k` must be between 1 and 20.
- `get_document(path)` reads one UTF-8 `.md` or `.txt` document under `DOCS_ROOT`.
  Absolute paths, traversal outside that root, and unsupported file types are rejected.

## Quality checks

```bash
pytest
ruff check .
docker compose config
```

Tests use fake embedding and vector-store implementations, so they do not need Qdrant or
an embedding model download.

## MVP limitations

- Only local `.md` and `.txt` files are supported.
- Indexing is synchronous and manually triggered.
- Search is vector-only; there is no BM25, hybrid search, or reranking.
- There is no LLM call, generated answer, RAG prompt, authentication, multi-tenancy,
  background worker, GitHub integration, or web UI.
- The FastAPI application exposes health status only.

## Possible next steps

- Reranking
- GitHub webhook and incremental indexing from webhook events
- Retrieval evaluation
- Hybrid search
- LangGraph query retry