OpenConstruction MCP

Servidor MCP local-first para el descubrimiento de catálogos de OpenConstruction, contexto de conjuntos de datos, adquisición consciente del proveedor y descargas seguras de conjuntos de datos.

La primera versión es un servidor MCP stdio local. Por defecto, lee la instantánea pública del catálogo en Ben11304/OC-clone/open-construction-data, normaliza los registros y los expone a asistentes compatibles con MCP. Esto mantiene la instalación de MCP independiente del despliegue upstream de OpenConstruction.

Sobrescribe OPENCONSTRUCTION_DATA_BASE_URL para usar otro endpoint de catálogo compatible. Por ejemplo, establécelo en https://www.openconstruction.org/data para seguir el sitio OpenConstruction desplegado en su lugar.

El punto de entrada remoto añade autorización OAuth 2.1 con PKCE, descubrimiento de recursos protegidos, registro dinámico de clientes, rotación de tokens de refresco y cuentas conectadas del lado del servidor para GitHub, Hugging Face y Baidu Netdisk.

Instalar con tu agente

Copia este prompt en un agente de codificación compatible con MCP:

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

Related MCP server: FilePilot AI

Instalación manual

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

Regístralo con Codex, reemplazando la ruta del proyecto por la ruta absoluta a tu checkout:

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

Conectar con Claude Desktop

Añade este servidor a tu configuración MCP de Claude Desktop:

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

Reinicia Claude Desktop después de guardar la configuración.

MCP remoto con inicio de sesión de OpenConstruction

Ejecuta el sitio web y el MCP/API remoto en un mismo origen durante el desarrollo:

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

El endpoint MCP remoto es:

http://127.0.0.1:8000/mcp

Los clientes MCP compatibles descubren OAuth a través de:

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

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

• /register, /authorize, /token, y /revoke

El cliente abre la página de autorización de OpenConstruction. El usuario inicia sesión con la cuenta OC existente respaldada por Supabase y aprueba el cliente MCP. Los códigos de autorización son de un solo uso, PKCE S256 es obligatorio, los tokens de acceso duran una hora y los tokens de refresco rotatorios duran hasta 30 días.

Se requiere HTTPS fuera del desarrollo en loopback.

Cuentas conectadas

La función de cuentas conectadas está implementada, pero diferida y deshabilitada por defecto. Establece OC_CONNECTED_ACCOUNTS_ENABLED=true cuando las aplicaciones de proveedor, el almacenamiento de secretos de producción y la revisión de privacidad estén listos. Los usuarios con sesión iniciada podrán entonces gestionar el acceso de proveedores en Workspace → Connections. Los recursos públicos no requieren una cuenta conectada.

Crea una aplicación OAuth por proveedor y registra estos callbacks, reemplazando el host por OC_PUBLIC_URL:

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

Establece las variables OC_GITHUB_*, OC_HF_* y OC_BAIDU_* correspondientes desde .env.example. Los tokens de acceso y de refresco de los proveedores se cifran con OC_TOKEN_ENCRYPTION_KEY; las respuestas de la API exponen solo el estado de la conexión y los metadatos públicos de la cuenta. Mantén esa clave y todos los secretos de cliente de los proveedores en el gestor de secretos del servidor, nunca en el bundle del sitio web.

Referencias de proveedores:

• GitHub OAuth Apps

• Hugging Face OAuth

• Baidu OAuth

Fuentes de metadatos

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

Herramientas 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 (solo stdio local)

• get_download_status (solo stdio local)

• cancel_download (solo stdio local)

Descargas de conjuntos de datos

OpenConstruction utiliza las mismas dos rutas de adquisición que el sitio web:

• Los registros distribution se resuelven en una descarga local directa.

• Los registros programmatic_access se resuelven en un adaptador de proveedor o en una guía estructurada de CLI.

Llama siempre a get_dataset_download_plan primero. Es de solo lectura e informa del proveedor, método, licencia, requisito de autenticación, tamaño estimado y de si el MCP local puede ejecutar la ruta. download_dataset requiere accept_license: true e inicia un trabajo en segundo plano. Consulta el download_id devuelto con get_download_status; las descargas completadas incluyen .openconstruction-manifest.json en el directorio del conjunto de datos.

La autenticación del proveedor permanece local para el usuario; no se requieren OAuth de OC ni intermediación de cuentas conectadas para las descargas de conjuntos de datos. Cuando una fuente protegida no tiene una credencial local utilizable, download_dataset devuelve status: auth_required, pasos de inicio de sesión específicos del proveedor, un aviso de seguridad y la carga útil exacta de herramienta segura para reintentar. El agente debe presentar esos pasos y esperar a que el usuario los complete en una terminal local. Nunca debe pedir al usuario que pegue un token, contraseña, código de autorización OAuth, cookie o archivo de credenciales en el chat.

Los ejecutores locales iniciales admiten archivos HTTP directos, http_files, github_clone, huggingface_snapshot y figshare_files. Otros métodos de proveedor devuelven instructions_required con orientación estructurada en lugar de ejecutar texto de shell proporcionado por el catálogo.

Las descargas se aíslan en OC_DOWNLOAD_ROOT (por defecto: ~/.openconstruction/datasets). El destination opcional es un nombre de directorio relativo a esa raíz. Establece OC_MAX_DOWNLOAD_BYTES para limitar el tamaño total de transferencia HTTP transmitida de un trabajo y rechazar conjuntos de datos cuyo tamaño declarado supere el límite; el valor por defecto es 500 GiB. Las instantáneas de Git y de proveedores sin tamaños declarados no se pueden verificar completamente antes de la ejecución. Los conjuntos de datos privados de Hugging Face reconocen las credenciales guardadas por hf auth login, así como HF_TOKEN configurado directamente en el proceso MCP local. Los valores de credenciales nunca se incluyen en los resultados de las herramientas MCP.

El MCP HTTP remoto expone get_dataset_download_plan, pero deliberadamente no expone herramientas que escriban archivos. Un servidor remoto no puede escribir en el sistema de archivos local del usuario; usa el MCP stdio para la ejecución.

Habilidades

Las habilidades son flujos de trabajo reutilizables sobre las herramientas MCP. El registro de habilidades propiedad del repositorio se encuentra en:

• skills/index.json

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

Los clientes MCP pueden usar list_skills o get_skill. Si el repositorio sigue siendo privado, el sitio web público debería usar un espejo publicado del registro o un endpoint de backend en lugar de leer directamente los archivos raw de GitHub.

dataset-discovery es la primera habilidad ejecutable. Está disponible a través de run_dataset_discovery y devuelve candidatos de conjuntos de datos clasificados, razones de idoneidad, comprobaciones y próximas acciones sugeridas.

Para proponer una nueva habilidad, abre un issue de GitHub con la plantilla de propuesta de habilidad. Consulta CONTRIBUTING.md para conocer los requisitos de metadatos, las comprobaciones de revisión y las expectativas de las pull requests.

Las habilidades oficiales iniciales se centran en:

• descubrimiento de conjuntos de datos

• comparación de conjuntos de datos

• descubrimiento de modelos

• explicación de esquemas

• análisis de brechas del catálogo

• preparación de benchmarks

Desarrollo

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

Ejecuta el servidor MCP localmente:

python -m openconstruction_mcp.server