Content
# GeryonMCP
> A free, offline, and CPU-only document search MCP server running on your local machine.
> It caches your company's wiki (like Confluence) in a local database, allowing searches without relying on paid AI or internet connectivity.
The name originates from **Geryon**, a giant from Greek mythology with multiple heads and bodies, symbolizing a search engine that integrates multiple sources into one.
## Features
- **Zero cost, offline, CPU-only, and within 16GB memory** — No paid or online inference calls. The model is received once and operates completely offline.
- **Keyword (BM25) + cross-encoder reranking (ONNX)** — Precise top results without relying on vectors. Supports **multilingual search (Korean and English, with phonetic and technical term cross-language matching)**.
- **Meta field-specific advanced search** (`advanced_search`) — Combine title, author, space, tags, and date as independent fields.
- **Multi-source federation** — Confluence, Jira, and Git (including GitHub, GitLab, and Bitbucket, with **source code and commits**) are stored as separate databases and integrated during search with reranking (no source limitations). New sources can be added as plugins without modifying search code.
- **Incremental indexing** — Only re-index changes using `manifest.last_change` (common to all sources, no API re-calls).
- **Medallion + dictionary** — Original preservation (Bronze) → Refined database (Silver) → Personalized dictionary (Gold). Manual dictionaries are always applied (optional), and **automatic bootstrapping is opt-in (default OFF)**.
- **MCP server** — Directly connects to MCP clients (Claude Desktop, VS Code, etc.).
## How it Works
```
Original Wiki ─[collection]→ Local file (Bronze) ─[loading and refinement]→ Local DB (Silver)
│
Query ─[search]→ Keyword candidates (BM25, Korean normalization FTS)
→ cross-encoder reranking (ONNX·int8) ← Core of accuracy
→ Results (vector search is auxiliary/fallback)
```
Keyword search quickly narrows down candidates, and the **reranking model brings the correct answers to the top**. All operations are performed on the local CPU without external calls.
## Core Design (measurement-based)
All design choices and exclusions were made based on **actual measurements**, not guesses.
- **Korean-friendly tokenization** — FTS5 tokenizer and inflectional normalization for Korean BM25 accuracy.
- **Cross-encoder reranking** — Fastembed ONNX (no torch required) and int8 quantization for sub-second performance on CPU. Replaces heavy vector brute-force with keyword + reranking for rebalancing.
- **Best-passage combination** — Evaluates title and body matching phrases together (max score combination) to recover documents centered on bodies, not titles.
- **Meta noise normalization** — Normalizes author status suffixes (e.g., `(Deactivated)`) and classification noise for consistent filtering and display.
- **License safety** — Reranking model is MIT-licensed (commercially usable).
## Prerequisites
1. **Python 3.10 or higher** — Verify with `python3 --version` (if not installed, use [python.org](https://www.python.org/downloads/) or your OS package manager).
> If you're new to this, **steps 2-3 (installation, bootstrap, and demo) are enough to experience search without credentials**. Actual wiki integration starts from step 4 (token).
## Quickstart
```bash
# 1) Installation
uv tool install . # or: pip install -e .
# 2) Bootstrap — automatic model download and sample settings (.env) generation
geryon bootstrap
# 3) Experience search without credentials (virtual data)
geryon demo
# 4) Real data — collection (acquire) → indexing (ingest)
# Fill in CONFLUENCE_URL / USERNAME / API_TOKEN in .env created in step 2 (or `geryon init`)
geryon acquire # External → Bronze original files (default: last month, idempotent/incremental)
# --since 2026-01-01 --until 2026-03-31 Specify date range / --all for all data
geryon ingest --source confluence --path ./bronze/confluence # Bronze → search DB
geryon serve # Start MCP server
```
> The reason for separating collection (`acquire`) and indexing (`ingest`) and detailed options (incremental/full, prune, data path specification) are in [docs/DATA_PIPELINE.md](docs/DATA_PIPELINE.md). If you only need to change the search logic, re-run `ingest` (no API re-calls).
> **Start without separate settings**: There's nothing to input besides following the flow. The synonym dictionary (`~/.geryon/gold/dictionary.yaml`) is **optional** — it doesn't affect search functionality and can be added later. Automatic synonym dictionaries are **OFF by default (data suitability check required for opt-in)**. All environment variables have reasonable default values for tuning-free usage.
`geryon demo` output example:
```
Query: 'zero-downtime deployment procedure' → Server deployment guide, data backup procedure
Query: 'vacation request' → Vacation policy
```
## Atlassian API Token Issuance (for actual wiki integration)
Required for step 4 `acquire`. Use a token instead of a password.
1. Access **https://id.atlassian.com/manage-profile/security/api-tokens** in your browser
2. Click **Create API token** → Enter a name (e.g., geryon) → Copy the generated token (can't be viewed again)
3. Open `.env` and fill in:
```
CONFLUENCE_URL=https://<company-domain>.atlassian.net/wiki
CONFLUENCE_USERNAME=<login email>
CONFLUENCE_API_TOKEN=<copied token>
```
(If `.env` doesn't exist, `geryon bootstrap` creates `.env.sample` which can be used)
## MCP Client Registration
To use search in AI clients (Claude Desktop, VS Code, etc.), register in the configuration file.
**Claude Desktop** — Open the settings file (`Settings → Developer → Edit Config`) and add:
```json
{
"mcpServers": {
"geryon": { "command": "geryon", "args": ["serve"] }
}
}
```
Restart the client after saving.
## Tools
| Tool | Description |
|---|---|
| `search` | Integrated search (keyword + reranking, synonyms, personalization) |
| `advanced_search` | Meta field-specific advanced search (title, author, space, tags, date) |
| `get_document` | Retrieve full document |
| `get_related` | Related documents (link-based) |
| `browse` | Space/hierarchy list |
| `list_sources` | Indexed source/space list |
| `reindex` | Trigger reindexing |
> Same search in the terminal: `geryon search "<query>"` (table/ `--json`) — Same core as MCP tools.
## Settings
All options are adjusted with `.env` (or environment variables). See the full list in the repository's `.env.sample`. If the file doesn't exist, `geryon bootstrap` **generates `.env` in the current directory with built-in templates** (no overwriting existing values).
Main options: `GERYON_RERANK_PASSAGE` (passage-centric strengthening on/off), `GERYON_RERANK_POOL` (candidate count), `GERYON_RERANK_QUANTIZE` (int8 acceleration), `GERYON_RERANK_MODEL`, `GERYON_LOG_LEVEL`.
## CLI
| Command | Description |
|---|---|
| `geryon bootstrap` | Model download + sample settings generation |
| `geryon init` | Set credentials and collection sources (Confluence space, Jira project, Git repo) in `.env` (interactive/flag-based) |
| `geryon demo` | Experience search with virtual data (no credentials) |
| `geryon sync --all` | Collection and indexing |
| `geryon search "<query>"` | Direct search in terminal (table / `--json`). Same core as MCP `search` |
| `geryon serve` | Start MCP server |
| `geryon status` / `health` | Status and health check |
## Documentation
- **[docs/USER_MANUAL.md](docs/USER_MANUAL.md) — User manual (installation to operation steps)**
- [docs/INSTALL_WALKTHROUGH.md](docs/INSTALL_WALKTHROUGH.md) — Verified step-by-step guide from installation to MCP connection (last month collection, multilingual support)
- [docs/AIRGAP_INSTALL.md](docs/AIRGAP_INSTALL.md) — Air-gap (offline network) installation and operation guide (offline wheel bundle and model import, verified)
- [docs/GOLDEN_AND_DICTIONARY.md](docs/GOLDEN_AND_DICTIONARY.md) — Golden test set and synonym dictionary creation tips (investigation type, translation round-trip, Korean-English phonetic matching)
- [docs/TEAM_DEPLOY.md](docs/TEAM_DEPLOY.md) — Team deployment (attaching search MCP to projects, project-specific indexes)
- [docs/EXTENDING_SOURCES.md](docs/EXTENDING_SOURCES.md) — Adding new data sources (extending multi-source support for Jira, GitHub, etc.)
- [docs/BEGINNER_GUIDE.md](docs/BEGINNER_GUIDE.md) — Beginner's guide to concepts and code mapping
- [docs/PERFORMANCE.md](docs/PERFORMANCE.md) — Search pipeline and performance tuning (rerank, pool, int8)
- [CHANGELOG.md](CHANGELOG.md) — Change history · [CONTRIBUTING.md](CONTRIBUTING.md) — Contribution guide
## Troubleshooting
| Symptom | Cause | Solution |
|---|---|---|
| `command not found: geryon` | Installation path not registered | Re-run `uv tool install .` or execute with `python -m geryon.cli ...` |
| `command not found: uv` | uv not installed | Refer to "Prerequisites" or use `pip install -e .` |
| Bootstrap takes too long | Initial one-time model download (hundreds of MB) | Normal. Subsequent usage is fast with caching (offline operation) |
| Empty search results | Indexing not done yet | Confirm with `geryon demo` → Use real data with `geryon sync --all` |
| `Confluence credentials not found` | `.env` not set | Fill `.env` as per "Atlassian API Token Issuance" |
| Health warns "no original data" | Before indexing | Normal. It disappears after indexing |
| Out of memory | Less than 16GB | Keep `GERYON_RERANK_QUANTIZE=1` (default) and lower `GERYON_RERANK_POOL` |
## Constraints and Philosophy
Zero cost, offline, and CPU/16GB are non-negotiable principles. Weaknesses are addressed directly, not covered with heavy solutions, and all decisions are based on measurements.
## License
[MIT](LICENSE)
