S N A P

SNAP-MCP服务器

S午睡 N笔记本 A.停留 P存在

代码分析管道通过模型上下文协议（MCP）公开快照类型。将代码、文档、数据和配置文件解析为结构化的数据库快照，以便进行有针对性的人工智能检索。

______________________________________________________________________

目录

• 快速开始
• 代理和客户端设置
• LLM权限模型
• 代理工作流
• 二进制文件头
• Nim解析器
• 管理员CLI
• 可用的MCP工具
• 快照类型
• 存储体系结构
• 配置
• 日志记录
• 建筑
• 安全
• 需求
• 故障排除

______________________________________________________________________

快速开始

SNAP是作为一个自包含的二进制文件分发的，不需要安装Python。

______________________________________________________________________

二进制安装

1.下载二进制文件

从以下网址下载适用于您平台的二进制文件 最新版本:

将二进制文件放在您选择的目录中，例如。 C:\Users\\snap\.

在Linux/macOS上，使其可执行：

chmod +x snap-mcp

所有解析器（Nim、tree sitter、semgrep）都是捆绑的，不需要额外安装。

2.创建数据目录结构

mkdir -p data/logs data/staging data/repos data/projects

3.配置环境

创建一个 .env 文件与二进制文件位于同一目录中：

# SQLite is the default — no additional setup required
SNAP_DB_MODE=sqlite
SNAP_SQLITE_PATH=data/snap.db

# Optional: PostgreSQL
# SNAP_DB_MODE=postgres
# SNAP_POSTGRES_DSN=postgresql://user:pass@localhost:5432/snap

# Logging
SNAP_LOG_LEVEL=INFO
SNAP_LOG_JSON=true

4.验证

# Windows
snap-mcp.exe --help

# Linux / macOS
./snap-mcp --help

______________________________________________________________________

企业/源访问

企业许可和源访问查询： cll.automata@outlook.com

______________________________________________________________________

代理和客户端设置

看 agent_setups.md 有关Claude Code、Claude Desktop、GitHub Copilot Chat、HTTP+SSE和Azure云部署的设置指南。

______________________________________________________________________

LLM权限模型

LLM在运行时具有严格限制的权利 app/mcp/tools.py --不是按照惯例或文件字符串。

允许--无需批准

DB快照只读。LLM从不读取原始文件。

每次通话都需要明确的用户批准

不允许——立即加薪

不允许的操作

LLM从不：读取原始文件、读取GitHub原始内容、摄取文件、排序/过滤文件或处理文件。SNAP完成了这一切。

______________________________________________________________________

代理工作流

SNAP是摄取引擎。LLM阶段内容——SNAP摄取它。

GitHub 仓库

LLM: clone_to_repos(repo_url, vendor_id)
    └─► Clones into repos/{project_id}/. project_id = repo name, derived by SNAP.
SNAP: auto-ingests in background thread → stores in DB → clears repos/
LLM (on request): query_snapshots / get_project_notebook

本地项目

LLM: copy_to_staging(project_id, source_path)
    └─► Copies files to staging/{project_id}/. Returns immediately.
SNAP: auto-ingests in background thread → stores in DB → clears staging/
LLM (on request): query_snapshots / get_project_notebook

规则：

• LLM stages ONE操作：克隆触发器（GitHub）或暂存副本（本地）
• LLM从不摄取、过滤、读取或处理文件
• 所有过滤和摄取都发生在SNAP内部
• LLM仅从数据库中读取结构化快照数据

______________________________________________________________________

二进制文件头

SNAP使用二进制文件头将文件与项目相关联，而不需要目录结构。

报头格式

FileHeader (variable size):
  magic:            "SNAPFILE" (8 bytes)
  version:          uint16 (2 bytes)
  project_id_len:   uint16 (2 bytes)
  project_id:       utf-8 string (variable)
  snapshot_count:   uint32 (4 bytes)
  [file content follows]

用法

from app.extraction.binary_packer import write_file_header, read_project_id_from_file

# Write file with project association
content = b"# Project Notes\n\nImplementation details..."
write_file_header("notes.md", "SNAP", content)

# Read project_id from file
project_id = read_project_id_from_file("notes.md")  # Returns "SNAP"

自动摄取工作流程

1. File with binary header uploaded via upload_to_staging
2. SNAP reads header → extracts project_id
3. File placed in staging/{project_id}/
4. Auto-ingested into {project_id} project in background
5. Staging cleared

使用案例：

• 聊天对话日志（project_id=工作项目名称）
• 项目说明和文件
• RAG查询的上下文文件
• 具有明确所有权的跨项目文件共享

______________________________________________________________________

Nim解析器

高性能本机解析器捆绑在snap-mcp二进制文件中。处理所有文档、数据和配置格式。

支持格式

XML在解析时自动分类：类文档标签→ text，重复记录行→ csv，其他一切→ config.

演出

注： Tree sitter和semgrep仍保留在Python中（外部工具，已经优化）。

______________________________________________________________________

管理员CLI

完全绕过MCP的人工操作。安装方法 pip install -e . 然后使用 snap-admin.

# List all ingested projects with snapshot and run counts
snap-admin list-projects

# Show all runs for a project (active / superseded / failed)
snap-admin runs 

# Health check and active-run summary for a project
snap-admin manifest 

# Browse snapshots — summary by type, or drill in by type or file
snap-admin snapshots 

snap-admin snapshots 
 --type 
snap-admin snapshots 
 --file 

# Delete a project and all its data (DB, repos, staging)
snap-admin delete-project 

# Copy a local directory into staging for a project
snap-admin upload-to-staging 
 

# Clone a GitHub repo directly (no LLM involved) — repos_watcher ingests
snap-admin clone-github 

也可调用为 python -m app.admin .

______________________________________________________________________

可用的MCP工具

______________________________________________________________________

快照类型

代码分析（7种类型）

安全与质量（2种类型）

文件（3种类型）

支持： .md, .html, .docx, .pdf, .txt, .rtf --以及 .xml 当被归类为文档时。

CSV/数据（2种类型）

支持： .csv, .tsv, .xml （当分类为行数据时）。

配置（1种类型）

支持： .json, .jsonl, .yaml, .yml, .toml, .xml （当分类为配置时）。

______________________________________________________________________

存储体系结构

SNAP使用具有二进制快照格式的混合存储模型，以实现高效的Nim集成。

数据库模式

通过设置 .env:

SNAP_DB_MODE=sqlite        # Default
SNAP_DB_MODE=postgres      # Requires SNAP_POSTGRES_DSN
SNAP_DB_MODE=dual          # Both databases

二进制快照格式

快照以二进制打包数据的形式存储，以提高性能和Nim兼容性。

快照结构：

SnapshotHeader (561 bytes):
  magic:         "SNAP" (4 bytes)
  version:       uint16 (2 bytes)
  snapshot_type: uint8 (1 byte)
  field_count:   uint16 (2 bytes)
  content_hash:  SHA-256 (32 bytes)
  simhash:       uint64 (8 bytes)
  minhash:       128 × uint32 (512 bytes)

FieldDescriptor (11 bytes each):
  field_id:      uint16 (2 bytes)
  data_type:     uint8 (1 byte)  # 0=string, 1=int, 2=binary, 3=array
  offset:        uint32 (4 bytes)
  length:        uint32 (4 bytes)

Data Block (variable):
  Packed field data referenced by descriptors

储存：

CREATE TABLE snapshot_notebooks (
    snapshot_id   TEXT PRIMARY KEY,
    run_id        TEXT NOT NULL,
    project_id    TEXT NOT NULL,
    snapshot_type TEXT NOT NULL,
    source_file   TEXT NOT NULL,
    binary_data   BYTEA NOT NULL,           -- Binary-packed snapshot
    source_hash   TEXT,
    content_hash  TEXT,                      -- SHA-256 hex
    simhash       BIGINT,                    -- 64-bit similarity hash
    minhash       TEXT,                      -- 128 × 32-bit MinHash (CSV)
    created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

基于哈希的版本控制

版本控制逻辑：

New file ingested:
  1. Calculate source_hash
  2. Query DB for existing snapshot with same source_file + source_hash
  3. If exists → skip (deduplication)
  4. If not exists → create new snapshot (versioning)
  5. Multiple versions coexist in DB (query by run_id or latest)

______________________________________________________________________

配置

环境变量使用 SNAP_ 前缀。

数据库

目录

系统

分析器限制

身份验证（仅限HTTP+SSE，默认禁用）

Stdio模式（Claude Code）从不受身份验证设置的影响。

______________________________________________________________________

日志记录

SNAP同时将结构化JSON日志写入三个目标。

日志文件

日志格式

受控于 SNAP_LOG_JSON （默认值 true).每一行都是一个JSON对象：

{"ts": "2026-02-15 12:00:00,000", "level": "INFO", "name": "snap", "msg": "Snapshot created", "snapshot_id": "...", "project_id": "...", "snapshot_type": "functions", "parser": "tree_sitter", "fields_count": 12}

集 SNAP_LOG_JSON=false 对于人类可读的输出：

2026-02-15 12:00:00,000 INFO snap Snapshot created

结构化日志事件

文件标签

______________________________________________________________________

建筑

管道流量

GitHub:
clone_to_repos(repo_url)
    ↓ clone completes synchronously
repos/{project_id}/
    ↓ auto-ingest background thread
ingest_cloned_repo()    ← security filtering, file enumeration
    ↓
file_router → parsers → field_mapper → snapshot_builder → DB
    ↓
repos/ cleared

Local:
copy_to_staging(source_path)
    ↓ stage_directory() filters and copies
staging/{project_id}/
    ↓ auto-ingest background thread
process_project()       ← security filtering, file enumeration
    ↓
file_router → parsers → field_mapper → snapshot_builder → DB
    ↓
staging/ cleared

文件结构

SNAP/
├── app/
│   ├── admin.py                         # Admin CLI (human-only: delete, upload, clone, list)
│   ├── main.py                          # Orchestration pipeline
│   ├── config/
│   │   └── settings.py
│   ├── extraction/
│   │   ├── binary_packer.py             # Binary snapshot packer/unpacker (Nim-compatible)
│   │   ├── field_mapper.py              # Maps parser output to snapshot types
│   │   └── snapshot_builder.py
│   ├── ingest/
│   │   ├── file_router.py               # Routes files to parsers by extension
│   │   ├── github_cloner.py             # Shallow clone → repos/
│   │   └── local_loader.py              # stage_directory() + staging helpers
│   │
│   ├── logging/
│   │   └── logger.py
│   ├── mcp/
│   │   ├── auth.py                      # JWT + GitHub OAuth
│   │   ├── run.py                       # Entry point: stdio or HTTP+SSE
│   │   ├── security.py                  # Input validation, path traversal prevention
│   │   ├── server.py                    # MCP server, tool registry, Starlette app
│   │   └── tools.py                     # Tool handlers + permission enforcement
│   ├── parsers/
│   │   ├── nim_parser.nim               # Native parser: doc, csv, config formats (compile to binary)
│   │   ├── nim_parser.py                # Python wrapper for Nim parser
│   │   ├── pre_converter.nim            # Pre-processing helper for Nim parser
│   │   ├── semgrep_parser.py
│   │   └── tree_sitter_parser.py
│   ├── schemas/
│   │   ├── master_notebook.yaml
│   │   └── snapshot_templates/          # JSON templates (defined and gated by master_notebook.yaml)
│   ├── security/
│   │   └── network_policy.py
│   └── storage/
│       ├── db.py
│       └── snapshot_repo.py             # CRUD, upsert, run versioning
├── data/
│   ├── logs/
│   ├── projects/                        # Project manifests
│   ├── repos/                           # GitHub clones (cleared after ingest)
│   └── staging/                         # Local file staging (cleared after ingest)
├── docker/
│   └── Dockerfile
├── docker-compose.yml
├── pyproject.toml
├── run_mcp.bat
└── run_mcp.sh

______________________________________________________________________

安全

LLM自治限制

• 未读取原始文件 --LLM仅读取结构化数据库快照
• 无摄入 --SNAP摄取并解析；LLM从不接触文件
• 无删除/写入权限 — delete_project, promote_run 立即提高
• project_id已锁定 --从克隆时的回购URL派生；LLM无法提供或重命名
• vendor_id受限 --字母数字+ _@.- 仅限，最多64个字符；阻止注入字符
• 运行时实施 — ALLOWED_TOOLS / NOT_ALLOWED_TOOLS 在处理程序入口处检查冷冻集

输入验证

• 项目ID: ^[a-zA-Z0-9_-]{3,64}$
• 供应商ID: ^[a-zA-Z0-9_@.\-]{1,64}$
• 文件名：无路径遍历(.., \x00, ~)，没有反斜杠，保留名称被阻止
• 回购URL：仅HTTPS GitHub URL
• 符号链接：在暂存时被拒绝

分级过滤器(stage_directory)

SNAP在复制时强制执行的所有筛选——LLM没有角色。

精简目录 （从未穿过）： node_modules · .git · .svn · .hg · __pycache__ · .venv · venv · .next · .nuxt · .expo · .gradle · build · dist · target · Pods · .terraform · vendor

忽略的文件模式：

架构治理

app/schemas/master_notebook.yaml 是所有快照类型和字段定义的唯一真实来源。

• 模板验证 — SnapshotBuilder 在启动时根据主笔记本验证每个模板文件。模板未在中注册 snapshot_templates 被拒绝，永远不会逃跑。
• 字段验证 --模板中未注册的任何字段 field_id_registry 导致整个模板被拒绝。
• MCP查询验证 — validate_snapshot_type 在运行时直接从主笔记本读取有效类型。没有硬编码列表。

解析时间注入保护

• 快速注射 --30多种模式被阻止：指令覆盖、角色劫持、越狱触发、渗透探测
• 秘密编辑 -AWS密钥、GitHub令牌、JWT、API密钥在所有字段值中自动重编辑
• AST水平过滤 --扫描树型节点以寻找命令式模式；标记为 [FILTERED:IMPERATIVE]
• 内容安全 --高熵检测、base64块、插入数据库前标记的十六进制编码数据

______________________________________________________________________

需求

二进制版本没有安装时依赖关系。所有解析器和库都是捆绑在一起的。

捆绑在二进制文件中： 树保姆（所有语言）·semgrep·nim_passer·所有Python依赖项。

______________________________________________________________________

故障排除

MCP服务器无法连接

1. 日志必须转到stderr （不是stdout）：

   handler = logging.StreamHandler(sys.stderr)

1. 使用包装脚本 --Claude Code不尊重cwd：

   @echo off
   cd /d C:\Users\\snap
   snap-mcp.exe %*

1. 验证连接:

   claude mcp list
   # snap: ... - ✓ Connected

缺少postgres_dsn

SNAP_POSTGRES_DSN=postgresql://user:pass@localhost:5432/snap

Semgrep未运行

SNAP在启动时自动安装和升级semgrep。如果自动安装失败：

.venv\Scripts\python.exe -m pip install --upgrade semgrep

______________________________________________________________________

©CLL自动机