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 
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=
ROC_MCP_AZURE_CONTAINER=

基于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文件。