使用说明

以下内容帮助你快速理解并使用该仓库实现的 MCP 服务器。

• 项目简介

  • 该仓库实现了一个基于 MCP 的服务器，用于从本地 Org-mode 文件构建知识图谱，向 MCP 客户端暴露资源、工具和查询能力。
  • 服务器核心围绕 Org-mode 文件的解析、缓存、节点内容清洗、以及对外提供的工具接口（如获取预览、搜索、创建节点、修改节点、连接节点等）展开。

• 主要功能点

  • 资源与工具注册
    • 提供应用级信息资源、用户信息资源等，及一组用于知识库操作的工具（如 list_knowledge_nodes、get_node_previews、search_knowledge_nodes、get_knowledge_nodes 等）。
  • 知识节点管理
    • 通过解析 Org-mode 文件，提取节点信息（ID、标题、 filepath、起止行、属性、背链等），并缓存以供快速查询。
    • 支持创建新节点、修改节点内容、在节点之间建立 backlinks。
  • 内容与预览
    • 提供 get_node_previews：对节点内容进行句子级截断的预览，尽量减少 token 消耗，支持批量请求。
    • 提供 get_knowledge_nodes：提取节点的完整文本内容（清洗掉 Org 头部元数据）。
  • 搜索与链接分析
    • 提供关键词搜索和模糊匹配搜索，以及自动模式选择。
    • 提供链接遍历（traverse_links）、获取前向链接（get_forward_links）和后向链接（get_backlinks）的工具。
  • 解析与缓存
    • 使用 parser_new、OrgPatterns、以及 parser 的组合，实现对 Org 文件结构的提取与边界定位，支持跨文件的节点去重、缓存失效等策略。
  • 安全与可扩展性
    • 支持缓存刷新、路径白名单校验、日志记录等，设计上考虑了结构化的节点数据和可扩展的工具/资源模型。

• 安装步骤

  • 克隆仓库并进入目录
  • 创建并激活虚拟环境
  • 安装依赖并以开发模式安装
  • 将 Org-mode 节点文件放在 nodes/ 目录（或通过 --nodes-dir 指定其他目录）
  • 启动服务器：python server.py
  • 运行测试（可选）：pytest test

• 服务器配置（MCP 客户端配置示例，不是客户端代码） 说明：MCP 客户端要连接到该服务器，需要知道服务器名称、启动命令及参数等信息。以下采用 JSON 形式描述，用以帮助客户端自动发现与连接。请将路径替换为你实际环境中的路径。

  { "server_name": "org-node-mcp", "command": "/path/to/python3", "args": [ "/path/to/org-node-mcp/server.py", "--nodes-dir", "/path/to/your/org-nodes-directory" ] // 备注：server_name 为 MCP 客户端用于识别的名称；command 指向运行环境的 python 解释器；args 为启动服务器的参数，包含节点目录 }

• 基本使用方法

  • 启动后端：进入仓库根目录，执行 python server.py（如需自定义节点目录，使用 --nodes-dir 指定）
  • 连接客户端：使用支持 MCP 的客户端工具，按照客户端说明进行连接（该仓库提供 http/json 传输与多种工具/资源）
  • 使用工具与资源：通过工具名访问相应功能，如获取节点预览、搜索、创建节点、修改内容、建立 backlinks 等
  • 针对开发者：可以查看 server.py 和 parser_new.py 的实现，理解如何从 Org 文件构建缓存、如何提供 MCP tool/resource、以及如何处理各种请求

• 注意事项

  • 本地 Org 文件需遵循示意的结构，以便解析正确提取节点信息（ID、标题、起止行、属性块等）。
  • 缓存有 5 分钟过期策略，确保对文件改动后能通过 reload_org_cache() 重新加载。
  • 服务器默认使用 STDIO/HTTP 等传输，具体传输协议由 FastMCP 框架支持决定。