README.md•3.97 kB
# MCP Data Server — Local file search you can call from Claude (or CLI)
**MCP Data Server** indexes files on your machine (PDF, TXT, CSV, Markdown, etc.) and lets you **search** them with embeddings. You can use it from:
- a friendly **CLI** (`ls`, `index`, `search`)
- an **MCP server** over stdio (so Claude Desktop/Cursor can call your tools)
> Works great on Windows 11. Also tested on macOS/Linux (see notes).
---
## Table of contents
- [Features](#features)
- [Prerequisites](#prerequisites)
- [Quick start (Windows)](#quick-start-windows)
- [Quick start (macOS/Linux)](#quick-start-macoslinux)
- [Usage (CLI)](#usage-cli)
- [Use with Claude Desktop (MCP)](#use-with-claude-desktop-mcp)
- [Configuration](#configuration)
- [Project structure](#project-structure)
- [Development (lint, type, test)](#development-lint-type-test)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)
---
## Features
- 🔎 **Local search** with SentenceTransformers embeddings (cosine similarity)
- ⚡ Optional **FAISS** index for fast Top-K search
- 🧰 Simple CLI: `ls`, `index`, `search`
- 🔌 **MCP server** so Claude Desktop can call tools: `list_docs_tool`, `index_docs_tool`, `search_chunks_tool`, `read_doc_tool`
- 🧩 Extensible loaders/chunkers; add new formats easily
- ✅ Batteries-included dev setup: Ruff, Black, MyPy, PyTest, pre-commit
---
## Prerequisites
- **Python 3.11+** (3.11 recommended)
- **Windows 11** (PowerShell)
macOS/Linux are fine too (bash)
- ~3 GB free disk space on first run (model cache)
- (Optional) **FAISS** CPU wheels installed automatically via `faiss-cpu`
---
## Quick start (Windows)
> Folder in this repo where you put files to index: `./data/`
```powershell
# 1) Clone and enter project
git clone https://github.com/hkonda015/McpServer.git
Set-Location .\McpServer\McpServer
# 2) Create & activate venv (PowerShell)
python -m venv .venv
.\.venv\Scripts\Activate.ps1
# 3) Install runtime (or dev) dependencies
pip install -r requirements.txt
# or for contributors:
pip install -r requirements-dev.txt
# 4) (Optional) pre-commit hooks
pre-commit install
# 5) Put a few files in .\data\ (txt/pdf/csv/md), then:
python -m mcp_data_server ls
python -m mcp_data_server index
python -m mcp_data_server search "your query" --k 5
## Usage (CLI)
The CLI lets you **list files**, **build/rebuild the index**, and **search** your local documents.
> **Prereq:** open a terminal at your repo root and activate the venv
> Windows (PowerShell):
> ```powershell
> Set-Location .\McpServer
> .\.venv\Scripts\Activate.ps1
> ```
> macOS/Linux (bash):
> ```bash
> cd McpServer
> source .venv/bin/activate
> ```
---
### 1) List files (`ls`)
Lists all **supported documents** under `DATA_DIR` (defaults to `./data`).
```powershell
python -m mcp_data_server ls
# Contributing to MCP Data Server
Thanks for your interest in contributing! This document explains how to set up your dev environment, the coding standards we use, how to run tests, and how to submit a good pull request.
---
## Ways to contribute
- **Bug reports**: include steps to reproduce, expected vs actual behavior, OS, Python version, and logs.
- **Feature requests**: explain the use case, not just the solution. Sketch CLI and/or MCP tool UX if relevant.
- **Documentation**: improve READMEs, examples, and comments.
- **Code**: bug fixes, new loaders, chunking strategies, performance improvements, tests.
Good first issues will be labeled **good first issue** and **help wanted**.
---
## Development setup
### Prerequisites
- Python **3.11+** (we recommend 3.11)
- Git
- ~3 GB free disk space for model cache on first run
### Clone and create a virtual environment
#### Windows (PowerShell)
```powershell
git clone https://github.com/hkonda015/McpServer.git
Set-Location .\McpServer\McpServer
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements-dev.txt
pre-commit install