sextant (Tideshift Labs)

六分仪

Sextant是一个MCP服务器，它在本地markdown文件文件夹上提供混合语义和关键字搜索。它为您的文档建立索引，按标题对其进行分组，通过本地Ollama模型嵌入它们，并通过模型上下文协议（MCP）公开搜索和检索工具。

然后，Claude Code（或任何MCP客户端）可以使用自然语言查询、精确关键字查找或两者的组合来搜索您的文档。

运作原理

1. 六分仪扫描一个文件夹中的markdown文件，并在每个标题边界将它们分成块。
2. 每个块都使用Ollama（nomic嵌入文本）在本地嵌入。
3. 块及其嵌入存储在Orama中，Orama在单个库中处理全文、矢量和混合搜索。
4. 在SQLite中跟踪文件元数据（通过bun:SQLite），因此重新启动时跳过未更改的文件。
5. 每个搜索请求都会检查过时的文件，并在需要时触发后台重新索引。
6. MCP服务器通过stdio公开了五个工具： search_docs, list_docs, get_doc, reindex_docs，以及 sextant_status.

整个堆栈在本地运行，没有外部服务。没有本机模块；一切都是纯JavaScript/TypeScript。

指标新鲜度

六分仪会自动更新其索引：

• 启动时，Sextant会将每个文件的修改时间与之前索引的时间进行比较。新文件和更改的文件被重新索引；已删除的文件将从索引中删除。这涵盖了在服务器未运行时更新文档的情况（例如，在 git pull).
• 每次搜索时，新鲜度检查都会检测新的、修改的或删除的文件，并在不阻止查询的情况下触发后台重新索引。如果文件已更改，响应中会包含一条注释和下一次搜索的结果更新。
• 如果另一个六分仪进程将较新的索引持久化到磁盘，则会在搜索之前自动拾取它。

先决条件

包子

六分仪继续奔跑 包子，它用作运行时、包管理器和bundler。

Windows（PowerShell）：

powershell -c "irm bun.sh/install.ps1 | iex"

macOS/Linux：

curl -fsSL https://bun.sh/install | bash

使用验证安装 bun --version.

奥拉玛

奥拉玛 必须在本地安装并运行。首次使用前拉动嵌入模型：

ollama pull nomic-embed-text

奥拉玛继续跑 http://localhost:11434 默认情况下。如果Ollama不运行，关键字搜索仍将工作，但语义和混合搜索将不可用。

使用Claude代码

将以下内容添加到您的Claude Code MCP配置中(.claude/mcp.json 在您的项目中）：

{
  "mcpServers": {
    "sextant": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@tideshift/sextant"],
      "env": {
        "DOCS_PATH": "/absolute/path/to/your/docs"
      }
    }
  }
}

集 DOCS_PATH 指向要索引的markdown文件夹的绝对路径。

配置后，Claude Code将可以访问以下工具：

• search_docs -使用混合语义+关键字搜索搜索文档。支持三种模式： hybrid （默认情况下，两者结合）， semantic （仅矢量相似性），以及 keyword （仅精确匹配文本）。接受可选的类别筛选器。
• list_docs -列出所有索引文档及其类别、标题和块计数。
• get_doc -按文件路径检索特定文档的完整内容。
• reindex_docs -强制对所有文档进行完全重新索引。
• 六分仪_状态 -检查服务器运行状况、索引进度、Ollama连接和索引统计信息。

配置

所有设置都可以通过环境变量或 .env 文件：

贡献

看 docs/contributing.md 用于本地开发设置、构建和诊断。

技术细节

看 docs/technical_details.md 用于架构、项目结构、组块策略、持久性模型、索引新鲜度逻辑和边缘案例。

许可证

由以下材料制成❤️ 在不列颠哥伦比亚省温哥华，由Tideshift Labs开发，使用 克劳德代码.

麻省理工学院