Gnosis MCP

Gnosis MCP

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.

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

摄入文件→ 使用亮点搜索→ 统计数据概述→ 为AI代理服务

______________________________________________________________________

没有文档服务器

• LLM对不存在的API签名产生幻觉
• 将整个文件转储到上下文中——每个文档3000-15000个令牌
• 架构决策隐藏在数十个文件中
• 每次重复查找都会支付全部上下文成本

使用Gnosis MCP

• search_docs 回报排名，突出显示摘录——通常为300-800个代币
• 真实的答案基于你的实际文档，而不是训练数据的猜测
• 跨数百个文件的一个本地索引——即时多文档搜索
• 5-10倍代币储蓄 当你的语料库涵盖了这个问题时，每次查找

______________________________________________________________________

是什么让gnosis mcp与众不同

• 您的数据保留在您的机器上。 默认情况下是SQLite，PostgreSQL是可扩展的——没有任何东西离开主机。
• 对文档中形成的任何内容进行索引。 Markdown，git提交历史记录，抓取网站-一个索引，一个搜索API。
• 已测量，未上市。 船舶BEIR科学事实编号（0.671nDCG@10--在Lucene BM25基线的1%以内），一个可重复的eval工具(gnosis-mcp eval)，以及显示质量平台实际所在位置的块大小扫描。

完全并排与Context7/docs-mcp-server/mcp本地rag： gnosismcp.com#比较.

______________________________________________________________________

特性

• 零配置 --默认情况下为SQLite， pip install 走吧
• 混合搜索 -关键字（BM25）+语义（本地ONNX嵌入，无API密钥）。调整RRF融合 GNOSIS_MCP_RRF_K.
• 交叉编码器重新排序 --可选 [reranking] 额外配备22M参数的ONNX型号。默认情况下为关闭。 启用前在您自己的语料库上进行测试 --捆绑的MS-MARCO重新登录器在我们的测量中损害了开发文档检索。
• Git历史记录 --将提交消息作为可搜索上下文进行摄取(ingest-git)
• 网络爬行 --通过站点地图或链接抓取从任何网站获取文档
• 多格式 — .md .txt .ipynb .toml .csv .json +可选 .rst .pdf
• 自动链接 — relates_to frontmatter创建可导航的文档图
• 观看模式 --文件更改时自动重新摄取
• 修剪陈旧的文档 — gnosis-mcp ingest --prune 删除源文件已被删除的块。 --wipe 在重新摄入之前进行完全重置。
• 内置eval线束 — gnosis-mcp eval 打印Hit@K/MRR/Precision@K在一个命令中
• PostgreSQL就绪 --需要缩放时使用pgvector+tsvector

演出

快。 平均8.7 ms的MCP往返时间。700文档语料库上的混合搜索p50\ Run with Docker (zero install)

多拱形映像，约140 MB，随附本地ONNX嵌入+REST：

# Serve your ./docs on http://localhost:8000 — MCP at /mcp, REST at /api/*
docker run -p 8000:8000 \
  -v "$PWD/docs:/docs:ro" -v gnosis-data:/data \
  ghcr.io/nicholasglazer/gnosis-mcp:latest

# First-run: ingest into the persistent volume
docker run --rm \
  -v "$PWD/docs:/docs:ro" -v gnosis-data:/data \
  ghcr.io/nicholasglazer/gnosis-mcp:latest \
  ingest /docs --embed

或使用承诺 :

docker compose up -d
docker compose exec gnosis gnosis-mcp ingest /docs --embed

图片已标记 :latest, :, :, :main, :sha-.

Try without installing (uvx)

uvx gnosis-mcp ingest ./docs/
uvx gnosis-mcp serve

Web爬网

Dry-run discovery → Crawl & ingest → Search crawled docs → SSRF protection

从任何网站获取文档——无需本地文件：

pip install gnosis-mcp[web]

# Crawl via sitemap (best for large doc sites)
gnosis-mcp crawl https://docs.stripe.com/ --sitemap

# Depth-limited link crawl with URL filter
gnosis-mcp crawl https://fastapi.tiangolo.com/ --depth 2 --include "/tutorial/*"

# Preview what would be crawled
gnosis-mcp crawl https://docs.python.org/ --dry-run

# Force re-crawl + embed for semantic search
gnosis-mcp crawl https://docs.sveltekit.dev/ --sitemap --force --embed

尊重 robots.txt，使用ETag/LastModified进行增量重新爬网的缓存，以及速率限制请求（5个并发，0.2秒延迟）。被抓取的页面使用URL作为文档路径，主机名作为类别——可以像其他文档一样进行搜索。

Git历史记录

将提交消息转化为可搜索的上下文——你的代理会学习 *为什么* 东西不仅是建造出来的 *什么* 存在：

gnosis-mcp ingest-git .                                  # current repo, all files
gnosis-mcp ingest-git /path/to/repo --since 6m           # last 6 months only
gnosis-mcp ingest-git . --include "src/*" --max-commits 5 # filtered + limited
gnosis-mcp ingest-git . --dry-run                         # preview without ingesting
gnosis-mcp ingest-git . --embed                           # embed for semantic search

每个文件的提交历史记录都会变成一个可搜索的markdown文档，存储为 git-history/。代理人通过以下方式找到它 search_docs 像其他文档一样，不需要新的工具。增量重新摄取会跳过历史记录不变的文件。

编辑器集成

将服务器配置添加到编辑器中——您的AI代理将获得 search_docs, get_doc，以及 get_related 工具自动：

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

VS Code (GitHub Copilot) — slightly different key

添加 .vscode/mcp.json （注： "servers" 不 "mcpServers"):

{
  "servers": {
    "docs": {
      "command": "gnosis-mcp",
      "args": ["serve"]
    }
  }
}

也可以通过VS Code MCP库进行搜索 @mcp gnosis 在“扩展”视图中。

运输

Stdio（默认）为每个编辑器会话生成一个服务器——最简单。HTTP在每个客户端共享一个进程，因此数据库、嵌入缓存和文件监视器在会话之间保持同步：

gnosis-mcp serve --transport streamable-http --host 0.0.0.0 --port 8000

{ "mcpServers": { "docs": { "type": "url", "url": "http://127.0.0.1:8000/mcp" } } }

为多会话代理设置选择HTTP（Claude Code与代理团队、并行终端、CI）。完整报道： gnosismcp.com/doc/docs/deploy.

REST API

v0.10.0+——同一端口上MCP旁边的HTTP端点。

gnosis-mcp serve --transport streamable-http --rest

CORS、Bearer auth、自定义公共路径allowlist——完整参考： docs/rest-api.md · gnosismcp.com/doc/docs/rest-api.

后端

自动检测： 集 GNOSIS_MCP_DATABASE_URL 到 postgresql://... 它使用PostgreSQL。不要设置它，它使用SQLite。覆盖 GNOSIS_MCP_BACKEND=sqlite|postgres.

PostgreSQL setup

pip install gnosis-mcp[postgres]
export GNOSIS_MCP_DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"
gnosis-mcp init-db              # create tables + indexes
gnosis-mcp ingest ./docs/       # load your markdown
gnosis-mcp serve

对于混合语义+关键字搜索，还启用pgvector：

CREATE EXTENSION IF NOT EXISTS vector;

然后回填埋件：

gnosis-mcp embed                        # via OpenAI (default)
gnosis-mcp embed --provider ollama      # or use local Ollama

Claude代码插件

对于Claude Code用户，请作为插件安装以获取MCP服务器和斜线命令：

claude plugin marketplace add nicholasglazer/gnosis-mcp
claude plugin install gnosis

这为您提供了：

该插件适用于SQLite和PostgreSQL后端。更喜欢手动复制粘贴而不是插件市场？看 llms-install.md 路径B。

Manual setup (without plugin)

添加 .claude/mcp.json:

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

对于PostgreSQL，添加 "env": {"GNOSIS_MCP_DATABASE_URL": "postgresql://..."}.

工具和资源

Gnosis MCP公开了9个工具和3个资源 主控程序。当您的AI代理需要您的文档中的信息时，它会自动调用这些。

读取工具始终可用。需要编写工具 GNOSIS_MCP_WRITABLE=true.

搜索是如何工作的

# Keyword search — works on both SQLite and PostgreSQL
gnosis-mcp search "stripe webhook"

# Hybrid search — keyword + semantic (requires [embeddings] or pgvector)
gnosis-mcp search "how does billing work" --embed

# Filtered — narrow results to a specific category
gnosis-mcp search "auth" -c guides

当通过MCP调用时，代理会传递 query 用于关键字搜索的字符串。配置嵌入后，搜索将使用往复式排名融合自动组合关键字和语义结果。结果包括a highlight 字段中有匹配的术语 `` 标签。

上下文加载

这 get_context 该工具提供使用加权文档摘要，非常适合会话启动或“什么最重要？”查询。

# Most-accessed docs (no topic)
get_context(limit=10)

# Topic-focused with access enrichment
get_context(topic="deployment", category="guides")

在幕后，Gnosis跟踪哪些文档是通过以下方式访问的 search_docs 和 get_doc，然后使用访问频率对重要性进行排名。禁用跟踪 GNOSIS_MCP_ACCESS_LOG=false.

图表和链接

Gnosis会自动从您的文档中提取链接——包括frontmatter relates_to 内容中的声明和markdown链接。使用图形工具探索连接：

# Direct neighbors
get_related("guides/auth.md")

# Multi-hop traversal (2 levels deep, with titles)
get_related("guides/auth.md", depth=2, include_titles=True)

# Filter out noisy git history links
get_related("guides/auth.md", relation_type="relates_to")

# Graph topology: find orphans and hubs
get_graph_stats()

关系类型： related （默认封面）， content_link （车身标记链接+ [[wikilinks]]), git_co_change （提交共现）， git_ref （git历史→ 源文件）。通过 relations: 前体块： prerequisite, depends_on, summarizes / summarized_by, extends / extended_by, replaces / replaced_by, audited_by / audits, implements / implemented_by, tests / tested_by, example_of, references.

嵌入

嵌入支持语义搜索——按含义查找文档，而不仅仅是关键字。

本地ONNX（推荐） -零配置，无API密钥：

pip install gnosis-mcp[embeddings]
gnosis-mcp ingest ./docs/ --embed       # ingest + embed in one step
gnosis-mcp embed                        # or embed existing chunks separately

用途 MongoDB/mdbr叶ir （约23MB量化，Apache 2.0）。首次运行时自动下载。

远程提供商 --OpenAI、Ollama或任何与OpenAI兼容的端点：

gnosis-mcp embed --provider openai      # requires GNOSIS_MCP_EMBED_API_KEY
gnosis-mcp embed --provider ollama      # uses local Ollama server

预先计算的向量 --通行证 embeddings 到 upsert_doc 或 query_embedding 到 search_docs 从你自己的管道。

配置

SQLite不需要任何东西——零配置有效。通过以下方式覆盖 GNOSIS_MCP_* env变量。最常用的：

完整列表（约40个变量，涵盖嵌入、爬网、REST、列重写、Webhook、日志记录）： docs/config.md ·可浏览 gnosismcp.com/doc/docs/config.

Custom search function (PostgreSQL)

将搜索委托给您自己的PostgreSQL函数进行自定义排名：

CREATE FUNCTION my_schema.my_search(
    p_query_text text,
    p_categories text[],
    p_limit integer
) RETURNS TABLE (
    file_path text, title text, content text,
    category text, combined_score double precision
) ...

GNOSIS_MCP_SEARCH_FUNCTION=my_schema.my_search

Multi-table mode (PostgreSQL)

跨多个单据表查询：

GNOSIS_MCP_CHUNKS_TABLE=documentation_chunks,api_docs,tutorial_chunks

所有表必须共享相同的架构。阅读使用 UNION ALL.写入目标为第一个表。

CLI reference

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

How ingestion works

gnosis-mcp ingest 扫描目录中支持的文件并将其加载到数据库中：

• 多格式 --Markdown原生； .txt, .ipynb, .toml, .csv, .json 自动转换。可选： .rst ([rst] 额外）， .pdf ([pdf] 额外）
• 智能分块 --按H2标题拆分（H3/H4用于超大部分），从不在代码块或表内拆分
• 前言 --提取物 title, category, audience, tags 来自YAML frontmatter
• 自动链接 — relates_to 在frontmatter中创建双向链接 get_related
• 自动分类 --从父目录名称推断类别
• 增量 --内容哈希跳过未更改的文件(--force 覆盖）
• 观看模式 — gnosis-mcp serve --watch ./docs/ 自动重新接收更改

Architecture

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

可用的

AI友好文档

发展

git clone https://github.com/nicholasglazer/gnosis-mcp.git
cd gnosis-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest                    # 632 tests, no database needed
ruff check src/ tests/

所有测试都在没有数据库的情况下运行。保持这种状态。

良好的初步贡献：新的嵌入提供者、导出格式、新文件类型的摄取（通过可选的额外功能）。首先打开一个问题以进行更大的更改。

赞助商

如果Gnosis MCP为您节省了时间，请考虑 赞助该项目.

许可证

麻省理工学院