WebAuthn规范检索服务

WebAuthn MCP（本地RAG）

一个专注于WebAuthn规范的本地、仅供检索的MCP服务器。它抓取规范，提取和清理内容，使用节感知进行块化，在本地嵌入（默认情况下为CPU），存储在持久向量数据库中，并公开一个名为 ask 用于语义检索。

默认情况下不需要外部LLM或API密钥。

几分钟后开始

1. 安装依赖项

• python-m venv.venv
• source.venv/bin/activate（Windows:.venv\Scripts\activate）
• pip安装-U pip
• pip安装-r要求.txt

1. 配置

• cp.env示例.env
• 设置为最小值：WEBAUTHN_SPEC_URL和VECTOR_DB_DIR

1. 构建/刷新索引

• python-m webauthn_mcp.cli构建索引--日志级别信息
• 可选的模拟运行：python-m webauthn_mcp.cli构建索引--模拟运行
• 在VECTOR_DB_DIR/INDEX_NAME/INDEX_VERSION/Manifest.json下编写的清单

1. 运行MCP服务器（选择一个）

• Stdio（默认）：python-m webauthn_mcp.cli服务
• 或者：python服务器.py
• HTTP（可通过FastMCP流式传输）：python-m webauthn_mcp.cli提供HTTP服务

1. 通过MCP客户端使用ask工具示例有效载荷：{“prompt”：“WebAuthn注册仪式是如何定义的？”，“top_k”：5，“include_sippets”：true}

特性

• 本地爬虫（BFS），具有：
  • .env配置
  • 尊重robots.txt（可选）
  • 礼貌并发，429/503的重试/回退，重试后+抖动
  • 每台主机的最小延迟和robots.txt抓取延迟支持
  • URL片段规范化以避免重复的锚点获取
  • ETag/上次修改的条件请求
  • 增量爬网缓存（URL元数据、内容哈希、时间戳）
• 内容物提取和清洁：
  • 特拉法图拉（如有）；BeautifulSoup可读性像回退
  • 删除导航/样板；保留标题、锚点、列表、代码、表格
  • 规范化空白，将相对链接转换为绝对链接
• 分段感知分块：
  • 按标题拆分，然后按段落拆分，目标为~800个标记和约120个重叠
  • 尽可能保持代码块完整
  • 稳定的块指纹用于跨运行的重复数据删除
• 本地嵌入和持久化：
  • 默认情况下为句子转换器（例如，全MiniLM-L6-v2或BAAI/bge小en）
  • 嵌入基于块指纹和模型的缓存
  • 持久向量存储：Chroma（默认），带FAISS回退
• 回收管道：
  • 查询规范化和扩展（缩略语、标题提示）
  • 具有MMR多样性的ANN；可选的本地交叉编码器重排
  • 重复数据消除，按分数稳定排序
• MCP工具：
  • ask：仅检索，返回结构化段落/片段
  • 验证输入，限制速率以防止滥用
• 索引命令：
  • 端到端构建或刷新索引
  • 模拟运行支持和统计数据清单
• 质量：
  • 重复和近似重复抑制（内容哈希+SimHash）
  • Unicode规范化和样板删除
  • WebAuthn术语的可选缩写扩展

需求

• Python 3.10+
• macOS、Linux或Windows
• 不需要GPU（默认情况下只需要CPU）

安装依赖项：

python -m venv .venv
. .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -U pip
pip install -r requirements.txt

关键包： mcp, fastmcp, httpx, beautifulsoup4, lxml, trafilatura, sentence-transformers, chromadb, faiss-cpu, pytest.

HTTPX基线

• 基线：httpx>=0.28.1。不需要其他兼容性配置文件。

配置

复制 .env-example 向 .env 并进行调整。所需密钥：

• WEBAUTHN_SPEC_URL：要抓取的根URL（例如。，https://www.w3.org/TR/webauthn/)
• VECTOR_DB_DIR：保存向量和状态的目录

推荐密钥（提供合理的默认值）：

• INDEX_NAME，INDEX_VERSION
• CRAWL_MAX_DEPTH、CRAWL_MAX-PAGES、CRAWL_CONCURRENCY、USER_AGENT、TIMEOUT_SECONDS、crawle_MIN_DELAY_SECONDS、RESPECT_ROBOTS、ALLOWED_HOSTS、included SITEMAP
• EMBEDDING_MODEL、EMBEDDING_DEVICE、embeding_BATCH_SIZE
• CHUNK_SIZE_tokes，CHUNK_OVERLAP_tokes
• 矢量背景（色度|faiss）
• RERANKER_MODEL（可选）
• ASK_RPM、ASK_BURST（速率限制）

请参阅提供的 .env-example 了解详情。

构建或刷新索引

端到端抓取/提取/组块/嵌入/追加：

python -m webauthn_mcp.cli build-index --log-level INFO

• 使用增量爬网缓存和重复数据消除的块指纹来避免重新下载或重新嵌入未更改的内容。
• 在以下位置创建或更新清单：VECTOR_DB_DIR/INDEX_NAME/INDEX_VERSION/manifest.json

试运行（无写入）：

python -m webauthn_mcp.cli build-index --dry-run

完全重建（擦除并重新嵌入）

当您想完全重新创建向量数据库时（例如，损坏、过时状态或强制重新创建），请使用此选项。

1. 停止所有正在运行的服务器

• Stdio服务器入口点： webauthn_mcp.cli.serve_cmd（）
• HTTP服务器入口点： webauthn_mcp.cli.serve_http_cmd（）

2. 删除当前索引数据（色度/FAISS+ID索引+清单）

此存储库中可见的默认索引的路径：

• vector_db/webauthn规范/v1/色度/
• vector_db/webauthn-spec/v1/ids.json
• vector_db/webauthn-spec/v1/manifest.json
• vector_db/webauthn规范/v1/faiss/ （仅当使用FAISS时）

macOS/Linux示例：

rm -rf vector_db/webauthn-spec/v1/chroma
rm -f  vector_db/webauthn-spec/v1/ids.json
rm -f  vector_db/webauthn-spec/v1/manifest.json
rm -rf vector_db/webauthn-spec/v1/faiss

3. 可选：清除缓存以强制重新计算

• 嵌入缓存： .cache/embeddings （由管理 webauthn_mcp.embeddings。嵌入模型（）)
• 爬网缓存： .cache/crawl

macOS/Linux示例：

rm -f  .cache/embeddings/cache_*.jsonl
rm -rf .cache/crawl

4. 重建索引

python -m webauthn_mcp.cli build-index --log-level INFO

5. 验证

• 打印清单： python -m webauthn_mcp.cli manifest （参见 webauthn_mcp.cli.manifest_cmd（）)
• 验证更新的文件： manifest.json, ids.json
• 如果诊断以下情况，请使用DEBUG日志： python -m webauthn_mcp.cli build-index --log-level DEBUG

笔记：

• 确保 .env VECTOR_DB_DIR、INDEX_NAME、INDEX_VERSION的值对于构建和服务都是一致的；看见 webauthn_mcp.config（）.
• ID索引防止重新扰乱现有块ID；删除 ids.json 是真正完全重建所必需的（请参见 _ID索引).
• 如果Chroma init失败，代码将自动回退到FAISS；如果切换，请清除两个后端的文件夹（请参阅 webauthn_mcp.vector_store.create_vector_store（）).

运行MCP服务器

• 通过CLI：

python -m webauthn_mcp.cli serve

• 或者使用顶级入口点：

python server.py

服务器使用官方的Python MCP库在stdio上运行，并注册了一个工具： ask.

运行 HTTP 服务器 (通过 FastMCP 流式传输 HTTP)

该项目还使用FastMCP的流式HTTP传输在HTTP服务器上公开MCP工具。这是可选的，不会取代stdio服务器。

安装：

• FastMCP包含在需求中；使用以下命令安装项目依赖项：

pip install -r requirements.txt

环境：

• 通过配置主机/端口 .env:
  • MCP_SERVER_HOST（默认值0.0.0.0）
  • MCP_SERVER_PORT（默认8080）
  • 看 .env示例

运行：

python -m webauthn_mcp.cli serve-http

可用工具：

• ask：与stdio服务器相同的仅用于检索的工具
• echo：一个简单的烟雾测试工具，用于验证HTTP端点是否可访问

笔记：

• HTTP入口点在 webauthn_mcp.mcp_http_server（） 并以如下方式连接到CLI serve-http 在……里面 webauthn_mcp.cli（）.
• FastMCP包含在基座中 需求.txt.

MCP工具：询问

• 姓名： ask
• 描述：询问有关WebAuthn的问题并检索相关规范段落
• 输入JSON：
  • 提示：字符串（必填）
  • top_k:int（可选，默认值5，有界[1，20]）
  • score_threshold：浮点数（可选）
  • include_sippets：bool（可选，默认为true）
• 输出JSON：
  • count：点击次数
  • 点击：对象列表：
    • url、title、heading_path、anchor_id、score、chunk_id、元数据
    • 当include_sippets为真时的摘录（简短突出显示的摘录）
• 行为：
  • 仅检索；不调用外部LLM
  • 如果索引为空，则返回错误，建议先运行索引器
  • 强制执行简单的利率限制

有效载荷示例：

{
  "prompt": "How is WebAuthn registration ceremony defined?",
  "top_k": 5,
  "include_snippets": true
}

示例结果（截断）：

{
  "count": 3,
  "hits": [
    {
      "url": "https://www.w3.org/TR/webauthn/#sctn-create-credential",
      "title": "Web Authentication: An API for accessing Public Key Credentials Level 3",
      "heading_path": "Registration > Ceremony",
      "anchor_id": "sctn-create-credential",
      "score": 0.78,
      "snippet": "…The **registration** **ceremony** consists of…",
      "chunk_id": "c7f4e…",
      "metadata": { "token_count": 732, "...": "..." }
    }
  ]
}

项目结构

• webauthn_mcp。初始化() --常量和助手
• webauthn_mcp.config（） --.env加载和数据类设置
• webauthn_mcp.utils（） --规范化、令牌计数、MMR、片段
• webauthn_mcp.rate_limit（） --令牌桶限制器
• webauthn_mcp.crawler（） --BFS爬虫，带机器人、ETag、缓存
• webauthn_mcp.extractor（） --trafilatura/BS提取、标题/锚
• webauthn_mcp.chunking（） --指纹识别分割器
• webauthn_mcp.embeddings（） --句子转换器+JSONL缓存
• webauthn_mcp.vector_store（） --Chroma持久商店，支持FAISS回退
• webauthn_mcp.retrieve（） --语义搜索、MMR、可选重新排序
• webauthn_mcp.indexer（） --端到端管道、清单
• webauthn_mcp.mcp_server（） --MCP服务器接线和 ask 工具
• webauthn_mcp.cli（） --CLI命令
• 服务器.py --stdio MCP入口点包装器

坚持和递增

• 所有状态都位于VECTOR_DB_DIR下：
  • 色度/FAISS指数数据
  • 清单（文档/块计数、模型、时间戳）
• 爬网缓存位于 .cache/crawl 默认情况下
• 嵌入缓存位于 .cache/embeddings 默认情况下
• 通过内容哈希+块指纹进行标识索引
• 后续运行避免重新下载未更改的页面和重新嵌入未更改的块

安全可靠

• 仅检索；无生成，无外部LLM调用
• 输入验证和界限 ask
• 速率限制以保护服务器
• 网络超时和重试回退
• 启用时尊重robots.txt
• 默认情况下仅CPU执行

测试

运行测试套件：

pytest -q

套房包括：

• 块状稳定性和指纹识别
• 嵌入缓存行为（无重复追加）
• 索引幂等性（无重复异常）
• 使用合成夹具进行检索排名和片段

故障排除

• 索引为空错误：
  • 运行： python -m webauthn_mcp.cli build-index
• 首次运行缓慢：
  • 初始抓取和模型下载可能需要时间；后续运行是增量的，并已缓存
• 429爬行过程中请求过多：
  • 集 CRAWL_CONCURRENCY=1 在……里面 .env
  • 增加 CRAWL_MIN_DELAY_SECONDS 2–3
  • 保持 ALLOWED_HOSTS 最小；通过规范化消除锚点URL的重复
• 色度问题：
  • 集 VECTOR_BACKEND=faiss 在……里面 .env 强制FAISS
• Reranker不可用：
  • 离开 RERANKER_MODEL 清空以跳过重新分级

许可证

看 许可证.