# Gnosis MCP

> Zero-config MCP server for searchable documentation (SQLite default, PostgreSQL optional)

## Overview

Gnosis MCP loads your markdown docs into a database and exposes them as Model Context Protocol (MCP) tools and resources. 6 tools and 3 resources for AI agents to search, retrieve, browse, and manage documentation. Works immediately with SQLite — no database server needed. Upgrade to PostgreSQL + pgvector for hybrid semantic search.

## Tools

### Read Tools (always available)

#### search_docs(query: str, category?: str, limit?: int, query_embedding?: list[float]) -> JSON
Search documentation using keyword (FTS5/tsvector) or hybrid semantic+keyword search.
When `query_embedding` is provided (PostgreSQL), combines keyword and cosine similarity scoring.
Returns: `[{"file_path", "title", "content_preview", "score"}]`

#### get_doc(path: str, max_length?: int) -> JSON
Retrieve full document by file path. Reassembles chunks in order.
Returns: `{"title", "content", "category", "audience", "tags"}`

#### get_related(path: str) -> JSON
Find related documents via bidirectional link graph.
Returns: `[{"related_path", "relation_type", "direction"}]`

### Write Tools (requires GNOSIS_MCP_WRITABLE=true)

#### upsert_doc(path: str, content: str, title?: str, category?: str, audience?: str, tags?: list, embeddings?: list[list[float]]) -> JSON
Insert or replace a document. Auto-splits into chunks at paragraph boundaries.
Optional `embeddings` parameter accepts pre-computed vectors (one per chunk).
Returns: `{"path", "chunks", "action": "upserted"}`

#### delete_doc(path: str) -> JSON
Delete a document and all its chunks + related links.
Returns: `{"path", "chunks_deleted", "links_deleted", "action": "deleted"}`

#### update_metadata(path: str, title?: str, category?: str, audience?: str, tags?: list) -> JSON
Update metadata on all chunks of a document. Only provided fields change.
Returns: `{"path", "chunks_updated", "action": "metadata_updated"}`

## Resources

- `gnosis://docs` -- list all documents (path, title, category, chunk count)
- `gnosis://docs/{path}` -- read document content by path
- `gnosis://categories` -- list categories with doc counts

## Backends

| | SQLite (default) | PostgreSQL |
|---|---|---|
| Install | `pip install gnosis-mcp` | `pip install gnosis-mcp[postgres]` |
| Config | Nothing | Set `DATABASE_URL` |
| Search | FTS5 keyword (BM25) | tsvector + pgvector hybrid |

Auto-detection: `DATABASE_URL` set to `postgresql://...` → PostgreSQL. Not set → SQLite at `~/.local/share/gnosis-mcp/docs.db`. Override: `GNOSIS_MCP_BACKEND=sqlite|postgres`.

## Configuration

Set `GNOSIS_MCP_DATABASE_URL` (or `DATABASE_URL`) for PostgreSQL. Leave unset for SQLite. Optional: `GNOSIS_MCP_BACKEND`, `GNOSIS_MCP_SCHEMA`, `GNOSIS_MCP_CHUNKS_TABLE` (comma-separated for multi-table on PG), `GNOSIS_MCP_LINKS_TABLE`, `GNOSIS_MCP_SEARCH_FUNCTION`, `GNOSIS_MCP_EMBEDDING_DIM`, `GNOSIS_MCP_WRITABLE`, `GNOSIS_MCP_WEBHOOK_URL`, `GNOSIS_MCP_COL_*` for column names. Embedding: `GNOSIS_MCP_EMBED_PROVIDER` (openai/ollama/custom), `GNOSIS_MCP_EMBED_MODEL`, `GNOSIS_MCP_EMBED_API_KEY`, `GNOSIS_MCP_EMBED_URL`, `GNOSIS_MCP_EMBED_BATCH_SIZE`. Tuning: `GNOSIS_MCP_CONTENT_PREVIEW_CHARS`, `GNOSIS_MCP_CHUNK_SIZE`, `GNOSIS_MCP_SEARCH_LIMIT_MAX`, `GNOSIS_MCP_WEBHOOK_TIMEOUT`, `GNOSIS_MCP_TRANSPORT`, `GNOSIS_MCP_LOG_LEVEL`.

## Database Schema

Chunks table: `(file_path, chunk_index, title, content, category, audience, tags, embedding, content_hash)`
Links table: `(source_path, target_path, relation_type)`

Run `gnosis-mcp init-db` to create tables manually, or `gnosis-mcp init-db --dry-run` to preview SQL. Tables are also auto-created on first `ingest`.

## Quick Start

```bash
pip install gnosis-mcp
gnosis-mcp ingest ./docs/       # auto-creates database + loads markdown
gnosis-mcp search "getting started"
gnosis-mcp serve
```

## Documentation

- [README](README.md): Install, quickstart, config, tools reference, examples
- [CLAUDE.md](CLAUDE.md): Architecture, design decisions, rules
- [llms-full.txt](llms-full.txt): Complete reference in one file
- [llms-install.md](llms-install.md): Step-by-step install guide
