📝 AI Sticky Notes - Python MCP Server

FastMCP를 사용하여 Python으로 구축된 가볍고 클라이언트에 구애받지 않는 Model Context Protocol (MCP) 서버입니다. 이 서버는 AI 어시스턴트(예: Claude Desktop, Google Antigravity, Cursor 및 모든 MCP 호환 클라이언트)에게 영구적인 메모 작성 기능을 제공합니다.

🌟 주요 기능

이 서버는 Model Context Protocol의 세 가지 핵심 프리미티브를 구현합니다:

• 🛠️ 도구 (작업 실행):

  • add_note(message: str) -> str: 로컬 저장소 파일에 새 스티커 메모를 추가합니다.

  • read_notes() -> str: 저장된 모든 메모를 읽어 단일 문자열로 반환합니다.

• 📦 리소스 (컨텍스트 공급):

  • notes://latest: 사용자 정의 URI를 통해 가장 최근에 저장된 메모를 동적으로 노출합니다.

• 💬 프롬프트 (재사용 가능한 LLM 템플릿):

  • note_summary_prompt(): AI가 현재 모든 스티커 메모를 요약하도록 지시하는 즉시 사용 가능한 프롬프트를 생성합니다.

📂 프로젝트 구조

.
├── main.py                  # Primary FastMCP server implementation
├── main_final.py            # Clean reference implementation
├── notes.txt                # Persistent note storage (auto-generated)
├── pyproject.toml           # uv / Python package and dependency configuration
├── BITACORA_DE_ERRORES.md   # Troubleshooting log & root-cause analyses (Linux & PATH notes)
├── MCP_PYTHON_SDK.md        # FastMCP quick reference cheatsheet
└── README.md                # Project documentation (this file)

🚀 시작하기

사전 요구 사항

• Python 3.12+

• uv (빠른 패키지 및 환경 관리를 위한 권장 도구)

1. 설치

이 저장소를 클론하고 종속성을 동기화하세요:

git clone https://github.com/<your-username>/<your-repo-name>.git
cd <your-repo-name>
uv sync

🧪 실행 및 테스트

옵션 A: 대화형 MCP Inspector (권장)

MCP Inspector는 도구를 테스트하고, 리소스를 검사하고, 프롬프트를 대화형으로 실행할 수 있는 시각적 웹 인터페이스를 제공합니다:

uv run mcp dev main.py

터미널에 표시된 URL(일반적으로 http://localhost:5173 또는 유사한 주소)을 열어 서버와 상호작용하세요.

옵션 B: Claude Desktop 통합

claude_desktop_config.json에 서버 정의를 추가하세요:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ai-sticky-notes": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/your/project",
        "run",
        "main.py"
      ]
    }
  }
}

💡 Linux / GUI 환경 팁: 데스크톱 환경이 셸의 대화형 PATH를 상속하지 않는 경우(spawn uv ENOENT 오류 발생), uv 바이너리의 절대 경로(예: /home/<user>/.local/bin/uv 또는 /home/<user>/miniconda3/bin/uv)를 지정하세요. 자세한 내용은 BITACORA_DE_ERRORES.md를 참조하세요.

옵션 C: 표준 MCP 클라이언트(Cursor, Antigravity, 사용자 정의 CLI)와의 통합

다음을 사용하여 표준 stdio 전송을 구성하세요:

• 명령어: uv

• 인수: ["--directory", "<PROJECT_PATH>", "run", "main.py"]

📖 MCP API 참조

도구

리소스

프롬프트

🛠️ 개발 및 문제 해결

개발 중 발생한 디버깅 단계, Linux 플랫폼 해결 방법 및 일반적인 설정 문제에 대한 자세한 변경 로그는 다음을 참조하세요:

• 📓 BITACORA_DE_ERRORES.md (스페인어로 작성된 로그)

• 📘 MCP_PYTHON_SDK.md (SDK 치트시트)

📄 라이선스 및 크레딧

• Model Context Protocol 및 FastMCP로 구축되었습니다.

• Tech With Tim의 MCP 서버 개발 튜토리얼에서 영감을 받았습니다.