# Antigravity PDF MCP Server
A powerful Model Context Protocol (MCP) server that enables intelligent document ingestion and querying capabilities for AI agents and IDEs. This server allows you to build a persistent knowledge base from PDFs, Markdown, and Text files, and query them using advanced hybrid search techniques.
## Features
- **Multi-Format Ingestion**: Support for `.pdf`, `.md`, and `.txt` files.
- **Smart Chunking**: Recursive character splitting preserves document structure (paragraphs, headers).
- **Persistent Storage**: Uses SQLite (`antigravity.db`) to store documents and vectors across restarts.
- **Advanced Retrieval**:
- **Hybrid Search**: Combines TF-IDF (keyword) and OpenAI Embeddings (semantic) using Reciprocal Rank Fusion (RRF).
- **Filtering**: Scope searches to specific documents.
- **Citations**: Returns page numbers (e.g., `[Page 5]`) for easy verification.
- **User Experience**: Real-time progress notifications during ingestion.
- **MCP Protocol**: Fully compliant with the Model Context Protocol over Stdio.
## Prerequisites
- Node.js (v18 or higher)
- npm
## Installation
1. Clone the repository:
```bash
git clone <repository-url>
cd antigravity-pdf-mcp
```
2. Install dependencies:
```bash
npm install
```
3. Build the project:
```bash
npm run build
```
## Configuration
To enable **Semantic Search** (Embeddings), create a `.env` file in the root directory:
```env
OPENAI_API_KEY=sk-your-api-key-here
```
*If no API key is provided, the server will fallback to local TF-IDF search only.*
## Tools
The server exposes the following MCP tools:
- **`ingest_document`**: Ingest a file (PDF, TXT, MD) into the knowledge base.
- `path`: Absolute path to the file.
- **`query_knowledge_base`**: Search the knowledge base.
- `query`: The search query.
- `document_id` (Optional): Filter results to a specific document ID.
- **`list_documents`**: List all ingested documents.
- **`reset_library`**: Clear the entire database.
- **`ingest_pdf`** (Deprecated): Alias for `ingest_document`.
## Usage with IDEs
This server uses the **Stdio** transport, making it compatible with any MCP-compliant client or IDE.
### Antigravity IDE
1. Open **Settings** > **MCP Servers**.
2. Click **Add Server**.
3. Configure the server:
- **Name**: `antigravity-pdf`
- **Command**: `node`
- **Arguments**:
```text
/absolute/path/to/antigravity-pdf-mcp/dist/server.js
```
- **Environment Variables**:
- `OPENAI_API_KEY`: Your OpenAI API key.
### VSCode / Claude Desktop
Add to your MCP configuration file (e.g., `claude_desktop_config.json`):
```json
{
"mcpServers": {
"antigravity-pdf": {
"command": "node",
"args": [
"/absolute/path/to/antigravity-pdf-mcp/dist/server.js"
],
"env": {
"OPENAI_API_KEY": "your-api-key-if-needed"
}
}
}
}
```
## Contributing
1. **Fork & Clone**: Clone your fork locally.
2. **Branch**: Create a feature branch (`git checkout -b feature/amazing-feature`).
3. **Develop**: Make your changes.
4. **Verify**:
- Run `npm run build` to check for errors.
- Use `npx ts-node verify_ux.ts` to test ingestion and retrieval.
5. **Commit & Push**: Push changes to your fork.
6. **Pull Request**: Open a PR against the main repository.
## License
[MIT](LICENSE)
