MCP 서버(AI 에이전트)

LightNote에는 작업 공간을 AI 에이전트용 도구(Claude Desktop, Claude Code, Cursor 등 MCP를 지원하는 모든 클라이언트)로 바꾸는 헤드리스 MCP(Model Context Protocol) 서버가 포함되어 있습니다. 에이전트는 파일을 읽고 쓰고, 검색하고, 표 형식 데이터와 데이터베이스를 조회하고, 작업을 다루고, Git을 사용하고, HTTP 요청을 보낼 수 있습니다 — 모두 해당 폴더로 제한됩니다(디렉터리 감옥: ..가 포함되거나 루트 밖의 경로는 거부됨). 전송 방식은 stdin/stdout을 통한 JSON-RPC 2.0이며, 세션마다 편집기 창과 별개로 가벼운 lnote.exe 프로세스가 실행됩니다.

원클릭 바로가기: AI → 이 폴더에서 AI 사용을 선택하면 LightNote가 MCP를 켜고 .mcp.json을 한 번에 씁니다(클릭이 곧 동의입니다). 폴더에서 AI가 이미 활성화되어 있으면 이 항목은 이 폴더의 AI 설정…으로 바뀌고 작업 공간 설정을 엽니다.

이중 안전 장치: (1) 해당 폴더에 대해 사전 동의한 경우에만 서버가 시작됩니다; (2) 모든 도구는 작업 공간 루트로 제한됩니다. 추가로 각 도구는 주석(읽기 전용, 파괴적, 멱등, "외부 세계에 영향")과 함께 안내되어 AI 클라이언트가 호출 전에 위험을 판단할 수 있습니다.

단계별 설정

1. 폴더에 MCP 활성화. 도구 → 작업 공간 → 작업 공간 설정...에서 이 작업 공간에 MCP 활성화를 체크하세요. 이 사전 동의 없이는 서버가 시작을 거부합니다(주요 관문입니다). 또는 명령줄에서: lnote --mcp-enable "C:\Path\to\workspace" (끄려면 --mcp-disable).
2. lnote.exe의 경로 찾기. lightnote.exe와 같은 폴더(앱 설치 폴더)에 있습니다. UI가 없는 "슬림" 콘솔 실행 파일로, 에이전트가 실행하는 대상입니다.
3. AI 클라이언트에 서버 등록 — 명령을 lnote.exe로 지정하고 --mcp와 작업 공간 폴더를 인자로 전달합니다. Claude Desktop / Cursor 등에서 사용하는 형식으로는:

{
  "mcpServers": {
    "lightnote": {
      "command": "C:\\Path\\to\\lnote.exe",
      "args": ["--mcp", "C:\\Path\\to\\workspace"]
    }
  }
}

설정 팁:

• 예제처럼 JSON의 백슬래시는 두 번 써야 합니다 (C:\\Users\\...\\lnote.exe).
• 여러 작업 공간을 노출하려면 폴더마다 항목을 하나씩 추가하되, 각각 고유한 이름("lightnote-projectA", "lightnote-projectB")을 사용해 자신의 루트를 가리키게 하세요.
• 설정을 저장한 뒤 AI 클라이언트를 재시작해 서버를 시작하게 하세요. 연결되면 에이전트가 lightnote_* 도구를 나열할 수 있어야 합니다. "작업 공간 파일을 나열해줘"라고 물어보아 동작을 확인하세요.
• Claude Code(CLI)의 경우 같은 서버를 claude mcp add lightnote -- "C:\Path\to\lnote.exe" --mcp "C:\Path\to\workspace"로 등록할 수 있습니다.

데이터베이스 비밀번호(선택 사항). db_query 도구는 .lnc 연결을 엽니다. 비밀번호가 암호 문구로 암호화되어 있다면 서버 블록에서 LNOTE_PASSPHRASE 환경 변수로 구문을 전달하세요(명령줄 인자로는 절대 전달하지 마세요) — 비밀번호가 "묻기" 모드인 연결은 자동으로 사용할 수 없습니다.

LightNote가 열려 있으면 데이터베이스는 창을 거칩니다. 앱의 터미널에서 실행되는 AI CLI(예: Claude Code)는 이미 열어 둔 세션으로 쿼리합니다. Oracle을 포함한 모든 데이터베이스에서, 이미 입력한 비밀번호와 연결된 SSH 터널을 그대로 씁니다. 연결이 닫혀 있으면 창에서 비밀번호를 묻고(거기서 거절하면 AI도 거절됩니다), AI 도구가 쿼리하면 상태 표시줄에 알려 줍니다. 큰 데이터베이스에서 쿼리를 쓸 때 AI는 db_search_objects로 이름으로 테이블을 찾고(모든 스키마 대상), db_list_objects로 설명과 예상 행 수가 붙은 목록을 읽고, db_describe로 JOIN을 알려 주는 외래 키와 함께 여러 테이블을 한 번에 설명합니다. 앱이 닫혀 있으면 위의 내용이 적용됩니다.

AI 쿼리는 연결별 옵트인입니다. 폴더에서 MCP를 켜도 연결이 노출되지 않습니다. 각 .lnc는 연결 대화상자에서 “AI 쿼리 허용 (MCP)”이 켜져 있을 때만 db_query에 응답합니다. 접근은 읽기 전용(SELECT)입니다. 이 허용은 이 컴퓨터의 폴더 설정에 저장됩니다. .lnc 파일에 기록되지 않고 Git으로 전달되지도 않으므로 AI가 파일을 편집해 켤 수 없습니다. 연결의 서버, 데이터베이스, 사용자 또는 터널을 바꾸면 옵션을 다시 선택할 때까지 허용이 중지됩니다. 파일 데이터베이스(SQLite, DuckDB)는 작업 공간 안에 있어야 하며, AI는 DuckDB를 통해 작업 공간 안의 파일만 읽으며, LightNote가 열려 있는 동안에는 어떤 파일도 읽지 않습니다.

에이전트를 통한 데이터베이스 내보내기. 조회뿐만 아니라 db_export로 SELECT를 파일로 구체화할 수 있습니다(Parquet, CSV, JSON 또는 .xlsx) — 응답에 담기에 너무 큰 결과에 유용합니다. 동일한 세 가지 안전장치가 이 순서로 적용됩니다: 쿼리는 읽기 전용이어야 하고, 연결에는 「AI 조회 허용(MCP)」 옵션이 필요하며(비밀번호를 복호화하기 전에 확인), 대상 경로는 작업 공간 안에 있어야 합니다. 대용량 내보내기는 시스템 임시 폴더를 작업 공간으로 사용하며 대략 결과물 크기만큼 차지합니다 — 디스크 공간을 확보하세요.

사용 가능한 도구

에이전트는 클라이언트의 접두사가 붙은 도구를 보게 됩니다(예: lightnote_read_file). 범주별로:

• 파일: read_file(줄 범위 지정 가능), write_file, edit_file(파일 전체를 다시 쓰지 않고 정확한 조각을 대체), append_file, list_files, move_file, make_dir, delete_file(완전 삭제가 아닌 휴지통으로 이동).
• 검색과 탐색: search_files(ripgrep, 하위 폴더/glob 필터와 개수 제한 포함), list_symbols(파일의 함수/클래스 개요), open_in_editor(LightNote 창이 열려 있으면 파일을 열거나 포커스).
• 데이터와 SQL: query(Parquet/CSV/JSON에 대한 DuckDB SQL, tsv/json/markdown 출력), describe_table (행을 덤프하지 않고 스키마+통계), export_query (COPY를 통해 SELECT를 파일로 구체화), sqlite_query (.sqlite/.db에 대한 SQL), db_list_connections (작업 공간의 .lnc 파일 나열), db_query (.lnc 연결에 대한 읽기 전용 SQL). 결과를 응답 대신 파일로 내보내려면 db_export(Parquet/CSV/JSON/.xlsx).
• 또한: search_notes(질문에 가장 관련성 높은 노트 조각을 검색 — AI 채팅과 같은 엔진), list_links(노트의 나가는 링크를, 해결됨/깨짐으로 표시), audit_vault_links(보관소 전체의 깨진 링크와 고아 노트), list_note_templates 와 create_note 의 template 매개변수, list_due_tasks(모든 프로젝트에서 오늘 마감이거나 기한이 지난 작업), xlsx_read(.xlsx 시트를 TSV로 읽기), data_diff(두 표 형식 파일 비교), 그리고 데이터베이스 카탈로그 db_list_objects/db_describe(테이블/뷰와 테이블의 열·키·DDL — db_query와 동일한 조건). 그리고 note_export(노트를 docx, odt, epub, LaTeX, Typst, HTML, reStructuredText, AsciiDoc, Org, MediaWiki, Notebook 또는 다른 Markdown 방언으로 내보내기 — 창 없이, lnote note-export로도). 그리고 note_import(반대 방향: docx, odt, epub, rtf, HTML 또는 tex 파일을 제목, 목록, 표, 강조, 링크, 수식, 이미지와 함께 원본 옆의 노트로 가져오기 — lnote note-import로도). 그리고 folder_export(폴더 전체가 HTML 사이트, 문서 모음 또는 Markdown 이 되고 링크도 다시 쓰입니다 —— lnote folder-export 로도).
• 아카이브: zip_list(.zip/ .isx의 구성원 나열)와 zip_read(구성원을 텍스트로 읽기) — 디스크에 아카이브를 추출하지 않고 수행합니다.
• 작업: list_task_projects(작업 공간의 .lnt 작업 프로젝트 나열), list_tasks, list_task_statuses(보드 열), create_task, update_task(제목, 작업량, 열, 우선순위, 날짜, %, 태그, 체크리스트, 보관), update_task_status(열 간 이동), delete_task, task_note(작업의 .md 노트 읽기/쓰기). 작업 공간에는 여러 .lnt 프로젝트가 있을 수 있습니다: project 매개변수(list_task_projects가 반환하는 name; 프로젝트가 하나뿐이면 생략 가능)로 선택하세요. id/ status_id는 세션 식별자입니다 — 이를 얻으려고 내부 .lnt 파일을 읽지 말고 작업 도구를 사용하세요.
• 노트(PKM): create_note(.md 노트 생성), append_daily_note(오늘의 노트에 캡처 추가), remember (당신에 대한 지속적인 사실을 기억 노트에 저장), list_backlinks(노트를 가리키는 노트들), list_note_tags와 search_by_tag(저장소의 #해시태그와 이를 사용하는 노트들), add_task(제목에 자연어를 받아 마감일/태그가 있는 작업 생성).
• Git: git_status, git_log, git_diff, git_restore.
• 웹과 알림: http_request(HTTP 요청을 보내고 상태/헤더/본문 반환), notify(열린 창에 트레이 알림 표시 — 에이전트가 작업 완료를 알리는 데 유용).
• AI 프록시: list_ai_models와 ask_ai (아래 참고).
• LightNote 자체: help_lookup(이 도움말을 섹션이나 용어로, 요청한 언어로 읽음)과 markdown_reference(앱이 그리는 Markdown의 정확한 문법). 연결하면 클라이언트는 도구를 범주별로 정리한 서버 설명도 받으며, 도움말과 Markdown 참고 자료는 리소스로도 나타납니다(lightnote://help/…와 lightnote://markdown/…).

서버는 또한 작업 공간 파일을 MCP 리소스(resources/list와 resources/read)로도 노출합니다. read_file을 호출하는 대신 파일을 "첨부"하는 방식을 선호하는 클라이언트를 위한 기능입니다.

당신의 프롬프트 라이브러리(작업 공간의 Prompts/ 폴더)는 MCP 프롬프트로 공개됩니다(prompts/list 와 prompts/get). Claude Code에서는 각 프롬프트가 슬래시 명령 /mcp__lightnote__<이름>이 되어 AI CLI 안에서 바로 사용할 수 있습니다.

쓰기 안전망. 파일을 덮어쓰거나(write_file/edit_file) 삭제하기(delete_file) 전에, 서버는 이전 버전을 로컬 기록(에디터와 동일한 안전망)에 저장합니다. 따라서 Git 저장소 밖에서도 에이전트가 한 변경을 되돌릴 수 있습니다.

각 도구는 읽기인지 쓰기인지 명시합니다: MCP 주석 (readOnlyHint/destructiveHint) 외에도 설명이 [read-only], [writes], [destructive] 뱃지로 시작합니다 — 허용 목록을 안전하게 구성하는 데 유용합니다.

AI 프록시(다른 모델에 위임)

MCP 열이 체크된 상태로 등록한 API 제공자는 list_ai_models(허용된 모델을 id, 이름, model과 함께 나열)와 ask_ai({model, prompt}) 두 도구를 통해 에이전트에 노출됩니다. 이를 통해 메인 에이전트가 더 저렴하거나 특화된 모델에 하위 작업을 위임할 수 있습니다. 호출은 실행 중인 LightNote가 중개합니다(MCP의 lnote.exe가 내부 브리지를 통해 요청을 앱 창으로 전달): API 키는 절대 이 기기를 벗어나지 않으며 에이전트에도 전달되지 않습니다. LightNote가 열려 있지 않으면 도구는 열어달라고 요청하는 오류를 반환합니다.