📝 AI Sticky Notes - Python MCP Server

Python で FastMCP を使用して構築された、軽量でクライアント非依存の Model Context Protocol (MCP) サーバーです。このサーバーは、永続的なメモ作成機能を AI アシスタント（Claude Desktop、Google Antigravity、Cursor、および MCP に準拠した任意のクライアント）に公開します。

🌟 主な機能

このサーバーは、Model Context Protocol の3つの中核プリミティブを実装しています：

• 🛠️ ツール（アクション実行）：

  • 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 は、ツールのテスト、リソースの検査、プロンプトの対話的な実行を行うためのビジュアルな Web インターフェースを提供します：

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 サーバー開発チュートリアルに触発されました。