# 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)