OpenConstruction MCP

Local-first MCP-Server für die OpenConstruction-Katalogsuche, den Datenkontext, den anbieterbewussten Abruf und sichere Dataset-Downloads.

Die erste Version ist ein lokaler stdio-MCP-Server. Standardmäßig liest er den öffentlichen Katalogschnappschuss unter Ben11304/OC-clone/open-construction-data, normalisiert die Datensätze und stellt sie MCP-kompatiblen Assistenten zur Verfügung. Dadurch bleibt die MCP-Installation unabhängig von der vorgelagerten OpenConstruction-Bereitstellung.

Überschreiben Sie OPENCONSTRUCTION_DATA_BASE_URL, um einen anderen kompatiblen Katalogendpunkt zu verwenden. Setzen Sie die Variable beispielsweise auf https://www.openconstruction.org/data, um stattdessen der bereitgestellten OpenConstruction-Website zu folgen.

Der Remote-Einstiegspunkt fügt OAuth-2.1-Autorisierung mit PKCE, die Erkennung geschützter Ressourcen, die dynamische Client-Registrierung, die Rotation von Aktualisierungstokens und serverseitige verbundene Konten für GitHub, Hugging Face und Baidu Netdisk hinzu.

Installation mit Ihrem Agenten

Kopieren Sie diese Eingabeaufforderung in einen MCP-kompatiblen Codierungsagenten:

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

Related MCP server: FilePilot AI

Manuelle Installation

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

Registrieren Sie es bei Codex und ersetzen Sie den Projektpfad durch den absoluten Pfad zu Ihrem Checkout:

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

Verbindung zu Claude Desktop herstellen

Fügen Sie diesen Server Ihrer Claude-Desktop-MCP-Konfiguration hinzu:

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

Starten Sie Claude Desktop nach dem Speichern der Konfiguration neu.

Remote-MCP mit OpenConstruction-Anmeldung

Führen Sie die Website und das Remote-MCP/API während der Entwicklung auf einem Ursprung aus:

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

Der Remote-MCP-Endpunkt lautet:

http://127.0.0.1:8000/mcp

Kompatible MCP-Clients erkennen OAuth über:

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

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

• /register, /authorize, /token und /revoke

Der Client öffnet die OpenConstruction-Autorisierungsseite. Der Benutzer meldet sich mit dem vorhandenen Supabase-gestützten OC-Konto an und genehmigt den MCP-Client. Autorisierungscodes sind nur einmal verwendbar, PKCE S256 ist Pflicht, Zugriffstokens sind eine Stunde gültig und rotierende Aktualisierungstokens bis zu 30 Tage.

Außerhalb der Loopback-Entwicklung ist HTTPS erforderlich.

Verbundene Konten

Verbundene Konten sind implementiert, aber zurückgestellt und standardmäßig deaktiviert. Setzen Sie OC_CONNECTED_ACCOUNTS_ENABLED=true, wenn die Anbieteranwendungen, die Produktionsspeicherung von Geheimnissen und die Datenschutzprüfung bereit sind. Angemeldete Benutzer verwalten dann den Anbieterzugriff unter Arbeitsbereich → Verbindungen. Öffentliche Ressourcen erfordern kein verbundenes Konto.

Erstellen Sie eine OAuth-Anwendung pro Anbieter und registrieren Sie diese Rückrufe, wobei Sie den Host durch OC_PUBLIC_URL ersetzen:

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

Legen Sie die entsprechenden Variablen OC_GITHUB_*, OC_HF_* und OC_BAIDU_* aus .env.example fest. Zugriffs- und Aktualisierungstokens des Anbieters werden mit OC_TOKEN_ENCRYPTION_KEY verschlüsselt; API-Antworten legen nur den Verbindungsstatus und öffentliche Kontometadaten offen. Bewahren Sie diesen Schlüssel und alle Client-Geheimnisse des Anbieters im Secret Manager des Servers auf, niemals im Website-Bundle.

Anbieterreferenzen:

• GitHub-OAuth-Apps

• Hugging-Face-OAuth

• Baidu-OAuth

Metadatenquellen

• /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-Tools

• 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 (nur lokales stdio)

• get_download_status (nur lokales stdio)

• cancel_download (nur lokales stdio)

Dataset-Downloads

OpenConstruction verwendet dieselben zwei Abrufwege wie die Website:

• distribution-Datensätze werden in einen direkten lokalen Download aufgelöst.

• programmatic_access-Datensätze werden in einen Anbieteradapter oder eine strukturierte CLI-Anleitung aufgelöst.

Rufen Sie immer zuerst get_dataset_download_plan auf. Dieser ist schreibgeschützt und meldet den Anbieter, die Methode, die Lizenz, die Authentifizierungsanforderung, die geschätzte Größe und ob das lokale MCP die Route ausführen kann. download_dataset erfordert accept_license: true und startet einen Hintergrundauftrag. Fragen Sie die zurückgegebene download_id mit get_download_status ab. Abgeschlossene Downloads enthalten .openconstruction-manifest.json im Dataset-Verzeichnis.

Die Anbieterauthentifizierung bleibt lokal beim Benutzer; OC-OAuth und die Vermittlung verbundener Konten sind für Dataset-Downloads nicht erforderlich. Wenn eine geschützte Quelle über keine verwendbaren lokalen Anmeldeinformationen verfügt, gibt download_dataset status: auth_required, anbieterspezifische Anmeldeschritte, einen Sicherheitshinweis und die genaue sichere Tool-Nutzlast zum erneuten Versuch zurück. Der Agent sollte diese Schritte präsentieren und darauf warten, dass der Benutzer sie in einem lokalen Terminal ausführt. Er darf den Benutzer niemals bitten, ein Token, ein Passwort, einen OAuth-Autorisierungscode, ein Cookie oder eine Datei mit Anmeldeinformationen in den Chat einzufügen.

Die anfänglichen lokalen Ausführenden unterstützen direkte HTTP-Dateien, http_files, github_clone, huggingface_snapshot und figshare_files. Andere Anbietermethoden geben instructions_required mit strukturierter Anleitung zurück, anstatt vom Katalog bereitgestellten Shell-Text auszuführen.

Downloads sind unter OC_DOWNLOAD_ROOT (Standard: ~/.openconstruction/datasets) in einer Sandbox isoliert. Das optionale destination ist ein Verzeichnisname relativ zu diesem Stammverzeichnis. Legen Sie OC_MAX_DOWNLOAD_BYTES fest, um die gesamte gestreamte HTTP-Übertragungsgröße eines Auftrags zu begrenzen und Datasets abzulehnen, deren deklarierte Größe über dem Limit liegt; der Standardwert ist 500 GiB. Git- und Anbieterschnappschüsse ohne deklarierte Größe können vor der Ausführung nicht vollständig überprüft werden. Private Hugging-Face-Datasets erkennen Anmeldeinformationen, die mit hf auth login gespeichert wurden, sowie HF_TOKEN, das direkt im lokalen MCP-Prozess konfiguriert ist. Anmeldeinformationen werden niemals in MCP-Toolergebnissen angezeigt.

Das Remote-HTTP-MCP stellt get_dataset_download_plan bereit, aber bewusst keine Tools, die Dateien schreiben. Ein Remoteserver kann nicht in das lokale Dateisystem des Benutzers schreiben; verwenden Sie für die Ausführung das Stdio-MCP.

Fähigkeiten

Fähigkeiten sind wiederverwendbare Arbeitsabläufe über die MCP-Tools. Die zum Repository gehörende Fähigkeitsregistrierung befindet sich unter:

• skills/index.json

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

MCP-Clients können list_skills oder get_skill verwenden. Wenn das Repository privat bleibt, sollte die öffentliche Website einen veröffentlichten Registrierungsspiegel oder Backend-Endpunkt verwenden, anstatt GitHub-Rohdateien direkt zu lesen.

dataset-discovery ist die erste ausführbare Fähigkeit. Sie ist über run_dataset_discovery verfügbar und gibt nach Relevanz sortierte Dataset-Kandidaten, Begründungen für die Eignung, Prüfungen und empfohlene nächste Schritte zurück.

Um eine neue Fähigkeit vorzuschlagen, öffnen Sie ein GitHub-Issue mit der Vorlage für Fähigkeitsvorschläge. Weitere Informationen zu Metadatenanforderungen, Überprüfungen und Pull-Request-Erwartungen finden Sie in CONTRIBUTING.md.

Die ersten offiziellen Fähigkeiten konzentrieren sich auf:

• Dataset-Erkennung

• Dataset-Vergleich

• Modellerkennung

• Schema-Erklärung

• Kataloglückenanalyse

• Benchmark-Vorbereitung

Entwicklung

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

Führen Sie den MCP-Server lokal aus:

python -m openconstruction_mcp.server