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는 브라우저 세션 쿠키 또는 PAT bearer 토큰으로 인증합니다. 브라우저 로그인만으로 외부 MCP 클라이언트가 인증되지는 않습니다.
연결된 스키마는 v0.1.2 기준입니다. 요청을 구현하기 전에 설치한 버전의 명세를 확인하세요. 자격 증명을 발급해도 워크스페이스 멤버십을 추가로 얻거나 범위·허용 워크스페이스 설정을 넘을 수는 없습니다.
올바른 워크스페이스에서 MCP 작업 시작
list_my_workspaces로 현재 연결이 접근할 수 있는 워크스페이스를 확인합니다.- 원하는 워크스페이스의 ID를 선택하고, 그
workspace_id로guide를 호출합니다. 반환된 작업 흐름과 정책 안내를 읽습니다. - 이후 워크스페이스 도구 호출에도 선택한
workspace_id를 전달합니다.search로 자료를 찾고fetch또는read로 내용을 확인합니다. - 작업을 이어가기 전에 결과와 경고를 읽습니다. 제목 검색 결과나 일부 응답만으로 근거 전체를 읽었다고 판단하지 않습니다.
워크스페이스 ID는 UUID이며 표시 이름이나 URL의 슬러그와 다릅니다. 다른 설치의 값을 추측해서 쓰지 말고, 올바른 서버·작업과 함께 관리하세요.
AI 앱을 연결한 뒤 다음과 같이 요청할 수 있습니다.
list_my_workspaces로 제품 출시 워크스페이스를 찾아줘. 해당 ID로guide를 호출하고, 출시 점검표를 검색해 관련 근거를 읽어줘. 출처를 포함해 남은 작업을 설명해줘. 페이지는 수정하지 마.
연결된 클라이언트에게 전달하는 지침 예시이며, 터미널에 붙여 넣는 명령은 아닙니다. 앱이 실제로 도구를 호출하고 반환된 자료를 사용해야 합니다.
작업에 맞는 도구 찾기
v0.1.2 등록 목록에는 도구 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 |
각 도구의 스키마에서 필수 입력과 응답 구조를 확인하세요. 목록에 도구가 있더라도 모든 워크스페이스나 페이지 상태에서 모든 작업이 허용되는 것은 아닙니다. 읽기 권한부터 시작하고, 쓰기 권한을 늘리기 전에 브라우저에서 결과를 검증합니다.
검토 가능한 Context 편집
기존 페이지를 바꾸려면 먼저 연습 워크스페이스에서 다음 순서를 확인하세요.
- 현재 페이지를 읽고
read_structure_map으로 구조를 확인합니다. 제목이나 절 단위 정보가 필요하면read_context_outline을 사용합니다. - 반환된 문서 버전을 기준으로
begin_context_edit를 호출해 자신의 개인 편집을 시작합니다. - 본문 일부를 바꾸려면 지원되는 작업 유형으로
patch_context_edit를 호출합니다. 본문 전체를 교체하거나 제목·태그·별칭·배치를 바꾸려면update_context_edit를 사용합니다. - 명세에 따라 편집의
editing_version_id, 현재expected_editing_revision, 필수 작업 키를 전달합니다. 버전이나 리비전이 충돌하면 최신 결과를 확인한 뒤 변경한 요청의 재시도를 판단합니다. - 브라우저에서 편집 내용을 확인합니다. 준비되면
submit_context_edit_for_review로 해당 편집을 명시적으로 검토 제출하고, 취소하려면discard_context_edit를 사용합니다.
새 페이지는 create_context_page로 만들고 반환된 편집 식별자로 작업을 이어갑니다. 아직 열려 있는 편집은 list_my_context_edits로 찾을 수 있습니다.
편집 저장이 검토 제출이나 게시를 자동으로 처리하지는 않습니다. 검토, 워크스페이스 내부 게시, 웹 공개는 별도 단계입니다. Context 페이지, 검토와 변경 기록을 함께 읽으세요.
update_context_edit는 메타데이터만 바꿀 때에도 전체 body_md가 필요합니다. Context 편집 도구에는 본문 없는 메타데이터 변경이나 인용 배열 쓰기가 없습니다. cite의 반환값이 편집 명령으로 자동 첨부되는 것도 아닙니다. 스키마와 실제 저장된 인용을 확인하세요.
구조 조회의 다음 결과 읽기
큰 문서는 여러 번 호출해야 할 수 있습니다. 첫 응답을 문서 전체로 판단하지 마세요.
| 도구 | 다음 결과를 읽는 방법 |
|---|---|
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를 보관하고 자격 증명이나 비공개 내용은 제외하세요.
버전 근거: MCP 도구 등록 목록, 워크스페이스 안내 입력, 워크스페이스 목록 입력.