plant-mcp: Instructions file for Claude Code

CLAUDE.md

이 저장소에서 작업할 때 알아야 할 것들. 다른 기기에서 처음 열었더라도 이 문서만 읽으면 바로 이어서 작업할 수 있도록 작성했다.

무엇인가

반려식물의 물주기·상태를 기록하는 MCP 서버. Claude Desktop에 stdio로 붙어서 사용자가 대화로 식물을 관리한다. 개인 포트폴리오 프로젝트.

src/plant_mcp/storage.py   SQLite 저장 계층 — MCP를 전혀 모른다
src/plant_mcp/server.py    MCP 서버 — storage를 호출해 툴로 노출

⚠️ mcp SDK 2.0 — 1.x와 API가 다르다

가장 흔한 실수. 학습 데이터에 있는 FastMCP 패턴으로 짜면 동작하지 않는다. 이 프로젝트는 mcp>=2.0.0을 쓴다.

# 이 프로젝트가 쓰는 것 (2.0)
from mcp.server import MCPServer

server = MCPServer(name="plant-care", version="0.1.0", instructions="...")

@server.tool(description="...")
def my_tool(x: int) -> str: ...

@server.resource("plant://{name}", mime_type="application/json")
def my_resource(name: str) -> str: ...

@server.prompt(name="diagnose")
def my_prompt(a: str) -> str: ...

server.run("stdio")

# 1.x 패턴 — 이 프로젝트에 없음. 쓰지 말 것
from mcp.server.fastmcp import FastMCP   # ← ImportError

응답 모델 필드는 snake_case다. 카멜케이스로 접근하면 AttributeError가 난다.

쓸 것	쓰면 안 되는 것
init.server_info	serverInfo
init.protocol_version	protocolVersion
tool.input_schema	inputSchema
result.resource_templates	resourceTemplates
template.uri_template	uriTemplate

server.list_tools() / call_tool() / read_resource() / get_prompt()는 모두 async다. 툴이 예외를 던지면 SDK가 ToolError로 감싸 올린다.

API가 기억과 다르면 추측하지 말고 설치된 패키지를 직접 확인할 것:

uv run python -c "from mcp.server import MCPServer; import inspect; print([n for n in dir(MCPServer) if not n.startswith('_')])"

설계 원칙 (지킬 것)

• storage.py는 MCP를 몰라야 한다. 서버 없이 단독 테스트가 가능해야 하고, 나중에 다른 인터페이스를 붙일 여지를 남긴다.
• 커넥션은 호출마다 연다. 서버가 툴을 여러 스레드에서 실행해도 안전하도록. 전역 커넥션을 만들지 말 것.
• 파괴적 동작에는 가드를 둔다. remove_plant는 confirm=True 없이는 삭제하지 않고 확인 문장만 돌려준다. 새로 추가하는 삭제성 툴도 같은 패턴을 따를 것.
• 오류 메시지는 LLM이 재호출로 교정할 수 있게 쓴다. 예: 없는 식물을 조회하면 등록된 식물 목록을 메시지에 포함한다.
• 조회 툴은 구조화된 dict/list를, 기록 툴은 사람이 읽을 문장을 돌려준다. LLM이 결과를 그대로 사용자에게 전달해도 자연스럽도록.
• 파생 상태를 저장하지 않는다. needs_water는 조회 시점에 계산한다 (마지막 물준 날 + 간격 <= 기준일). 갱신 배치가 필요 없어진다.