dans_lazy_file_dump MCP 服务器

使用说明（Markdown）

• 项目简介

  • 该仓库实现了一个 MCP 服务器端，具备对资源、工具、Prompts 的注册、执行与渲染能力，并提供通过 stdio/HTTP 的 MCP 通信、会话管理与能力声明等核心特性，适用于 LLM 客户端来访问文档、执行工具以及获取 Prompt 模板。
  • 服务器还集成了文档索引/检索管线（LanceDB/LlamaIndex），支持向量检索、BM25/FTS 以及跨模型的嵌入、OCR、LLM enrich 等能力，形成完整的 MCP 后端解决方案。

• 主要功能点

  • MCP 服务端实现：支持 stdio 模式以及 HTTP 的 MCP 交互，提供多种传输形式与会话管理能力。
  • MCP 工具集：提供多达 17 种工具接口（如 file_search、file_get_chunk、file_list_documents、file_status 等），可供 LLM 客户端在对话中进行检索、浏览、过滤与元数据管理。
  • 文档索引与检索：通过自定义 LanceDB/LlamaIndex 存储，支持向量检索、关键字检索、分段检索和富文本元数据。
  • LLM 集成与 enrichment：支持通过不同后端（OpenRouter、Ollama、Baseten、Gemini 等）进行文档富化（enrichment），并将结果暴露在 MCP 数据中。
  • 配置与健康状况：提供配置驱动的工作流、流量控制和健康诊断（FTS、向量检索、重排名器等健康标志）。
  • 静态/动态元数据管理：支持 frontmatter、LLM enrichment、以及能在检索中作为过滤条件使用的动态字段。

• 安装与运行步骤

  • 1. 克隆仓库并进入项目目录。
  • 2. 创建并激活虚拟环境后安装依赖。
  • 3. 配置 MCP、索引、OCR、嵌入和 LLM 提供方（如 OpenRouter、Baseten、Ollama、Gemini 等），并根据需要开启本地自托管（如 LanceDB/LLamaServer 等）。
  • 4. 启动服务器：可通过标准 MCP 路径启动（stdio 模式）或 HTTP 模式结合附带的 api_server/ server 入口一起运行。
  • 5. 通过 MCP 客户端连接并加载 mcpServers 配置，来注册并启动对 MCP 的请求。

• 服务器配置（MCP 客户端使用的 JSON 配置示意） { "server_name": "doc-organizer-mcp", "command": "/path/to/venv/bin/python", // 启动 MCP 服务所用可执行文件 "args": [ "/path/to/dans_lazy_file_dump/mcp_server.py" // 需要执行的 MCP 服务器入口脚本 ], "cwd": "/path/to/dans_lazy_file_dump" // 相对工作目录，确保脚本能正确定位资源 }

  说明：

  • server_name: 这是你在客户端配置中识别的服务器名称，便于在多服务器场景下区分调用目标。
  • command: 指向启动 MCP 服务器所需的解释器或可执行程序（如虚拟环境中的 python）。
  • args: MCP 服务器入口脚本的路径（本仓库的入口脚本为 mcp_server.py）。
  • cwd: 运行脚本时的工作目录，通常设为仓库根目录的路径，确保相对资源可正确定位。

• 基本使用方法

  • 启动 MCP 服务：
    • 针对本仓库的实现，使用配置好的命令与参数在目标主机上启动，以便客户端可以通过 MCP 协议与之通信。
  • 连接并调用工具：
    • 使用支持 MCP 的 AI 助手（Claude Code、OpenClaw、Claude Desktop、Cursor 等）并在配置中指向上面的 server_name。
    • 通过 MCP 的工具接口（如 file_search、file_get_chunk、file_list_documents 等）请求文档检索、Chunk 读取、文档元数据等。
  • 会话与安全：
    • MCP 服务器实现中包含会话管理与能力声明，支持不同传输协议（stdio、HTTP），并可在需要时启用 HTTP Bearer Token 认证。
  • 本地/云部署：
    • 支持本地自托管的嵌入/OCR/LLM 路线，也可切换到云端提供方，构建灵活的后端上下文服务。

• 备注

  • 该实现包含服务器端入口（mcp_server.py、server.py）以及用于健康检查、测试和集成的完整模块，符合 MCP 服务器实现的核心要素（MCP 请求处理、JSON 响应、工具注册、会话管理、跨传输协议、以及与客户端的集成能力）。
  • 代码中集成的测试用例覆盖了 MCP 输出契约、请求处理以及健康/容错场景，进一步提升了可用性与稳定性。

• 资源与参考

  • MCP 服务器入口与路由实现、工具注册、HTTP 与 stdio 的双模通信、以及与 Flow/Index 流程的整合可用于对接各类 MCP 兼容客户端。