Programmatic Access

Provide tools and assistants structured access to OpenConstruction catalogs through a Web API and an Agent Interface (MCP).

Overview

Access Architecture

OpenConstruction provides two complementary machine-access interfaces to the same authoritative catalogs.

Web API (Static JSON)

Best for: scripts, web apps, pipelines, reproducible research, CI.

Fetch JSON No auth Versionable
Agent Interface (MCP)

Best for: AI assistants and tool-calling workflows.

Tool interface Read-only Assistant-ready
Read-only policy

Both interfaces are read-only to protect integrity and provenance. Contributions occur through the OpenConstruction contribution workflow.

Web API

Static JSON API

Public, machine-readable endpoints served under /data/.

Endpoints

Catalogs are served as static JSON:

📦 Datasets
/data/datasets.json
🧠 Models
/data/models.json
🧩 Use cases
/data/use-cases.json
🛠️ Tools
/data/tools.json
📘 Guides
/data/guides.json
🎓 OERs
/data/oer.json
🌍 Contributors
/data/contributors.json
🧭 Taxonomy
/data/object_vocab.json /data/object_taxonomy_config.json
Data shape compatibility

Catalogs may be stored as an array, an envelope object containing an array, or an {id: record} map. If you need a stable normalized interface, use the SDK below.

Access patterns

https://www.openconstruction.org/data/datasets.json
https://raw.githubusercontent.com/ruoxinx/open-construction/main/site/data/datasets.json

SDK (optional)

The OpenConstruction SDK provides normalization + search helpers. Keep code examples in README; the page below provides minimal copy-paste blocks. 

npm i @openconstruction/api
import { OpenConstructionClient } from "@openconstruction/api";

const oc = new OpenConstructionClient({
  baseUrl: "https://www.openconstruction.org",
  noCache: true
});

const hits = await oc.search("models", "BIM", { limit: 50 });
Agent Interface

Model Context Protocol (MCP)

What is MCP?

Model Context Protocol (MCP) standardizes how AI assistants connect to external tools and data sources. The OpenConstruction MCP server exposes read-only access to our Datasets, Models, Use Cases, Tools, and Guides catalogs through a small set of server tools.

Example

Ask: “Find 2024 datasets for safety monitoring.” → receive structured metadata with links back to the catalog entries.

MCP quick links
Capabilities

Available Tools

Core tool groups exposed by the OpenConstruction MCP server:

🔍 Search resources
search_models search_datasets search_use_cases
📊 Get details
get_model_details get_dataset_details
🛠️ Browse & guidance
list_tools get_best_practices
📈 Catalog statistics
get_catalog_stats
Setup

Install & Connect

Minimal steps to run the server locally and connect it to an MCP-compatible client (e.g., Claude Desktop).

  • Clone repository 
    git clone https://github.com/ruoxinx/openconstruction-mcp-server.git
cd openconstruction-mcp-server
  • Install dependencies 
    npm install
  • Build server 
    npm run build
  • Configure Claude Desktop

    Add to claude_desktop_config.json:

    {
  "mcpServers": {
    "openconstruction": {
      "command": "node",
      "args": ["/path/to/build/index.js"]
    }
  }
}

    See: Claude Desktop MCP guide

  • Restart & verify

    Reopen Claude Desktop and run.

Examples

Usage Scenarios

Dataset discovery: “List point cloud datasets for semantic segmentation.”
Model search: “Find models for safety monitoring published after 2023.”
Use-case exploration: “Show industry deployments of computer vision.”
Issue or Suggestion?