API와 MCP 참조

이 페이지는 연동 프로그램을 만들거나 AI 클라이언트에 작업 지침을 작성하는 사람을 위한 안내입니다. 일반적인 브라우저 사용은 첫 워크스페이스부터 시작하세요. 기존 AI 앱을 연결하려면 AI 앱 연결을 따릅니다.

연동 방식 선택

하려는 일	방식	요청·응답 명세
AI 클라이언트가 dtxWiki 도구를 찾아 사용하도록 연결	`/mcp`의 인증된 Streamable HTTP	MCP 입력·출력 스키마
HTTP 리소스를 호출하는 앱이나 스크립트 개발	`/api/v1` 아래 REST	REST OpenAPI 스키마

두 방식 모두 실행 중인 dtxWiki 서버와 접근 권한 검사를 사용합니다. 원격 서버에는 HTTPS를 사용하세요. MCP는 PAT 또는 dtxWiki OAuth bearer 토큰으로, REST는 해당 동작이 Bearer 인증을 허용하면 브라우저 세션 쿠키 또는 PAT·OAuth JWT bearer 토큰으로 인증합니다. 브라우저 로그인만으로 외부 MCP 클라이언트가 인증되지는 않습니다. 액세스 키 관리, 서버 관리자용 첨부 파일 작업처럼 브라우저 세션만 받는 REST 작업도 있습니다. 각 작업이 받는 인증 방식은 OpenAPI 스키마의 security 항목에서 확인하세요.

연결된 스키마는 v0.2.1 기준입니다. 요청을 구현하기 전에 설치한 버전의 명세를 확인하세요. 달라진 점은 0.2 연동 변경에 정리되어 있습니다. 자격 증명을 발급해도 워크스페이스 멤버십을 추가로 얻거나 범위·허용 워크스페이스 설정을 넘을 수는 없습니다.

올바른 워크스페이스에서 MCP 작업 시작

list_my_workspaces로 현재 연결이 접근할 수 있는 워크스페이스를 확인합니다.
원하는 워크스페이스의 ID를 선택하고, 그 workspace_id로 guide를 호출합니다. 반환된 작업 흐름과 정책 안내를 읽습니다.
이후 워크스페이스 도구 호출에도 선택한 workspace_id를 전달합니다. search로 자료를 찾고 fetch 또는 read로 내용을 확인합니다.
작업을 이어가기 전에 결과와 경고를 읽습니다. 제목 검색 결과나 일부 응답만으로 근거 전체를 읽었다고 판단하지 않습니다.

워크스페이스 ID는 UUID이며 표시 이름이나 URL의 슬러그와 다릅니다. 다른 설치의 값을 추측해서 쓰지 말고, 올바른 서버·작업과 함께 관리하세요.

AI 앱을 연결한 뒤 다음과 같이 요청할 수 있습니다.

list_my_workspaces로 제품 출시 워크스페이스를 찾아줘. 해당 ID로 guide를 호출하고, 출시 점검표를 검색해 관련 근거를 읽어줘. 출처를 포함해 남은 작업을 설명해줘. 페이지는 수정하지 마.

연결된 클라이언트에게 전달하는 지침 예시이며, 터미널에 붙여 넣는 명령은 아닙니다. 앱이 실제로 도구를 호출하고 반환된 자료를 사용해야 합니다.

작업에 맞는 도구 찾기

v0.2.1 등록 목록에는 도구 29개가 있습니다. 해당 연결이 실제로 사용할 수 있는 목록은 tools/list 응답으로 확인합니다. 자격 증명의 범위와 접근 권한 검사에 따라 목록이 제한될 수 있습니다.

작업	도구
탐색과 읽기	`list_my_workspaces`, `guide`, `search`, `fetch`, `grep_wiki`, `what_changed`, `read`, `get_index`, `read_concept`, `read_context_outline`, `read_structure_map`, `list_changes`
Context 편집	`create_context_page`, `begin_context_edit`, `update_context_edit`, `submit_context_edit_for_review`, `discard_context_edit`, `patch_context_edit`, `list_my_context_edits`, `upload_image`, `cite`, `submit_feedback`
Agent 지침 활용	`list_agent_categories`, `read_agent_page`, `write_agent_page_draft`, `build_agent_input_bundle`
검토와 유지보수	`list_requested_changes`, `submit_revision_for_review`, `wiki_maintenance`

각 도구의 스키마에서 필수 입력과 응답 구조를 확인하세요. 목록에 도구가 있더라도 모든 워크스페이스나 페이지 상태에서 모든 작업이 허용되는 것은 아닙니다. 읽기 권한부터 시작하고, 쓰기 권한을 늘리기 전에 브라우저에서 결과를 검증합니다.

도구 명세는 개정 29입니다. 서버는 이 값을 serverInfo.version에 <app version>+llmwiki.mcp.v1.tools.29.<digest> 형태로 알려 줍니다. 명세가 바뀌었는지 알아내려면 버전의 높고 낮음을 비교하지 말고 문자열 전체나 tools.<N> 부분을 비교하세요. 값이 바뀌면 tools/list를 다시 받으세요.

브라우저의 설정 → 실험실 선택은 MCP 도구나 REST API에 영향을 주지 않습니다. MCP로 작성된 Agent 페이지 초안을 확인하는 사람은 자신의 Agent 메뉴가 숨겨져 있어도 복사한 /workspaces/<workspace_id>/agent/pages/<page_id> 링크로 열 수 있고, Agent 메뉴 표시를 켤 수도 있습니다. Agent 페이지를 참고하세요.

upload_image로 올린 이미지는 페이지의 어느 버전에서도 참조하지 않고 열린 편집본도 붙잡고 있지 않으면 미사용 파일이 됩니다. 백그라운드 정리는 업로드 시점부터 워크스페이스 보존 기간이 지난 미사용 파일을 회수합니다. 기본값은 7일이며, 소유자가 설정 → 첨부 파일에서 바꾸거나 끌 수 있습니다.

검토 가능한 Context 편집

기존 페이지를 바꾸려면 먼저 연습 워크스페이스에서 다음 순서를 확인하세요.

현재 페이지와 read_structure_map의 구조를 읽습니다. 제목·절 정보에는 read_context_outline을 사용합니다. fetch, Context 읽기, begin_context_edit는 읽을 수 있는 버전의 references도 제공합니다.
begin_context_edit를 호출하고 반환된 version_id, editing_revision, content_hash를 보관합니다. MCP의 editing 세션은 작성자 전용이며, 같은 워크스페이스의 편집자·소유자가 볼 수 있는 브라우저 초안 저장과 다릅니다.
본문 일부는 patch_context_edit, 전체 교체·메타데이터 변경은 update_context_edit를 사용합니다. version_id, 현재 editing_revision을 넣은 expected_editing_revision, idempotency_key를 전달합니다.
근거 문서를 검색하고 읽은 뒤 제출 전에 cite로 열린 편집에 참고문헌을 등록합니다. 모든 쓰기 이후 다음 명령에는 반환된 editing_revision을 사용하세요. 참고문헌만 바뀌어도 이 번호가 바뀔 수 있습니다.
해당 버전의 본문·참고문헌을 다시 읽고 브라우저에서도 확인합니다. 작업이 준비되면 submit_context_edit_for_review로 한 번 제출하고, 버리려면 discard_context_edit를 사용합니다. 반환된 검토·게시 상태를 확인하세요.

새 페이지는 create_context_page의 반환 식별자로 이어갑니다. list_my_context_edits는 아직 열린 편집을 찾습니다. 오래된 버전·개정 번호 충돌 시 최신 상태를 읽은 뒤 변경 요청을 다시 판단하세요. 같은 명령의 재시도에는 같은 idempotency_key를 쓰되 다른 편집에 재사용하지 않습니다. 채팅에서 expected_editing_revision은 원본 요청 정보 → 덮어쓰기 방지 번호로 표시됩니다.

MCP 편집 저장·검토 제출·워크스페이스 게시·웹 공개는 별도입니다. 제출한 초안은 권한 있는 편집자에게 보일 수 있지만 뷰어에게 게시된 것은 아닙니다. Context 페이지, 검토와 이력을 참고하세요.

update_context_edit는 메타데이터만 바꿀 때도 전체 body_md가 필요합니다. 관리 frontmatter를 포함해 최종 본문이 1,000,000자를 넘을 수 없습니다. 참고문헌은 일반 편집 요청에 지원하지 않는 인용 배열을 덧붙이는 대신 전용 cite 명령으로 등록합니다.

`cite`로 참고문헌 등록하기

개정 29의 cite는 Register references입니다. 자신의 열린 Context 편집에 선택한 Context·Library·Agent 문서 ID를 실제 등록합니다. 먼저 search와 read/fetch로 문서를 선택하세요. 자격 증명에는 UI의 쓰기에 포함된 draft-write가 필요하고 워크스페이스 역할도 충족해야 합니다. 읽기 전용 자격 증명으로 등록할 수는 없습니다.

입력	전달할 값
`workspace_id`, `page_id`	명시적인 워크스페이스 UUID와 Context 페이지 UUID 또는 지원하는 안정 주소.
`version_id`, `expected_editing_revision`	마지막 읽기·쓰기에서 받은 열린 편집과 현재 개정 번호. 게시·제출한 버전은 열린 편집이 아님.
`idempotency_key`	명령별 고유 키. 결과가 불확실한 같은 요청의 재시도에 유지. `retry_only`로 새 작업 없이 기존 명령을 확인할 수 있음.
`add`	선택한 `{target_kind, target_id, note?}`. 종류는 `context_page`, `library_item`, `agent_page`. `target_id`는 버전이 아닌 문서 UUID이며 메모는 최대 2,000자.
`remove`	`{target_kind, target_id}` 쌍 또는 해당 출처 문서의 참고문헌 메타데이터에서 받은 `reference_id`.
`conversation_token`	이 MCP 작업의 토큰을 그대로 전달. 새 채팅을 의도할 때만 `new` 사용.

추가·삭제 항목이 하나 이상 필요합니다. 요청 하나에 둘을 합쳐 최대 500개이며 각 목록의 중복 대상, 같은 대상을 동시에 추가·삭제하는 입력은 거부합니다. 문서의 본문 인용과 등록 참고문헌 전체에는 서로 다른 대상 최대 500개 한도가 적용됩니다.

결과에는 version_id, editing_revision, references_hash, 추가·삭제·변경 없음 항목과 영수증이 반환됩니다. 참고문헌 메타데이터를 바꾸며 게시하거나 본문 표시를 넣지는 않습니다. 본문 인용이 필요하면 주소 기반 @cite{...}를 넣으세요. 브라우저에서는 참고문헌 선택기가 이 작업을 돕습니다. 등록을 지워도 남은 본문 인용은 없어지지 않으니 remaining_inline_occurrences와 본문을 확인합니다.

옛 주장 검색용 cite 입력은 더 이상 받지 않습니다. 도구 스키마를 다시 받고 검색·읽기 다음 참고문헌 등록 순서로 바꾸세요. 게시 그래프의 인용 관계는 출처 문서 버전을 게시할 때 바뀝니다.

입력 한도

dtxWiki는 한도를 넘는 입력을 줄여서 저장하지 않고 거부합니다. 표에 바이트로 적힌 항목을 빼면 길이는 문자(Unicode 코드 포인트) 수로 셉니다. MCP 도구는 validation_failed 코드와 retryable: false가 담긴 도구 오류를 반환합니다. REST는 HTTP 422와 error_code validation_failed를 반환하며, 브라우저에는 “입력한 정보 중 일부가 올바르지 않습니다.”로 표시됩니다. 스키마에는 x-normalized-maxLength, x-final-maxLength 같은 확장 항목을 포함해 이 한도가 공개되어 있습니다.

입력	한도
페이지·Agent 페이지 제목	한 줄로 최대 256자. 앞뒤 공백을 먼저 제거한 길이
페이지·Agent 페이지 본문(`body_md`, `body_markdown`)	관리 frontmatter를 포함해 최종 저장되는 Markdown 기준 최대 1,000,000자
`tags`, `aliases`	각각 최대 32개. 태그는 1~~48자, 별칭은 1~~80자
`reason`, `patch_description`, `risk_notes`, 본문 댓글 외의 `note` 필드, `suggested_action`	최대 2,000자
`nav_summary`, 워크스페이스의 `goal`	각각 최대 160자, 512자
`patch_context_edit`의 `operations`	요청당 최대 20개 작업. 처리 후 본문도 본문 한도를 지켜야 함
`submit_feedback`의 `body`	최대 10,000자
참고문헌	문서당 본문 인용·등록 참고문헌 합산 서로 다른 대상 500개, `cite` 요청당 add/remove 합산 500개
`build_agent_input_bundle`	`requested_categories`: `agent_guide`, `persona`, `skill`, `memory` 중 최대 4개. `context_refs`, `library_artifact_refs`: 각각 최대 128개
폴더·채팅·워크스페이스 제목(REST)	각각 최대 80자, 120자, 128자. 워크스페이스 슬러그 최대 80자
질문(Ask) 메시지(REST)	앞뒤 공백 제거 후 최대 8,000자
검색 `query`(REST)	최대 2,048자
본문 댓글 `note`(REST)	최대 5,000자. 선택한 `anchor_text` 최대 2,000자, `context_before`와 `context_after` 각각 최대 500자
액세스 키 이름, 사용자 지정 AI 앱 표시 이름	한 줄로 1~128자, 최대 160자
액세스 키·OAuth 승인 하나당 워크스페이스	최대 256개
계정 이메일·표시 이름·새 비밀번호(REST)	이메일 최대 254바이트(@ 앞부분 최대 64바이트), 표시 이름 1~~32자, 새 비밀번호 8~~128자

구조 조회의 다음 결과 읽기

큰 문서는 여러 번 호출해야 할 수 있습니다. 첫 응답을 문서 전체로 판단하지 마세요.

도구	다음 결과를 읽는 방법
`read_structure_map`	`next_cursor`를 따릅니다. 블록·표 행의 생략 정보를 확인하세요. `document.block_count`는 문서 전체 블록 수입니다.
`read_context_outline`	제목 목록을 이어서 읽으려면 반환된 `outline_next_cursor`를 다음 요청의 `outline_cursor`로 전달합니다. 별도의 `cursor`는 선택한 절의 본문을 이어서 읽을 때 사용합니다.

제목 목록과 절 본문의 커서는 용도가 다릅니다. 각 커서를 해당 도구·워크스페이스·문서·요청과 함께 관리하세요.

REST 읽기 요청으로 확인

MCP 접근 설정에서 필요한 워크스페이스 접근을 가진 PAT를 만듭니다. 승인된 비밀값 관리 방법 또는 단계별 환경 변수 안내로 DTXWIKI_MCP_PAT를 준비한 뒤, 같은 터미널에서 아래 검사를 실행하세요. 실제 토큰을 공유 스크립트나 터미널 기록에 쓰지 않습니다.

다음 Bash 예시는 자격 증명이 접근할 수 있는 워크스페이스를 조회합니다. 서버 예시 주소를 실제 주소로 바꾸세요.

DTXWIKI_API='https://wiki.example.com/api/v1'
printf 'Authorization: Bearer %s\n' "$DTXWIKI_MCP_PAT" |
  curl --fail-with-body --silent --show-error \
    --header @- "$DTXWIKI_API/workspaces"

인증 헤더는 표준 입력으로 전달합니다. 반환된 워크스페이스 정보는 비공개일 수 있으므로 진단 보고서를 공유하기 전에 민감한 내용을 제거하세요. 조회 성공은 해당 요청의 확인이며, 쓰기 흐름이나 특정 AI 앱의 연결까지 검증한 것은 아닙니다.

워크스페이스 리소스는 /api/v1/workspaces/{workspace_id}/context/pages처럼 경로에 워크스페이스 UUID를 사용합니다. 요청 방식·본문·인증·페이지네이션·오류는 OpenAPI 스키마를 따릅니다. REST 오류에는 error_code, message, request_id, warnings가 포함됩니다. 운영자에게 조사를 요청할 때는 요청 ID를 보관하고 자격 증명이나 비공개 내용은 제외하세요. 한도를 넘는 입력은 HTTP 422와 validation_failed를 반환합니다. 입력 한도를 참고하세요.

v0.1에서 연동 업그레이드

dtxWiki v0.2.1의 계약은 개정 29입니다. serverInfo.version 전체가 바뀌면 tools/list와 생성한 입력·출력 스키마를 다시 받으세요.

계약 영역	필요한 변경
워크스페이스	모든 워크스페이스 도구·동적 프롬프트에 `workspace_id`가 필수입니다. 누락·형식 오류 도구 호출은 trace·chat 생성 없이 오류 envelope를 반환합니다. `list_my_workspaces`는 대상 없이 사용합니다. 화면의 현재 선택을 가정하지 마세요.
탐색	`personal_workspace_id`, 멤버의 `is_personal_anchor_owner`는 제거됐습니다. 반환된 `default_workspace_id`·`current_workspace_id`는 힌트로 사용한 뒤 원하는 UUID를 명시합니다.
Context 식별	읽기·검색·검토 결과는 `concept_path`·`resource_uri` 대신 워크스페이스를 포함한 `stable_url`·`link_markdown`을 사용합니다. UUID 또는 `/p/<workspace_id>/<page_id>`를 전달하세요. 옛 `/p/<page_id>` 도구 입력은 명시한 워크스페이스 안에서만 허용됩니다. 공유용 브라우저 링크는 두 ID를 포함하세요.
인덱스	명시한 공간에서 정확한 `dtxwiki://index/<kind>/<id>` 목적지를 사용합니다. 폴더 참조는 `get_index.node`, Context·Library 참조는 `read_concept.path`에 전달합니다. 다른 도구는 명세의 UUID·브라우저 링크를 사용하며 일반 내보내기는 조회 경로를 유지합니다.
Guide	기본값은 `detail_level="brief"`입니다. `normal`은 분류·프롬프트·리소스·정책·도구를, `detailed`는 전체 필드 안내를 추가합니다. `full`은 별칭입니다. 제거된 `placement_parent_candidates`·`active_agent_pages` 대신 `get_index(format="nodes")`·`list_agent_categories`를 사용합니다. 배치 부모의 `can_have_children`을 확인하세요. 큰 공간은 과도한 전체 묶음 대신 검색·인덱스로 안내합니다.
편집 응답	`create_context_page`·`update_context_edit`·`patch_context_edit`·`submit_context_edit_for_review`는 `body_md` 없이 ID·해시·상태·검토·`edit_receipt`를 반환합니다. 본문은 반환된 `version_id`로 읽습니다. `my_edit`는 아직 열린 편집만 뜻하며 `begin_context_edit`는 계속 본문을 반환합니다.
영수증·진단	`first_change` 대신 `edit_receipt.changes`와 생략 수를 읽습니다. `body_adjusted`·`server_fixes`·`lint_report`를 확인하세요. Agent 초안은 인덱스 참조의 `normalization_report`를 추가합니다. 성공 제출의 `context_page_has_no_graph_visible_links`는 안내이며 실패나 연결 존재 증명이 아닙니다.
결과 envelope	`result_status`·`request_id`·`conversation_token`, 선택적 경고·검토 ID·실패 필드를 읽습니다. `envelope.meta`·`result_summary`는 제거됐습니다. 빈 기본값은 생략될 수 있으니 스키마 기본값으로 해석하세요. null이 미확인을 뜻하는 `edit_receipt.changes`·`edit_receipt.body_adjusted`·`envelope.retryable`은 명시합니다. 프로토콜 `_meta`에도 `com.dtxwiki/requestId`가 있습니다.
대기 편집	같은 MCP 채팅의 아직 대기 중인 자기 제출은 `begin_context_edit`가 같은 버전 ID로 다시 열고 이전 검토를 철회할 수 있습니다. 다음 제출이 검토를 교체합니다. 다른 채팅·작성자·이미 결정된 버전은 일반 분기입니다. 작업 하나의 편집을 유지하고 준비 후 한 번 제출하세요.
참고문헌(개정 29)	`cite`는 후보 검색 대신 열린 편집의 참고문헌을 실제 등록. Context 읽기와 `fetch`·`begin_context_edit`에 참고문헌 포함. 게시는 등록 문헌·주소 기반 본문 인용을 합쳐 인용 그래프 관계에 반영.
발행 변경	`what_changed`는 발행 head 이동입니다. `unpublished`는 `version_id=null`이며 `page_id`로 캐시를 무효화합니다. `created`는 재발행·복구일 수도 있어 upsert로 처리합니다. `previous_version_id`는 이전 발행 head이며 초안 부모와 다를 수 있습니다. 접근 권한에 따라 필터링된 메타데이터를 따르세요.

기존 입력 한도는 유지됩니다. 오래된 기준 버전 충돌이 잘못된 본문 검사보다 먼저 나올 수 있으니 기준을 다시 읽고 재시도하세요. 복원·복사·제출·발행은 과거 바이트를 보존하며 직접 작성 저장·발행 Lint 유지보수의 정규화 규칙은 별도입니다.

REST 추가와 호환성

정확한 요청·인증 계약은 고정한 OpenAPI 스키마를 따르세요.

동작	목적
`GET /api/v1/workspaces/{workspace_id}/graph/capability`	워크스페이스 지도 가용성과 관리 가능 여부.
`POST …/graph/query`, `POST …/graph/overview/query`	현재 사용자가 읽을 수 있는 한도 내 로컬 그래프·지도 장면. 전체 감사·이력 내보내기는 아님.
`POST …/context/pages/{page_id}/references`	자신의 열린 편집에 참고문헌 추가·삭제. 편집자 권한과 Bearer의 `draft-write`, `version_id`·`expected_editing_revision`·`idempotency_key`, 합산 최대 500개 항목 필요.
`POST …/graph/citations/evidence/query`	선택한 인용 쌍의 보존된 근거 읽기. `source_page_id`·`target_kind`·`target_id`, 선택적 `cursor`·`limit`(1~50, 기본 20). 일반 콘텐츠 읽기 권한 적용. 표시 항목이 비어도 `next_cursor`가 있으면 다음 결과 확인.
`GET /api/v1/workspaces/{workspace_id}/inbox`, `GET /api/v1/users/me/inbox`	현재 사용자의 범위별 알림. `POST …/marks`는 본 항목 개정에 표시를 적용.
`POST …/reviews/{review_item_id}/decisions/{decision_id}/undo`	브라우저 세션에서 조건부 결정 취소. 바뀐 결과·취소 불가는 409일 수 있음.
`POST /api/v1/admin/deployment/update-check`	관리자 업데이트 조회. 패키지 설치는 하지 않음.

워크스페이스 화면 경로에는 UUID가 포함됩니다. 공간 없는 page-location API는 제거됐으니 공간을 고른 뒤 요청하세요. Context 페이지 응답에는 해당 버전의 references와 references_hash가 있습니다. 변경 가능한 editing 버전을 브라우저 세션으로 게시할 때는 읽은 references_hash를 expected_references_hash로 전달하고 expected_content_hash도 전달해야 합니다. 이미 제출해 고정된 버전은 참고문헌이 그 버전에 묶여 있습니다. 해시·개정 번호가 바뀌면 다시 읽고 결과를 확인하세요.

일반 검색 all은 피드백·변경을 제외하고 권한 있는 명시적 범위는 유지합니다. 브라우저 Agent 검색은 Labs를 따르며 API·MCP는 해당 스키마·권한 검사를 따릅니다. 로컬 화면 설정으로 접근 권한을 추정하지 마세요.

계정 SSO와 MCP OAuth 승인은 별개입니다. 로그인 제공자를 연결해도 PAT를 대체하거나 범위를 늘리지 않습니다. Access Key의 워크스페이스 변경은 기존 Streamable HTTP 세션의 다음 요청부터 반영됩니다. 전송 재연결 여부보다 계약 변경에 따라 목록을 다시 받으세요.

버전 근거: MCP 도구 등록 목록, 도구 명세 개정, 워크스페이스 안내 입력, 워크스페이스 목록 입력, 입력 한도, MCP 입력 오류, OAuth 등록 한도, 준비 상태 검사, 계정 입력 정책, 활동 피드 명세, 활동 작업과 접근 검사, 참고문헌 명령, 참고문헌 등록 서비스, 인용 근거 조회, 게시 해시 검사.

연동 방식 선택​

올바른 워크스페이스에서 MCP 작업 시작​

작업에 맞는 도구 찾기​

검토 가능한 Context 편집​

cite로 참고문헌 등록하기​

입력 한도​

구조 조회의 다음 결과 읽기​

REST 읽기 요청으로 확인​

v0.1에서 연동 업그레이드​

REST 추가와 호환성​