OpenConstruction MCP

ローカルファーストのMCPサーバーで、OpenConstructionカタログの検出、データセットのコンテキスト、プロバイダーを意識した取得、安全なデータセットのダウンロードを提供します。

最初のリリースはローカル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に登録し、プロジェクトパスをチェックアウトの絶対パスに置き換えます:

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

開発中は、Webサイトとリモート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が必須です。アクセストークンは1時間有効で、ローテーションするリフレッシュトークンは最大30日間有効です。

ループバック開発以外ではHTTPSが必要です。

接続アカウント

接続アカウントは実装されていますが、延期されており、デフォルトでは無効です。プロバイダーアプリケーション、本番シークレットストレージ、プライバシーレビューの準備ができたら、OC_CONNECTED_ACCOUNTS_ENABLED=true を設定します。サインインしたユーザーは、ワークスペース → 接続 でプロバイダーアクセスを管理できるようになります。公開リソースには接続アカウントは必要ありません。

プロバイダーごとに1つの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レスポンスは接続ステータスと公開アカウントメタデータのみを公開します。そのキーとすべてのプロバイダークライアントシークレットは、サーバーのシークレットマネージャーに保管し、Webサイトのバンドルには決して含めないでください。

プロバイダーリファレンス:

• 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は、Webサイトと同じ2つの取得ルートを使用します:

• distribution レコードは直接ローカルダウンロードに解決されます。

• programmatic_access レコードはプロバイダーアダプターまたは構造化CLIガイダンスに解決されます。

常に最初に get_dataset_download_plan を呼び出してください。これは読み取り専用で、プロバイダー、メソッド、ライセンス、認証要件、推定サイズ、ローカルMCPがルートを実行できるかどうかを報告します。download_dataset は accept_license: true を必要とし、バックグラウンドジョブを開始します。返された download_id を get_download_status でポーリングします。完了したダウンロードには、データセットディレクトリに .openconstruction-manifest.json が含まれます。

プロバイダー認証はユーザーのローカルに留まります。データセットのダウンロードにOC OAuthや接続アカウントのブローカーは必要ありません。保護されたソースに使用可能なローカル資格情報がない場合、download_dataset は status: auth_required、プロバイダー固有のログイン手順、セキュリティ通知、再試行する正確な安全なツールペイロードを返します。エージェントはこれらの手順を提示し、ユーザーがローカルターミナルで完了するのを待つ必要があります。トークン、パスワード、OAuth認可コード、Cookie、資格情報ファイルをチャットに貼り付けるようユーザーに求めてはなりません。

初期のローカルエグゼキュータは、直接HTTPファイル、http_files、github_clone、huggingface_snapshot、figshare_files をサポートしています。他のプロバイダーメソッドは、カタログ提供のシェルテキストを実行する代わりに、構造化ガイダンス付きの instructions_required を返します。

ダウンロードは OC_DOWNLOAD_ROOT (デフォルト: ~/.openconstruction/datasets) の下にサンドボックス化されます。オプションの destination は、そのルートに対する1つのディレクトリ名です。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 を使用できます。リポジトリがプライベートのままの場合、公開WebサイトはGitHubのrawファイルを直接読み取る代わりに、公開されたレジストリミラーまたはバックエンドエンドポイントを使用する必要があります。

dataset-discovery は最初の実行可能なスキルです。run_dataset_discovery を通じて利用でき、ランク付けされたデータセット候補、適合理由、チェック、推奨される次のアクションを返します。

新しいスキルを提案するには、スキル提案テンプレートを使用してGitHub issueを開いてください。メタデータ要件、レビューチェック、プルリクエストの期待については、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