Spicedocs MCP

SpiceDocs MCP服务器

一个模型上下文协议（MCP）服务器，为Claude提供对NAIF SPICE文档的本地web存档的访问。此服务器允许通过MCP协议搜索、浏览和查询SPICE工具包文档。

概述

SpiceDocs MCP服务器为NAIF SPICE文档页面建立索引并提供全文搜索功能。它使用SQLite和FTS5（全文搜索）进行高效搜索，并包括几个用于浏览文档的工具：

• 搜索存档：在所有文档页面上进行全文搜索
• get_page：检索特定文档页面
• 列表_页面：使用可选筛选浏览可用页面
• 提取链接：从页面中提取内部/外部链接
• 获取存档状态：查看有关文档存档的统计信息

特性

• 使用FTS5进行全文搜索（如果不可用，则退回基本搜索）
• HTML文档文件的自动索引
• 从HTML页面中提取干净的文本
• 安全文件访问的路径遍历保护
• 支持存档中的相对和绝对路径
• 链接提取用于相关页面之间的导航

系统要求

必需

• Python 3.10或更高版本 -服务器需要Python 3.10+才能获得类型提示和异步功能
• 紫外线 包管理器 -用于依赖关系管理和运行服务器
• Internet连接 -首次下载文档时需要（~28MB）
• 磁盘空间 -至少100MB的免费下载和缓存文档

可选（推荐）

• 带FTS5扩展名的SQLite -通过BM25排名实现快速全文搜索。Python包括SQLite，但FTS5的支持取决于系统的SQLite库是如何编译的。如果FTS5不可用，服务器会自动回退到基本搜索。

要检查FTS5是否在您的系统上可用：

python3 -c "
import sqlite3
conn = sqlite3.connect(':memory:')
try:
    conn.execute('CREATE VIRTUAL TABLE t USING fts5(c)')
    print('FTS5 is available')
except Exception:
    print('FTS5 is not available')
"

如果命令显示“FTS5不可用”，则SQLite不支持FTS5。服务器仍将工作，但搜索速度会变慢。

快速开始

使用SpiceDocs MCP的最简单方法是使用Claude Desktop和 uvx:

使用Claude Desktop进行安装

1. 如果您还没有安装uv：

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

1. 将SpiceDocs MCP添加到您的Claude Desktop配置中：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "spicedocs": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/medley56/spicedocs-mcp@1.0.0",
        "spicedocs-mcp"
      ]
    }
  }
}

注： 替换 @1.0.0 带有所需的版本标签。看 发布 对于可用版本。不带版本标记的安装将从主分支安装未发布的代码。

1. 重新启动克劳德桌面

首次运行时，服务器将自动下载并缓存NAIF SPICE文档（约28MB，约710个HTML文件）。这需要2-5分钟，具体取决于您的连接。后续启动是即时的。

高级安装

为了发展

如果要修改或扩展服务器：

1. 克隆此存储库：

git clone https://github.com/medley56/spicedocs-mcp
cd spicedocs-mcp

1. 使用uv安装依赖项：

uv sync

文档归档结构

服务器会自动从NAIF网站下载文档并将其存储在缓存目录中。缓存的文档具有以下结构：

archive_directory/
  naif.jpl.nasa.gov/
    pub/
      naif/
        toolkit_docs/
          C/
            index.html
            cspice/
              spkpos_c.html
              furnsh_c.html
              ...
            ug/
              mkspk.html
              ...

运行服务器

命令行选项

spicedocs-mcp [OPTIONS]

Options:
  --refresh         Force re-download of cached documentation
  --cache-dir       Show cache directory location and exit
  --help, -h        Show help message

首次运行时，文档会自动下载到适合平台的缓存目录中。

用于开发/测试

如果您已克隆存储库并希望在本地运行服务器：

# Use cached/downloaded documentation (recommended)
uv run spicedocs-mcp

使用Claude Desktop（开发模式）

如果您已经克隆了存储库，并希望在Claude Desktop中使用您的本地版本：

{
  "mcpServers": {
    "spicedocs": {
      "command": "uv",
      "args": [
        "run",
        "spicedocs-mcp"
      ],
      "cwd": "/absolute/path/to/your/cloned/spicedocs-mcp"
    }
  }
}

替换 /absolute/path/to/your/cloned/spicedocs-mcp 使用克隆存储库的实际路径。

使用示例

连接后，Claude可以使用以下工具：

搜索文档

Search for "ephemeris kernels" in the SPICE documentation

这使用了 search_archive 查找相关页面的工具。

获取特定页面

Show me the documentation for spkpos_c.html

这使用了 get_page 用于检索特定页面完整内容的工具。

列出可用页面

List all pages in the user guide (ug/ directory)

这使用了 list_pages 带有过滤功能的工具。

提取链接

Show me all internal links from the index.html page

这使用了 extract_links 查找导航链接的工具。

存档统计

What's the size and structure of the documentation archive?

这使用了 get_archive_stats 获取概述信息的工具。

缓存管理

缓存位置

文档缓存在适合平台的目录中：

• Linux: ~/.cache/spicedocs-mcp
• macOS: ~/Library/Caches/spicedocs-mcp
• 视窗: %LOCALAPPDATA%\spicedocs\spicedocs-mcp\Cache

要查看缓存位置，请执行以下操作：

uvx --from git+https://github.com/medley56/spicedocs-mcp@1.0.0 spicedocs-mcp --cache-dir

刷新缓存

要重新下载文档（例如，如果NAIF更新了他们的文档）：

uvx --from git+https://github.com/medley56/spicedocs-mcp@1.0.0 spicedocs-mcp --refresh

清除缓存

要释放磁盘空间，请删除缓存目录：

# Linux/macOS
rm -rf ~/.cache/spicedocs-mcp

# Windows
rmdir /s "%LOCALAPPDATA%\spicedocs-mcp"

数据库索引

服务器自动创建SQLite数据库(.archive_index.db)第一次运行时在缓存目录中。此数据库：

• 为下载文档中的所有HTML文件建立索引
• 提取标题和文本内容
• 创建全文搜索索引（FTS5）（如果可用）
• 缓存元数据以实现快速检索

下载文档后，索引会自动构建。要重建，请使用 --refresh 标记以重新下载和重新索引。

建筑

构建使用：

• FastMCP：现代MCP服务器框架
• SQLite+FTS5：全文搜索功能
• 美丽汤：HTML解析和文本提取
• httpx：用于下载文档的HTTP客户端
• 平台：适用于平台的缓存目录管理
• 紫外线：快速Python包和项目管理器

故障排除

服务器无法启动

• 网络问题：如果是第一次下载文档，请检查您的互联网连接
• 缓存目录：确保您对缓存目录具有写入权限
• 依赖项：检查是否安装了uv依赖项： uv sync
• 日志：在日志中查找错误消息（写入stderr）

首次下载速度慢或失败

• 第一次运行下载约28MB的文档，可能需要2-5分钟
• 如果下载因网络问题而失败，请删除缓存目录并重试
• 使用 --cache-dir 查看文档缓存的位置
• 如果无法连接到naif.jpl.nasa.gov，请检查防火墙设置

搜索未返回任何结果

• 确保文档已成功下载
• 检查缓存目录是否包含 .archive_index.db
• 尝试刷新： spicedocs-mcp --refresh
• 检查FTS5是否可用（参见 系统要求)

FTS5不可用

如果您在日志中看到“FTS5不可用，使用基本搜索”：

• Linux（Debian/Ubuntu）：在大多数发行版上，FTS5通常包含在Python 3.10+中
• macOS：FTS5通常包含在SQLite系统中
• 视窗：FTS5通常包含在Python捆绑的SQLite中

如果缺少FTS5，您仍然可以使用服务器——它将退回到基本的基于LIKE的搜索，这种搜索速度较慢但功能齐全。

Claude Desktop看不到服务器

• 验证配置文件路径和JSON语法
• 修改配置后重新启动Claude Desktop
• 检查Claude Desktop日志中的连接错误
• 确保uv已安装并位于PATH中

发展

建立发展环境

1. 克隆存储库：

git clone https://github.com/medley56/spicedocs-mcp
cd spicedocs-mcp

1. 安装所有依赖项（包括开发和测试）：

uv sync --all-extras

1. 安装预提交挂钩：

# Install pre-commit (if not already installed)
pip install pre-commit
# or
pipx install pre-commit

# Install the git hooks
pre-commit install

代码质量工具

此项目使用预提交挂钩来确保代码质量：

• 颈毛：快速Python linter和格式化程序
• 米皮：静态类型检查
• 尾随空格：删除尾随空格
• 文件结束修复程序：确保文件以换行符结尾
• 检查yaml：验证YAML文件
• 检查添加的大文件：防止提交大文件

手动运行所有检查：

pre-commit run --all-files

运行测试

uv run pytest tests/ -v

进行更改

1. 编辑 服务器.py
2. 使用添加新工具 @mcp.tool() 装饰器
3. 在提交之前运行预提交钩子
4. 通过直接运行服务器来测试更改

许可证

\[在此处指定您的许可证\]

贡献

\[如适用，添加捐款指南\]