# Gnosis MCP

> Zero-config MCP server that makes your markdown docs searchable by AI agents.
> SQLite default, PostgreSQL optional. Works with Claude Code, Cursor, Windsurf, Cline.

## What it does

Gnosis MCP loads markdown files into a database, chunks them by H2 headings, and exposes them as MCP tools and resources. AI agents call `search_docs` to find relevant documentation instead of guessing or reading entire files.

## Quick Start

```bash
pip install gnosis-mcp
gnosis-mcp ingest ./docs/       # auto-creates SQLite database + loads markdown
gnosis-mcp serve                # start MCP server
```

Add to your editor's MCP config (e.g. `.claude/mcp.json` for Claude Code):

```json
{
  "mcpServers": {
    "docs": {
      "command": "gnosis-mcp",
      "args": ["serve"]
    }
  }
}
```

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

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

## Editor Config Locations

| Editor | Config Path |
|--------|------------|
| Claude Code | `.claude/mcp.json` |
| Cursor | `.cursor/mcp.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| Cline | Cline MCP settings panel |

## Documentation

- [README](README.md): Quick start, editor setup, backend comparison, configuration
- [llms-full.txt](llms-full.txt): Complete reference in one file
- [llms-install.md](llms-install.md): Step-by-step install guide
