OpenConstruction MCP
by ruoxinx
README.md
# 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`](https://github.com/Ben11304/OC-clone/tree/main/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:
```text
Install and configure the OpenConstruction MCP for this agent from https://github.com/ruoxinx/openconstruction-tools.
```
## Manual Install
```bash
git clone https://github.com/ruoxinx/openconstruction-tools.git
cd openconstruction-tools
uv sync --python 3.12 --frozen
```
Alternatively, 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.
```bash
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 --json
```
`show` 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:
```bash
openconstruction search "hardhat" --data-base-url https://www.openconstruction.org/data --json
```
Global 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`:
```bash
openconstruction download MINC-2500 --accept-license
openconstruction prepare MINC-2500 --accept-license
openconstruction status <download-or-preparation-id> --json
```
Without 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:
```bash
codex mcp add openconstruction -- uv --directory /absolute/path/to/openconstruction-tools run --frozen openconstruction-mcp
```
## Connect To Claude Desktop
Add this server to your Claude Desktop MCP configuration:
```json
{
"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:
```bash
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
```
The remote MCP endpoint is:
```text
http://127.0.0.1:8000/mcp
```
Compatible 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`:
```text
/api/connections/github/callback
/api/connections/huggingface/callback
/api/connections/baidu/callback
```
Set 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:
- [GitHub OAuth Apps](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps)
- [Hugging Face OAuth](https://huggingface.co/docs/hub/en/oauth)
- [Baidu OAuth](https://openauth.baidu.com/doc/doc.html)
## 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_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`
- `prepare_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.
```text
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:
1. Return the existing Research Bundle immediately when its dataset source
and dataset-license fingerprint still match.
2. Resume a matching interrupted checkpoint without asking the user to accept
the same license again.
3. 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:
- `distribution` records resolve to a direct local download.
- `programmatic_access` records 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.json`
- `skills/<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](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
```bash
python scripts/validate_skills.py
python scripts/package_skills.py
python -m unittest discover -s tests
python scripts/smoke_stdio.py
```
Run the MCP server locally:
```bash
python -m openconstruction_mcp.server
```
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues