[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_129":130},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":-5,"_41":42,"_43":44,"_45":46,"_47":48,"_49":50,"_51":52,"_53":54,"_55":-5,"_56":48,"_57":58,"_59":60,"_61":-5,"_62":-5,"_63":-5,"_64":-5,"_65":66,"_67":68,"_69":70,"_71":72,"_73":74,"_75":-5,"_76":-5,"_77":-5,"_78":48,"_79":-5,"_80":81,"_82":83,"_84":85,"_86":87,"_88":89,"_90":91,"_92":93},"apiUrl","https://odel.app/api","creator","nicholasglazer","moduleId","gnosis-mcp","@nicholasglazer/gnosis-mcp","displayName","Gnosis MCP","tagline","Zero-config MCP server for searchable documentation. SQLite or PostgreSQL.","iconKey","https://avatars.githubusercontent.com/u/7410355?v=4","category","local","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","pricingModel","free","creatorUserId","system:external-import","createdAt",1783342628000,"updatedAt",1788069096000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.nicholasglazer%2Fgnosis","sourceVerified",true,"sourceMissingSince","importedAt","upstreamStars",29,"upstreamUpdatedAt",1787251893000,"detectedTransport","detectedAuthType","probeStatus","lastProbedAt","githubRepoUrl","https://github.com/nicholasglazer/gnosis-mcp","githubRepoFullName","nicholasglazer/gnosis-mcp","releaseId","ext-nicholasglazer-gnosis-mcp","version","0.14.1","descriptionMarkdown","\n

\n\n

Gnosis MCP

\n\n

Stop pasting files into context. Your AI agent searches your local docs instead.
5–10× fewer tokens per lookup. 92 % Hit@5 on real dev docs. Zero cloud dependencies.

\n\n

\n $\"PyPI\"$ \n $\"Downloads\"$ \n $\"Python\"$ \n $\"MIT$ \n $\"CI\"$ \n

\n\n

\n Quick Start ·\n Git History ·\n Web Crawl ·\n Backends ·\n Editors ·\n Tools ·\n Embeddings ·\n Full Reference\n

\n\n $\"Gnosis$ \n
\n_{Ingest docs → Search with highlights → Stats overview → Serve to AI agents}\n\n

\n\n---\n\n### Without a docs server\n\n- LLMs hallucinate API signatures that don't exist\n- Entire files dumped into context — 3,000–15,000 tokens per doc\n- Architecture decisions buried across dozens of files\n- Every repeated lookup pays full context cost\n\n### With Gnosis MCP\n\n- `search_docs` returns ranked, highlighted excerpts — typically 300–800 tokens\n- Real answers grounded in your actual docs, not guesses from training data\n- One local index across hundreds of files — instant multi-doc search\n- **5–10× token savings** per lookup when your corpus covers the question\n\n---\n\n## What makes gnosis-mcp different\n\n- **Your data stays on your machine.** SQLite by default, PostgreSQL at scale — nothing leaves the host.\n- **Index anything that's docs-shaped.** Markdown, git commit history, crawled websites — one index, one search API.\n- **Measured, not marketed.** Ships BEIR SciFact numbers (0.671 nDCG@10 — within 1 % of the Lucene BM25 baseline), a reproducible eval harness (`gnosis-mcp eval`), and a chunk-size sweep showing where the quality plateau actually sits.\n\nFull side-by-side vs Context7 / docs-mcp-server / mcp-local-rag: [gnosismcp.com#compare](https://gnosismcp.com/#compare).\n\n---\n\n## Features\n\n- **Zero config** — SQLite by default, `pip install` and go\n- **Hybrid search** — keyword (BM25) + semantic (local ONNX embeddings, no API key). Tune RRF fusion with `GNOSIS_MCP_RRF_K`.\n- **Cross-encoder reranking** — optional `[reranking]` extra with a 22M-param ONNX model. Off by default. **[Test on your own corpus before enabling](https://github.com/nicholasglazer/gnosis-mcp/blob/main/docs/bench-experiments-2026-04-18.md)** — the bundled MS-MARCO reranker hurts dev-doc retrieval in our measurements.\n- **Git history** — ingest commit messages as searchable context (`ingest-git`)\n- **Web crawl** — ingest documentation from any website via sitemap or link crawl\n- **Multi-format** — `.md` `.txt` `.ipynb` `.toml` `.csv` `.json` + optional `.rst` `.pdf`\n- **Auto-linking** — `relates_to` frontmatter creates a navigable document graph\n- **Watch mode** — auto-re-ingest on file changes\n- **Prune stale docs** — `gnosis-mcp ingest --prune` removes chunks whose source file was deleted. `--wipe` for a full reset before re-ingest.\n- **Built-in eval harness** — `gnosis-mcp eval` prints Hit@K / MRR / Precision@K in one command\n- **PostgreSQL ready** — pgvector + tsvector when you need scale\n\n## Performance\n\n**Fast.** 8.7 ms mean MCP round-trip. Hybrid search p50 < 30 ms on a 700-doc corpus. Keyword QPS scales from 9,463 @ 100 docs to 471 @ 10,000 docs ([full numbers](https://gnosismcp.com/#numbers)).\n\n**Finds the right answer.** On 558 real dev docs with 25 hand-written golden queries: Hit@5 = **0.92**, nDCG@10 = **0.87**, MRR = **0.79**. On BEIR SciFact (5,183 docs, public retrieval benchmark): nDCG@10 = **0.671** — within 1 % of the Lucene BM25 baseline.\n\n**Tokens saved.** Each `search_docs` call returns 200–500 tokens of on-point snippets instead of the 3,000–15,000 tokens a full-file Read would have cost. Track your own with `gnosis-mcp savings` (v0.12.0+) — the ledger writes to `search_access_log` on every call and aggregates per tool per `--days N`:\n\n```\n$ gnosis-mcp savings --days 7\n Tool calls: 142\n Tokens returned: 7,104\n Tokens baseline: 231,580\n Tokens saved: 224,476\n Ratio: 32.6×\n```\n\nTypical compression runs 10–60× depending on corpus coverage and query specificity — verify on yours. `access_log` is on by default; `GNOSIS_MCP_ACCESS_LOG=false` opts out.\n\n**Reproducible.** `gnosis-mcp eval` runs a RAG eval harness locally in one second. `tests/bench/*.py` reproduce every number. Methodology: [`docs/benchmarks.md`](https://github.com/nicholasglazer/gnosis-mcp/blob/main/docs/benchmarks.md).\n\n**Rerankers stay off by default.** The bundled MS-MARCO cross-encoder drops nDCG@10 by 27 points on dev-docs and adds 400× latency; BGE-reranker-v2-m3 drops it 31 points at 2400×. Test on your corpus before enabling — full write-up: [bench-experiments-2026-04-18](https://github.com/nicholasglazer/gnosis-mcp/blob/main/docs/bench-experiments-2026-04-18.md).\n\n## Quick Start\n\n```bash\npip install gnosis-mcp # or: uv tool install gnosis-mcp\ngnosis-mcp ingest ./docs/ # loads docs into SQLite (auto-created)\ngnosis-mcp serve # starts MCP server\n```\n\nThat's it. Your AI agent can now search your docs.\n\n**Connect your editor** — see [`llms-install.md`](https://github.com/nicholasglazer/gnosis-mcp/blob/main/llms-install.md) for copy-paste JSON snippets for Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, JetBrains, and Cline.\n\n**Re-organized your docs?** `gnosis-mcp ingest ./docs --prune` re-ingests and removes any DB chunk whose source file no longer exists. `--wipe` resets the entire index first. Or run `gnosis-mcp prune ./docs --dry-run` to preview what would be deleted.\n\n**Want semantic search?** Add local embeddings — no API key needed:\n\n```bash\npip install gnosis-mcp[embeddings]\ngnosis-mcp ingest ./docs/ --embed # ingest + embed in one step\ngnosis-mcp serve # hybrid search auto-activated\n```\n\nTest it before connecting to an editor:\n\n```bash\ngnosis-mcp search \"getting started\" # keyword search\ngnosis-mcp search \"how does auth work\" --embed # hybrid semantic+keyword\ngnosis-mcp stats # see what was indexed\n```\n\n

Run with Docker (zero install)

\n\nMulti-arch image, ~140 MB, ships with local ONNX embeddings + REST:\n\n```bash\n# Serve your ./docs on http://localhost:8000 — MCP at /mcp, REST at /api/*\ndocker run -p 8000:8000 \\\n -v \"$PWD/docs:/docs:ro\" -v gnosis-data:/data \\\n ghcr.io/nicholasglazer/gnosis-mcp:latest\n\n# First-run: ingest into the persistent volume\ndocker run --rm \\\n -v \"$PWD/docs:/docs:ro\" -v gnosis-data:/data \\\n ghcr.io/nicholasglazer/gnosis-mcp:latest \\\n ingest /docs --embed\n```\n\nOr use the committed [`docker-compose.yaml`](https://github.com/nicholasglazer/gnosis-mcp/blob/main/docker-compose.yaml):\n\n```bash\ndocker compose up -d\ndocker compose exec gnosis gnosis-mcp ingest /docs --embed\n```\n\nImages tagged `:latest`, `:`, `:`, `:main`, `:sha-`.\n\n

\n\n

Try without installing (uvx)

\n\n```bash\nuvx gnosis-mcp ingest ./docs/\nuvx gnosis-mcp serve\n```\n\n

\n\n## Web Crawl\n\n

\n $\"Gnosis$ \n
\n_{Dry-run discovery → Crawl & ingest → Search crawled docs → SSRF protection}\n

\n\n
\n\nIngest docs from any website — no local files needed:\n\n```bash\npip install gnosis-mcp[web]\n\n# Crawl via sitemap (best for large doc sites)\ngnosis-mcp crawl https://docs.stripe.com/ --sitemap\n\n# Depth-limited link crawl with URL filter\ngnosis-mcp crawl https://fastapi.tiangolo.com/ --depth 2 --include \"/tutorial/*\"\n\n# Preview what would be crawled\ngnosis-mcp crawl https://docs.python.org/ --dry-run\n\n# Force re-crawl + embed for semantic search\ngnosis-mcp crawl https://docs.sveltekit.dev/ --sitemap --force --embed\n```\n\nRespects `robots.txt`, caches with ETag/Last-Modified for incremental re-crawl, and rate-limits requests (5 concurrent, 0.2s delay). Crawled pages use the URL as the document path and hostname as the category — searchable like any other doc.\n\n## Git History\n\nTurn commit messages into searchable context — your agent learns *why* things were built, not just *what* exists:\n\n```bash\ngnosis-mcp ingest-git . # current repo, all files\ngnosis-mcp ingest-git /path/to/repo --since 6m # last 6 months only\ngnosis-mcp ingest-git . --include \"src/*\" --max-commits 5 # filtered + limited\ngnosis-mcp ingest-git . --dry-run # preview without ingesting\ngnosis-mcp ingest-git . --embed # embed for semantic search\n```\n\nEach file's commit history becomes a searchable markdown document stored as `git-history/`. The agent finds it via `search_docs` like any other doc — no new tools needed. Incremental re-ingest skips files with unchanged history.\n\n## Editor Integrations\n\nAdd the server config to your editor — your AI agent gets `search_docs`, `get_doc`, and `get_related` tools automatically:\n\n```json\n{\n \"mcpServers\": {\n \"docs\": {\n \"command\": \"gnosis-mcp\",\n \"args\": [\"serve\"]\n }\n }\n}\n```\n\n| Editor | Config file |\n|--------|------------|\n| **Claude Code** | `.claude/mcp.json` (or [install as plugin](#claude-code-plugin)) |\n| **Cursor** | `.cursor/mcp.json` |\n| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |\n| **JetBrains** | Settings > Tools > AI Assistant > MCP Servers |\n| **Cline** | Cline MCP settings panel |\n\n

VS Code (GitHub Copilot) — slightly different key

\n\nAdd to `.vscode/mcp.json` (note: `\"servers\"` not `\"mcpServers\"`):\n\n```json\n{\n \"servers\": {\n \"docs\": {\n \"command\": \"gnosis-mcp\",\n \"args\": [\"serve\"]\n }\n }\n}\n```\n\nAlso discoverable via the VS Code MCP gallery — search `@mcp gnosis` in the Extensions view.\n\n

\n\n## Transport\n\nStdio (default) spawns one server per editor session — simplest. HTTP shares one process across every client so the DB, embedding cache, and file watcher stay in sync across sessions:\n\n```bash\ngnosis-mcp serve --transport streamable-http --host 0.0.0.0 --port 8000\n```\n\n```json\n{ \"mcpServers\": { \"docs\": { \"type\": \"url\", \"url\": \"http://127.0.0.1:8000/mcp\" } } }\n```\n\nPick HTTP for multi-session agent setups (Claude Code with agent teams, parallel terminals, CI). Full write-up: **[gnosismcp.com/doc/docs/deployment](https://gnosismcp.com/doc/docs/deployment)**.\n\n## REST API\n\n> v0.10.0+ — HTTP endpoints alongside MCP on the same port.\n\n```bash\ngnosis-mcp serve --transport streamable-http --rest\n```\n\n| Endpoint | Returns |\n|----------|---------|\n| `GET /health` | status, version, distinct-doc + chunk counts |\n| `GET /api/search?q=` | hybrid search (auto-embeds with `local` provider) |\n| `GET /api/docs/{path}` | full document |\n| `GET /api/docs/{path}/related` | graph neighbours |\n| `GET /api/categories` | category → doc count |\n| `GET /api/context?topic=` | usage-weighted topic primer |\n| `GET /api/graph/stats` | orphans, hubs, relation distribution |\n| `POST /v1/embed` | OpenAI-compatible embeddings (`v0.14.0+`) — `{texts, model?}` → `{model, dim, vectors, usage}` |\n\nCORS, Bearer auth, custom public-path allowlist — full reference: **[`docs/rest-api.md`](https://github.com/nicholasglazer/gnosis-mcp/blob/main/docs/rest-api.md)** · **[gnosismcp.com/doc/docs/rest-api](https://gnosismcp.com/doc/docs/rest-api)**.\n\n### Self-hosted embeddings service (v0.14.0+)\n\n`POST /v1/embed` turns gnosis-mcp into a drop-in OpenAI-shaped embeddings backend. Point any client that already speaks the `/v1/embeddings` shape at your gnosis-mcp instance — your hardware, your model choice, no per-token bills:\n\n```bash\ncurl -X POST http://localhost:8000/v1/embed \\\n -H \"Authorization: Bearer $GNOSIS_MCP_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"texts\": [\"hello\", \"hola\"], \"model\": \"intfloat/multilingual-e5-large\"}'\n```\n\nPick your model with `GNOSIS_MCP_EMBED_MODEL` (default `MongoDB/mdbr-leaf-ir`):\n- `MongoDB/mdbr-leaf-ir` — 23M params, #1 MTEB ≤100M, English-specialised\n- `intfloat/multilingual-e5-large` — 560M, 100+ languages\n- `BAAI/bge-m3` — 568M, multilingual, dense + sparse hybrid\n\nLimits: 256 texts × 50 KB per request. Same Bearer auth as the rest of the REST API.\n\n## Backends\n\n| | SQLite (default) | SQLite + embeddings | PostgreSQL |\n|---|---|---|---|\n| **Install** | `pip install gnosis-mcp` | `pip install gnosis-mcp[embeddings]` | `pip install gnosis-mcp[postgres]` |\n| **Config** | Nothing | Nothing | Set `GNOSIS_MCP_DATABASE_URL` |\n| **Search** | FTS5 keyword (BM25) | Hybrid keyword + semantic (RRF) | tsvector + pgvector hybrid |\n| **Embeddings** | None | Local ONNX (23MB, no API key) | Any provider + HNSW index |\n| **Multi-table** | No | No | Yes (`UNION ALL`) |\n| **Best for** | Quick start, keyword-only | Semantic search without a server | Production, large doc sets |\n\n**Auto-detection:** Set `GNOSIS_MCP_DATABASE_URL` to `postgresql://...` and it uses PostgreSQL. Don't set it and it uses SQLite. Override with `GNOSIS_MCP_BACKEND=sqlite|postgres`.\n\n

PostgreSQL setup

\n\n```bash\npip install gnosis-mcp[postgres]\nexport GNOSIS_MCP_DATABASE_URL=\"postgresql://user:pass@localhost:5432/mydb\"\ngnosis-mcp init-db # create tables + indexes\ngnosis-mcp ingest ./docs/ # load your markdown\ngnosis-mcp serve\n```\n\nFor hybrid semantic+keyword search, also enable pgvector:\n\n```sql\nCREATE EXTENSION IF NOT EXISTS vector;\n```\n\nThen backfill embeddings:\n\n```bash\ngnosis-mcp embed # via OpenAI (default)\ngnosis-mcp embed --provider ollama # or use local Ollama\n```\n\n

\n\n## Claude Code Plugin\n\nFor Claude Code users, install as a plugin to get the MCP server plus slash commands:\n\n```bash\nclaude plugin marketplace add nicholasglazer/gnosis-mcp\nclaude plugin install gnosis\n```\n\nThis gives you:\n\n| Component | What you get |\n|-----------|-------------|\n| **MCP server** | `gnosis-mcp serve` — auto-configured, search tools in every chat |\n| **`/gnosis:setup`** | First-time wizard: install → init-db → ingest → wire your editor |\n| **`/gnosis:ingest`** | Bulk ingest (files, git history, web crawl) + re-ingest + prune |\n| **`/gnosis:search`** | Keyword / hybrid / git-history search, formatted output |\n| **`/gnosis:manage`** | Single-file CRUD — add, delete, update metadata |\n| **`/gnosis:tune`** | Chunk-size sweep against your own golden queries |\n| **`/gnosis:eval`** | Single-shot retrieval quality check with baseline tracking |\n| **`/gnosis:context`** | Usage-weighted topic primer for session startup |\n| **`/gnosis:status`** | Connectivity, schema, corpus health diagnostic |\n| 5 subagents | `doc-explorer`, `doc-keeper`, `corpus-sync`, `context-loader`, `doc-reviewer` |\n\nThe plugin works with both SQLite and PostgreSQL backends. Prefer manual copy-paste over the plugin marketplace? See [`llms-install.md`](https://github.com/nicholasglazer/gnosis-mcp/blob/main/llms-install.md) Path B.\n\n

Manual setup (without plugin)

\n\nAdd to `.claude/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"gnosis\": {\n \"command\": \"gnosis-mcp\",\n \"args\": [\"serve\"]\n }\n }\n}\n```\n\nFor PostgreSQL, add `\"env\": {\"GNOSIS_MCP_DATABASE_URL\": \"postgresql://...\"}`.\n\n

\n\n## Tools & Resources\n\nGnosis MCP exposes 9 tools and 3 resources over [MCP](https://modelcontextprotocol.io/). Your AI agent calls these automatically when it needs information from your docs.\n\n| Tool | What it does | Mode |\n|------|-------------|------|\n| `search_docs` | Search by keyword or hybrid semantic+keyword | Read |\n| `get_doc` | Retrieve a full document by path | Read |\n| `get_related` | Find linked/related documents (multi-hop, relation type filtering) | Read |\n| `search_git_history` | Search indexed git commit history | Read |\n| `get_context` | Usage-weighted context summary | Read |\n| `get_graph_stats` | Knowledge graph topology: orphans, hubs, relation distribution | Read |\n| `upsert_doc` | Create or replace a document | Write |\n| `delete_doc` | Remove a document and its chunks | Write |\n| `update_metadata` | Change title, category, tags | Write |\n\nRead tools are always available. Write tools require `GNOSIS_MCP_WRITABLE=true`.\n\n| Resource URI | Returns |\n|-----|---------|\n| `gnosis://docs` | All documents — path, title, category, chunk count |\n| `gnosis://docs/{path}` | Full document content |\n| `gnosis://categories` | Categories with document counts |\n\n### How search works\n\n```bash\n# Keyword search — works on both SQLite and PostgreSQL\ngnosis-mcp search \"stripe webhook\"\n\n# Hybrid search — keyword + semantic (requires [embeddings] or pgvector)\ngnosis-mcp search \"how does billing work\" --embed\n\n# Filtered — narrow results to a specific category\ngnosis-mcp search \"auth\" -c guides\n```\n\nWhen called via MCP, the agent passes a `query` string for keyword search. With embeddings configured, search automatically combines keyword and semantic results using Reciprocal Rank Fusion. Results include a `highlight` field with matched terms in `` tags.\n\n### Context Loading\n\nThe `get_context` tool provides usage-weighted document summaries — ideal for session startup or \"what matters most?\" queries.\n\n```bash\n# Most-accessed docs (no topic)\nget_context(limit=10)\n\n# Topic-focused with access enrichment\nget_context(topic=\"deployment\", category=\"guides\")\n```\n\nBehind the scenes, Gnosis tracks which documents are accessed via `search_docs` and `get_doc`, then uses access frequency to rank importance. Disable tracking with `GNOSIS_MCP_ACCESS_LOG=false`.\n\n### Graph & Links\n\nGnosis automatically extracts links from your documentation — both frontmatter `relates_to` declarations and markdown links in content. Use the graph tools to explore connections:\n\n```bash\n# Direct neighbors\nget_related(\"guides/auth.md\")\n\n# Multi-hop traversal (2 levels deep, with titles)\nget_related(\"guides/auth.md\", depth=2, include_titles=True)\n\n# Filter out noisy git history links\nget_related(\"guides/auth.md\", relation_type=\"relates_to\")\n\n# Graph topology: find orphans and hubs\nget_graph_stats()\n```\n\n**Relation types:** `related` (default frontmatter), `content_link` (body markdown links + `[[wikilinks]]`), `git_co_change` (commit co-occurrence), `git_ref` (git history → source file). Plus 16 typed edges via the `relations:` frontmatter block: `prerequisite`, `depends_on`, `summarizes` / `summarized_by`, `extends` / `extended_by`, `replaces` / `replaced_by`, `audited_by` / `audits`, `implements` / `implemented_by`, `tests` / `tested_by`, `example_of`, `references`.\n\n## Embeddings\n\nEmbeddings enable semantic search — finding docs by meaning, not just keywords.\n\n**Local ONNX (recommended)** — zero-config, no API key:\n\n```bash\npip install gnosis-mcp[embeddings]\ngnosis-mcp ingest ./docs/ --embed # ingest + embed in one step\ngnosis-mcp embed # or embed existing chunks separately\n```\n\nUses [MongoDB/mdbr-leaf-ir](https://huggingface.co/MongoDB/mdbr-leaf-ir) (~23MB quantized, Apache 2.0). Auto-downloads on first run.\n\n**Remote providers** — OpenAI, Ollama, or any OpenAI-compatible endpoint:\n\n```bash\ngnosis-mcp embed --provider openai # requires GNOSIS_MCP_EMBED_API_KEY\ngnosis-mcp embed --provider ollama # uses local Ollama server\n```\n\n**Pre-computed vectors** — pass `embeddings` to `upsert_doc` or `query_embedding` to `search_docs` from your own pipeline.\n\n## Configuration\n\nNothing required for SQLite — zero config works. Override via `GNOSIS_MCP_*` env vars. Most-used:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `GNOSIS_MCP_DATABASE_URL` | SQLite auto | PostgreSQL URL or SQLite file path |\n| `GNOSIS_MCP_WRITABLE` | `false` | Enable `upsert_doc` / `delete_doc` / `update_metadata` |\n| `GNOSIS_MCP_EMBED_PROVIDER` | unset | `local` turns on hybrid search (needs `[embeddings]` extra) |\n| `GNOSIS_MCP_COLLAPSE_BY_DOC` | `false` | Dedup top-K by file_path (+2 nDCG on mixed corpora) |\n| `GNOSIS_MCP_RERANK_ENABLED` | `false` | Cross-encoder rerank — **test first**, hurts dev-docs |\n\nFull list (~40 variables covering embeddings, crawl, REST, column overrides, webhooks, logging): **[`docs/config.md`](https://github.com/nicholasglazer/gnosis-mcp/blob/main/docs/config.md)** · browsable at **[gnosismcp.com/doc/docs/config](https://gnosismcp.com/doc/docs/config)**.\n\n

Custom search function (PostgreSQL)

\n\nDelegate search to your own PostgreSQL function for custom ranking:\n\n```sql\nCREATE FUNCTION my_schema.my_search(\n p_query_text text,\n p_categories text[],\n p_limit integer\n) RETURNS TABLE (\n file_path text, title text, content text,\n category text, combined_score double precision\n) ...\n```\n\n```bash\nGNOSIS_MCP_SEARCH_FUNCTION=my_schema.my_search\n```\n\n

\n\n

Multi-table mode (PostgreSQL)

\n\nQuery across multiple doc tables:\n\n```bash\nGNOSIS_MCP_CHUNKS_TABLE=documentation_chunks,api_docs,tutorial_chunks\n```\n\nAll tables must share the same schema. Reads use `UNION ALL`. Writes target the first table.\n\n

\n\n

CLI reference

\n\n```\ngnosis-mcp ingest [--dry-run] [--force] [--embed] [--prune] [--wipe] [--include-crawled]\ngnosis-mcp ingest-git [--since] [--until] [--author] [--max-commits-per-file]\n [--include] [--exclude] [--include-merges]\n [--dry-run] [--force] [--embed]\ngnosis-mcp crawl [--sitemap] [--max-depth N] [--include] [--exclude] [--max-pages N]\n [--dry-run] [--force] [--embed]\ngnosis-mcp serve [--transport stdio|sse|streamable-http] [--host HOST] [--port PORT]\n [--ingest PATH] [--watch PATH] [--rest]\ngnosis-mcp search [-n LIMIT] [-c CAT] [--embed] Search docs\ngnosis-mcp stats Document, chunk, and embedding counts\ngnosis-mcp check Verify DB connection + extensions\ngnosis-mcp embed [--provider P] [--model M] [--batch-size N] [--dry-run]\ngnosis-mcp init-db [--dry-run] Create tables + indexes\ngnosis-mcp export [-f json|markdown] [-c CAT] Export documents\ngnosis-mcp diff Preview changes on re-ingest\ngnosis-mcp prune [--dry-run] [--include-crawled] Delete chunks for missing files\ngnosis-mcp cleanup [--days N] Purge old access log entries\ngnosis-mcp eval [--json] Retrieval quality harness (Hit@5, MRR, P@5)\ngnosis-mcp fix-link-types Migrate pre-0.10 git-history links\n```\n\n

\n\n

How ingestion works

\n\n`gnosis-mcp ingest` scans a directory for supported files and loads them into the database:\n\n- **Multi-format** — Markdown native; `.txt`, `.ipynb`, `.toml`, `.csv`, `.json` auto-converted. Optional: `.rst` (`[rst]` extra), `.pdf` (`[pdf]` extra)\n- **Smart chunking** — splits by H2 headings (H3/H4 for oversized sections), never splits inside code blocks or tables\n- **Frontmatter** — extracts `title`, `category`, `audience`, `tags` from YAML frontmatter\n- **Auto-linking** — `relates_to` in frontmatter creates bidirectional links for `get_related`\n- **Auto-categorization** — infers category from parent directory name\n- **Incremental** — content hashing skips unchanged files (`--force` to override)\n- **Watch mode** — `gnosis-mcp serve --watch ./docs/` auto-re-ingests on changes\n\n

\n\n

Architecture

\n\n```\nsrc/gnosis_mcp/\n├── backend.py DocBackend protocol + create_backend() factory\n├── pg_backend.py PostgreSQL — asyncpg, tsvector, pgvector\n├── sqlite_backend.py SQLite — aiosqlite, FTS5, sqlite-vec hybrid search (RRF)\n├── sqlite_schema.py SQLite DDL — tables, FTS5, triggers, vec0 virtual table\n├── config.py Config from env vars, backend auto-detection\n├── db.py Backend lifecycle + FastMCP lifespan\n├── server.py FastMCP server — 9 tools, 3 resources, auto-embed queries\n├── ingest.py File scanner + converters — multi-format, smart chunking\n├── crawl.py Web crawler — sitemap/BFS, robots.txt, ETag caching\n├── parsers/ Non-file ingest sources (git history, future: schemas)\n│ └── git_history.py Git log → markdown documents per file\n├── watch.py File watcher — mtime polling, auto-re-ingest\n├── schema.py PostgreSQL DDL — tables, indexes, search functions\n├── embed.py Embedding providers — OpenAI, Ollama, custom, local ONNX\n├── local_embed.py Local ONNX embedding engine — HuggingFace model download\n└── cli.py CLI — serve, ingest, crawl, search, embed, stats, check, cleanup\n```\n\n

\n\n## Available On\n\n[MCP Registry](https://registry.modelcontextprotocol.io) (feeds VS Code MCP gallery and GitHub Copilot) · [PyPI](https://pypi.org/project/gnosis-mcp/) · [mcp.so](https://mcp.so) · [Glama](https://glama.ai) · [cursor.directory](https://cursor.directory)\n\n## AI-Friendly Docs\n\n| File | Purpose |\n|------|---------|\n| [`llms.txt`](https://github.com/nicholasglazer/gnosis-mcp/blob/main/llms.txt) | Quick overview — what it does, tools, config |\n| [`llms-full.txt`](https://github.com/nicholasglazer/gnosis-mcp/blob/main/llms-full.txt) | Complete reference in one file |\n| [`llms-install.md`](https://github.com/nicholasglazer/gnosis-mcp/blob/main/llms-install.md) | Step-by-step installation guide |\n\n## Development\n\n```bash\ngit clone https://github.com/nicholasglazer/gnosis-mcp.git\ncd gnosis-mcp\npython -m venv .venv && source .venv/bin/activate\npip install -e \".[dev]\"\npytest # 632 tests, no database needed\nruff check src/ tests/\n```\n\nAll tests run without a database. Keep it that way.\n\nGood first contributions: new embedding providers, export formats, ingestion for new file types (via optional extras). Open an issue first for larger changes.\n\n## Sponsors\n\nIf Gnosis MCP saves you time, consider [sponsoring the project](https://github.com/sponsors/nicholasglazer).\n\n## License\n\n[MIT](https://github.com/nicholasglazer/gnosis-mcp/blob/main/LICENSE)\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"iconType","image","upstream",{"_110":111,"_112":113,"_114":115,"_116":117,"_118":119,"_120":121},"requiredSecrets",[],"tags",[96,97,98,99,100,101,102,103,104,105,106,107,108,109],"assets",[],"stats",{"_94":81,"_95":81},"ratingAvg","reviewCount","ai","claude","developer-tools","documentation","knowledge-base","llm","pgvector","postgresql","python","rag","search","self-hosted","sqlite","vector-search","topics",[96,97,98,99,100,101,126,127,128,102,103,104,105,106,107,108,109],"license","MIT","language","Python","registryName","io.github.nicholasglazer/gnosis","homepage","https://gnosismcp.com","packages",[122],{"_123":124,"_125":21,"_71":72},"registryType","pypi","identifier","mcp","mcp-server","model-context-protocol","ENV",{"_131":132,"_133":134,"_135":136},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]