OpenConstruction MCP

面向 OpenConstruction 的目录发现、数据集上下文、提供方感知的获取以及安全数据集下载的本地优先 MCP 服务器。

首个版本是本地 stdio MCP 服务器。默认情况下，它从 Ben11304/OC-clone/open-construction-data 读取公共目录快照，对记录进行规范化，并将其暴露给兼容 MCP 的智能助手。这样可以让 MCP 安装独立于上游 OpenConstruction 部署。

覆盖 OPENCONSTRUCTION_DATA_BASE_URL 即可使用另一个兼容的目录端点。例如，将其设置为 https://www.openconstruction.org/data 以跟随已部署的 OpenConstruction 站点。

远程入口点添加了支持 PKCE 的 OAuth 2.1 授权、受保护资源发现、动态客户端注册、刷新令牌轮换，以及腾讯 GitHub、Hugging Face 和 Baidu Netdisk 的服务器端连接账户。

使用你的智能体安装

将这段提示复制到兼容 MCP 的编码智能体中：

Install and configure the OpenConstruction MCP for this agent from https://github.com/Ben11304/OC-mcp.

Related MCP server: FilePilot AI

手动安装

git clone https://github.com/Ben11304/OC-mcp.git
cd OC-mcp
uv sync --python 3.12 --frozen

将它注册到 Codex 中，将 project path 替换为你检出目录的绝对路径：

codex mcp add openconstruction -- uv --directory /absolute/path/to/OC-mcp run --frozen openconstruction-mcp

连接到 Claude Desktop

将此服务器添加到你的 Claude Desktop MCP 配置中：

{
  "mcpServers": {
    "openconstruction": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/OC-mcp", "run", "--frozen", "openconstruction-mcp"]
    }
  }
}

保存配置后重启 Claude Desktop。

通过 OpenConstruction 登录的远程 MCP

开发期间，在同一个 origin 上运行网站和远程 MCP/API：

cp .env.example .env
# Fill SUPABASE_URL, SUPABASE_ANON_KEY, and OC_TOKEN_ENCRYPTION_KEY.
set -a && source .env && set +a
uv run openconstruction-remote

远程 MCP 端点是：

http://127.0.0.1:8000/mcp

兼容的 MCP 客户端通过以下方式发现 OAuth：

• /.well-known/oauth-protected-resource/mcp

• /.well-known/oauth-authorization-server

• /register、/authorize、/token 和 /revoke

客户端会打开 OpenConstruction 授权页面。用户使用现有的基于 Supabase 的 OC 账户登录并批准该 MCP 客户端。授权码为一次性，必须使用 PKCE S256，访问令牌有效期为一小时，轮换的刷新令牌最长有效期为 30 天。

在回环（loopback）开发之外，HTTPS 是必需的。

已连接账户

已连接账户功能已经实现，但暂缓上线并默认禁用。在提供方应用、生产密钥存储和隐私审查就绪后，设置 OC_CONNECTED_ACCOUNTS_ENABLED=true。然后，已登录用户就可以在 Workspace → Connections 下管理提供方访问。公共资源不需要已连接账户。

为每个提供方创建一个 OAuth 应用，并注册这些回调，将主机替换为 OC_PUBLIC_URL：

/api/connections/github/callback
/api/connections/huggingface/callback
/api/connections/baidu/callback

根据 .env.example 设置对应的 OC_GITHUB_*、OC_HF_* 和 OC_BAIDU_* 变量。提供方的访问令牌和刷新令牌使用 OC_TOKEN_ENCRYPTION_KEY 加密；API 响应只暴露连接状态和公共账户元数据。请将该密钥以及所有提供方客户端机密保存在服务器密钥管理器中，切勿放入网站 bundle。

提供方参考：

• GitHub OAuth Apps

• Hugging Face OAuth

• Baidu OAuth

元数据来源

• /data/datasets.json

• /data/models.json

• /data/use-cases.json

• /data/oer.json

• /data/tools.json

• /data/guides.json

• /data/contributors.json

• /data/benchmark-results.json

• /data/task-vocabulary.json

MCP 工具

• search_resources

• get_resource

• compare_resources

• get_catalog_stats

• ask_openconstruction

• find_datasets

• run_dataset_discovery

• find_models

• explain_schema

• analyze_catalog_gaps

• prepare_benchmark_submission

• validate_metadata_record

• list_skills

• get_skill

• get_dataset_download_plan

• download_dataset（仅限本地 stdio）

• get_download_status（仅限本地 stdio）

• cancel_download（仅限本地 stdio）

数据集下载

OpenConstruction 使用与网站相同的两条获取路径：

• distribution 记录解析为本地直接下载。

• programmatic_access 记录解析为提供方适配器或结构化 CLI 指引。

务必先调用 get_dataset_download_plan。它是只读的，并会报告提供方、方法、许可证、身份验证要求、估算大小，以及本地 MCP 是否可以执行该路径。download_dataset 需要 accept_license: true，并会启动一个后台任务。用 get_download_status 轮询返回的 download_id；完成的下载会在数据集目录中包含 .openconstruction-manifest.json。

提供方身份验证保持在用户本地；数据集下载不需要 OC OAuth 或已连接账户代管。当受保护源没有可用的本地凭据时，download_dataset 会返回 status: auth_required，并给出提供方特定的登录步骤、安全提示，以及用于重试的确切安全工具载荷。智能体应展示这些步骤，并等待用户在本地终端中完成。智能体绝不能让用户将令牌、密码、OAuth 授权码、cookie 或凭据文件粘贴到聊天中。

初始的本地执行器支持直接 HTTP 文件、http_files、github_clone、huggingface_snapshot 和 figshare_files。其他提供方方法返回 instructions_required 并提供结构化指引，而不是执行目录提供的 shell 文本。

下载被沙盒限制在 OC_DOWNLOAD_ROOT 下（默认：~/.openconstruction/datasets）。可选的 destination 是相对于该根目录的一个目录名。设置 OC_MAX_DOWNLOAD_BYTES 可以限制单个任务的流式 HTTP 传输总大小，并拒绝声明大小超过该上限的数据集；默认值是 500 GiB。对于没有声明大小的 Git 和提供方快照，无法在执行前进行完全检查。私有 Hugging Face 数据集能够识别通过 hf auth login 保存的凭据，以及直接配置在本地 MCP 进程中的 HF_TOKEN。凭据值不会出现在 MCP 工具结果中。

远程 HTTP MCP 暴露了 get_dataset_download_plan，但刻意不暴露写文件的工具。远程服务器不能写入用户的本地文件系统；请使用 stdio MCP 来执行。

技能

技能是 MCP 工具之上的可复用工作流。仓库拥有的技能注册表位于：

• skills/index.json

• skills/<skill-id>/metadata.json

MCP 客户端可以使用 list_skills 或 get_skill。如果仓库保持私有，公共网站应使用已发布的注册表镜像或后端端点，而不是直接从 GitHub raw 文件读取。

dataset-discovery 是第一个可执行的技能。它可以通过 run_dataset_discovery 使用，并返回排序后的候选数据集、匹配理由、检查项和后续建议操作。

如需提议新技能，请使用技能建议素材打开 GitHub issue。元数据要求、评审清单和 pull request 预期请参阅 CONTRIBUTING.md。

初始官方技能聚焦于：

• 数据集发现

• 数据集比较

• 模型发现

• schema 说明

• 目录缺口分析

• 基准准备

开发

python scripts/validate_skills.py
python scripts/package_skills.py
python -m unittest discover -s tests
python scripts/smoke_stdio.py

在本地运行 MCP 服务器：

python -m openconstruction_mcp.server