OpenConstruction MCP
Provides connected-account OAuth integration for Baidu Netdisk, allowing signed-in users to manage provider access under Workspace → Connections. Provider tokens are encrypted, and API responses expose only connection status and public account metadata.
Provides connected-account OAuth integration for GitHub, allowing signed-in users to manage provider access under Workspace → Connections. Provider tokens are encrypted, and API responses expose only connection status and public account metadata.
Provides connected-account OAuth integration for Hugging Face, allowing signed-in users to manage provider access under Workspace → Connections. Provider tokens are encrypted, and API responses expose only connection status and public account metadata.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
OpenConstruction Tools
Local-first MCP server and CLI for OpenConstruction catalog discovery, dataset context, provider-aware acquisition, and safe dataset downloads.
The first release is a local stdio MCP server. By default it reads the public catalog snapshot under Ben11304/OC-clone/open-construction-data, normalizes the records, and exposes them to MCP-compatible assistants. This keeps the MCP install independent from the upstream OpenConstruction deployment.
Override OPENCONSTRUCTION_DATA_BASE_URL to use another compatible catalog endpoint. For example, set it to https://www.openconstruction.org/data to follow the deployed OpenConstruction site instead.
The CLI and MCP use the same OpenConstructionService. Catalog results include
catalog_provenance: the source URL, load time, per-file content hashes, an aggregate
snapshot hash, and any load errors. These hashes identify the fetched JSON content;
they do not pin future requests to a Git revision. Export selected records to preserve
the evidence used in a run. The existing OC-clone default is retained for compatibility
with its acquisition metadata; it is not a claim that the snapshot equals the deployed
OpenConstruction catalog.
The remote entry point adds OAuth 2.1 authorization with PKCE, protected-resource discovery, dynamic client registration, refresh-token rotation, and server-side connected accounts for GitHub, Hugging Face, and Baidu Netdisk.
Install With Your Agent
Copy this prompt into an MCP-compatible coding agent:
Install and configure the OpenConstruction MCP for this agent from https://github.com/ruoxinx/openconstruction-tools.Related MCP server: MCP4RS Open Earth Explorer
Manual Install
git clone https://github.com/ruoxinx/openconstruction-tools.git
cd openconstruction-tools
uv sync --python 3.12 --frozenAlternatively, use python -m pip install . (Python 3.10 or newer).
Command-line access
After installation, run openconstruction --help. From an uv checkout, prefix
commands with uv run --frozen. The CLI runs directly against the shared service;
an MCP client or remote server is not required.
openconstruction search "hardhat" --type dataset --json
openconstruction show dataset MINC-2500
openconstruction discover --task "object detection" --object-class hardhat --license "CC BY 4.0" --json
openconstruction compare MINC-2500 SCUT-HEAD --type dataset --json
openconstruction export MINC-2500 SCUT-HEAD --output selected-resources.json
openconstruction plan MINC-2500 --jsonshow requires an exact ID (case-insensitive); titles and URL substrings are not IDs.
discover ranks candidates and exposes matched, not_matched, or unknown for
each requested constraint. It does not silently discard incomplete candidates or
certify license compatibility. Matching uses the relevant structured fields;
missing annotation or modality metadata remains unknown. compare returns reported
values and missing fields, not a suitability judgment. validate_metadata_record
currently checks required-field presence, not full canonical JSON Schema validity.
Choose a catalog explicitly with --data-base-url or the environment variable:
openconstruction search "hardhat" --data-base-url https://www.openconstruction.org/data --jsonGlobal options (--json, --data-base-url, --download-root) work before or after
the subcommand. --json writes one JSON result to stdout; download progress goes to
stderr. export writes UTF-8 JSON with full selected records and catalog provenance;
it refuses to write when an ID is missing or the catalog is incomplete. An existing
output file is replaced on a successful export.
Review the download plan and terms before using --accept-license:
openconstruction download MINC-2500 --accept-license
openconstruction prepare MINC-2500 --accept-license
openconstruction status <download-or-preparation-id> --jsonWithout acceptance, download returns a read-only plan and prepare returns its
license review (or reuses/resumes a previously accepted matching research package).
download --destination NAME selects one directory inside --download-root or
OC_DOWNLOAD_ROOT. prepare also creates a research summary and provenance manifest.
Both write commands wait through verification and bundle creation, then join their
local worker before exiting. Ctrl+C requests cancellation and retains saved progress;
repeat the accepted command to resume. status reads persistent job state and
distinguishes a running process from an interrupted checkpoint. There is no detached
background CLI mode. Cross-process destination locks work on Windows and POSIX.
Exit codes: 0 success (including an empty search), 1 operation failure, missing
record, or incomplete catalog, 2 argument usage error, 3 action required (license,
authentication, manual acquisition, changed source, or interrupted job), 130 Ctrl+C.
Register the MCP server
Register it with Codex, replacing the project path with the absolute path to your checkout:
codex mcp add openconstruction -- uv --directory /absolute/path/to/openconstruction-tools run --frozen openconstruction-mcpConnect To Claude Desktop
Add this server to your Claude Desktop MCP configuration:
{
"mcpServers": {
"openconstruction": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/openconstruction-tools", "run", "--frozen", "openconstruction-mcp"]
}
}
}Restart Claude Desktop after saving the configuration.
Remote MCP with OpenConstruction login
Run the website and remote MCP/API on one origin during development:
cp .env.example .env
# Fill SUPABASE_URL, SUPABASE_ANON_KEY, and OC_TOKEN_ENCRYPTION_KEY.
set -a && source .env && set +a
uv run openconstruction-remoteThe remote MCP endpoint is:
http://127.0.0.1:8000/mcpCompatible MCP clients discover OAuth through:
/.well-known/oauth-protected-resource/mcp/.well-known/oauth-authorization-server/register,/authorize,/token, and/revoke
The client opens the OpenConstruction authorization page. The user signs in with the existing Supabase-backed OC account and approves the MCP client. Authorization codes are single-use, PKCE S256 is mandatory, access tokens last one hour, and rotating refresh tokens last up to 30 days.
HTTPS is required outside loopback development.
Connected Accounts
Connected Accounts is implemented but deferred and disabled by default. Set OC_CONNECTED_ACCOUNTS_ENABLED=true when the provider applications, production secret storage, and privacy review are ready. Signed-in users will then manage provider access under Workspace → Connections. Public resources do not require a connected account.
Create one OAuth application per provider and register these callbacks, replacing the host with OC_PUBLIC_URL:
/api/connections/github/callback
/api/connections/huggingface/callback
/api/connections/baidu/callbackSet the corresponding OC_GITHUB_*, OC_HF_*, and OC_BAIDU_* variables from .env.example. Provider access and refresh tokens are encrypted with OC_TOKEN_ENCRYPTION_KEY; API responses expose only connection status and public account metadata. Keep that key and all provider client secrets in the server's secret manager, never in the website bundle.
Provider references:
Metadata Sources
/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_resourcesget_resourcecompare_resourcesget_catalog_statsask_openconstructionfind_datasetsrun_dataset_discoveryfind_modelsexplain_schemaanalyze_catalog_gapsprepare_benchmark_submissionvalidate_metadata_recordlist_skillsget_skillget_dataset_download_planprepare_dataset_for_research(local stdio only)get_research_preparation_status(local stdio only)download_dataset(local stdio only)get_download_status(local stdio only)cancel_download(local stdio only)
Dataset Downloads
For the simplest researcher-facing workflow, ask the agent to prepare a dataset
for research. The MCP prefers prepare_dataset_for_research, returns one
plain-language license review, and waits for explicit acceptance before it
starts. The agent then polls get_research_preparation_status and presents one
progress stream instead of exposing the underlying download and bundle steps.
Prepare TunGPR for my research.The completed package contains the dataset, .openconstruction-manifest.json,
and a research/ directory with bundle.json plus a human-readable README.md.
Completed bundle metadata is stored on disk, so get_research_preparation_status
can rediscover a ready package after the MCP restarts.
Reuse and resume are automatic. A normal request such as Prepare TunGPR for my research follows this order:
Return the existing Research Bundle immediately when its dataset source and dataset-license fingerprint still match.
Resume a matching interrupted checkpoint without asking the user to accept the same license again.
Start a new download only when no matching local package or checkpoint exists.
Persistent job state is kept under
OC_DOWNLOAD_ROOT/.openconstruction-state/. HTTP downloads retain an adjacent
.part file and use Range plus If-Range with the saved ETag or
Last-Modified value when the host supports it. A host that ignores range
requests restarts only that incomplete file, not already verified files in the
package. Figshare resumes each file through the same HTTP mechanism; Hugging
Face reuses its local snapshot cache; an interrupted Git clone reuses a valid
matching checkout and fetches the missing revision when necessary.
OpenConstruction verifies the size and SHA-256 of every completed HTTP file
before reusing it. On POSIX systems it also holds a per-destination lock so two
local MCP processes do not download the same package concurrently. If the
catalog route or license changes, the source fingerprint changes
and the MCP returns source_changed rather than overwriting the existing
directory. Git and Hugging Face sources that name a mutable branch still cannot
predict a new upstream commit until the catalog pins or updates that revision.
The lower-level download tools remain available for advanced control and diagnostics:
OpenConstruction uses the same two acquisition routes as the website:
distributionrecords resolve to a direct local download.programmatic_accessrecords resolve to a provider adapter or structured CLI guidance.
Always call get_dataset_download_plan first. It is read-only and reports the
provider, method, license, authentication requirement, estimated size, and
whether the local MCP can execute the route. download_dataset requires
accept_license: true and starts a background job. Poll the returned
download_id with get_download_status; completed downloads include
.openconstruction-manifest.json in the dataset directory.
Every download status includes progress_percent, progress_bar, average
speed_bytes_per_second, eta_seconds, and a ready-to-display progress_text.
MCP instructions ask compatible agents to poll at most once every two seconds
and show that text until the job reaches a terminal status. Downloads whose
provider does not expose a total size return an indeterminate bar and the bytes
received instead of an unreliable percentage.
Provider authentication stays local to the user; OC OAuth and connected-account
brokerage are not required for dataset downloads. When a protected source has no
usable local credential, download_dataset returns status: auth_required,
provider-specific login steps, a security notice, and the exact safe tool payload
to retry. The agent should present those steps and wait for the user to complete
them in a local terminal. It must never ask the user to paste a token, password,
OAuth authorization code, cookie, or credential file into chat.
The initial local executors support direct HTTP files, http_files,
github_clone, huggingface_snapshot, and figshare_files. Other provider
methods return instructions_required with structured guidance instead of
executing catalog-provided shell text.
Downloads are sandboxed under OC_DOWNLOAD_ROOT (default:
~/.openconstruction/datasets). The optional destination is one directory
name relative to that root. Set OC_MAX_DOWNLOAD_BYTES to cap a job's total
streamed HTTP transfer size and reject datasets whose declared size is above
the limit; the default is 500 GiB. Git and provider snapshots without declared
sizes cannot be fully checked before execution. Private Hugging Face datasets
recognize credentials saved by hf auth login as well as HF_TOKEN configured
directly in the local MCP process. Credential values are never included in MCP
tool results.
Remote HTTP MCP exposes get_dataset_download_plan but deliberately does not
expose tools that write files. A remote server cannot write into the user's
local filesystem; use the stdio MCP for execution.
Skills
Skills are reusable workflows over the MCP tools. The repo-owned skill registry lives at:
skills/index.jsonskills/<skill-id>/metadata.json
MCP clients can use list_skills or get_skill.
dataset-discovery is the first executable skill. It is available through run_dataset_discovery and returns ranked dataset candidates, fit reasons, checks, and suggested next actions.
To propose a new skill, open a GitHub issue with the skill proposal template. See CONTRIBUTING.md for metadata requirements, review checks, and pull request expectations.
Initial official skills focus on:
dataset discovery
dataset comparison
model discovery
schema explanation
catalog gap analysis
benchmark preparation
Development
python scripts/validate_skills.py
python scripts/package_skills.py
python -m unittest discover -s tests
python scripts/smoke_stdio.pyRun the MCP server locally:
python -m openconstruction_mcp.serverTool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Search and read the aicoolies catalog of AI and developer tools via a remote MCP knowledge graph.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP gateway and offline catalog CLI that aggregates multiple upstream MCP servers into a single stdio endpoint, and provides tool recommendation and catalog inspection without connecting to upstreams.MIT
- AlicenseNot gradedqualityDmaintenanceEnables discovery, analysis, and explanation of open satellite data through MCP, with support for STAC catalogs and NASA GIBS.1MIT
- AlicenseCqualityDmaintenanceLocal-first MCP server enabling catalog discovery, dataset context, and safe downloads of construction datasets.18Apache 2.0
- AlicenseAqualityBmaintenanceProvides construction-supervision tools for small-to-medium building projects, including stage guidance, inspection checklists, progress tracking, next-stage recommendations, and quotation analysis. It enables local, standards-based MCP interaction over stdio without third-party MCP SDKs.5MIT