{"_id":"@aeriis-kr/opendata-mcp","_rev":"2-d9fc50d2cd33edd60afd9d30c4b970b0","name":"@aeriis-kr/opendata-mcp","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.2":{"name":"@aeriis-kr/opendata-mcp","version":"1.0.2","keywords":[],"author":"","license":"ISC","_id":"@aeriis-kr/opendata-mcp@1.0.2","maintainers":[{"name":"ohkingtaek","email":"ohkingtaek@aeriis.kr"}],"bin":{"opendata-mcp":"build/http.js"},"dist":{"shasum":"f68f64e73c94d259be682cfbc33e927a86f3cb4f","tarball":"https://registry.npmjs.org/@aeriis-kr/opendata-mcp/-/opendata-mcp-1.0.2.tgz","fileCount":11,"integrity":"sha512-UmQ3Txxmrh66y8HWUXSeMedHGy8As8tIK0Kb6wASMAgIsgQ0hdPuiRjI/Vw6zutrs5Z1omiIl8jQdJjvyqeiGw==","signatures":[{"sig":"MEYCIQDekTxa+qYfWTtM4Iq+PLCNYZuDQ+DhY3b81EolHTQKkgIhAOjWfhS/Y7wNRYN6CQ57vxewJcCnDdt8eK26w6Sfy/GY","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":41838},"main":"./build/index.js","type":"module","module":"./build/index.js","gitHead":"4cebf4adc469db7c8fc36147369add766410bdb6","scripts":{"dev":"tsx watch src/http.ts","test":"node --import tsx --test test/*.test.ts","build":"tsc","start":"node build/http.js","prepack":"npm run build","typecheck":"tsc --noEmit"},"_npmUser":{"name":"ohkingtaek","email":"ohkingtaek@aeriis.kr"},"_npmVersion":"11.19.0","description":"한국 공공데이터포털(OpenAPI)을 더 쉽게 탐색·호출할 수 있도록 돕는 Model Context Protocol(MCP) 서버입니다. 다음과 같은 MCP 도구를 제공합니다:","directories":{},"_nodeVersion":"24.20.0","dependencies":{"zod":"^3.25.76","winston":"^3.17.0","@modelcontextprotocol/sdk":"^1.30.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.4","typescript":"^5.6.3","@types/node":"20.19.11"},"_npmOperationalInternal":{"tmp":"tmp/opendata-mcp_1.0.2_1789109209608_0.10898423022145454","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@aeriis-kr/opendata-mcp","version":"1.0.3","description":"한국 공공데이터포털(OpenAPI)을 더 쉽게 탐색·호출할 수 있도록 돕는 Model Context Protocol(MCP) 서버입니다. 다음과 같은 MCP 도구를 제공합니다:","main":"./build/index.js","module":"./build/index.js","type":"module","bin":{"opendata-mcp":"build/http.js"},"publishConfig":{"access":"public"},"scripts":{"dev":"tsx watch src/http.ts","build":"tsc","start":"node build/http.js","test":"node --import tsx --test test/*.test.ts","typecheck":"tsc --noEmit","prepack":"npm run build"},"keywords":[],"author":"","license":"ISC","dependencies":{"@modelcontextprotocol/sdk":"^1.30.0","winston":"^3.17.0","zod":"^3.25.76"},"devDependencies":{"@types/node":"20.19.11","tsx":"^4.19.4","typescript":"^5.6.3"},"gitHead":"4cebf4adc469db7c8fc36147369add766410bdb6","_id":"@aeriis-kr/opendata-mcp@1.0.3","_nodeVersion":"24.20.0","_npmVersion":"11.19.0","dist":{"integrity":"sha512-JBKKYWb8bn1zEfkF39D/2sErDsm0rcOnKEFPeh0W5t5sOO4XtyQCZNYix/+t8xfZMHssO3i5uQuGGfjO5YO10g==","shasum":"6524d96e0ccfa554b365913bb61f16099bddc93f","tarball":"https://registry.npmjs.org/@aeriis-kr/opendata-mcp/-/opendata-mcp-1.0.3.tgz","fileCount":11,"unpackedSize":41838,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC6xmEXJlXZhvPk7Wi+z9vVbUZ2Tnah7a3TFWL/f7+2qwIgR8b+1TqlGmWRH5/nQ1/FDr3MWJfQ05GItJhHnO1b0vM="}]},"_npmUser":{"name":"ohkingtaek","email":"ohkingtaek@aeriis.kr"},"directories":{},"maintainers":[{"name":"ohkingtaek","email":"ohkingtaek@aeriis.kr"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/opendata-mcp_1.0.3_1789109635787_0.05352088939734312"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-11T06:46:49.427Z","modified":"2026-09-11T06:53:56.132Z","1.0.2":"2026-09-11T06:46:49.747Z","1.0.3":"2026-09-11T06:53:55.934Z"},"license":"ISC","keywords":[],"description":"한국 공공데이터포털(OpenAPI)을 더 쉽게 탐색·호출할 수 있도록 돕는 Model Context Protocol(MCP) 서버입니다. 다음과 같은 MCP 도구를 제공합니다:","maintainers":[{"name":"ohkingtaek","email":"ohkingtaek@aeriis.kr"}],"readme":"## Open Data MCP\n한국 공공데이터포털(OpenAPI)을 더 쉽게 탐색·호출할 수 있도록 돕는 Model Context Protocol(MCP) 서버입니다. 다음과 같은 MCP 도구를 제공합니다:\n\n- **search_api**: 키워드로 공공데이터 API를 검색\n- **get_std_docs**: 검색 결과에서 선택한 `listId` 목록으로 표준 문서(markdown) 병합\n- **fetch_data**: 표준 문서/메타데이터를 바탕으로 실제 OpenAPI 엔드포인트 호출\n\n내부적으로 검색/문서 도구는 `mcp.ezrnd.co.kr`(HTTPS) 백엔드를 사용합니다.\n\n### 원격 MCP 연결\n\n배포된 Streamable HTTP 엔드포인트는 `https://mcp.ezrnd.co.kr/mcp`입니다. MCP 클라이언트에서 이 URL을 연결하고, 공공데이터포털의 **디코딩된 원문 서비스 키**를 `x-odp-service-key` 헤더로 전달하세요.\n\n```json\n{\n  \"mcpServers\": {\n    \"opendata\": {\n      \"url\": \"https://mcp.ezrnd.co.kr/mcp\",\n      \"headers\": {\n        \"x-odp-service-key\": \"<공공데이터포털_디코딩_서비스키>\"\n      }\n    }\n  }\n}\n```\n\n### npx로 로컬 실행\n\nNode.js 환경에서는 별도 설치 없이 다음 명령으로 로컬 HTTP MCP 서버를 시작할 수 있습니다.\n\n```bash\nnpx -y @aeriis-kr/opendata-mcp\n```\n\n기본 MCP 엔드포인트는 `http://127.0.0.1:8787/mcp`이며, 상태 확인 주소는 `http://127.0.0.1:8787/health`입니다. 포트를 바꾸려면 `PORT=18787 npx -y @aeriis-kr/opendata-mcp`처럼 실행하세요. 로컬 클라이언트에도 같은 `x-odp-service-key` 헤더를 설정합니다.\n\n### 요구 사항\n- Docker 또는 Node.js 최신 LTS\n- npm\n\n### 설치\n```bash\nnpm install\n```\n\n### 실행(개발)\n```bash\nnpm run dev\n```\n\nMCP 엔드포인트는 `http://localhost:8787/mcp`, 상태 확인은 `http://localhost:8787/health`입니다.\n\n### Docker 배포\n```bash\ndocker compose up -d --build\ndocker compose ps\n```\n\nCompose 파일은 프록시 네트워크를 지정하지 않습니다. 컨테이너를 프록시 네트워크에 연결한 뒤 `opendata-mcp:8787`의 `/mcp`로 프록시하세요.\n외부 공개 시 인증과 요청 빈도 제한은 리버스 프록시에서 적용하세요. 애플리케이션은 MCP 요청 본문을 1 MiB로 제한합니다.\n\nSmithery에는 이 서버를 중복 호스팅하지 않고, 배포된 Streamable HTTP URL을 외부 서버로 등록합니다. 등록 명령은 `npx smithery mcp publish https://mcp.ezrnd.co.kr/mcp -n aeriis-kr/opendata-mcp`입니다.\n\n### 설정\n- **PORT**: HTTP 포트. 기본값은 `8787`입니다.\n- **MCP_ALLOWED_HOSTS**: MCP 요청에 허용할 `Host` 헤더의 쉼표 구분 목록입니다. 기본값은 `mcp.ezrnd.co.kr`과 로컬 개발 호스트입니다.\n- **ODP_ALLOWED_HOSTS**: `fetch_data`가 호출할 수 있는 API 호스트의 쉼표 구분 목록입니다. 기본값은 `apis.data.go.kr,api.odcloud.kr`입니다.\n- **x-odp-service-key** 요청 헤더: 공공데이터포털 서비스 키. 서버 공용 환경변수로 저장하지 않고 MCP 요청별로 전달합니다.\n  - 파라미터 이름에 `serviceKey`가 포함되어 있으면 자동 주입됩니다.\n  - 헤더 이름이 `Authorization`이면 `{Prefix} {키}` 형식으로 자동 주입됩니다.\n  - 키와 Authorization 값은 로그에 기록하지 않으며, 허용된 API 호스트에만 전송됩니다.\n\n### 제공 도구 상세\n\n#### search_api\n- **설명**: 공공데이터포털에서 키워드로 API 목록을 검색합니다.\n- **입력**:\n  - `query`: 문자열 배열(공백 없는 키워드, 최대 5개 권장)\n  - `page`: 페이지 번호(1부터)\n  - `pageSize`: 페이지 크기\n- **출력**: 검색 결과(JSON 문자열)\n\n#### get_std_docs\n- **설명**: `search_api` 결과에서 선택한 항목들의 `listId` 배열을 받아 표준 문서(markdown)를 합쳐 반환합니다.\n- **입력**:\n  - `listId`: number[]\n- **출력**: 통합된 markdown 문자열\n\n#### fetch_data\n- **설명**: OpenAPI 메타데이터를 기반으로 특정 엔드포인트를 호출합니다. 기본 프로토콜은 HTTPS입니다.\n- **입력**: `requestData`\n  - `baseInfo.host`: 예) `apis.data.go.kr` (프로토콜/슬래시 금지)\n  - `baseInfo.base_path`: 예) `/B552015/NpsBplcInfoInqireServiceV2`\n  - `endpointInfo.path`: 예) `/getBassInfoSearchV2`\n  - `endpointInfo.method`: `GET`\n  - `endpointInfo.params`: `[{ name, value }]` 배열. 값이 없으면 제외됩니다.\n  - `endpointInfo.headers`: `[{ name, prefix, value }]` 배열. `Authorization`에 서비스키 자동 주입 지원.\n- **출력**: 응답 본문(JSON 문자열 또는 텍스트)\n\n### 라이선스\n이 저장소의 라이선스는 루트의 `LICENSE` 파일을 참고하세요.\n","readmeFilename":"README.md"}