OpenConstruction MCP

Local-first MCP-сервер для обнаружения каталога OpenConstruction, контекста наборов данных, получения данных с учётом провайдера и безопасной загрузки наборов данных.

Первый выпуск — это локальный stdio MCP-сервер. По умолчанию он читает публичный снимок каталога из Ben11304/OC-clone/open-construction-data, нормализует записи и предоставляет их MCP-совместимым ассистентам. Это сохраняет независимость установки MCP от вышестоящего развёртывания OpenConstruction.

Переопределите OPENCONSTRUCTION_DATA_BASE_URL, чтобы использовать другую совместимую конечную точку каталога. Например, установите её в https://www.openconstruction.org/data, чтобы вместо этого следовать за развёрнутым сайтом OpenConstruction.

Удалённая точка входа добавляет авторизацию OAuth 2.1 с PKCE, обнаружение защищённых ресурсов, динамическую регистрацию клиентов, ротацию refresh-токенов и серверные подключённые учётные записи для 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, заменив путь к проекту абсолютным путём до вашей локальной копии:

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

Подключение к Claude Desktop

Добавьте этот сервер в конфигурацию MCP вашего Claude Desktop:

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

Перезапустите Claude Desktop после сохранения конфигурации.

Удалённый MCP со входом в OpenConstruction

Во время разработки запускайте веб-сайт и удалённый MCP/API на одном origin:

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. Пользователь входит с помощью существующей учётной записи OC на базе Supabase и одобряет MCP-клиента. Коды авторизации одноразовые, PKCE S256 обязателен, токены доступа действуют один час, а ротационные refresh-токены — до 30 дней.

Вне разработки через loopback требуется HTTPS.

Подключённые учётные записи

Функция Connected Accounts реализована, но отложена и отключена по умолчанию. Установите OC_CONNECTED_ACCOUNTS_ENABLED=true, когда будут готовы приложения провайдеров, производственное хранилище секретов и проверка конфиденциальности. После этого вошедшие пользователи смогут управлять доступом провайдеров в разделе Workspace → Connections. Публичные ресурсы не требуют подключённой учётной записи.

Создайте по одному OAuth-приложению для каждого провайдера и зарегистрируйте эти callback-адреса, заменив хост на OC_PUBLIC_URL:

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

Задайте соответствующие переменные OC_GITHUB_*, OC_HF_* и OC_BAIDU_* из .env.example. Токены доступа и refresh-токены провайдеров шифруются с помощью OC_TOKEN_ENCRYPTION_KEY; ответы API раскрывают только статус подключения и публичные метаданные учётной записи. Храните этот ключ и все клиентские секреты провайдеров в менеджере секретов сервера, никогда — в бандле веб-сайта.

Справочные материалы провайдеров:

• 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 и запускает фоновое задание. Опрашивайте возвращённый download_id с помощью get_download_status; завершённые загрузки включают .openconstruction-manifest.json в каталог набора данных.

Аутентификация провайдера остаётся локальной для пользователя; OAuth OC и брокеридж подключённых учётных записей не требуются для загрузки наборов данных. Когда у защищённого источника нет пригодных локальных учётных данных, 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, а также HF_TOKEN, настроенный непосредственно в локальном процессе MCP. Значения учётных данных никогда не включаются в результаты инструментов MCP.

Удалённый HTTP MCP предоставляет get_dataset_download_plan, но намеренно не предоставляет инструменты, которые записывают файлы. Удалённый сервер не может записывать в локальную файловую систему пользователя; для выполнения используйте stdio MCP.

Навыки

Навыки — это переиспользуемые рабочие процессы поверх инструментов MCP. Реестр навыков, принадлежащий репозиторию, находится здесь:

• skills/index.json

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

MCP-клиенты могут использовать list_skills или get_skill. Если репозиторий остаётся приватным, публичный веб-сайт должен использовать опубликованное зеркало реестра или серверную конечную точку вместо прямого чтения raw-файлов GitHub.

dataset-discovery — первый исполняемый навык. Он доступен через run_dataset_discovery и возвращает ранжированных кандидатов наборов данных, причины соответствия, проверки и предлагаемые следующие действия.

Чтобы предложить новый навык, откройте issue на GitHub с шаблоном предложения навыка. О требованиях к метаданным, проверках при ревью и ожиданиях от pull request см. в CONTRIBUTING.md.

Первоначальные официальные навыки сосредоточены на:

• обнаружении наборов данных

• сравнении наборов данных

• обнаружении моделей

• объяснении схем

• анализе пробелов каталога

• подготовке бенчмарков

Разработка

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