OpenConstruction MCP

로컬 우선 MCP 서버로, OpenConstruction 카탈로그 탐색, 데이터셋 컨텍스트, 공급자 인지 획득, 안전한 데이터셋 다운로드를 제공합니다.

첫 번째 릴리스는 로컬 stdio MCP 서버입니다. 기본적으로 Ben11304/OC-clone/open-construction-data 아래의 공개 카탈로그 스냅샷을 읽고, 레코드를 정규화한 다음 MCP 호환 어시스턴트에 노출합니다. 이렇게 하면 MCP 설치가 업스트림 OpenConstruction 배포와 독립적으로 유지됩니다.

OPENCONSTRUCTION_DATA_BASE_URL을 재정의하여 다른 호환 카탈로그 엔드포인트를 사용할 수 있습니다. 예를 들어, 배포된 OpenConstruction 사이트를 따르려면 https://www.openconstruction.org/data로 설정하세요.

원격 진입점은 PKCE가 포함된 OAuth 2.1 인증, 보호 리소스 검색, 동적 클라이언트 등록, 리프레시 토큰 순환, GitHub, Hugging Face, Baidu Netdisk용 서버 측 연결 계정을 추가합니다.

에이전트와 함께 설치하기

이 프롬프트를 MCP 호환 코딩 에이전트에 복사하세요:

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

Related MCP server: FilePilot AI

수동 설치

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

프로젝트 경로를 체크아웃의 절대 경로로 바꿔 Codex에 등록하세요:

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

Claude Desktop에 연결하기

이 서버를 Claude Desktop MCP 구성에 추가하세요:

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

구성을 저장한 후 Claude Desktop을 다시 시작하세요.

OpenConstruction 로그인을 사용한 원격 MCP

개발 중에는 웹사이트와 원격 MCP/API를 하나의 오리진에서 실행하세요:

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

원격 MCP 엔드포인트는 다음과 같습니다:

http://127.0.0.1:8000/mcp

호환 MCP 클라이언트는 다음을 통해 OAuth를 검색합니다:

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

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

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

클라이언트는 OpenConstruction 인증 페이지를 엽니다. 사용자는 기존 Supabase 기반 OC 계정으로 로그인하고 MCP 클라이언트를 승인합니다. 인증 코드는 일회용이며, PKCE S256이 필수이고, 액세스 토큰은 1시간 동안 유효하며, 순환 리프레시 토큰은 최대 30일 동안 유효합니다.

루프백 개발 외에는 HTTPS가 필요합니다.

연결 계정

연결 계정(Connected Accounts)은 구현되었지만 지연되었으며 기본적으로 비활성화되어 있습니다. 공급자 애플리케이션, 프로덕션 비밀 저장소, 개인정보 검토가 준비되면 OC_CONNECTED_ACCOUNTS_ENABLED=true를 설정하세요. 그러면 로그인한 사용자는 Workspace → Connections에서 공급자 액세스를 관리할 수 있습니다. 공개 리소스에는 연결 계정이 필요하지 않습니다.

공급자별로 OAuth 애플리케이션을 하나씩 만들고 호스트를 OC_PUBLIC_URL로 바꿔 다음 콜백을 등록하세요:

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

.env.example에서 해당 OC_GITHUB_*, OC_HF_*, OC_BAIDU_* 변수를 설정하세요. 공급자 액세스 및 리프레시 토큰은 OC_TOKEN_ENCRYPTION_KEY로 암호화됩니다. API 응답은 연결 상태와 공개 계정 메타데이터만 노출합니다. 해당 키와 모든 공급자 클라이언트 비밀은 서버의 비밀 관리자에 보관하고, 웹사이트 번들에는 절대 포함하지 마세요.

공급자 참조:

• GitHub OAuth Apps

• Hugging Face OAuth

• Baidu OAuth

메타데이터 소스

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

• 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 (로컬 stdio 전용)

• get_download_status (로컬 stdio 전용)

• cancel_download (로컬 stdio 전용)

데이터셋 다운로드

OpenConstruction은 웹사이트와 동일한 두 가지 획득 경로를 사용합니다:

• distribution 레코드는 직접 로컬 다운로드로 연결됩니다.

• programmatic_access 레코드는 공급자 어댑터 또는 구조화된 CLI 안내로 연결됩니다.

항상 먼저 get_dataset_download_plan을 호출하세요. 이 도구는 읽기 전용이며 공급자, 방법, 라이선스, 인증 요구 사항, 예상 크기, 로컬 MCP가 해당 경로를 실행할 수 있는지 여부를 보고합니다. download_dataset는 accept_license: true가 필요하며 백그라운드 작업을 시작합니다. 반환된 download_id를 get_download_status로 폴링하세요. 완료된 다운로드에는 데이터셋 디렉터리에 .openconstruction-manifest.json이 포함됩니다.

공급자 인증은 사용자 로컬에 유지됩니다. 데이터셋 다운로드에는 OC OAuth 및 연결 계정 브로커리지가 필요하지 않습니다. 보호된 소스에 사용 가능한 로컬 자격 증명이 없는 경우, download_dataset는 status: auth_required, 공급자별 로그인 단계, 보안 공지, 재시도할 정확한 안전한 도구 페이로드를 반환합니다. 에이전트는 해당 단계를 제시하고 사용자가 로컬 터미널에서 완료할 때까지 기다려야 합니다. 사용자에게 토큰, 비밀번호, OAuth 인증 코드, 쿠키 또는 자격 증명 파일을 채팅에 붙여넣도록 요청해서는 절대 안 됩니다.

초기 로컬 실행기는 직접 HTTP 파일, http_files, github_clone, huggingface_snapshot, figshare_files를 지원합니다. 다른 공급자 방법은 카탈로그 제공 셸 텍스트를 실행하는 대신 구조화된 안내와 함께 instructions_required를 반환합니다.

다운로드는 OC_DOWNLOAD_ROOT(기본값: ~/.openconstruction/datasets) 아래에 샌드박스 처리됩니다. 선택적 destination은 해당 루트를 기준으로 한 디렉터리 이름 하나입니다. OC_MAX_DOWNLOAD_BYTES를 설정하여 작업의 총 스트리밍 HTTP 전송 크기를 제한하고 선언된 크기가 한도를 초과하는 데이터셋을 거부할 수 있습니다. 기본값은 500GiB입니다. 선언된 크기가 없는 Git 및 공급자 스냅샷은 실행 전에 완전히 확인할 수 없습니다. 비공개 Hugging Face 데이터셋은 hf auth login으로 저장된 자격 증명과 로컬 MCP 프로세스에 직접 구성된 HF_TOKEN을 인식합니다. 자격 증명 값은 MCP 도구 결과에 절대 포함되지 않습니다.

원격 HTTP MCP는 get_dataset_download_plan을 노출하지만 파일을 쓰는 도구는 의도적으로 노출하지 않습니다. 원격 서버는 사용자의 로컬 파일 시스템에 쓸 수 없습니다. 실행에는 stdio MCP를 사용하세요.

스킬

스킬은 MCP 도구를 기반으로 한 재사용 가능한 워크플로입니다. 저장소 소유 스킬 레지스트리는 다음 위치에 있습니다:

• skills/index.json

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

MCP 클라이언트는 list_skills 또는 get_skill을 사용할 수 있습니다. 저장소가 비공개로 유지되는 경우, 공개 웹사이트는 GitHub 원시 파일을 직접 읽는 대신 게시된 레지스트리 미러 또는 백엔드 엔드포인트를 사용해야 합니다.

dataset-discovery는 첫 번째 실행 가능한 스킬입니다. run_dataset_discovery를 통해 사용할 수 있으며 순위가 매겨진 데이터셋 후보, 적합성 이유, 검사 항목, 제안된 다음 작업을 반환합니다.

새 스킬을 제안하려면 스킬 제안 템플릿으로 GitHub 이슈를 여세요. 메타데이터 요구 사항, 검토 확인 사항, 풀 리퀘스트 기대 사항은 CONTRIBUTING.md를 참조하세요.

초기 공식 스킬은 다음에 중점을 둡니다:

• 데이터셋 탐색

• 데이터셋 비교

• 모델 탐색

• 스키마 설명

• 카탈로그 격차 분석

• 벤치마크 준비

개발

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

MCP 서버를 로컬에서 실행하세요:

python -m openconstruction_mcp.server