{
  "markdown": "# scienceON-mcp\n\n<!-- mcp-name: io.github.rubatoyd/scienceon-mcp -->\n\n[![CI](https://github.com/rubatoyd/scienceON-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/rubatoyd/scienceON-mcp/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/rubatoyd/scienceON-mcp)](https://github.com/rubatoyd/scienceON-mcp/releases/latest)\n[![Downloads](https://img.shields.io/github/downloads/rubatoyd/scienceON-mcp/total?label=downloads)](https://github.com/rubatoyd/scienceON-mcp/releases)\n\n<!-- usage:start -->\n> 📈 **사용량** — 최근 14일 조회 **6**회(고유 3) · 클론 **132**회(고유 71) · 릴리스 자산 누적 다운로드 **—**\n>\n> ![일별 클론·조회 추이](docs/usage.svg)\n>\n> <sub>2026-09-07 자동 갱신 · 전체 이력은 [`docs/usage.csv`](docs/usage.csv). GitHub 트래픽 통계는 14일 창만 제공하므로 이 저장소가 매일 찍어 누적한다.</sub>\n<!-- usage:end -->\n\nKISTI **ScienceON OpenAPI** 문헌 검색·메타데이터 수집기 — **MCP 서버 + CLI**.\n자기 ScienceON API 키만 발급받으면 Claude(또는 CLI)에서 국내외 논문·보고서 서지 메타데이터를\n검색·수집할 수 있다.\n\n> An MCP server + CLI for KISTI ScienceON OpenAPI. Bring your own API key and let\n> Claude search & collect academic literature metadata in any project.\n\n## 기능\n\n- **검색** — 논문(ARTI)·보고서(REPORT) 등 서지 메타데이터. 다중쿼리 합집합 · 와일드카드(`*`) ·\n  연도범위 · `contains`/`lang` 후처리 필터\n- **상세** — 제어번호(CN)로 초록·서지 전체\n- **다중그룹 수집** — 그룹마다 다른 검색 전략을 걸어 한 코퍼스로 합침\n- **내보내기** — xlsx · csv · json · sqlite\n- **두 가지 사용법** — Claude 에서 도구 호출(MCP) · 터미널 배치(CLI), 같은 코어 공유\n\n지원 티켓: `ARTI` 논문 · `REPORT` 보고서 · `ATT` 동향 · `RESEARCHER` 연구자 · `ORGAN` 연구기관\n(계정 구독 범위에 따름)\n\n## API 키 발급\n\n1. [ScienceON](https://scienceon.kisti.re.kr) 회원가입·로그인\n2. **API Gateway → 인증키 발급 신청** → 승인 후 `인증키`·`Client ID` 발급\n3. **인증키관리**에서 신청 **MAC 주소** 등록, **IP관리**에서 호출 PC 의 공인 IP 등록\n4. 사용할 **서비스 콘텐츠(티켓)** 체크\n\n자격증명은 MCP 설정의 `env` 블록 또는 `.env`(`.env.example` 복사)로 전달한다. 코드·커밋·로그에는\n넣지 않는다.\n\n## 설치\n\n### Claude Desktop\n\n**`.mcpb` 원클릭** — [릴리스](https://github.com/rubatoyd/scienceON-mcp/releases/latest)에서 받아\n더블클릭/드래그 → 설치 창에서 인증키·Client ID·MAC 입력.\n\n| 자산 | 특징 |\n|---|---|\n| `scienceon-mcp-win-x64.mcpb` / `…-macos-arm64.mcpb` / `…-linux-x64.mcpb` | 자체완결 — Python·uv 불필요 |\n| `scienceon-mcp.mcpb` | 경량. 실행에 `uv` 필요 |\n\n**수동 config** — `claude_desktop_config.json`:\n```json\n{\n  \"mcpServers\": {\n    \"scienceon\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"git+https://github.com/rubatoyd/scienceON-mcp\", \"scienceon-mcp\"],\n      \"env\": {\n        \"SCIENCEON_AUTH_KEY\": \"발급_32자리_인증키\",\n        \"SCIENCEON_CLIENT_ID\": \"발급_client_id\",\n        \"SCIENCEON_MAC_ADDRESS\": \"AA-BB-CC-DD-EE-FF\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add scienceon -- uvx --from \"git+https://github.com/rubatoyd/scienceON-mcp\" scienceon-mcp\n```\n\n첫 실행 시 빌드(수 초), 이후 캐시. 최신 반영은 `uvx --refresh …`.\n\n### 다른 MCP 클라이언트\n\n표준 stdio MCP 서버이므로 MCP 를 지원하는 에이전트면 그대로 붙는다 — Cursor · Windsurf · Cline ·\nZed · VS Code Copilot(agent mode) · OpenAI Agents SDK · 자체 클라이언트 등. 위 `command`/`args`/`env`\n3요소를 각 클라이언트 설정에 옮기면 된다.\n\n### 전송 방식\n\n```bash\nscienceon-mcp                                # stdio (기본)\nscienceon-mcp --transport streamable-http    # http://127.0.0.1:8000/mcp\nscienceon-mcp --transport sse --port 9000    # http://127.0.0.1:9000/sse\n```\n\n환경변수: `SCIENCEON_MCP_TRANSPORT` · `SCIENCEON_MCP_HOST` · `SCIENCEON_MCP_PORT`.\n\n## MCP 도구\n\n| 도구 | 하는 일 |\n|---|---|\n| `scienceON_status` | 연결/토큰 점검 (+공인 IP — E4006 진단용) |\n| `scienceON_search` | 문헌 검색 — 다중쿼리 · 와일드카드 · 연도범위 · `contains` · `lang` |\n| `scienceON_detail` | 제어번호(CN)로 초록·서지 전체 |\n| `scienceON_export` | 대량 수집 → xlsx/csv/json/sqlite 저장 |\n| `scienceON_collect_groups` | 다중 검색그룹을 한 코퍼스로 합쳐 수집 |\n\n### 다중그룹 수집\n\n단일 검색어로는 만들 수 없는 코퍼스가 있다. 변별력 있는 단어는 전체(BI)로 그대로 검색하고,\n색인이 안 되는 토큰은 제목(TI) 와일드카드 + `contains` 후처리로 정밀화하는 식으로 그룹마다 다른\n전략을 걸어 합집합을 만든다.\n\n```jsonc\n[\n  { \"field\": \"BI\", \"terms\": [\"경계선지능\", \"경계선 지능\"] },\n  { \"field\": \"TI\", \"terms\": [\"느린*\"], \"contains\": [\"느린학습자\", \"느린 학습자\"] }\n]\n```\n\n그룹 키: `field`(BI/TI/AB/AU/KW) · `terms` · `contains` · `lang` · `max`.\n`save: false` 로 부르면 저장 없이 결과를 미리 볼 수 있다(응답에는 앞 100건만).\n\n## 알아둘 제한\n\n**수집량이 `max_records` 와 정확히 일치하면 거의 항상 절단된 것이다.** 수집 도구는 `total` 과\n플래그를 함께 반환하므로 절단 여부를 확인할 수 있다. 절단된 결과를 완전한 코퍼스로 오인하면\n후속 분석이 통째로 무효가 된다.\n\n**ScienceON 이 보고하는 `total` 은 실제로 받을 수 있는 건수보다 클 수 있다.** 그래서 두 상황을\n다른 플래그로 구분한다.\n\n| 플래그 | 뜻 | 대처 |\n|---|---|---|\n| `truncated` | `max_records` 상한에 걸렸다 | 상한을 올려 재수집하면 늘어난다 |\n| `total_mismatch` | 끝까지 페이징했는데 `total` 에 못 미쳤다 | 상한을 올려도 늘지 않는다. 회수량을 확정 수치로 쓴다 |\n\n`meta.union_upper_bound` 는 실행한 검색축들의 `total` 합, 즉 합집합의 상한이다(중복 미보정).\n\n**다중 페이지 질의는 호출마다 결과가 미세하게 달라진다.** 단일 페이지 질의는 안정적이다.\n`total` 에 못 미치고 상한도 아니면 한 번 더 훑어 합집합을 취한다(`meta.sweeps` 가 1보다 크면\n보정된 것).\n\n보정이 걸린 축은 전체를 재페이징하므로 그만큼 요청이 늘어난다. 대규모 수집에서 부담되면\n`scienceON_search` · `scienceON_export` · `scienceON_collect_groups` 의 `retry_incomplete=0`\n으로 끈다 — 대신 결손이 남고 `total_mismatch` 로만 표시된다.\n\n**출력 파일명은 정규화된다.** `name` 을 지정하지 않으면 검색어가 그대로 파일명이 되므로,\n경로 구분자·`..`·윈도 금지문자는 제거되고 결과는 항상 `out_dir` 안에만 저장된다.\n한글 파일명은 그대로 보존된다.\n\n**서버측 파이프 OR(`|`)는 쓰지 않는다.** 공백이 든 용어에서 토큰이 분리돼 과대매칭되므로,\n용어별 개별 검색 후 CN 합집합을 취한다.\n\n**Claude 앱 안에서 검색해 설치할 수는 없다.** 공식 MCP 레지스트리 등재와 Claude Desktop 인앱\n커넥터 디렉터리는 별개이고 자동 동기화되지 않는다.\n\n**도구 설명이 한국어다.** 한국어를 다루는 모델이어야 도구 선택이 정확하다.\n\n**`mcp` SDK 는 1.x 로 고정된다**(`mcp>=1.2.0,<2`). 2.0 에서 `mcp.server.fastmcp` 가 제거되어\n상한이 없으면 기동에 실패한다.\n\n## CLI\n\n```bash\nuv run scienceon status\nuv run scienceon search --target ARTI --query \"인공지능\" --year 2015~2024 --rows 100\nuv run scienceon collect --config config/search.example.yaml\n```\n\n로컬 개발은 clone 후 `uv sync`. 클라우드 동기화 폴더(OneDrive 등)라면 venv 를 폴더 밖에 두기를\n권한다(`UV_PROJECT_ENVIRONMENT`).\n\n## 문서\n\n- [docs/SCIENCEON_API_GUIDE.md](docs/SCIENCEON_API_GUIDE.md) — API 호출 규격\n- [docs/COLLECTION_WORKFLOW.md](docs/COLLECTION_WORKFLOW.md) — 반복 수집 SOP\n- [docs/PROMPTS.md](docs/PROMPTS.md) — Claude 구동용 프롬프트 템플릿\n- [docs/ROADMAP.md](docs/ROADMAP.md) — 기능 구현 계획\n\n## 보안 / 네트워크\n\n- 자격증명은 `.env` 또는 MCP `env` 블록으로만 전달한다. `.env` 와 토큰 캐시는 gitignore 대상이다.\n- 교육망·사내망 **SSL 인터셉션** 환경에서는 `truststore` 로 OS 신뢰저장소를 사용해 통과한다\n  (TLS 검증을 끄지 않는다). 정식 의존성이라 `.mcpb` 설치본에도 적용된다. 비활성은 `SCIENCEON_OS_TRUST=0`.\n- 자격증명 오류·타임아웃 등 어떤 예외도 도구 밖으로 새지 않는다(항상 `{\"error\": …}` 형태로 반환).\n- HTTP 전송에는 인증이 없다. 기본 바인드는 루프백(`127.0.0.1`)이다. `--host 0.0.0.0` 으로 외부에\n  열면 자격증명을 가진 서버가 그대로 노출되므로 신뢰된 망에서만 쓴다.\n- 호출은 throttle(기본 0.5s)·지수 백오프를 건다. 429 가 나면 throttle 을 올린다.\n\n## 관련 프로젝트\n\n- [ansua79/scienceon-mcp](https://github.com/ansua79/scienceon-mcp) — KISTI 개발자의 ScienceON MCP.\n  ScienceON 전 API(논문·특허·보고서·동향·연구자·기관·기술트렌드·뉴스 등 17개 도구)를 폭넓게\n  노출하고 GUI 설치기도 제공한다. **폭넓은 탐색**이 목적이면 이 도구를 권한다.\n- [rubatoyd/KCI_openAPI](https://github.com/rubatoyd/KCI_openAPI) — 한국연구재단 KCI 수집기(자매 프로젝트).\n\n본 프로젝트는 **연구용 자료수집·코퍼스 구축**에 특화되어 있다 — 다중쿼리 합집합 · 와일드카드 ·\n후처리 필터 · 다중그룹 수집 · 대량 내보내기 · config 재현 수집.\n\n## 라이선스\n\nMIT © Yeondong Yang. 본 프로젝트는 KISTI 의 비공식 클라이언트이며 제휴 관계가 없다.\nScienceON 데이터 이용은 KISTI 약관·트래픽 정책을 따른다.\n",
  "bytes": 6702,
  "sha": "59d9fc0bd17538038247b3f7f6971b5e9aa7aaca67f377d9094356e293fb0be5",
  "repo_slug": "rubatoyd/scienceon-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_rubatoyd_scienceon_mcp_caca0303/readme"
}