> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tiro.ooo/llms.txt
> Use this file to discover all available pages before exploring further.

# Wiki

> 자동 생성된 워크스페이스 위키를 검색하고 탐색합니다 (읽기 전용)

## 개요

위키 도구는 Tiro가 자동 생성한 워크스페이스 위키, 즉 회의 노트에서 추출된 엔티티, 개념, 관계를 에이전트가 탐색할 수 있는 지식 그래프로 노출합니다. 네 개의 **읽기 전용** 도구가 검색 → 읽기 → 탐색으로 이어지는 체인을 구성합니다.

* **`search_wiki`**: 위키 페이지에 대한 키워드 검색입니다. 진입점 역할을 하며, 나머지 세 도구에 전달할 순위가 매겨진 페이지(`pageGuid`, `name`, `pageType`, 관련도)를 반환합니다.
* **`get_wiki_page`**: 단일 페이지의 본문(설명 + 생성 상태)과 메타데이터, 그리고 구조화된 mentions, aliases, links를 반환합니다.
* **`list_wiki_mentions`**: 페이지를 참조하는 노트 단락들, 즉 노트 전체에서 해당 페이지가 언급되는 위치입니다.
* **`get_wiki_graph`**: 페이지들이 어떻게 연결되는지 탐색할 수 있도록 지식 그래프의 노드+엣지 단면을 반환합니다.

노트 검색에 비해 위키가 갖는 차별적 가치는 **그래프**입니다. 단순히 텍스트를 읽는 데 그치지 않고, 엔티티에서 그것이 언급된 위치(`list_wiki_mentions`)로, 다시 연결된 개념(`get_wiki_graph`)으로 이동할 수 있습니다.

다섯 번째 보조 도구인 \*\*`list_workspaces`\*\*는 체인 자체의 일부는 아닙니다. 여러 워크스페이스를 가진 계정이 어떤 워크스페이스를 대상으로 할지(각 워크스페이스의 `guid`와 위키 활성화 여부) 찾을 수 있게 해 주며, 위의 네 도구에 명시적인 `workspaceGuid`를 전달할 수 있도록 합니다.

<Note>
  **읽기 전용 (v1).** 이 도구들은 위키를 읽기만 합니다. 위키 페이지의 생성, 이름 변경, 병합, 삭제는 v1에서 MCP로 노출되지 않습니다(OAuth 쓰기 동의 대기 중). 노트 콘텐츠에는 이 도구들을 사용하지 마세요. 대신 `search_notes` / `get_note`를 사용하세요.
</Note>

## 접근 권한과 요금제 게이트

위키는 **유료, 옵트인** 기능입니다. 네 도구는 항상 `tools/list`에 표시되지만(모든 연결에서 보입니다), 사용 자격은 **호출 시점에** 백엔드에서 검증됩니다. 따라서 사용 가능한 것처럼 보이는 도구라도 게이트 응답을 반환할 수 있습니다.

워크스페이스는 다음 **두 가지**가 모두 충족될 때만 위키를 사용할 수 있습니다.

1. **자격 있는 요금제**: 워크스페이스의 구독이 Pro, Max, Team, Enterprise 중 하나입니다. Free와 Lite는 자격이 없습니다.
2. **활성화됨**: 워크스페이스 관리자가 해당 워크스페이스에서 위키를 켰습니다.

호출이 게이트에 걸리면, 도구는 기계 판독 가능한 `error_code`와 함께 오류 엔벨로프(HTTP `402`)를 반환합니다.

| `error_code`         | 의미                                        | 호출자가 취할 조치                                                                                           |
| -------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `WIKI_PLAN_REQUIRED` | 요금제에 위키가 포함되어 있지 않음(Free/Lite/구독 없음/비활성). | 업그레이드. `action_url`은 요금제(B2C) 또는 팀 결제(팀 관리자) 페이지를 가리킵니다. 팀 구성원의 경우 `null`이며, 관리자에게 요청하라는 메시지가 표시됩니다. |
| `WIKI_NOT_ACTIVATED` | 요금제 자격은 있으나 관리자가 위키를 활성화하지 않음.            | 워크스페이스 설정에서 위키를 활성화하거나(관리자), 관리자에게 요청(구성원). 업셀 없음. `required_plans`는 `null`입니다.                      |

엔벨로프 형태(백엔드에서 그대로 전달됨):

```json theme={"system"}
{
  "success": false,
  "error_code": "WIKI_PLAN_REQUIRED",
  "message": "위키 기능은 Pro 이상 요금제에서 사용할 수 있어요. 웹에서 로그인 후 요금제를 업그레이드해 주세요.",
  "current_plan": "Lite",
  "required_plans": ["pro", "max", "team", "enterprise"],
  "action_url": "https://tiro.ooo/#pricing",
  "status_code": 402
}
```

* `current_plan`: 워크스페이스의 현재 요금제 표시 이름, 구독이 없을 경우 `null`.
* `required_plans`: `WIKI_PLAN_REQUIRED`의 업그레이드 대상. `WIKI_NOT_ACTIVATED`에서는 `null`. (Team Free Trial은 의도적으로 제외됩니다. 이미 보유 중인 체험이지 업그레이드 대상이 아니기 때문입니다.)
* `action_url`: 조치를 취할 웹 링크, 호출자가 직접 조치할 수 없을 때(팀 구성원이거나 관리자에 의한 활성화)는 `null`.

<Note>
  **워크스페이스 선택.** 기본적으로 위키 도구는 API 키로부터 워크스페이스를 암묵적으로 결정합니다. 워크스페이스 바인딩 키나 팀 키는 직접 결정되고, 개인 또는 OAuth 토큰은 **기본** 워크스페이스로 결정됩니다. 노트 도구의 범위 지정 방식과 동일합니다.

  계정이 **여러 워크스페이스**에 속해 있다면 [`list_workspaces`](#list_workspaces)를 호출해 목록을 나열하고(각각 `guid`와 위키 활성화 여부 포함), 선택한 `workspaceGuid`를 임의의 위키 도구에 전달하여 해당 워크스페이스를 명시적으로 대상으로 지정하세요. `workspaceGuid`를 생략하면 기본 워크스페이스 동작이 유지됩니다. 백엔드는 전달한 워크스페이스의 구성원인지 검증합니다.
</Note>

## `list_workspaces`

API 키가 접근할 수 있는 워크스페이스 목록을 각각의 `guid`, `name`, 위키 활성화 여부와 함께 반환합니다. 계정이 둘 이상의 워크스페이스에 속해 있을 때 위키 도구에 사용할 `workspaceGuid`를 고르는 데 사용하세요.

이 도구는 매개변수를 받지 않습니다. 다음을 반환합니다.

```json theme={"system"}
{
  "workspaces": [
    { "guid": "ws_abc", "name": "Acme", "isWikiEnabled": true },
    { "guid": "ws_def", "name": "Personal", "isWikiEnabled": false }
  ]
}
```

* 개인/OAuth 토큰은 구성원으로 속한 모든 워크스페이스를 나열하고, 워크스페이스 바인딩 키나 팀 키는 해당 워크스페이스 하나만 나열합니다.
* `isWikiEnabled`는 해당 워크스페이스에서 위키가 요금제 자격이 있고 **동시에** 활성화되어 있는지를 반영합니다. `true`인 워크스페이스를 골라 그 `guid`를 `workspaceGuid`로 전달하세요.

## `search_wiki`

키워드로 위키 페이지를 검색합니다. 가장 먼저 사용하세요. 반환된 `pageGuid`를 다른 도구에 전달합니다.

| 매개변수            | 타입     | 필수 여부  | 설명                                                              |
| --------------- | ------ | ------ | --------------------------------------------------------------- |
| `keyword`       | string | **필수** | 페이지 이름과 매칭되는 검색어.                                               |
| `workspaceGuid` | string | 선택     | 특정 워크스페이스를 대상으로 지정(`list_workspaces`에서 가져옴). 생략하면 기본 워크스페이스 사용. |

순위가 매겨진 페이지 결과를 반환하며, 각각 `pageGuid`, `name`, `pageType`(예: `CONCEPT`, `ENTITY`), 관련도 점수를 포함합니다.

## `get_wiki_page`

`pageGuid`(`search_wiki`에서 가져옴)로 위키 페이지 하나를 가져옵니다.

| 매개변수            | 타입     | 필수 여부  | 설명                                                              |
| --------------- | ------ | ------ | --------------------------------------------------------------- |
| `pageGuid`      | string | **필수** | `search_wiki`가 반환한 페이지 식별자.                                     |
| `workspaceGuid` | string | 선택     | 특정 워크스페이스를 대상으로 지정(`list_workspaces`에서 가져옴). 생략하면 기본 워크스페이스 사용. |

페이지 **본문**(설명 + 생성 상태)과 **메타데이터**(제목, 타입, mention/alias/link 수, 타임스탬프), 그리고 페이지의 구조화된 `mentions`, `aliases`, `links`를 반환합니다. 이어서 `list_wiki_mentions`로 페이지가 노트 전체에서 어디에 참조되는지 확인하세요.

## `list_wiki_mentions`

위키 페이지를 언급하는 노트 단락들을 나열합니다.

| 매개변수            | 타입     | 필수 여부  | 설명                                                              |
| --------------- | ------ | ------ | --------------------------------------------------------------- |
| `pageGuid`      | string | **필수** | 페이지 식별자(`search_wiki` / `get_wiki_page`에서 가져옴).                 |
| `cursor`        | string | 선택     | 이전 응답에서 받은 페이지네이션 커서.                                           |
| `workspaceGuid` | string | 선택     | 특정 워크스페이스를 대상으로 지정(`list_workspaces`에서 가져옴). 생략하면 기본 워크스페이스 사용. |

언급 레코드(소스 노트, 단락, 추출된 텍스트, kind)와 페이지네이션 커서를 반환합니다.

## `get_wiki_graph`

위키 지식 그래프의 노드+엣지 단면을 가져옵니다. `{ nodes, edges }`를 반환하며, 각 엣지는 두 페이지 사이의 타입이 지정된 관계를 담습니다.

| 매개변수                   | 타입        | 필수 여부  | 설명                                                                                         |
| ---------------------- | --------- | ------ | ------------------------------------------------------------------------------------------ |
| `mode`                 | string    | **필수** | `seed`, `expand`, `around`, `links` 중 하나(아래 참조).                                           |
| `pageGuid`             | string    | 조건부    | `expand` / `around`의 기준 페이지.                                                               |
| `pageGuids`            | string\[] | 조건부    | `links`를 위한 명시적 페이지 집합.                                                                    |
| `depth`                | number    | 선택     | `expand`의 탐색 깊이.                                                                           |
| `radius`               | number    | 선택     | `around`의 이웃 반경.                                                                           |
| `limit`                | number    | 선택     | 반환되는 최대 노드 수. 기본값 `50`, 최대 `200`.                                                          |
| `q` / `type` / `since` | —         | 선택     | `seed`를 위한 개요 필터.                                                                          |
| `folderId`             | number    | 선택     | `seed` 전용: 이 폴더(하위 폴더 포함, 재귀) 내 노트가 언급한 페이지로 그래프를 제한합니다. 비어 있거나 접근할 수 없는 폴더는 빈 그래프를 반환합니다. |
| `workspaceGuid`        | string    | 선택     | 특정 워크스페이스를 대상으로 지정(`list_workspaces`에서 가져옴). 생략하면 기본 워크스페이스 사용.                            |

| `mode`   | 반환                                                                 |
| -------- | ------------------------------------------------------------------ |
| `seed`   | 워크스페이스에 대한 개요 그래프(선택적으로 `q` / `type` / `since` / `folderId`로 필터링). |
| `expand` | `pageGuid`에서 `depth`만큼 바깥으로의 탐색.                                   |
| `around` | `radius`로 정한 페이지의 이웃.                                              |
| `links`  | 명시적인 `pageGuids` 집합 간의 링크들.                                        |

<Note>
  **결과 상한.** `get_wiki_graph`는 최대 `limit`개의 노드(기본값 `50`, 최대 `200`)와 그 반환된 노드들 **사이의** 엣지만 반환합니다(연결되지 않은 엣지는 제거되므로 모든 엣지의 양 끝점이 `nodes`에 존재합니다). 기반 그래프가 상한보다 컸던 경우, 응답에 `truncated: true`가 설정됩니다. `mode` / `q` / `type` 또는 더 작은 `radius` / `depth`로 좁혀 집중된 단면을 얻으세요. 이를 통해 허브 페이지의 이웃이 무한정 큰 페이로드를 반환하는 것을 방지합니다.
</Note>

<Note>
  **클러스터 기반 탐색은 아직 노출되지 않았습니다.** 웹 앱의 최신 그래프 탐색 뷰(overview/context/cluster)는 내부 전용입니다. MCP `get_wiki_graph` 도구는 `seed` / `expand` / `around` / `links` 모드를 노출합니다. 클러스터 탐색의 외부 노출은 로드맵에 있습니다.
</Note>

## 권장 체인

* **워크스페이스 먼저 선택(여러 워크스페이스):** `list_workspaces` → 선택한 `workspaceGuid`를 아래의 임의 도구에 전달.
* **위키가 어떤 주제에 대해 아는 내용 찾기:** `search_wiki` → `get_wiki_page`.
* **페이지가 노트에서 어디에 근거하는지 찾기:** `search_wiki` → `list_wiki_mentions`.
* **개념들이 어떻게 연결되는지 탐색하기:** `search_wiki` → `get_wiki_graph`(`mode: "around"`, `pageGuid`).