AI导哈

RO-Crate索引查询服务器

基于FastMCP的服务器，提供RO-Crate索引、语义搜索和存储资源管理功能，支持文件系统和Azure Blob Storage等多种后端。

  • by johannehouweling
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 johannehouweling/ro-crate-mcp-server

使用说明

ro机箱mcp服务器

MCP服务器，用于索引和查询RO板条箱。

此存储库提供了一个基于FastMCP的服务器，提供了列出和检查索引RO板条箱、执行语义搜索（可选）以及列出可插拔后端（文件系统或Azure Blob存储）的存储资源的工具。服务器是通过一个复制设置类配置的，该类读取前缀为ROC_MCP_的环境变量。权威映射见src/rocrate_mcp/config.py。

亮点

  • 基于FastMCP的服务器（使用 mcp 用于开发和调用的CLI）
  • 可插拔存储后端：文件系统、azure或无（内存中/可跳过）
  • SQLite FTS支持的索引（SqliteFTSIndexStore），用于快速文本搜索
  • 通过MCP公开的工具：list_all_indexed_crates、semantic_search、get_rate_metadata、storage_list_resources

需求

  • Python>=3.12
  • 推荐的依赖关系在pyproject.toml中声明。重要套餐包括：
    • mcp[cli]（快速mcp命令行界面）
    • 罗克拉特
    • rdflib、sqlalchemy、aiosqlite
    • azure存储blob（可选，用于azure后端）

安装

克隆并安装可编辑（开发）环境：

git clone <repo-url>
cd ro-crate-mcp-server
python -m pip install -e .[dev]

或者安装该软件包以正常使用：

python -m pip install .

开发快速入门

  1. 配置环境

复制示例env文件并根据需要编辑值：

cp src/rocrate_mcp/.env.example .env

服务器读取带有ROC_MCP_前缀的环境变量（请参阅下面的配置）。

  1. 使用MCP运行开发服务器

建议的开发流程是使用了解FastMCP寿命和工具的mcp CLI：

# Run the app in development mode (auto-reload, lifecycle invoked)
mcp dev

您也可以直接运行服务器（生产/一次性）：

python -m rocrate_mcp.main

配置（环境变量）

所有运行时配置都是通过前缀为ROC_MCP_的pydantic设置设置和环境变量提供的。权威名称在src/rocrate_mcp/config.py中定义；最常用的变量是：

  • ROC_MCP_INDEX_MODE：'渴望'|其他（默认：渴望）--控制是否在服务器生命周期启动期间构建索引
  • ROC_MCP_STORAGE_BACKEND:“sqlite+fts”|“rdflib”--内部索引存储选择
  • ROC_MCP_BACKEND:“文件系统”|“azure”|“http”|“无”--选择要使用的机箱存储后端
  • ROC_MCP_FILESYSTEM_ROOT：文件系统后端根的路径（当backend=文件系统时需要）
  • ROC_MCP_FILESSYSTEM_ROOT_PREFIX：文件系统位置的可选前缀
  • ROC_MCP_FILESSYSTEM_DEFAULT_SUFFIXES：逗号分隔的后缀（默认值：.zip）
  • ROC_MCP_AZURE_CONNECION_STRING：AZURE连接字符串（后端=AZURE时需要）
  • ROC_MCP_AZURE_CONTAINER:AZURE容器名称（当BACKEND=AZURE时需要）
  • ROC_MCP_INDEXED_DB_PATH：sqlite索引数据库文件的路径（默认为rocrate_index.sqlite）
  • ROC_MCP_FIELDS_TO_INDEX：从ro-crate到索引的逗号分隔的字段列表（请参阅Settings.get_FIELDS_TO_INDEX（））
  • ROC_MCP_EMBEDDINGS_PROVIDER：“本地”|“openai”|“无”（控制语义嵌入提供程序）
  • ROC_MCP_EMBEDDINGS_API_KEY:外部嵌入提供程序的API密钥（保留为SecretStr）

注意：Settings类允许使用一些历史/备用环境名称（例如ROC_MCP_ROC_FIELDS_TO_INDEX或ROC_MCP_NOC_MCP_FIELDS_DO_INDEX）——有关详细信息，请参阅src/rocrate_MCP/config.py。

存储后端

文件系统后端（本地目录）

文件系统后端的.env设置示例：

ROC_MCP_BACKEND=filesystem
ROC_MCP_FILESYSTEM_ROOT=C:/data/ro-crates
ROC_MCP_FILESYSTEM_DEFAULT_SUFFIXES=.zip,.tar.gz

Azure Blob存储后端

Azure的.env设置示例：

ROC_MCP_BACKEND=azure
ROC_MCP_AZURE_CONNECTION_STRING=<your-azure-connection-string>
ROC_MCP_AZURE_CONTAINER=<container-name>

基于HTTP目录索引的后端

HTTPStorageBackend可用于对通过提供目录样式HTML列表（例如Apache或Nginx自动索引）的web服务器公开的板条箱进行索引。它将配置的基本URL视为根，并通过解析列表页面中的锚链接来发现文件和子目录。下载的文件被流式传输，处理方式类似于文件系统/azure后端（例如，提取ZIP存档以定位ro-crate metadata.json）。

示例.env设置来配置HTTP后端（项目读取ROC_MCP_前缀变量；根据部署调整名称）：

ROC_MCP_BACKEND=http
ROC_MCP_HTTP_BASE_URL=https://example.org/
ROC_MCP_HTTP_ROOT_PREFIX=optional/prefix/
ROC_MCP_HTTP_DEFAULT_SUFFIXES=.zip,.tar.gz
ROC_MCP_HTTP_TIMEOUT=10

如果ROC_MCP_BACKEND未设置（或设置为“无”），服务器将不会连接存储后端，这对于测试非存储功能非常有用。

MCP工具/API

该项目通过FastMCP公开了一小部分工具。这些工具在src/rocrate_mcp/tools.py中注册，可以使用 mcp 服务器运行后（或使用 mcp call 在适当的时候对包执行命令）。

可用工具（高级）

  • list_all_indexed_crates（限制：int=100，偏移量：int=0） 返回索引板条箱ID和一些元数据的分页列表。

  • 语义搜索（查询：str） 对索引内容执行语义搜索（需要配置嵌入提供程序）。

  • get_rate_metadata（crate_id:str） 返回给定crate（便利端点）的顶级ro-crate-metadata.json。

  • storage_list_resources（前缀：str|None=None，后缀：list[str]|None=（“.zip”，），限制：int=100，偏移量：int=0） 列出已配置存储后端的原始资源。

mcp CLI使用示例（使用以下命令启动服务器后 mcp dev):

mcp call rocrate-mcp.list_all_indexed_crates --args '{"limit":10}'
mcp call rocrate-mcp.get_crate_metadata --args '{"crate_id":"some-crate-id"}'
mcp call rocrate-mcp.storage_list_resources --args '{"prefix":"2025/","limit":50}'

临床（MCP客户端）配置

将服务器添加到Cline MCP配置中。使用virtualenv Python并通过env-vars设置后端：

{
  "mcpServers": {
    "rocrate-mcp": {
      "command": "/path/to/ro-crate-mcp-server/.venv/bin/python",
      "args": ["-m", "rocrate_mcp.main"],
      "cwd": "/path/to/ro-crate-mcp-server",
      "env": {
        "ROC_MCP_BACKEND": "filesystem",
        "ROC_MCP_FILESYSTEM_ROOT": "/path/to/ro-crates",
        "ROC_MCP_FILESYSTEM_DEFAULT_SUFFIXES": ".zip"
      }
    }
  }
}

如果您的板条箱没有拉链，请更新或删除ROC_MCP_FILESSYSTEM_DEFAULT_SUFFIXES。

测试

使用pytest运行测试（需要额外的开发工具）：

python -m pip install -e .[dev]
pytest -q

您可以执行单个测试模块：

pytest tests/test_zip_utils.py -q

注意：需要Azure或其他外部服务的集成测试可能需要额外的环境配置，默认测试套件不包括在内。

贡献

  • 使用常规的提交消息。此更改的首选提交消息是：

    docs（readme）：重写readme以供FastMCP使用

  • 保持README和pyproject元数据同步。如果您添加了env驱动的功能，请更新src/rocrate_mcp/.env.example和此README。

许可证

这个项目是麻省理工学院授权的。有关详细信息，请参阅LICENSE文件。

相关 MCP