7. AI 통합 (MCP)

AI 통합 (MCP)

PinSlip에는 MCP 서버(Model Context Protocol, MCP 표준 프로토콜)가 내장되어 있습니다.
AI 어시스턴트(Claude Code / Kimi Work / MCP 호환 클라이언트 모두)가 사용자의 메모를 검색, 읽기, 쓰기, 삭제할 수 있습니다.
기본으로 켜져 있으며 127.0.0.1의 고정 포트에서 수신 대기합니다.

7.1 MCP란 무엇인가

MCP(Model Context Protocol)는 Anthropic이 제정한 오픈 프로토콜로, AI 어시스턴트가 로컬 도구를 호출할 수 있도록 합니다. PinSlip의 MCP 서버는 12개의 도구를 노출하며, 「읽기 + 쓰기 + 동기화」 세 가지 시나리오를 모두 다룹니다.

수명 주기

• PinSlip 애플리케이션과 함께 시작되고 종료됨 — 애플리케이션이 실행되지 않으면 MCP를 사용할 수 없음

• 127.0.0.1의 고정 포트에서 수신 대기 (로컬 전용 통신, 외부에서 접근 불가)

• 프로토콜: Streamable HTTP (MCP 표준)

총 스위치

• 설정 → MCP 서비스

• 기본 켜짐

• 끄면 서비스 측 /mcp 엔드포인트가 404를 반환

7.2 연동 디스커버리

PinSlip이 시작될 때 디스커버리 정보를 <vault>/.pinslip/mcp.json에 기록합니다.

{
  "port": 17639,
  "pid": 12345,
  "version": "1.0.1",
  "mcpPath": "/mcp",
  "startedAt": "2026-07-31T14:00:00+08:00"
}

• 클라이언트는 어떻게 연결할까요? 이 파일을 직접 읽으면 됩니다 (Plug-and-Play 방식의 AI 어시스턴트는 반드시 읽을 수 있어야 함).

• pid가 죽은 경우 → 「PinSlip 애플리케이션을 시작하세요」라는 안내 표시

• 설정 서랍에는 「연동 정보 한 번에 복사」 버튼이 있어, mcpServers JSON을 클립보드로 복사할 수 있습니다.

7.3 클라이언트 설정 예시

Claude Code

{
  "mcpServers": {
    "pinslip": {
      "url": "http://127.0.0.1:17639/mcp",
      "type": "http"
    }
  }
}

<port>를 mcp.json의 실제 값으로 바꾸면 됩니다.

연동 정보 복사

설정 → MCP 서비스 → 「연동 정보 복사」 → 클라이언트 설정에 바로 붙여 넣습니다.

7.4 12개의 도구

데이터 측면 (10개)

동기화 측면 (2개)

시간 필터

search_notes / list_notes에서 다음을 지원합니다.

• since / until은 폐구간

• YYYY-MM-DD (로컬 시간대) 또는 완전한 RFC3339 형식 허용

• timeField = updated (기본) / created

7.5 AI가 할 수 있는 것 / 할 수 없는 것

✅ AI가 할 수 있는 것

• 모든 메모 검색 (전문 + 태그 + 폴더 + 시간)

• 모든 메모의 전체 내용 읽기

• 새 메모 만들기 (지정 폴더, 지정 태그로 저장)

• 메모 수정 (전체 교체 / 인라인 교체 / 덧붙이기)

• 메모 삭제 (여전히 휴지통을 거침, 휴지통을 절대 우회하지 않음)

• 동기화 트리거, 동기화 상태 조회

❌ AI가 할 수 없는 것

• UI 상태: 항상 위 고정, 색상, 접기, 그룹 관계

• 동기화 설정: 리포지토리 주소, token, 브랜치

• 물리적 삭제: 휴지통을 우회한 직접 삭제

• vault 외부의 파일 수정 (vault 디렉터리만 스캔)

7.6 전형적인 사용 시나리오

AI에게 일일 보고서 작성 시키기

사용자: 오늘 무엇을 했는지 알려줘. 일일 보고서를 써 줘.
​
AI 사고 과정:
1. list_notes(since: 2026-07-31)
2. 후보 메모를 read_note
3. 요약 작성
4. create_note(folder="일일 보고서", title="일일 보고서 2026-07-31", content=요약)

AI에게 inbox 정리 시키기

사용자: inbox의 오늘 메모를 주제별로 해당 폴더에 분류해 줘.
​
AI 사고 과정:
1. list_notes(folder="inbox")
2. 각 메모 read_note
3. 분류, 대상 폴더 판단
4. update_note(folder=대상)

AI에게 잊었던 아이디어 찾기

사용자: 예전에 「백엔드 성능 최적화」에 관한 메모를 적어 둔 적이 있는데, 찾아 줘.
​
AI 사고 과정:
1. search_notes("백엔드 성능 최적화")
2. read_note 매칭 항목

AI에게 작업 목록 점검 시키기

사용자: 오늘 완료하지 못한 작업은 무엇인가요?
​
AI 사고 과정:
1. search_notes "- [ ]" 또는 모든 메모를 읽고 grep
2. 미완료 항목 나열

AI에게 태그 일괄 변경 시키기

사용자: #work 태그가 붙은 모든 메모에 #2026Q3 태그를 추가해 줘.
​
AI 사고 과정:
1. list_notes(tag="work")
2. 메모별로 update_note / patch_note로 태그 추가

7.7 보안 주의 사항

• MCP는 127.0.0.1에서만 수신 대기: 외부 네트워크에서는 접근할 수 없으며, 로컬 에이전트 클라이언트만 사용할 수 있음

• token 인증 없음: 루프백에 바인딩되는 것 자체가 인증이 되기 때문 (OS 수준에서 보장)

• 애플리케이션 종료 → 서비스 종료: 장기간 노출되는 상황은 발생하지 않음

• 삭제는 휴지통을 거침: 실수로 삭제해도 복구 가능

• 권장 사항: 공용 컴퓨터 / 공유 계정에서는 MCP 스위치를 끄세요

7.8 문제 해결