# Jelly Memo Local MCP Server

Jelly Memo의 **사용자 Windows 기기 전용 AI 협업 서버**와 installer를 공개하는 저장소입니다. 한국어 안내가 먼저 나오며 [English documentation](#english)은 아래에 있습니다.

## 한국어

### 무엇을 제공하나요?

- 오픈소스 Python MCP 로컬 서버
- 서버 실행·자동 테스트 스크립트
- PyInstaller 실행 파일 build 정의
- Inno Setup Windows installer build 정의
- 바로 설치할 수 있는 Windows installer Release

이 저장소에는 Jelly Memo Flutter 앱 본체 source, Firebase 설정, 사용자 메모, 인증정보가 포함되지 않습니다.

### 메모를 직접 제어합니다

이 도구는 AI의 변경 제안을 보관하거나 사용자의 승인을 기다리는 프로그램이 아닙니다. MCP를 지원하는 AI 도구가 Jelly Memo의 메모를 검색하고 다음 작업을 직접 수행할 수 있게 합니다.

- 새 메모 생성
- 전체 메모 상태 조회
- 제목, 아이콘, 본문, 고정, 보관, 줄노트, 색상 수정
- 인라인 참조, 텍스트 서식, 링크 배지, 미션 배지 수정
- Canvas, 지도 위치, 노드 보기 위치 수정
- 본문 이미지와 상·하단 배너의 추가, 배치·크기·crop 수정, 다운로드, 삭제
- 메모를 휴지통으로 이동하고 다시 복원
- 동기화된 버전 이력 조회와 특정 버전 복원
- 휴지통 메모 영구 삭제와 휴지통 비우기
- 일정 날짜 태그 추가와 레거시 태그 이관

즉 UI 버튼을 원격 클릭하는 방식이 아니라, 사용자가 앱에서 만들 수 있는 **모든 메모 저장 결과**를 MCP tool로 만들 수 있게 하는 것이 이 서버의 기준입니다. 영구 삭제와 휴지통 비우기에는 실수 방지를 위해 `confirm=true`가 필요합니다.

쓰기 tool 호출은 단순 접수만으로 성공하지 않습니다. 로컬 서버가 실행 중인 Jelly Memo Web 또는 Windows 앱에 명령을 전달하고, 앱의 기존 저장·암호화·동기화 경로가 끝난 뒤에만 성공을 반환합니다. 앱이 실행 중이지 않으면 `app_unavailable` 오류를 반환합니다.

### 로컬 전용·개인정보 보호

- 서버는 사용자 컴퓨터의 `127.0.0.1:8765`에서만 실행됩니다.
- `0.0.0.0` 또는 외부 네트워크 주소로의 bind를 거부합니다.
- 서버는 Firebase, Firestore, Firebase Storage에 직접 연결하지 않습니다.
- 서버는 Flutter 앱의 로컬 저장소를 직접 읽거나 쓰지 않습니다.
- 실제 메모 변경은 Jelly Memo 앱의 `MemoSystem`이 수행합니다.
- 검색 snapshot과 처리 중 command는 로컬 서버 메모리에만 보관되며 서버 종료 시 사라집니다.
- 선택적으로 pairing token을 설정해 snapshot·command endpoint를 보호할 수 있습니다.
- `idempotency_key`를 재사용하면 동일 작업의 중복 실행을 방지합니다.
- 명령 protocol version을 확인하므로 구버전 앱이 새 명령을 가져가지 않으며, Web 새로고침으로 취소된 long-poll도 이후 명령을 가로채지 않습니다.

### 가장 쉬운 설치 방법

1. [최신 Windows installer](https://github.com/egm7126/simpleMemo-releases/releases/latest/download/JellyMemoMcpInstaller-windows-x64.exe)를 다운로드합니다.
2. installer를 실행합니다.
3. Jelly Memo Web을 처음 연결할 때 브라우저의 **로컬 네트워크 접근** 요청을 허용합니다.
4. Jelly Memo Web 또는 Windows 설정의 **AI 협업 도구**에서 연결 상태를 확인합니다.

Jelly Memo의 설치 버튼도 위 고정 주소를 사용합니다. 최신 Release에는 앱을 다시 배포하지 않아도 같은 버튼으로 새 버전을 받을 수 있도록 `JellyMemoMcpInstaller-windows-x64.exe` asset을 유지합니다. 서버는 공식 Jelly Memo Web origin만 허용하며 임의의 외부 웹사이트에는 CORS 접근을 허용하지 않습니다.

현재 installer는 Authenticode 코드 서명이 적용되지 않아 Windows SmartScreen 경고가 나타날 수 있습니다. 다운로드 파일이 이 저장소의 공식 Release에서 왔는지 확인한 뒤 설치하세요.

### 소스에서 실행하기

요구 사항: Windows, Python 3.10 이상

```powershell
git clone https://github.com/egm7126/simpleMemo-releases.git
cd simpleMemo-releases
py -3.10 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\scripts\run_companion.ps1 -PythonPath ".\.venv\Scripts\python.exe"
```

MCP endpoint는 `http://127.0.0.1:8765/mcp`입니다.

### 테스트와 Windows installer build

```powershell
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
.\.venv\Scripts\python.exe -m compileall jellymemo_mcp_companion tests
.\.venv\Scripts\python.exe -m pip install -e ".[build]"
.\packaging\build_server.ps1 -PythonPath ".\.venv\Scripts\python.exe"
.\packaging\build_installer.ps1
```

installer build에는 [Inno Setup 6](https://jrsoftware.org/isinfo.php)가 필요합니다. 산출물은 `build/mcp_companion/` 아래에 생성됩니다.

### 오픈소스와 기여

이 로컬 MCP 서버는 [MIT License](LICENSE)로 공개됩니다. 소스를 사용·검토·수정·재배포할 수 있습니다. 버그 제보와 개선은 GitHub Issues 또는 Pull Request로 보내주세요.

---

## English

This repository publishes the **local AI collaboration server for Jelly Memo**, together with its Windows installer releases. It does not contain the Jelly Memo Flutter application source, Firebase configuration, user notes, or credentials.

### Direct note control

This tool is not a suggestion or approval queue. MCP-compatible AI tools can directly create and fully read notes; edit titles, icons, content, pin/archive/lined/color state, references, rich-text ranges, link and mission badges, canvases, and map/node positions; add, crop, resize, download, and remove body or banner images; move notes to trash and restore them; inspect and restore synchronized revisions; and permanently delete trashed notes. Permanent deletion and empty-trash calls require `confirm=true`.

The parity target is every persisted note result available in the Jelly Memo UI, rather than remotely clicking UI buttons.

A write tool does not succeed merely because a request was queued. The local server forwards the command to the running Jelly Memo Web or Windows app and returns success only after the app completes its normal save, encryption, and synchronization path. If the app is unavailable, the tool returns `app_unavailable`.

### Local-only privacy model

- The server listens only on `127.0.0.1:8765` on the user's computer.
- Binding to `0.0.0.0` or another external address is rejected.
- The server never connects directly to Firebase, Firestore, or Firebase Storage.
- The server never reads or writes Flutter app storage directly.
- Jelly Memo's `MemoSystem` performs every actual note change.
- Search snapshots and in-flight commands exist only in local server memory and disappear when it stops.
- An optional pairing token protects snapshot and command endpoints.
- Reusing an `idempotency_key` prevents duplicate command execution.
- Command protocol negotiation prevents older app builds from claiming newer commands, and a canceled browser long-poll cannot steal a later command after a reload.

### Installation

1. Download the [latest Windows installer](https://github.com/egm7126/simpleMemo-releases/releases/latest/download/JellyMemoMcpInstaller-windows-x64.exe).
2. Run the installer.
3. The first time Jelly Memo Web connects, allow the browser's **local network access** request.
4. Check the connection under **AI collaboration tools** in Jelly Memo Web or Windows settings.

Jelly Memo's install button uses the same stable URL. Every latest Release keeps a `JellyMemoMcpInstaller-windows-x64.exe` asset so future installer updates do not require an app redeployment. The server allows CORS access from the official Jelly Memo Web origins only, not arbitrary external websites.

The installer is currently not Authenticode-signed, so Windows SmartScreen may display a warning. Verify that the file came from this repository's official Release before installing it.

### Run, test, and build from source

Requirements: Windows and Python 3.10 or newer. Use the PowerShell commands in the Korean section above. The MCP endpoint is `http://127.0.0.1:8765/mcp`, and build outputs are written under `build/mcp_companion/`.

### Open source and contributing

This local MCP server is available under the [MIT License](LICENSE). You may use, inspect, modify, and redistribute it. Bug reports and improvements are welcome through GitHub Issues and Pull Requests.