Astrolabe MCP 服务端

使用说明（Markdown 格式）

• 项目简介
  • Astrolabe MCP 服务器实现一个后端服务，负责加载配置、建立并维护本地文档索引、提供一组可供客户端调用的工具方法（如获取 Cosmos、列出文档、按查询检索、读取文档、更新索引、重新索引等），并通过 MCP 标准进行 JSON-RPC 交互。服务器本身运行在 Python 环境中，支持通过环境变量指定配置文件路径，提供跨机器共享索引的能力（通过云端共享的索引文件）等特性。
• 主要功能点
  • 资源管理与索引：对配置中的项目目录进行扫描，构建并维护一个文档索引，支持并发访问与惰性更新。
  • 工具接口：通过 MCP 工具暴露多种功能，例如读取文档、查询、更新元数据、重新索引、获取文档卡等，返回结构化的 JSON 数据，方便 LLM 客户端消费。
  • 读取与搜索：支持按段落、标题、范围读取文档内容，以及对文档进行基于关键字、标题、摘要等字段的加权检索。
  • 跨机器共享：支持将索引文件放在云端目录，结合哈希标准化与 Desync 处理，实现在多机器之间共享一致的文档状态与搜索能力。
  • 安全与稳定性：采用文件锁机制保护索引文件的并发访问，提供 desync、passthrough、force 重建等状态处理逻辑，确保在分布式环境中的可预测行为。
• 安装步骤
  • 获取源码：将仓库下载到本地或服务器环境中。
  • 创建虚拟环境并安装：按照项目提供的依赖方式，创建虚拟环境并安装为开发模式（如 pip install -e ".[dev]"）。
  • 配置文件：使用 runtime/config.json 作为默认配置路径，必要时复制示例配置并按实际项目路径修改。
  • 启动方式：以模块运行服务器，例如 python -m astrolabe.server（也可以通过配置环境变量 ASTROLABE_CONFIG 指向 runtime/config.json 指定的配置文件来启动）。
• 服务器配置（MCP 客户端需要的启动信息，JSON 格式，含 server name、command、args 等）
  • 服务器名称（server_name）： Astrolabe
  • 启动命令（command）：/absolute/path/to/虚拟环境/bin/python
  • 参数（args）：["-m", "astrolabe.server"]
  • 工作目录（cwd）：/absolute/path/to/astrolabe-mcp
  • 环境变量（env）：{ "ASTROLABE_CONFIG": "/absolute/path/to/astrolabe-mcp/runtime/config.json" } 注释：
  • 上述配置用于 MCP 客户端在需要时启动并连接到 Astrolabe 的服务端。ASTROLABE_CONFIG 指向服务器启动所用的配置文件，以确保服务器能够正确加载配置、索引以及 doc_types 等信息。客户端本身只需要知道服务器的启动信息即可发起请求。
• 基本使用方法
  • 客户端连接与调用：通过 MCP 客户端启动时提供的命令与参数，启动 Astrolabe 服务端进程并建立与之的 JSON-RPC 通道。
  • 常用交互：使用 get_cosmos、list_docs、search_docs、get_card、read_doc、update_index_tool、reindex_tool 等工具接口获取/修改索引及文档信息。
  • 更新与同步：在本地项目有新增/修改文件时，调用 reindex_tool 或在需要时通过 read_doc/update_index_tool 进行 enrichment，以保持索引与文件的一致性。