SNAP MCP Server

使用说明内容（Markdown格式）

• 项目简介

  • SNAP MCP 服务器是一个面向 LLM 应用的后端服务，基于 MCP（Model Context Protocol）实现，核心职责包括托管与管理资源（如快照数据、代码分析结果等）、注册并执行工具（如分析、查询、上传到 staging 等）、定义和渲染 Prompt 模板，并通过 JSON-RPC 及多种传输方式（如 STDIO、HTTP+SSE）与客户端通信。

• 主要功能点

  • MCP 服务端：实现 MCP 的工具注册、调用、模板渲染等核心能力，提供对外的 API 接入点与传输通道。
  • 工具集合：包括处理 GitHub 仓库、处理本地 staging、获取项目笔记本、查询快照、清理 staging、获取系统指标等。
  • 快照与笔记本：对代码、文档、CSV 等内容生成 14 组快照类型，并能按类型/文件筛选，最终聚合成项目笔记本。
  • 数据存储与隔离：采用 PostgreSQL 存储，支持按项目隔离的快照数据，提供删除项目等操作。
  • 安全与沙箱：对输入、文件大小、仓库结构、路径遍历等进行严格校验，提供对外部资源请求的域名白名单与速率限制等安全措施。
  • 部署与传输：支持 STDIO 模式（与 Claude Code 集成）和 HTTP+SSE 模式（Remote 客户端连接），便于本地与远端使用。
  • 管理与看板：提供 dashboard（通过 app/dashboard.py）展示聚合指标与运行状态。

• 安装与运行步骤

  1. 建立虚拟环境并安装依赖：
     • 基本步骤同 README 快速开始中的内容，建议使用 Python 3.11+。
  2. 配置数据库与存储：
     • 使用 PostgreSQL，依据 README 指示运行 docker-compose 或配置 SANDBOX_POSTGRES_DSN 环境变量。
  3. 配置与启动 MCP 服务器：
     • 服务器启动有两种模式：
       • STDIO 模式（用于 Claude Code 集成等本地通讯场景）： 启动命令示例：在项目根目录执行 python -m app.mcp.run
       • HTTP+SSE 模式（远程客户端访问）： 启动命令示例：python -m app.mcp.run --sse --host 0.0.0.0 --port 8080
  4. 关注点与日志：
     • 服务端日志默认输出到 stderr（MCP 要求），同时也会写日志文件以便 dashboard 读取。
  5. 客户端连接与配置
     • MCP 客户端需配置服务器信息以建立连接。具体信息如下（JSON 描述，供客户端参考，不需要直接运行代码）： { "server_name": "snap", "command": "python", "args": ["-m", "app.mcp.run", "--sse", "--host", "0.0.0.0", "--port", "8080"] } 注释：
       • server_name 指定为客户端在工具中识别的服务器别名（README/文档中使用的 snap）。
       • command 与 args 描述服务器的启动方式与参数，客户端在初始化连接时会使用该信息启动并连接 MCP 服务。
       • 如需本地 Windows 环境，可使用仓库提供的 run_mcp.bat 包装脚本来启动同样的服务器进程。
  6. 基本使用方法
     • 通过 Claude/Claude Code：
       • 在 Claude Code 中将 SNAP MCP 服务器注册为名为 snap 的服务器，使用上面的启动命令信息即可与 MCP 服务器建立连接。
     • 通过远程客户端（HTTP+SSE）：
       • 客户端通过 /sse 建立事件流，/messages/ 用于 MCP 传输消息，/health 进行健康检查。
     • 常用操作包括：对仓库执行分析、上传到 staging、查询快照、获取项目笔记本、删除项目等。

• 基本使用示例

  • 启动命令（在服务器端执行，以启动 MCP 服务）
  • 客户端连接信息（JSON 配置示例，供参考并用于理解启动参数，不是直接嵌入代码）
  • 连接后的常用流程：将代码/仓库提交到服务器，服务器执行解析、生成快照并聚合成笔记本，用户可通过工具查询笔记本或快照进行内容检索。