Metadata-Version: 2.4
Name: hippobox
Version: 0.1.2
Summary: HippoBox MCP + Knowledge Store Server
Requires-Python: >=3.13
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: alembic>=1.17.2
Requires-Dist: argon2-cffi>=25.1.0
Requires-Dist: asyncpg>=0.29.0
Requires-Dist: bcrypt>=5.0.0
Requires-Dist: black>=25.11.0
Requires-Dist: fakeredis>=2.23.0
Requires-Dist: fastapi-mcp>=0.4.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: flake8>=7.3.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: isort>=7.0.0
Requires-Dist: langchain-openai>=1.0.3
Requires-Dist: mcp[cli]>=1.17.0
Requires-Dist: openai>=2.8.1
Requires-Dist: passlib>=1.7.4
Requires-Dist: pydantic>=2.6.0
Requires-Dist: pyjwt>=2.10.1
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: python-jose>=3.5.0
Requires-Dist: qdrant-client>=1.7.0
Requires-Dist: redis[hiredis]>=5.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: uvicorn[standard]>=0.29.0
Provides-Extra: dev
Requires-Dist: hatchling>=1.24.0; extra == 'dev'
Description-Content-Type: text/markdown

# HippoBox

![HippoBox logo](https://raw.githubusercontent.com/HippoBox/hippobox/main/src/frontend/public/hippobox-banner.png)

HippoBox is a unified FastAPI + FastAPIMcp for managing a personal knowledge base.
It provides CRUD operations for knowledge entries, semantic search powered by embeddings, and MCP tool integration for use in Claude Desktop or other MCP-compatible clients.

### Overview

See the knowledge entry once it is created in HippoBox.
![Knowledge created](src/frontend/public/guide/step-6.png)

### Hippo Search (VDB)

Use Hippo Search to run VDB searches over your knowledge.
![Hippo Search](src/frontend/public/guide/step-3.png)

### setup MCP

Configure MCP to connect HippoBox with Claude, Cursor, and Codex.
![setup MCP](src/frontend/public/guide/step-4.png)

# Running as a package

```bash
pip install hippobox
```

```bash
# Basic execution
hippobox run

# Custom host and port
hippobox run --host 0.0.0.0 --port 8080
```

# Quick Start from Source

## 1. Install uv

**macOS / Linux**

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Windows (PowerShell)**

```powershell
irm https://astral.sh/uv/install.ps1 | iex
```

## 2. Setup Project

```bash
cd src/backend
uv sync
```

## 3. Run Server

### macOS / Linux

```bash
cd src/backend
uv run uvicorn hippobox.server:app --reload
```

## 4. Run Frontend

```bash
cd src/frontend
npm install
npm run dev # watch build to keep src/frontend/dist updated for backend serving
npm run dev:vite # Vite dev server with HMR (default 5173)
npm run build # build to src/frontend/dist for backend serving
npm run preview # preview the built bundle
```

# MCP settings

## <img src="https://raw.githubusercontent.com/HippoBox/hippobox/main/src/frontend/src/assets/claude.svg" width="30" height="30" align="center"> Using with Claude Desktop

Add the following to your `claude_desktop_config.json`:

```json
{
    "mcpServers": {
        "hippobox": {
            "command": "uvx",
            "args": [
                "mcp-proxy",
                "--transport",
                "streamablehttp",
                "http://localhost:8000/mcp"
            ],
            "env": {
                "API_ACCESS_TOKEN": "<YOUR_ACCESS_TOKEN>"
            }
        }
    }
}
```

## <img src="https://raw.githubusercontent.com/HippoBox/hippobox/main/src/frontend/src/assets/cursor.svg" width="30" height="30" align="center"> Using with Cursor

Add the following to your Cursor mcp settings:

```json
{
    "mcpServers": {
        "hippobox": {
            "url": "http://localhost:8000/mcp",
            "headers": {
                "Authorization": "Bearer <YOUR_ACCESS_TOKEN>"
            }
        }
    }
}
```

## <img src="https://raw.githubusercontent.com/HippoBox/hippobox/main/src/frontend/src/assets/openai-codex.svg" width="35" height="35" align="center"> Using with Codex

Add the following to your `config.toml`:

```toml
[mcp_servers.hippobox]
startup_timeout_sec = 30
command = "uvx"
args = [
    "mcp-proxy",
    "--transport",
    "streamablehttp",
    "http://localhost:8000/mcp"
]
[mcp_servers.hippobox.env]
API_ACCESS_TOKEN = "<YOUR_ACCESS_TOKEN>"
```
