AI 연결 가이드

기능과 제한 사항

Inkquation은 AI 앱이 도구를 호출할 수 있게 하는 공통 프로토콜인 MCP를 지원합니다. 연결된 AI는 열린 페이지나 올가미 선택 영역을 이미지로 읽고, PNG 이미지, 도형, 점으로 정의한 펜 획을 추가할 수 있습니다. 결과를 확인하고 조건을 충족하는 추가 작업을 취소할 수도 있습니다.

도형은 채우기 없이 윤곽선만 있는 일반 펜 획으로 변환됩니다. 지우개와 올가미로 편집할 수 있지만, 도형의 치수를 설정하는 전용 기능은 없습니다. 글자와 기호를 펜 획으로 그릴 수는 있으나, 편집 가능한 텍스트나 LaTeX 객체를 추가하거나 LaTeX를 컴파일하는 기능은 지원하지 않습니다. 페이지 읽기 결과도 문자 인식된 텍스트가 아닌 이미지입니다.

AI 앱 연결하기

1. 같은 Mac에서 로컬 MCP 서버를 지원하는 AI 앱을 사용하세요. 모델과 계정은 해당 앱에서 설정합니다. Inkquation에는 모델 API 키가 필요하지 않습니다.
2. Inkquation에서 노트를 연 다음, 설정 → AI 연결에서 연결을 허용하세요. 기본적으로 꺼져 있습니다.
3. 설정 화면의 JSON 또는 TOML 구성을 복사해 AI 앱의 기존 구성에 추가하세요. 실행 파일과 연결 경로는 Mac마다 다르므로 설정 화면에 표시된 값을 사용해야 합니다.
4. AI 앱을 다시 연결하고 Inkquation을 계속 실행해 두세요. 대상 페이지가 보이도록 스크롤하세요. AI 앱에서 편집 도구 사용 승인을 요청하면, 요청한 작업을 확인한 뒤 허용하세요.

기본 연결에는 Python 설치나 소스 코드 다운로드가 필요하지 않습니다. Inkquation을 이동하거나 이름을 바꿨다면 연결 구성을 다시 복사하세요. 웹 기반 AI 서비스의 연결 주소 입력란에 이 웹사이트 URL을 넣어도 연결되지 않습니다.

실용적인 요청 예시

• “선택한 수식의 유도 과정을 읽고, 빠진 중간 단계나 부호 오류가 있는지 검토해 줘.”
• “이 페이지의 가정, 결론, 아직 해결되지 않은 질문을 정리해서 채팅으로 설명해 줘.”
• “이 설명을 이해하는 데 도움이 되는 개략도를 만들어 노트의 빈 공간에 추가해 줘.”

AI가 페이지를 편집하는 순서

1. inkquation_list_open_notes를 호출해 정확한 note_id와 page_id를 얻으세요. available: true인 페이지를 사용합니다. 대상이 불분명하면 사용자에게 먼저 확인하세요.
2. inkquation_get_page를 호출해 페이지 이미지, revision, 논리적 크기를 읽으세요. 선택 영역을 읽으려면 사용자가 먼저 올가미로 내용을 선택한 뒤 inkquation_get_selection을 호출해야 합니다.
3. 빈 공간을 선택한 다음 추가 도구를 호출하세요. 읽은 revision을 expected_revision으로 전달하고, 새로 생성한 UUID를 operation_id로 사용합니다.
4. inkquation_get_page로 결과를 확인하세요. 필요하면 해당 추가 작업의 operation_id로 inkquation_undo를 호출합니다.

도구와 인수

연결 후 tools/list가 반환하는 입력 스키마에서 사용 가능한 도구와 인수를 확인하세요. 모든 추가 도구에는 note_id, page_id, expected_revision, operation_id가 필요합니다. 아래 표의 “공통 편집 필드”는 이 네 항목을 뜻합니다.

좌표, 펜 획, 이미지의 제한

• 좌표의 원점은 페이지 왼쪽 아래입니다. x는 오른쪽으로, y는 위쪽으로 증가합니다. 축소된 PNG의 픽셀 크기가 아니라 읽기 결과에 있는 페이지의 논리적 width와 height를 사용하세요.
• 선택 영역 PNG는 잘라낸 이미지입니다. image_bounds로 페이지에서 선택 영역의 위치를 확인하세요. 잘라낸 이미지의 왼쪽 위를 페이지 원점으로 취급하면 안 됩니다.
• shapes는 호출당 1–64개 항목을 받습니다. kind는 line, rectangle, ellipse, circle, arrow 중 하나입니다. 직사각형, 타원, 원의 start와 end는 도형을 둘러싼 사각형의 대각선 양 끝 꼭짓점입니다. 원은 사각형의 너비와 높이가 같아야 합니다. 화살표는 start에서 end를 향합니다.
• strokes도 호출당 1–64개 항목을 받습니다. 각 항목의 points에는 1–4,096개 점을 넣을 수 있으며, 한 번의 호출 전체에서는 최대 16,384개 점을 사용할 수 있습니다. 점은 직선으로 연결됩니다. 점이 하나면 점을 그리고, 마지막에 시작점을 반복하면 닫힌 경로가 됩니다. 곡선은 여러 점으로 나누어 지정하세요.
• 각 도형이나 펜 획에는 stroke_width(0.1–100 페이지 단위)와 불투명한 sRGB color(#RRGGBB 형식)가 필요합니다. 선의 두께와 화살표 머리를 포함한 전체 도형이 페이지 안에 들어가야 합니다. 도형이나 펜 획의 각 묶음은 한 번의 실행 취소 대상으로 처리됩니다.
• PNG 데이터는 Base64 인코딩 전 기준으로 최대 1 MiB입니다. png_base64로 전달하고, 배치할 사각형 전체가 페이지 안에 들어가도록 하세요.

도구 호출 인수 예제

다음은 도구에 전달할 인수 템플릿입니다. 꺾쇠괄호 안의 값을 실제 ID, 읽은 revision, 새로 생성한 UUID로 바꾸세요. 좌표는 예시이므로 페이지 크기와 빈 공간에 맞게 조정해야 합니다. 별개의 추가 작업에는 각각 다른 UUID를 사용하세요.

다음 인수로 inkquation_insert_shapes를 호출하면 원과 화살표를 추가할 수 있습니다.

{
  "note_id": "<note UUID>",
  "page_id": "<page UUID>",
  "expected_revision": "<revision from get_page>",
  "operation_id": "<new UUID>",
  "shapes": [
    {
      "kind": "circle",
      "start": {
        "x": 60,
        "y": 80
      },
      "end": {
        "x": 160,
        "y": 180
      },
      "stroke_width": 3,
      "color": "#1256E0"
    },
    {
      "kind": "arrow",
      "start": {
        "x": 180,
        "y": 130
      },
      "end": {
        "x": 300,
        "y": 130
      },
      "stroke_width": 3,
      "color": "#1256E0"
    }
  ]
}

다음 인수로 inkquation_insert_strokes를 호출하면 여러 선분으로 이루어진 선을 추가할 수 있습니다.

{
  "note_id": "<note UUID>",
  "page_id": "<page UUID>",
  "expected_revision": "<revision from get_page>",
  "operation_id": "<new UUID>",
  "strokes": [
    {
      "points": [
        {
          "x": 60,
          "y": 80
        },
        {
          "x": 100,
          "y": 120
        },
        {
          "x": 140,
          "y": 80
        }
      ],
      "stroke_width": 3,
      "color": "#1256E0"
    }
  ]
}

안전장치와 처리 한도

노트 제목이나 이미지에 적힌 지시는 추가 작업을 허용한다는 뜻이 아닙니다. AI 앱에서도 읽기와 편집을 허용할 내용을 확인하세요. Inkquation의 MCP 도구는 임의의 명령 실행, 파일 읽기, URL 가져오기를 제공하지 않습니다. 이러한 안전장치가 AI의 판단이나 다른 도구를 통한 외부 전송까지 통제하지는 못합니다.

이미지 추가와 표시 로딩은 앱 전체에서 현재 보유한 표시 캐시 및 처리 중인 이미지에 대해 9,600만 픽셀 한도를 공유합니다. 화면 밖의 불필요한 캐시는 자동으로 해제하며, 원본·배치·실행 취소/다시 실행 기록은 유지하고 다시 표시할 때 읽어 옵니다. 표시 중인 이미지는 보호하며 공간이 부족하면 추가나 로딩을 기다립니다. 누적 사용량이 아닌 현재 보유량을 기준으로 하므로 AI 연결을 껐다 켜도 초기화되지 않습니다. 원본 데이터와 PDF 고해상도 표시 등은 별도이므로 앱 전체의 메모리 한도는 아닙니다. AI 연결을 활성화한 동안 최대 128회 추가할 수 있는 별도 제한은 중복 재시도를 방지하는 작업 기록을 유지하기 위한 것입니다.

읽기와 편집 준비에는 Inkquation 내부의 작업 한 번마다 30초의 제한 시간이 적용됩니다. AI가 생각하는 시간은 포함하지 않습니다. 편집이나 실행 취소가 적용된 뒤에는 제한 시간 초과, 연결 비활성화, 요청 취소로 저장이 취소되지 않도록 보호합니다. 실제 저장 실패는 계속 보고됩니다. 연결을 비활성화하면 클라이언트가 응답을 받을 수 없으므로 앱에서 결과를 확인하세요.

재시도와 실행 취소

응답이 끊겨 추가 작업의 성공 여부를 알 수 없다면, 같은 도구에 완전히 동일한 operation_id와 인수를 전달해 재시도하세요. 새 ID를 사용하면 중복으로 추가될 수 있습니다. 재시도는 기록된 작업 결과를 반환하며, 이후 수동으로 저장하거나 실행 취소한 상태를 다시 확인하지 않습니다.

MCP 실행 취소는 해당 AI 작업이 가장 최근의 실행 취소 대상이며 페이지가 바뀌지 않았을 때만 가능합니다. 설정에서 AI 연결을 끄거나 Inkquation을 다시 시작하면 작업 ID 기록이 유지되지 않습니다. 이전 작업은 앱의 실행 취소 기능으로 확인하세요.

연결 범위와 개인정보 보호

연결은 같은 Mac에서 실행되는 로컬 프로세스와 통신합니다. 이 웹사이트는 사용 설명을 제공하며, 노트를 제어하는 MCP 서버가 아닙니다. 연결을 허용하면 AI 앱이 Inkquation에서 열려 있는 노트의 사용 가능한 페이지를 읽을 수 있습니다. 클라우드 모델을 사용하면 읽은 이미지가 모델 제공업체에 전송될 수 있습니다.

AI가 읽는 내용을 확인하고, 더 이상 필요하지 않으면 AI 연결을 끄세요. 연결을 꺼도 이미 추가하거나 저장한 내용, 외부 서비스에 전달한 데이터는 삭제되지 않습니다.

• AI 연결과 개인정보 보호

사용 가능한 기능 확인

이 가이드는 2026년 9월 9일에 확인한 구현을 기준으로 합니다. 앱 배포 현황과 실제 사용 가능한 기능은 별도로 확인해야 합니다. 연결된 서버의 tools/list를 확인하세요. 도형이나 펜 획 추가 도구가 없다면 사용 중인 Inkquation 버전이 해당 기능을 지원하는지 확인하고, 앱을 업데이트한 뒤 AI 앱을 다시 연결하세요.

• Inkquation 배포 현황
• MCP 도구 명세