# plant-mcp

반려식물의 물주기와 상태를 기록하고 조회하는 **MCP(Model Context Protocol) 서버**입니다.
Claude Desktop에 연결하면 대화로 식물을 관리할 수 있습니다.

> "몬스테라 물 줬어" → 기록됨
> "오늘 뭐 목말라?" → 밀린 순서로 알려 줌
> "몬스테라 아랫잎이 노래져" → 관리 이력을 근거로 원인 추정

## 왜 MCP인가

식물 관리 앱은 이미 많습니다. 이 프로젝트의 목적은 앱을 하나 더 만드는 게 아니라,
**내 개인 데이터를 LLM이 직접 다룰 수 있는 형태로 노출**하는 것입니다.
사용자는 UI를 익힐 필요 없이 평소 말투로 기록하고, 조회하고, 상담합니다.

## MCP 3요소를 모두 사용

| 구성요소 | 이 프로젝트에서의 쓰임 |
|---|---|
| **Tools** (9개) | 등록·기록·수정·삭제·조회. LLM이 호출하는 동작 |
| **Resources** | `plant://{name}` — 식물 한 그루의 프로필을 JSON으로 노출 |
| **Prompts** | `diagnose` — 증상과 관리 이력을 묶어 진단을 요청하는 템플릿 |

### Tools

| 툴 | 하는 일 |
|---|---|
| `add_plant` | 식물 등록 (품종·위치·물주기 간격·입양일) |
| `log_watering` | 물 준 기록. 날짜 생략 시 오늘 |
| `log_note` | 관찰 기록 ("아랫잎이 노래짐", "새순 나옴") |
| `update_plant` | 품종·위치·물주기 간격 수정 |
| `remove_plant` | 삭제. `confirm=True` 없이는 실행되지 않음 |
| `list_plants` | 전체 목록 + 경과일 + 다음 예정일 |
| `plants_needing_water` | 물 줄 때가 된 것만, 많이 밀린 순 |
| `get_plant` | 한 그루 상태 요약 |
| `plant_history` | 물주기·관찰 기록 통합 타임라인 |

조회 툴은 구조화된 JSON을 돌려주고, 기록 툴은 사람이 읽을 수 있는 확인 문장을
돌려줍니다. LLM이 결과를 그대로 사용자에게 전달해도 자연스럽도록 한 설계입니다.

## 설계 노트

- **파괴적 동작에는 가드를 뒀습니다.** `remove_plant`는 첫 호출에서 삭제하지 않고
  확인을 요구하는 문장을 돌려줍니다. LLM이 실수로 데이터를 날리지 못하게 하는
  최소한의 안전장치입니다.
- **오류 메시지를 LLM이 고쳐 부를 수 있게 썼습니다.** 없는 식물을 조회하면 등록된
  식물 목록을 함께 돌려주므로, 오타가 있어도 다음 호출에서 바로 교정됩니다.
- **저장 계층을 서버와 분리했습니다.** `storage.py`는 MCP를 모릅니다. 서버 없이
  단독 테스트가 가능하고, 나중에 다른 인터페이스를 붙이기도 쉽습니다.
- **커넥션은 호출마다 엽니다.** 서버가 툴을 여러 스레드에서 실행해도 안전합니다.
- **DB 경로가 설치 방식에 의존하지 않습니다.** 패키지 위치가 아니라 OS의 사용자
  데이터 폴더를 씁니다. 편집 설치든 일반 설치든 같은 DB를 가리킵니다.

## 설치

필요한 것: [uv](https://docs.astral.sh/uv/), Python 3.12 이상

```bash
git clone <repo> plant-mcp
cd plant-mcp
uv sync
```

## Claude Desktop 연결

`claude_desktop_config.json`에 다음을 추가합니다.

- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "plant-care": {
      "command": "<프로젝트 경로>/.venv/Scripts/plant-mcp.exe"
    }
  }
}
```

macOS·Linux에서는 `command`를 `<프로젝트 경로>/.venv/bin/plant-mcp`로 지정합니다.
저장한 뒤 **Claude Desktop을 완전히 종료했다가 다시 실행**해야 서버가 잡힙니다.

## 데이터 저장 위치

기본값은 OS의 사용자 데이터 폴더입니다.

- Windows: `%LOCALAPPDATA%\plant-mcp\plants.db`
- macOS·Linux: `~/.local/share/plant-mcp/plants.db`

`PLANT_MCP_DB` 환경변수로 바꿀 수 있습니다.

```json
{
  "mcpServers": {
    "plant-care": {
      "command": "...",
      "env": { "PLANT_MCP_DB": "D:/data/plants.db" }
    }
  }
}
```

SQLite 파일 하나이므로 백업은 복사, 이전은 이동으로 끝납니다.

## 다른 기기에서 이어서 작업하기

### 새 컴퓨터에 설치

```bash
git clone https://github.com/azureiraraavis-png/plant-mcp.git
cd plant-mcp
uv sync
```

그다음 그 기기의 `claude_desktop_config.json`에 등록합니다. 경로는 OS마다 다릅니다.

| OS | 설정 파일 | `command` 값 |
|---|---|---|
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` | `<프로젝트>\.venv\Scripts\plant-mcp.exe` |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` | `<프로젝트>/.venv/bin/plant-mcp` |

`command`에는 **절대 경로**를 넣어야 합니다. 저장한 뒤 Claude Desktop을 완전히
종료했다가 다시 실행합니다.

기존 설정에 다른 MCP 서버가 이미 있다면 `mcpServers` 안에 항목만 추가하세요.
설정 파일 전체를 덮어쓰면 Claude Desktop의 다른 설정이 날아갑니다.

### 기록(DB)은 따라오지 않습니다

코드는 git으로 옮겨가지만 `plants.db`는 **기기마다 별개**입니다. 개인 기록이라
저장소에 넣지 않기 때문입니다(`.gitignore`에 `*.db`).

기기 간에 같은 기록을 보시려면 `PLANT_MCP_DB`를 클라우드 동기화 폴더로 지정합니다.

```json
{
  "mcpServers": {
    "plant-care": {
      "command": "...",
      "env": { "PLANT_MCP_DB": "C:/Users/사용자명/OneDrive/plant-mcp/plants.db" }
    }
  }
}
```

두 가지를 주의하셔야 합니다.

- **두 기기에서 동시에 쓰면 DB가 손상될 수 있습니다.** SQLite는 클라우드 동기화를
  전제하지 않습니다. Claude Desktop을 양쪽에서 동시에 켜두지 마세요.
- OneDrive·Google Drive의 온디맨드 기능으로 파일이 클라우드에만 있으면 읽기가
  실패할 수 있습니다. 해당 폴더를 **"이 디바이스에 항상 유지"**로 설정하세요.

한 기기에서만 쓰신다면 기본 경로 그대로 두는 편이 안전합니다.

### 휴대폰에서는 아직 안 됩니다

Claude 모바일 앱은 로컬 stdio MCP 서버를 붙일 수 없습니다. 폰에서 쓰려면 이 서버를
원격 MCP(HTTP)로 전환해 인터넷에 호스팅해야 합니다. 코드 변경 자체는 작지만
(`run("stdio")` → `run("streamable-http")`) 호스팅과 인증이 별도 작업입니다.
로드맵에 있습니다.

## 사용 예시

```
나:     거실 창가에 몬스테라 들였어. 일주일에 한 번 물 주면 된대.
Claude: (add_plant 호출) '몬스테라' 등록했습니다. 7일마다 물주기로 잡아뒀어요.

나:     오늘 몬스테라 물 흠뻑 줬어
Claude: (log_watering 호출) 기록했습니다. 다음 예정일은 8월 7일이에요.

나:     오늘 뭐 목말라?
Claude: (plants_needing_water 호출) 산세베리아가 3일 밀렸습니다.

나:     몬스테라 아랫잎이 계속 노래져
Claude: (diagnose 프롬프트 + plant_history 참고)
        마지막 물주기가 11일 전이고 간격이 7일이니 물부족 가능성이 우선...
```

## 데이터 모델

```
plants     id, name(unique), species, location, acquired_on,
           water_every_days, created_at
waterings  id, plant_id → plants, watered_on, amount, created_at
notes      id, plant_id → plants, noted_on, body, created_at
```

`needs_water`는 저장하지 않고 조회 시점에 계산합니다
(`마지막 물준 날 + 간격 <= 기준일`). 배치 작업이나 갱신 로직이 필요 없습니다.

## 개발

저장 계층만 단독으로 두드려 보기:

```bash
uv run python -c "from plant_mcp import storage; print(storage.list_plants())"
```

서버를 직접 띄우기:

```bash
uv run plant-mcp
```

stdio로 JSON-RPC를 주고받으므로 터미널에서는 응답 없이 대기하는 것이 정상입니다.

## 로드맵

- [x] 관리 기록 서버 (Tools / Resources / Prompts)
- [ ] 식물 관리 지식베이스 RAG 검색 툴 추가
- [ ] 물주기 간격 자동 보정 (계절·실제 기록 기반)

## 라이선스

MIT