curseforge-ark-mcp

ARK: Survival Ascended를 위한 CurseForge 모드 큐레이션, 검색 및 업데이트 감시를 위한 읽기 전용 MCP 서버입니다.

이것은 v0입니다. 여기 있는 어떤 것도 실제 응답에 대해 검증되지 않았습니다.

아직 CurseForge API 키가 존재하지 않습니다. 키는 셀프 서비스가 아니며 — Overwolf에 신청하여 부여받습니다 — 따라서 이 저장소에서 누군가에 의해 인증된 호출이 단 한 번도 이루어진 적이 없습니다. 모든 픽스처와 모든 도구 출력의 모든 필드 경로는 게시된 스키마에서 읽은 가설입니다.

이것은 겸손이 아닙니다. 형제 저장소 nitrado-ark-mcp는 동일한 방식으로 문서에서 픽스처를 구축했으며, 해당 저장소의 커밋 5481c04는 실제 응답에 대해 확인될 때까지 잘못되었던 세 개의 필드 경로를 수정했습니다. 이 저장소에도 자체적으로 세 개의 잘못된 경로가 있을 것으로 가정하십시오.

버전 번호는 0.1.0이며 이는 검증 상태에 대한 주장입니다. 이 README에는 "실제 계정에 대해 검증됨" 섹션이 없으며, 그 부재는 누락이 아니라 정확한 표현입니다.

오늘 검증된 것은 이 저장소 자체의 동작입니다: 엔드포인트 허용 목록, 호스트 고정, 경로 정규화, 페이지네이션 경계, 봉투 처리, 그리고 세 가지 상태(부재/빈/알 수 없음) 규율입니다. 이 모든 것은 키도 네트워크도 없이 주입된 가짜 fetch에 대해 테스트되었습니다. 작성 시점 기준 146개 테스트, 0개 실패.

설계 기록: docs/adr/ADR-002-endpoint-allow-list.md (상태: 제안됨). 아래의 모든 섹션 참조(§1, §4.3, §14.3 …)는 해당 문서를 가리킵니다.

기능 및 의도적으로 수행하지 않는 작업

일곱 가지 도구, 모두 읽기 전용:

다음 작업은 수행할 수 없습니다:

• 아무것도 다운로드하거나 설치할 수 없습니다. GET /v1/mods/{modId}/files/{fileId}/download-url은 문서화된 읽기이며, 고정된 호스트에 있지만 거부됩니다 — 엔드포인트 허용 목록에 없기 때문입니다(DEC-002 §11.3). Nitrado가 자체적으로 모드를 설치합니다.

• 어디에도 쓸 수 없습니다. 허용 목록 항목 중 변경을 일으키는 엔드포인트를 가리키는 것은 없습니다. CurseForge는 다른 호스트에서 변경을 일으키는 업로드 API를 운영합니다(§14.2). 호스트 고정이 독립적인 이유로 다시 한 번 거부합니다.

• 모드를 게시하거나 제작할 수 없습니다. 완전히 거부됩니다(DEC-002 판결 2). 약속이 아닌 부트 어설션에 의해 강제됩니다: 계층 1 이외의 것을 선언하는 도구를 등록하면 프로세스가 시작을 거부합니다.

• Nitrado를 건드릴 수 없습니다. 이 저장소의 구성 표면에는 NITRADO_* 변수가 존재하지 않으며, 그 부재는 통제 수단입니다. 이 서버는 Nitrado 토큰을 보유하지 않으며 Nitrado 구성을 읽지 않습니다.

• 타이머에 의해 깨어나 서버를 업데이트할 수 없습니다. 스케줄러, 폴링 루프, 지속된 "마지막으로 본 버전" 상태가 없습니다(§10). 감시는 모델이 새 버전을 관찰할 수 있음을 의미합니다. 행동을 취할 수는 없습니다.

병목 지점: 메서드 확인이 아닌 엔드포인트 허용 목록

코드를 건드리기 전에 읽어야 할 유일한 설계 결정입니다.

CurseForge는 읽기에 POST를 사용합니다. POST /v1/mods와 POST /v1/mods/files는 대량 검색이며, 이로 인해 resolve_mod_dependencies가 노드당 하나의 요청이 아닌 종속성 레벨당 하나의 요청만 소모하게 됩니다. 따라서 형제 저장소의 method !== "GET" → 거부는 여기서 가장 비용이 많이 드는 방식으로 실패할 것입니다: 작동할 것입니다. 무언가를 거부하고, 자체 테스트를 통과하며, 조용히 서버를 제 역할을 못하게 만들 것입니다.

그리고 명백한 수정은 버그보다 더 나쁩니다:

allowed = { GET }          → the batch reads are refused (broken, loudly)
allowed = { GET, POST }    → every request this client can construct is allowed

문서화된 카탈로그 API에는 GET과 POST만 포함됩니다. 둘 다 허용하는 게이트는 모든 것을 허용합니다 — 계속해서 정상적으로 보이면서도.

따라서 대신, 모든 아웃바운드 요청은 닫힌 {method, path} 쌍 목록의 명시적 항목과 일치해야 합니다. src/allowlist.ts에 있는 일곱 개의 항목:

메커니즘:

• {method, path}를 함께 매칭합니다. E3는 DELETE /v1/mods/123을 승인하지 않습니다. E6는 POST /v1/mods/123을 승인하지 않습니다.

• 호스트는 고정되어 https://api.curseforge.com이며, 고정은 다른 명명된 출처를 거부하는 것이 아니라 하나의 출처를 허용하는 것입니다.

• ID 세그먼트는 [0-9]+에 바인딩되며, [^/]+가 아닙니다. 이는 중요한 역할을 합니다: 관대한 {modId}는 E3가 /v1/mods/search를 삼키게 만듭니다. 숫자 바인딩은 이러한 모호성을 매치 순서에 의존하지 않고 구조적으로 불가능하게 만듭니다 — 그리고 전체 목록을 뒤집어 순서가 구원자가 아님을 증명하는 테스트가 있습니다.

• 확인 전에 한 번 정규화하며, URL은 그 출력에서 빌드됩니다. 퍼센트 디코딩을 한 번 수행하고, 살아남은 %는 거부합니다. 백슬래시를 접습니다. ., .. 및 빈 세그먼트를 거부합니다.

• E6/E7만 본문을 가질 수 있으며, 전송 전에 형태가 확인됩니다. GET 항목의 본문은 드롭되지 않고 거부됩니다.

• resolve_mod_dependencies만 POST 항목에 도달할 수 있으며(§8), 전송 계층에서 강제됩니다.

실패 모드는 "일치하지 않는 요청 거부"이며, "인식되지 않은 요청 전송"이 아닙니다. 그리고 기능 추가는 검토 가능한 한 줄 차이이며, 검토 질문 — "이 엔드포인트는 읽기인가?" — 은 인간이 실제로 답할 수 있는 질문입니다.

허용 목록임을 증명하는 테스트

GET /v1/mods/{modId}/files/{fileId}/download-url은 거부됩니다. 문서화된 읽기이며, GET이고, 고정된 호스트에 있으며, 잘 구성된 숫자 ID를 가집니다. 순전히 목록에 없기 때문에 거부됩니다. 만약 그 테스트가 다른 이유(호스트 고정 거부, 경로 거부)로 통과한다면, 해당 속성은 구현되지 않은 것이므로 테스트는 단순히 무언가가 던져졌다는 것이 아니라 거부의 코드와 세부 사항을 단언합니다.

모든 거부 테스트는 또한 가짜 fetch의 호출 횟수를 단언합니다. 왜냐하면 "요청이 빌드되기 전에 거부됨"이 실제 조항이며, 전송 후에 발생한 오류는 더 약한 단언을 만족시킬 것이기 때문입니다. 그리고 거부 테스트 모음은 모든 일곱 항목이 실제로 전송됨을 증명하는 원상(preimage) 테스트가 선행됩니다 — 아무것도 보낼 수 없는 클라이언트에 대한 거부 모음은 완벽하게 통과하지만 아무것도 증명하지 않습니다.

여전히 검증되지 않음

아래의 모든 행은 가설입니다. 이는 ADR-002의 §14.3을 전체 재현한 것입니다. 필드 경로는 게시된 스키마에서 읽었으며, 이는 형제 저장소에서 세 개의 잘못된 경로를 생성한 바로 그 인공물 클래스입니다.

도구 출력에서 볼 수 있는 두 가지 결과

relationType과 releaseType은 원시 정수로 표시되며 매핑되지 않습니다. required/optional 또는 release/beta/alpha로 매핑되지 않습니다. CurseForge는 둘 중 어느 것에도 값 테이블을 게시하지 않으며, 잘못된 레이블은 아무도 확인하지 않을 방식으로 잘못된 종속성 목록 또는 업데이트 권장 사항을 생성할 수 있습니다. 따라서 resolve_mod_dependencies는 모든 엣지를 따르며 그렇게 명시합니다. 즉, 과다 수집하며, 그 출력은 이를 명확히 언급합니다. 넓은 그물은 적어도 시각적으로 넓습니다.

get_latest_file은 사용자가 "최신"이 무엇을 의미하는지 말하도록 요구합니다. fileDate 기준 최신, 게임 버전 일치 기준 최신, 주어진 releaseType을 가진 최신은 서로 다른 답변을 제공하며, 잘못된 기준으로 모드 업데이트를 결정하는 것은 이 저장소가 방지하려는 자신만만한 잘못된 답변에 정확히 해당합니다. selection에는 기본값이 없습니다:

명명된 release/beta/alpha 필터는 없습니다. U7이 해결되지 않았고 이 서버가 매핑을 발명하지 않기 때문입니다. 원하는 정수를 전달하면 됩니다.

이 정의는 공개된 제품 질문입니다. ADR-002의 미해결 질문 2는 이를 창립자 결정으로 표시하며, 이 서버가 구축될 당시에는 결정되지 않았으므로, 도구는 의견을 제시하지 않고 매개변수화되었습니다. 답변이 도착하면 기본값이 되거나 하나의 변형이 줄어듭니다 — 재작성이 아닌 작은 변경입니다. 모든 답변은 사용한 순서, 필터링한 기준, 고려한 후보 수, 후보의 출처를 재진술합니다.

설정

Node 20+ (22에서 개발). 구성할 빌드 단계 없음; npm test가 먼저 빌드합니다.

npm install
npm test          # builds, then runs the suite — no key, no network
npm run typecheck
npm run smoke     # refuses cleanly until a key exists, naming what it would probe

그런 다음 키를 받으면:

cp .env.example .env
# set CURSEFORGE_API_KEY, then:
npm run smoke

MCP 클라이언트 구성 (stdio):

{
  "mcpServers": {
    "curseforge-ark": {
      "command": "node",
      "args": ["C:/path/to/curseforge-ark-mcp/dist/src/server.js"],
      "env": { "CURSEFORGE_API_KEY": "your-key" }
    }
  }
}

서버는 키 없이 시작을 거부하며, 검색한 두 위치, 정확한 변수 이름, 키가 자체 서비스가 아님을 명시합니다. 깔끔하게 시작한 후 일곱 가지 도구 모두에서 오류를 던지는 stdio MCP 서버는 디버깅하기 매우 불쾌합니다.

키 정보

API 키는 x-api-key 요청 헤더로 전송됩니다. Authorization: Bearer 토큰이 아닙니다. 이는 형제 Nitrado 서버의 방식이며, 이 저장소는 의도적으로 둘 다 지원하지 않습니다. 둘 다 지원하면 이 코드가 CurseForge가 문서화하지 않은 형태로 자격 증명을 전송할 수 있기 때문입니다.

키는 애플리케이션별로 Overwolf에 부여되며 양도할 수 없습니다. 실제 결과 — 그리고 이 문단이 존재하는 유일한 이유는 유출 시 철회 및 재신청이 필요하며, 재신청은 대기열이며 자체 서비스 재설정이 아닙니다. 잠시 커피를 마시면서 재생성할 수 없고 다른 사람의 키를 빌릴 수도 없습니다. 그에 따라 취급하십시오 — .env는 gitignored이며, .env.example은 변수 이름과 빈 값을 포함하며, 커밋된 파일에는 키 값이 나타나지 않습니다.

이 저장소에는 범위 행렬이 없으며, 이는 누락이 아닙니다: CurseForge는 읽기 전용 범위나 범위 선택을 게시하지 않으므로 행렬화할 것이 없습니다. 이 서버의 읽기 전용 속성은 자체 엔드포인트 허용 목록에서 비롯되며, 더 좁은 자격 증명에서 비롯된 것이 아닙니다. 또한 토큰 유출 Runbook이 없습니다 — 유출된 키는 공개 카탈로그에 대한 읽기 액세스와 할당량 소비를 부여하며, 이는 실제이며 형제 저장소의 Nitrado 토큰(게임 서버에 대한 완전한 제어와 동일하다고 문서화됨)과 같은 범주가 아닙니다. 이러한 적절한 크기 조정은 ADR-002 §12에서 논의되며, 반증될 수 있도록 명시된 하나의 주장에 의존합니다: CurseForge 카탈로그 데이터는 구조적으로 공개되어 있습니다.

삭제, 전부 다

한 가지 규칙: API 키를 절대 출력하지 않는다. 하나의 함수, src/scrub.ts가 오류 메시지와 모든 업스트림 본문 조각에 적용됩니다. 요청 헤더는 오류에 절대 나타나지 않습니다. 키도, 삭제된 키도, 헤더 이름 목록도 아닙니다. get_api_diagnostics는 키가 구성되어 있는지 여부를 보고하며 해당 값, 값의 접두사, 또는 길이는 절대 보고하지 않습니다.

출력을 읽기 전에 알아두면 좋은 동작

• 빈 값은 알 수 없음이 아닙니다. data: []는 CurseForge가 "없음"이라고 답했음을 의미합니다. 즉, 실제 답변으로, 쿼리가 그대로 표시되어 무엇이 아무것도 반환하지 않았는지 확인할 수 있습니다. 필드가 없으면 null이며, 절대 0, "" 또는 []가 아닙니다. 완료되지 않은 요청이나 형태가 잘못된 응답은 오류이며, 값이 절대 아닙니다.

• data 키가 없으면 빈 결과가 아니라 오류입니다. 이를 []로 강제 변환하면 깨진 통합이 "결과 없음"으로 둔갑하게 됩니다.

• 페이지 매김 엔드포인트에서 pagination이 없으면 역시 오류입니다. 한 페이지가 전체라고 가정하는 것은 도구가 900개 모드 중 50개를 마치 전체인 것처럼 보고하는 방식입니다 (U8이 정확히 이 미해결 질문입니다).

• pageSize > 50은 잘리지 않고 거부됩니다, index + pageSize > 10000도 마찬가지입니다. 메시지에는 해당 인덱스에서 허용되는 최대 페이지 크기가 명시됩니다. 200을 요청하고 조용히 50을 받은 모델은 페이지를 집합인 것처럼 추론하게 됩니다.

• totalCount가 10000을 초과하면 도구 출력은 그 단어 그대로 끝부분은 UNREACHABLE이라고 말하며, 페이지를 매기는 대신 필터를 좁히라고 조언합니다.

• ASA gameId는 런타임에 발견됩니다 GET /v1/games에서 가져오며 프로세스 수명 동안 캐시됩니다. 절대 하드코딩되거나 추측되지 않습니다. 해결할 수 없으면 서버는 무엇을 검색했는지, 키가 볼 수 있는 게임 수를 명명하며 크게 실패합니다. gameId는 필수 검색 필터이므로 잘못된 값을 사용하면 오류 대신 깨끗하고 비어 있으며 완전히 잘못된 결과가 반환되기 때문입니다. 기본 제공 후보가 잘못된 것으로 판명되면 CURSEFORGE_GAME_SLUG를 설정하세요.

• resolve_mod_dependencies는 깊이 4와 노드 400개로 제한됩니다, 순환을 위한 방문 집합과 함께. 제한에 도달하면 결과는 truncated라는 단어 그대로 보고되며, 탐색되지 않은 경계가 나열됩니다.

리포지토리 구조

src/
  allowlist.ts    THE CHOKEPOINT — seven entries, host pin, normalization, bounds, body checks
  client.ts       the single transport; the ONLY place x-api-key is attached; envelope unwrap
  config.ts       refuse-to-start; no NITRADO_*, no mode switch, no settable base URL
  coerce.ts       empty / absent / unknown, kept apart
  errors.ts       the error taxonomy
  game.ts         runtime gameId resolution (injected, process-lifetime cache)
  registry.ts     ToolDef + tier, and the boot assertion that refuses a non-tier-1 tool
  scrub.ts        never echo the key. That is the whole module.
  probe-plan.ts   one probe per unverified row, asserted complete by a test
  server.ts       stdio entry point
  smoke.ts        the key-arrival command
  tools/          the seven tools
test/             146 tests; fixtures are synthetic in content, structural in shape
scripts/          buildinfo generator, test enumerator

src/buildinfo.ts는 생성되고 gitignore되는 파일로, 모든 tsc 실행 전에 커밋과 dirty 플래그가 찍히며 get_api_diagnostics를 통해 표면화됩니다. dist/는 gitignore되며 서버는 장기 실행 프로세스로 여기서 실행되므로, "어떤 코드가 그 답변을 생성했는가?"는 런타임 시 git으로 알 수 없습니다. 그 정보는 아티팩트와 함께 이동해야 합니다.

형제 리포지토리와의 차이점, 의도적으로 명시됨

ADR-002의 미해결 질문 7과 8은 이러한 사항이 발생하는 곳에서 명명하도록 요구합니다:

• 의도적으로 동일한 베이스라인. Node ≥20, TypeScript 5.9.3, @modelcontextprotocol/sdk 1.30.0, zod 4.4.3, 동일한 scripts/run-tests.mjs 열거자를 통한 node:test. 동일한 검토자, 동일한 관용구, 둘 다 읽는 비용 절감.

• @cfworker/json-schema는 여기서 의존성이 아닙니다. 이는 형제의 cron 표현식 검증을 지원하지만, 여기서 검증할 쓰기 경로가 없습니다.

• registry.ts는 구조가 이식되고 tier를 유지하지만 mode/enabled-list 메커니즘은 제거됩니다 — 모든 도구가 tier 1이고 모든 엔드포인트가 읽기이므로 필터링할 것이 없습니다. 뒤에 아무것도 없는 모드 변수는 존재하지 않는 제어 기능을 광고하는 것입니다. 하나의 5줄 부팅 어서션이 하위 시스템을 대체합니다.

• redact.ts는 이식되지 않았습니다 (§12.1). 위의 "삭제, 전부 다"를 참조하세요.

• UNKNOWN_OUTCOME 오류 코드가 없습니다. 형제 프로젝트에는 이것이 필요합니다. PUT에 대한 응답 손실이 여전히 세상을 바꿨을 수 있기 때문입니다. 이 클라이언트가 만들 수 있는 모든 요청은 읽기이므로 타임아웃은 실제로 "일어나지 않았다"는 뜻이며 재시도는 안전합니다.

• npm run smoke는 키가 없어 거부할 때 0으로 종료됩니다. 거부는 오늘 그것을 실행했을 때 기대되는 결과이며, 배너는 SMOKE NOT RUN이라고 놓칠 수 없게 표시합니다. 키 누락 시 파이프라인이 실패하도록 하려면 이 종료 코드가 아니라 키로 파이프라인을 게이트하세요.

관련 기록

형제 리포지토리 nitrado-ark-mcp는 여기서 읽기 전용입니다 — 그 리포지토리의 어떤 것도 이 리포지토리에 의해 수정되지 않았습니다:

• docs/decisions/EXECUTIVE-BOARD-2026-08-16-curseforge-mods.md — 이 리포지토리가 실행하는 이사회 회의록(DEC-002)입니다. 의장의 판결은 구속력이 있습니다.

• docs/decisions/decision-log.md — DEC-002 및 §10이 의존하는 범위 분할에 대한 DEC-001.

• docs/adr/ADR-001-write-path-enforcement.md — ADR-002가 이식하는 형태이자 정규화 규칙, 부팅 검사 추론, 시작 거부 추론의 출처입니다.

두 서버는 독립적으로 유지됩니다. nitrado-ark-mcp는 *"이 프로젝트 ID들이 active-mods에 있다"*고 답하고, 이 리포지토리는 *"프로젝트 X의 최신 파일은 v2.1입니다"*라고 답합니다. 모델은 둘 다 보유합니다. 어떤 서버도 다른 서버를 호출하지 않으며, 둘 중 어느 것도 상대방의 자격 증명을 보유하지 않습니다.