transport-lit — MCP를 통한 교통 그레이 문헌

(2026-08-27에 dot-lit에서 이름이 변경되었으며, DOT_LIT_* 환경 변수와 이전 데이터 디렉터리는 여전히 인식됩니다.)

transport-lit는 PubMed가 색인하지 않고 Semantic Scholar가 제대로 다루지 못하는 교통 연구 보고서에 대해 AI 어시스턴트(Claude Desktop, Claude Code, 모든 MCP 클라이언트)에 키워드 검색을 제공합니다. 이 프로젝트는 미국 National Transportation Library의 저장소인 ROSA-P(NHTSA DOT HS 보고서, FHWA/FRA/FTA/FAA, UTC 및 주 DOT 연구; https://rosap.ntl.bts.gov)에서 시작하여, 현재는 세 대륙의 6개 OAI-PMH 소스와 TRID에서 내보낸 모든 자료를 수집합니다:

transport-lit sources는 이들을 나열하고, transport-lit harvest --source <key>|all은 이들을 수집합니다. search_reports의 collection 필터는 하나를 선택합니다(예: "VTI", "BASt", "World Bank", "CEPAL", "TRID"). 다른 OAI-PMH 저장소를 추가하는 것은 src/transport_lit/sources.py의 한 항목입니다.

저는 이 프로젝트를 개인적인 학술 및 연구 목적으로 만들었으며, 유용하게 사용하실 다른 분들과 공유하게 되어 기쁩니다. 오류, 통합 요구 사항, 개선 사항 및 기타 의견을 환영합니다. 정기적으로 확인하고 가능한 한 통합한 후 문서화하겠습니다. 이 프로젝트를 지원하거나 다른 아이디어가 있으시다면 언제든지 환영합니다! — Alex Quistberg (이슈 열기)

이 작업은 OAI-PMH 소스에 유일하게 작동하는 방식으로 수행됩니다. 즉, 전체 저장소의 메타데이터를 로컬 SQLite 데이터베이스로 수집하고, 그 위에 FTS5 전문(full-text) 인덱스를 구축한 다음, 해당 인덱스에서 검색을 제공합니다. 전체 텍스트를 위한 선택적 PDF 가져오기를 제외하고는 실시간으로 쿼리되는 것이 없습니다. 재수집은 증분 방식(OAI 요청의 from=)이며 비용이 저렴합니다.

도구 목록

여기에 하나의 프롬프트인 literature_scan(topic)이 추가로 있는데, 이는 모델이 인용과 함께 다중 쿼리 스캔을 수행하도록 안내합니다. 모든 도구에는 MCP 주석(readOnlyHint, idempotentHint)이 포함되어 있습니다. get_fulltext만 openWorldHint인데, PDF 하나를 가져올 수 있기 때문입니다.

id는 dot:93144, 93144, oai:dot.stacks:dot:93144 또는 랜딩 URL을 허용합니다. 가져온 레코드는 다른 접두사를 사용합니다(trid:813520, import:…).

쿼리 구문: 단독 단어는 먼저 AND로 결합됩니다. limit보다 적은 수의 결과가 모든 용어와 일치하면 나머지 자리는 임의의 용어 일치로 채워집니다(match_mode = all_terms / any_terms). 구문은 따옴표로 묶고("driver improvement"), 접두어에는 끝에 *를 사용합니다. 순위는 BM25이며 제목, 보고서 번호, 저자가 초록보다 높은 가중치를 갖습니다.

Related MCP server: Personal Research Assistant MCP

설정

Python 3.12+ 및 uv가 필요합니다.

git clone https://github.com/aquistbe/transport-lit && cd transport-lit
uv tool install .            # installs `transport-lit` (CLI) and `transport-lit-mcp` (server) on PATH
export TRANSPORT_LIT_CONTACT=you@example.org   # identifies your harvester to ROSA-P (put it in your shell profile)
transport-lit probe                # live check: Identify / ListMetadataFormats / ListSets
transport-lit harvest              # full harvest the first time (~15 min), incremental afterwards
transport-lit status               # counts, last run, coverage by year
transport-lit search driver improvement program evaluation

개발 시에는 uv sync를 사용하고 명령어 앞에 uv run을 붙이세요(예: uv run pytest).

모든 MCP 클라이언트, 모든 모델

서버는 stdio(기본값)와 Streamable HTTP / SSE를 통해 표준 MCP를 사용합니다(transport-lit-mcp --transport streamable-http --port 8765, 엔드포인트 /mcp). transport-lit mcp-config [client]는 붙여넣기만 하면 되는 스니펫을 출력합니다: Claude Desktop, Claude Code, Cursor, VS Code(Copilot 에이전트 모드), Zed, Continue, LM Studio, Goose, Open WebUI 및 LibreChat(마지막 두 개는 HTTP 사용). Dockerfile은 인덱스를 볼륨에 저장하는 HTTP 서버 이미지를 빌드합니다.

오픈 모델. 2026-08-26에 Ollama qwen2.5:3b(3 B 파라미터)를 tests/ollama_smoke.py를 통해 종단 간 테스트했습니다. "운전자 향상 프로그램에 관한 보고서를 찾아서 제목 3개를 연도와 id와 함께 나열하세요"라는 요청에 모델은 search_reports({"query": "driver improvement", "limit": 3})를 한 번 호출하고 세 소스에서 올바른 제목, 연도, id 및 랜딩 URL로 답변했습니다. 작은 모델이 작동하도록 만드는 설계 선택: 한 줄 우선 설명이 있는 10개의 도구, 기본값이 있는 평면 JSON 인수, 간결한 결과 객체(검색 결과에 원시 메타데이터 없음), 소스와 필터를 명명하는 서버 instructions 문자열. 도구를 사용할 수 있는 모든 모델로 스모크 테스트를 실행하세요: OLLAMA_MODEL=llama3.1 uv run python tests/ollama_smoke.py "…".

Claude Desktop에 등록

transport-lit install-claude-desktop          # prints the JSON to add
transport-lit install-claude-desktop --write  # merges it into claude_desktop_config.json (keeps a .bak)

작성하는 항목은 단순히 다음과 같습니다:

{ "mcpServers": { "transport-lit": { "command": "/Users/you/.local/bin/transport-lit-mcp", "args": [],
                               "env": { "TRANSPORT_LIT_DATA_DIR": "/Users/you/.local/share/transport-lit",
                                        "TRANSPORT_LIT_CONTACT": "you@example.org" } } } }

그 후 Claude Desktop을 다시 시작하세요. Claude Code의 경우: claude mcp add transport-lit -- transport-lit-mcp.

구성(환경 변수)

변수는 ~/.config/transport-lit/env에 KEY=VALUE 줄로도 저장할 수 있습니다(실제 환경 변수가 우선). NII 애플리케이션 ID나 NCBI 키는 여기에 두면 launchd 작업, MCP 서버, 수동 실행 모두에서 볼 수 있습니다. 자격 증명은 필요 없습니다. 모든 엔드포인트는 공개입니다.

PyPI에서 설치(클론 없이)

uv tool install transport-lit            # CLI + MCP server on PATH
uvx --from transport-lit transport-lit-mcp   # or run the server ad hoc
uv tool install "transport-lit[semantic]"    # with the bundled embedding backend

https://pypi.org/project/transport-lit/에 GitHub의 신뢰된 퍼블리싱(trusted publishing)을 통해 게시됩니다. 태그가 release.yml(빌드, GitHub 릴리스)을 실행하면 publish.yml이 디스패치되는데, 이 워크플로가 신뢰된 퍼블리셔로 등록된 유일한 워크플로이며, 업로드는 pypi 환경에서 관리자의 승인을 기다립니다. PyPI는 재사용 가능한 워크플로의 토큰을 거부하고 최상위 워크플로 파일과 일치해야 하므로, 퍼블리싱은 릴리스 내부의 작업이 아니라 별도의 디스패치된 워크플로입니다. server.json은 MCP 레지스트리(registry.modelcontextprotocol.io)용 매니페스트로, PyPI 패키지가 생성된 후 제출합니다.

고정된 버전

릴리스는 git 태그 vMAJOR.MINOR.PATCH입니다(시맨틱 버저닝: patch = 수정, minor = 새 도구/소스, major = 도구 표면 또는 데이터베이스 스키마의 호환성 깨짐). 각 태그는 테스트를 실행하고 wheel + sdist를 빌드하여 GitHub 릴리스에 첨부하는 release 워크플로를 트리거합니다. Python 의존성은 커밋된 uv.lock으로 고정되며, CI는 uv sync --frozen으로 설치하므로 릴리스는 항상 테스트된 정확한 버전으로 실행됩니다. 특정 버전을 설치하려면:

uv tool install "transport-lit==0.3.0"                            # a pinned PyPI release
uv tool install git+https://github.com/aquistbe/transport-lit@v0.3.0  # or the matching git tag
uv tool upgrade transport-lit                                     # move to the latest release

수집(Harvesting)

transport-lit harvest                     # ROSA-P; auto: incremental if a complete full harvest exists, else full
transport-lit harvest --source all        # every configured source (vti, bast, wbokr, ipea, cepal, rosap)
transport-lit harvest --mode full         # walk the whole repository again
transport-lit harvest --mode incremental  # from = start of last complete run − 1 h, until = now
transport-lit harvest --from 2026-08-01T00:00:00Z   # explicit window (full timestamp required)
transport-lit harvest --max-pages 3       # testing only; the run is recorded as failed/partial
transport-lit reindex                     # re-parse the cached raw pages (no network) after a parser change

수집기가 수행하는 작업과 그 이유(모든 동작은 2026-08-26에 ROSA-P에 대해 검증됨):

• ListRecords&metadataPrefix=oai_dc, 페이지당 100개 레코드, resumptionToken을 따라가며 토큰 없이 페이지가 도착할 때까지 계속합니다. 그래야만 실행이 complete로 표시됩니다. 오류가 발생하면 failed로 남고 "마지막 수집" 포인터가 진행되지 않으므로 harvest_status가 부분 인덱스를 완료로 주장하지 않습니다.

• 페이싱(Pacing): TRANSPORT_LIT_MIN_INTERVAL초(기본 1초)마다 요청 1회. 토큰은 발급 후 약 60초 후에 만료되므로 재시도는 짧은 백오프(2/4/6초)를 사용합니다.

• badResumptionToken, 전송 오류, 잘린 XML, 또는 토큰이 유효한 동안 빈 봉투(envelope) → 목록이 재발급됩니다. ROSA-P는 레코드를 안정적인 datestamp 순서로 반환하지 않으므로(모든 페이지에서 확인됨) 복구는 목록을 처음부터 다시 시작합니다. upsert 덕분에 멱등적입니다. 순서가 단조적이었다면 수집기는 대신 until=을 통해 본 가장 작은 datestamp부터 재개했을 것입니다. 실행당 최대 8회 복구 후 failed가 됩니다.

• noRecordsMatch: ROSA-P는 오류 코드를 보내지 않습니다. 빈 선택 수집은 <ListRecords> 요소가 없는 OAI-PMH 봉투로 반환됩니다. 이는 토큰이 작동 중이지 않을 때만 "할 일 없음"으로 매핑되며, 목록 중간에서는 잘림으로 처리됩니다.

• 조용한 잘림 검사: 토큰의 cursor가 모든 페이지에서 로컬 개수와 비교됩니다. 이전 전체 수집보다 5% 이상 적은 레코드를 반환하는 전체 수집은 실행 노트에 플래그가 지정됩니다. 둘 다 harvest_status().last_harvest.notes에 나타납니다.

• 삭제: 저장소는 deletedRecord=no를 보고하므로 로컬에서 삭제되는 것은 없습니다. ROSA-P에서 사라진 레코드는 새 TRANSPORT_LIT_DATA_DIR에 대한 전체 재수집이 있을 때까지 인덱스에 남아 있습니다.

• 캐싱: 모든 OAI 페이지는 raw/run<N>-p<page>.xml.gz 아래에 gzip으로 저장되므로 파서를 변경하고 네트워크에 접촉하지 않고 인덱스를 재구축할 수 있습니다. PDF와 추출된 텍스트는 pdf/와 fulltext 테이블에 캐시됩니다.

• from/until은 각 저장소가 선언한 granularity(Identify에서 읽음)에 맞게 형식화됩니다. ROSA-P, DiVA, DSpace는 전체 YYYY-MM-DDThh:mm:ssZ 타임스탬프를 사용하고, OPUS(BASt)는 YYYY-MM-DD만 사용하며 창은 양쪽으로 하루씩 넓혀집니다.

• 광범위한 저장소(World Bank, IPEA, CEPAL)는 수집 시 다국어 교통 어휘(sources.TRANSPORT_RE, en/es/pt/de/fr/sv)로 필터링됩니다. 제목에 용어가 나타나거나(IPEA, CEPAL의 경우) 주제 표제 중에 서로 다른 용어 두 개가 나타나면 레코드가 유지됩니다. 초록은 무시됩니다(개발 문헌은 도로와 항구를 지나가는 말로 언급함). World Bank 주제도 무시됩니다(레코드당 100개 이상의 표제). 이는 2026-08-26에 무작위 20개 제목 샘플로 조정되었습니다. 느슨한 제목+주제+초록 규칙은 약 35–50% 정밀도로 World Bank 레코드 15,271개를 유지했습니다. 최종 규칙은 18/20에서 976개, IPEA는 ~16/20에서 207개, CEPAL은 ~15/20에서 1,165개를 유지합니다. 재현율이 대가입니다. 다른 트레이드오프를 원하면 sources.py에서 min_subject_hits를 느슨하게 하고 transport-lit reindex --source <key>(네트워크 없음)를 실행하세요. 실행 노트는 유지 vs 건너뜀을 기록합니다.

• transport-lit doctor [--repair]는 SQLite 무결성, 두 FTS 인덱스, running 상태로 멈춘 실행, 불가능한 타임스탬프, WAL 크기를 확인하고 안전한 항목을 복구합니다. 저장소는 닫을 때 WAL도 체크포인트합니다. transport-lit cite prefetch [--source …]는 DOI/PMID/OpenAlex가 있는 모든 레코드를 일괄적으로(요청당 50개) OpenAlex 작업으로 해석하여 레코드별 호출 없이 cited_by_count를 알 수 있게 합니다.

transport-lit reindex --source <key>는 캐시된 페이지를 다시 파싱하고 **현재 파서/필터가 더 이상 유지하지 않는 레코드를 정리(prune)**하므로 필터 변경 시 재수집이 필요 없습니다.

월간 재구축 및 주간 업데이트(유지보수 일정)

코퍼스는 천천히 변하므로 주기는 주간 증분 수집과 월간 새 재구축입니다. harvest --fresh는 임시 저장소에 전체 수집한 다음 라이브 인덱스의 dot: 레코드를 원자적으로 교체합니다. 이는 ROSA-P가 더 이상 제공하지 않는 레코드가 사라지는 유일한 방법입니다(ROSA-P의 OAI-PMH 엔드포인트는 삭제를 추적하지 않음). 가져온 소스(TRID 내보내기)는 건드리지 않으며, 실패한 재구축은 아무것도 변경하지 않습니다.

transport-lit install-schedule          # shows the two launchd agents
transport-lit install-schedule --write  # installs them: Mon 06:00 `--source all` incremental, 1st 05:00 `--source all --fresh`

로그는 $TRANSPORT_LIT_DATA_DIR/logs/에 저장됩니다. Linux에서는 명령이 출력하는 cron 줄을 사용하세요.

월간 유지보수 체크리스트(재구축과 함께 수행): 새 GitHub 이슈 읽기; uv lock --upgrade && uv run pytest; 릴리스의 변경 로그 섹션에 수정 사항 기록; pyproject.toml과 src/transport_lit/__init__.py의 version 올리기; git tag vX.Y.Z && git push --tags.

TRID: 내보낸 것을 가져오기

TRID(https://trid.trb.org)는 가장 완전한 교통 서지 데이터베이스이며 ROSA-P의 자연스러운 보완재이지만 API가 없고, FAQ에 따르면 TRB는 "TRID 백엔드 시스템에 대한 접근을 허용하지 않으며 내보내기/다운로드 제한을 해제하지 않는다"고 하며, robots.txt는 AI 크롤러를 금지합니다. 모든 사용자가 할 수 있는 것은 검색과 내보내기입니다. 따라서:

1. TRID에서 검색을 실행하고 Export → RIS를 선택합니다(CSV와 XML도 제공됨).

2. transport-lit import ~/Downloads/trid-driver-improvement.ris --collection "TRID: driver improvement"

레코드는 TRID 보기 URL에서 trid:<accession> ID를 받아 TRID 컬렉션(search_reports(..., collection="TRID"))에 들어가며, 같은 파일을 다시 가져와도 멱등적입니다. 임포터는 일반적인 RIS이므로 Zotero/EndNote/Scopus 내보내기도 --source <prefix>로 동일하게 작동합니다. 가져온 레코드의 get_fulltext는 직접 .pdf 링크만 따릅니다. 그 외에는 landing_url을 사용하세요.

ROSA-P의 OAI-PMH 엔드포인트가 제공하는 것

https://rosap.ntl.bts.gov/fedora/oai — 저장소 "DOT Stacks"(CDC Stacks 플랫폼), 프로토콜 2.0, 가장 이른 datestamp 2008-07-02, 삭제 추적 없음, OAI 세트 없음(ListSets는 비어 있음), 그리고 oai_dc가 유일한 메타데이터 형식입니다. 그러나 이는 위장된 정규화된 Dublin Core입니다. dc:contributor.author, dc:description.abstract, dc:relation.isPartOf, dc:identifier.uri(DOI 및 보고서 번호, 예: DOT HS 813 827), dc:coverage.spatial, dc:title.alternative, dc:description.tableOfContents와 같은 요소가 모두 존재합니다. 파서(dc.py)는 모든 원시 필드를 유지하고 여기에서 유형화된 열을 파생합니다. dc:relation.isPartOf(세미콜론으로 구분)가 list_collections / collection 필터가 사용하는 것입니다.

PDF 링크는 메타데이터에 없습니다. get_fulltext는 랜딩 페이지에서 citation_pdf_url을 읽고 데이터스트림 규칙 /view/dot/{n}/dot_{n}_DS1.pdf로 폴백합니다.

검증(2026-08-26)

v0.4.0 의미 검색. 342,462개 벡터(fastembed 다국어 MiniLM-L12, 384차원, 8코어에서 94 records/s 데이터 병렬 — 코퍼스에 60분). 교차 언어 확인: semantic 모드의 "elderly pedestrian crashes at night"는 상위 8개 중 PubMed 및 영어 CiNii 항목 옆에 일본어 CiNii 보고서 3개(夜間 高齢歩行者 死亡事故 분석, 1995–2011)를 반환합니다. 어휘 확인: "point system for problem drivers license suspension recidivism"은 쿼리 단어를 공유하지 않는 ROSA-P의 1997년 캘리포니아 차량 압수 평가와 1986년 행정 면허 취소 보고서를 찾습니다. 하이브리드 지연 시간 ≈ 0.6초(쿼리 인코딩이 지배적), 키워드 ≈ 25ms. 아무도 반복하지 않도록 여기에 기록하는 운영 교훈: 다른 프로세스(예: 실행 중인 MCP 서버)가 데이터베이스를 열어 둔 상태에서 SQLite -wal 파일을 절대 삭제하지 마세요. 아직 체크포인트되지 않은 커밋된 데이터를 보유하고 있습니다.

v0.3.0 API 소스. OpenAlex: 58페이지, 11,448건의 보고서(10개 토픽, type:report), 그중 1,428건에 PDF 링크. CiNii: 730페이지, 20개 쿼리에서 144,348건의 적중, 118,609건 고유. PubMed: 17개 날짜 슬라이스에서 105,028건의 논문(E-utilities는 retstart를 10,000으로 제한하므로 슬라이스를 재귀적으로 찾음). 오픈 모델 확인: Ollama qwen2.5:3b가 운전자 개선 질문에 search_reports 호출 한 번으로 정확히 응답했다.

v0.2.0 다중 소스 수집. VTI: 120페이지, 11,944건 확인, 11,460건 고유(DiVA는 일부 레코드를 여러 세트로 제공), 재개 0회. BASt: 30페이지, 2,987건 확인, 2,970건 고유; 1,901건은 직접 PDF 링크 보유; 일 단위 증분 경로를 실행했다(24건). World Bank: 404페이지 / 40,332건 확인; IPEA: 144 / 14,400; CEPAL: 522 / 52,199 — 모두 토큰 없는 페이지에서 종료되었고 재개 0회; 위 수치는 필터링 후의 수치. 표적 검색: Fußgänger Unfall(BASt) → 충돌 재구성 및 지방도로 충돌 통계; acidentes de trânsito mortalidade(IPEA) → "Mortalidade por acidentes de transporte terrestre e desigualdades interestaduais no Brasil"; seguridad vial peatones(CEPAL) → 도로안전 거버넌스 및 캠페인 평가; pedestrian safety(VTI) → 1990년대 아동 보행자 훈련 연구.

v0.1.0 (첫 ROSA-P 수집)

수집 완전성. 1차 실행(full)은 15분(00:03:59–00:19:11 UTC) 동안 908페이지 / 90,706개 레코드를 순회했고, 재개 0회, 커서 불일치 0회였으며, 재개 토큰이 없는 6개 레코드 페이지에서 종료되었다 — 이는 OAI-PMH가 정의하는 완전한 목록이다. 스토어에는 90,603개의 고유 레코드가 있다. 103건의 차이는 동일한 레코드가 두 페이지에 나타나기 때문이며, 이는 ROSA-P가 레코드를 안정적인 순서로 반환하지 않아서 발생한다(하베스터는 이를 "2페이지에서 날짜 스탬프 정렬 위반"으로 로그에 남긴다). 30분 후 별도 디렉터리로 수행한 두 번째 독립 전체 패스도 정확히 같은 수치를 반환했다 — 908페이지, 90,706건 확인, 90,603건 고유 — 그리고 두 ID 집합은 동일하다(어느 패스에만 있는 레코드도 0건). 103건의 중복은 저장소가 동일한 레코드를 두 페이지에 제공하기 때문이며, 레코드가 건너뛰어진 것이 아니다.

연대별 커버리지 (74,448건 = 82%에 연도가 있으며, 나머지 16,155건은 어떤 메타데이터 필드에도 날짜가 없다. year_source는 연도가 dc:date(48,658건), 연도만 있는 설명 줄(22,205건), 또는 제목(3,585건)에서 왔는지 나타낸다):

알려진 항목 검색 (transport-lit search …, 별도 표시가 없으면 1순위):

실제 쿼리 driver improvement program evaluation negligent operator (상위 6/10):

1. dot:18905 — An evaluation of the short-term effects of the Virginia driver improvement program (Lynn) — all_terms

2. dot:29326 — Review of NJ point system (Carnegie, Ozbay, Mudigonda, 2013; FHWA NJ-2013-004) — all_terms

3. dot:18959 — …Virginia driver improvement program on negligent driving: 12-month report (Lynn)

4. dot:18969 — …Virginia driver improvement program on negligent driving: 24-month report (Lynn)

5. dot:17678 — Study of recidivism rates among drivers administratively sanctioned by the New Jersey MVC (Carnegie et al., 2009)

6. dot:17677 — Study of the effects of plea bargaining motor vehicle offenses (Carnegie et al., 2009)

전문(full-text) 추출은 dot:93144(DOT HS 813 827, 3.7MB PDF, citation_pdf_url로 확인)에서 검증했다. 단위 테스트: uv run pytest(두 메타데이터 프로필용 파서, 연도 폴백, FTS 검색/필터, upsert 멱등성, 쿼리 토크나이저, ID 정규화).

레이아웃

src/transport_lit/
  config.py    paths, User-Agent, pacing, limits (env-overridable)
  oai.py       rate-limited OAI-PMH client; typed errors; raw-page cache
  dc.py        oai_dc record -> typed dict (authors, year, DOI, report numbers, collections …)
  store.py     SQLite schema, FTS5 index + triggers, search, stats, harvest-run bookkeeping
  harvest.py   full / incremental harvest with completeness + truncation handling
  fulltext.py  PDF resolution, download (size-capped), pypdf extraction, cache
  server.py    MCP tools (FastMCP / MCPServer)
  importers.py RIS import (TRID exports and any other reference-manager export)
  cli.py       transport-lit probe | harvest [--fresh] | import | reindex | status | search | get | fulltext
               | install-claude-desktop | install-schedule
.github/workflows/  ci.yml (tests on push/PR), release.yml (wheel + GitHub Release on tag)
tests/         unit tests (parser, store, query tokenizer)

나중에 두 번째 소스 추가하기 (예: NHTSA crashstats)

스토어는 소스에 구애받지 않는다: records.id는 접두사가 붙은 문자열이고(현재는 dot:93144), harvest_runs.source는 어떤 하베스터가 실행을 기록했는지 저장하며, FTS 인덱스는 행이 어디서 왔는지 상관하지 않는다. 소스를 추가하려면:

1. src/transport_lit/sources/<name>.py를 작성하여 harvest(store, *, mode, progress)를 노출한다. 이 함수는 dc.parse_record가 생성하는 것과 동일한 형태의 dict(id, title, authors, year, abstract, report_numbers, doi, landing_url, collections, raw, …)를 생성하고 store.upsert_records()를 호출한다. 새 ID 접두사(nhtsa:812115)를 사용하고 store.start_run()에 고유한 source 이름을 전달하여 harvest_status가 별도로 보고할 수 있게 한다.

2. 예의를 위해 oai.RateLimiter와 config.USER_AGENT를 재사용하고, 재현성을 위해 원시 응답을 raw/<source>/ 아래에 저장한다.

3. harvest.status()에 소스별 블록을 추가한다(id 접두사로 집계).

4. transport-lit harvest에 --source 옵션을 추가하고, 소스에 고유한 패싯이 있으면 search_reports에 해당 필터를 추가한다.

5. ROSA-P와의 중복 제거는 제목이 아니라 DOI / 보고서 번호(records.doi, records.report_numbers)로 수행한다. NHTSA 보고서는 두 곳에 모두 있는 경우가 많다.

NHTSA crashstats 소스에 대해 검증된 사실은 다음과 같으니 누구도 다시 도출하지 않아도 된다: https://crashstats.nhtsa.dot.gov/Api/Public/Publication/{id}는 PDF를 직접 반환한다(812115 → NMVCCS critical-reasons 보고서, application/pdf, ~0.5MB). 이는 검색이나 목록 API가 아니라 문서 검색 엔드포인트이므로, 커넥터는 크롤링 대신 열거 전략(예: ROSA-P report_numbers에 이미 있는 DOT HS 번호)이 필요하다.

미국 외: 평가된 후보 소스 (2026-08-26)

실제로 (a) 보유 자료가 데이터셋이 아니라 문헌인지, (b) 이 하베스터에 맞는 기계 접근이 가능한지를 살펴보았다. 수치는 해당일 엔드포인트가 보고한 값이다.

지역별 (당일 프로브, "open"은 인증 없는 기계 접근이 확인되었음을 의미):

completeListSize를 지원하는 세 개의 OAI-PMH 리포지토리(VTI, BASt, World Bank OKR)는 소스 접두어와 소스별 metadataPrefix로 기존 하베스터에 맞습니다. DSpace 7 사이트도 from/until을 허용하고 올바른 noRecordsMatch를 반환하므로, oai.py의 ROSA-P 특이사항이 이미 더 까다로운 사례입니다.

TRID는 범위 외

TRID(https://trid.trb.org)는 공개 API, OAI-PMH 엔드포인트, 대량 내보내기가 없습니다. FAQ에 따르면 "TRB는 개인이나 조직에 TRID 백엔드 시스템 접근을 허용하지 않으며 내보내기/다운로드 제한을 해제하지 않는다"고 하고, 데이터베이스는 LLM 학습에 사용할 수 없습니다. 따라서 여기서 의도적으로 스크래핑하지 않습니다.

v2 순서(2026-08-26 합의)

1. VTI + BASt(완료, v0.2.0) — 2. World Bank OKR, IPEA, CEPAL(완료, v0.2.0) —

2. IRDB 일본 — 4. OpenAlex type:report를 글로벌 백스톱으로 — 5. PubMed 교통 하위 집합(아래 참조). VTI 참고: DiVA의 oai_dc는 전문 링크를 포함하지 않음; 해당 소스를 swepub_mods/mets_kb로 전환하면 get_fulltext가 FULLTEXT01.pdf URL을 얻을 수 있음.

PubMed: 전체가 아닌 교통/상해 하위 집합

PubMed의 E-utilities(esearch/efetch, 무료, 키 없이 초당 3회 요청)는 고정 전략에서 로컬 하위 집합을 유지할 수 있으며, 동일한 주간/월간 주기로 mindate/maxdate로 새로고침합니다. OR로 결합된 두 가지 보완 필터:

• MeSH 전략 — "Accidents, Traffic"[MeSH] OR "Pedestrians"[MeSH] OR "Bicycling"[MeSH] OR "Automobile Driving"[MeSH] OR "Motorcycles"[MeSH] OR "Wounds and Injuries"[MeSH] AND ("Transportation"[MeSH] OR "Built Environment"[MeSH] OR "City Planning"[MeSH]) — 일반 및 임상 학술지의 교통 논문을 포착.

• 학술지 목록 — Accident Analysis & Prevention, Traffic Injury Prevention, Journal of Safety Research, Injury Prevention, Injury Epidemiology, Journal of Transport & Health, Safety Science, Transportation Research Part F, Transport Reviews, BMC Public Health (교통 태그만) 등 — MeSH 용어 없이 색인된 교통 논문을 포착.

SafetyLit(safetylit.org, WHO 제휴 주간 상해 문헌 게시판)은 정확히 그러한 학술지 목록을 유지하고 주제별로 수동 분류하므로 학술지 필터의 최상의 시드가 될 수 있습니다. 2026-08-26 확인 시 사이트에 접속할 수 없었고(모든 호스트 이름에서 연결 거부), 현재 상태는 확인되지 않았습니다.

주간 다이제스트(SafetyLit 스타일 게시판)

transport-lit digest --days 7 [--abstracts]는 지난주에 인덱스에 들어온 모든 항목의 Markdown 게시판을 소스별로 그룹화하고 개수와 함께 출력합니다. 이는 레코드가 처음 발견된 시점에 설정되고 새 빌드에서도 유지되는 first_seen_at으로 구동되므로, 월간 재빌드가 전체 인덱스를 새 것처럼 보이게 하지 않습니다. whats_new 도구는 동일한 데이터를 모델에 노출하며, 모델이 요약을 작성할 수 있습니다 — SafetyLit이 수동으로 수행하던 편집 단계입니다.

다른 문헌 MCP와 비교

PubMed, Semantic Scholar, OpenAlex 및 arXiv MCP 서버는 단일 API에 실시간 쿼리를 프록시합니다. transport-lit는 세 가지 면에서 다릅니다: 통합자가 갖지 못한 그레이 문헌(기관 보고서, 주 DOT 평가, ITRD 기여 기관)을 색인하고, 수확 후 로컬 인덱스에서 오프라인으로 실행되며(쿼리 시 속도 제한 없음, 키 불필요), 다중 소스를 단일 ID 체계로 통합하므로 모델이 모든 것을 한 번에 검색하고 인용을 내보낼 수 있습니다. 이들 서버가 가지고 있지만 이 도구에 아직 없는 것: 인용 그래프(누가 누구를 인용하는지), 저자 동일성 판별, 의미(임베딩) 검색 — 아래 참조.

인용 그래프(v0.5)

get_references / get_citations(CLI: transport-lit cite refs|cites <id> [--in-index])는 OpenAlex의 인용 그래프를 인덱스에 연결합니다. 레코드는 OpenAlex ID, DOI, PMID 또는 — 날짜가 없고 DOI가 없는 많은 기관 보고서의 경우 — 연도 ±1 범위의 정규화된 정확한 제목으로 OpenAlex 작업과 일치합니다(결과의 match가 어떤 방식인지 표시). 엣지는 첫 요청 시 가져와 citations/works 테이블에 캐시됩니다. 인용 목록은 90일 후 새로고침되고, 참조는 변경되지 않습니다. 인덱스에 있는 인용된 작업은 record_id와 함께 반환되며, 검색 결과는 cited_by_count가 알려지면 이를 포함합니다.

2026-08-27 검증: Oregon DMV DIP 평가(dot:21848, DOI 없음, ROSA-P에 날짜 없음)가 제목으로 해석되어 6건의 인용 작업을 나열했으며, 그중 Iowa의 DIP 평가와 NJ 재범 연구가 포함됨; Lynn의 1982년 Virginia 24개월 보고서는 2003년 Cochrane 운전면허 후 교육 검토(pubmed:12917984, 인덱스에 있음)에 인용됨; 2020년 서울 노인 보행자 논문은 참조 57건 중 19건이 인덱스에 있음. OpenAlex는 NTL의 10.21949/… DOI를 해석함(ROSA-P 레코드 15,493건이 보유); DOI가 없는 레코드 — ROSA-P 90,599건 중 73,000건 — 는 제목 일치에 의존하며, 정규화된 정확한 제목, 접두어 관계(판본 또는 부제 꼬리), 또는 ≥ 0.8 토큰 중첩을 허용하며 항상 연도 ±1 범위입니다. 색인된 매체에서 아무도 인용하지 않은 그레이 문헌은 여전히 0으로 표시됩니다. 이는 인덱스가 아닌 인용 데이터의 속성입니다. OpenCitations와 Semantic Scholar는 동일한 테이블에 폴백으로 추가할 수 있습니다.

의미 검색(v0.4)

키워드 검색은 FTS5/BM25입니다. 벡터를 추가하면 search_reports가 하이브리드 검색 (BM25와 코사인을 상호 순위로 융합)으로 바뀌어 의미와 언어를 넘어 레코드를 찾습니다 — 영어 쿼리가 스웨덴어, 독일어, 스페인어, 포르투갈어 또는 일본어 레코드에 도달합니다. 모든 것이 로컬에서 실행됩니다. 계정 없음, GPU 없음.

uv tool install "transport-lit[semantic]"   # adds fastembed (ONNX runtime), ~60 MB
transport-lit embed                         # default backend: fastembed, multilingual MiniLM-L12 (384-d, 220 MB model, one-time download)
transport-lit embed --backend ollama --model qwen3-embedding:8b     # opt-in: any Ollama embedding model, truncated to 1024-d
transport-lit search "programa de mejoramiento de conductores" --mode semantic

의미 검색 결과는 소스별로 다양화됩니다. source/collection으로 검색을 좁히지 않는 한 단일 소스가 요청된 결과의 절반 이상을 채울 수 없습니다 (TRANSPORT_LIT_SEMANTIC_PER_SOURCE). 측정된 이유: CiNii는 인덱스의 3분의 1을 차지하며 초록이 있는 레코드보다 짧은 쿼리에 더 가까운 수천 개의 짧은 영어 제목("Pedestrian safety problems and countermeasures")을 보유합니다. 초록 유무 코사인 격차는 ~0.01에 불과하므로 이는 길이 아티팩트가 아닌 말뭉치 구성 문제이며, 상한선이 정직한 해결책입니다. mode="semantic"은 전문가용 설정이고 hybrid가 기본값으로 유지됩니다.

하이브리드 융합은 키워드 목록에 1.0, 의미 목록에 0.7의 가중치를 부여하며 (TRANSPORT_LIT_SEMANTIC_WEIGHT), 의미 전용 후보는 코사인 0.5를 넘어야 합니다 (TRANSPORT_LIT_SEMANTIC_MIN). 이는 정밀 쿼리의 정밀도를 유지하면서 mode="semantic"은 재현율/교차 언어 설정으로 남습니다.

embed는 아직 벡터가 없는 레코드만 처리하므로 첫 패스 이후 주간 수확은 몇 초만 추가됩니다. 벡터는 $TRANSPORT_LIT_DATA_DIR/vectors/<backend-model>/에 메모리 매핑 float16 행렬(342k × 384 ≈ 260 MB)로 저장됩니다. 검색은 청크 내적이며 확장 기능이 없습니다. 활성 벡터 세트는 인덱스에 기록되므로 search_reports(mode=…)는 이를 생성한 백엔드를 사용합니다: hybrid(기본값), keyword, 또는 semantic; 모든 결과의 mode_used는 무엇이 실행되었는지 표시하며, 벡터가 없으면 키워드로 저하됩니다. harvest_status()는 백엔드, 모델, 차원 및 적용 범위를 보고합니다.

백엔드는 2026-08-26에 10코어 Apple Silicon 노트북에서 실제 레코드 256개(제목 + 초록)로 측정되었습니다. fastembed MiniLM-L12는 CPU에서 ≈ 30 records/s입니다(CoreML 제공자는 더 빠르지 않습니다). Ollama qwen3-embedding:0.6b ≈ 20/s(1024차원), qwen3-embedding:8b ≈ 1.4/s(4096차원, 1024로 절단)입니다. 따라서 기본 모델로 342k 레코드를 처음 전체 처리하는 데는 한 번에 약 3시간이 걸리며, 주간 증분은 수초에 불과합니다. --source를 사용하면 더 무거운 모델로 하나의 소스를 임베딩할 수 있습니다. MiniLM 모델은 최대 128토큰(제목과 초록의 첫 약 90단어)만 읽습니다. Qwen은 전체 1,500자 창을 읽고 쿼리에는 모델의 검색 명령 접두사가 붙습니다. 대부분의 사용자는 (아래의) snapshot을 설치하고 전체 처리를 아예 실행하지 않아야 합니다.

Snapshots: harvest 건너뛰기

uv tool install "transport-lit[semantic]"
transport-lit snapshot install https://github.com/aquistbe/transport-lit/releases/download/v0.4.0/transport-lit-2026-08.tar.gz
transport-lit mcp-config claude-desktop     # or install-claude-desktop --write

이것은 몇 분 안에 완료되는 완전하고 검색 가능한 설치입니다. 벡터가 포함된 224k 레코드(CiNii와 TRID를 제외한 모든 것)입니다. transport-lit snapshot build <file.tar.gz>는 SQLite 인덱스와 활성 벡터를 함께 패킹합니다. snapshot install <url-or-file>은 이를 새 TRANSPORT_LIT_DATA_DIR에 풀며, 이후 주간 증분 harvest가 최신 상태를 유지합니다(snapshot은 harvest 북키핑을 포함하므로 harvest --source all이 어디서 재개할지 압니다). Snapshots는 CiNii(해당 API 약관은 등록을 요구하고 재배포에 대해 침묵합니다)와 TRID 가져오기(TRB의 약관)를 제외합니다. 사용자는 이를 직접 harvest해야 합니다. 릴리스에는 snapshot이 빌드된 경우 해당 snapshot이 포함됩니다.