📝 AI Sticky Notes - Python MCP 服务器

一个轻量级、与客户端无关的 模型上下文协议（MCP） 服务器，基于 Python 使用 FastMCP 构建。该服务器为 AI 助手（如 Claude Desktop、Google Antigravity、Cursor 以及任何符合 MCP 的客户端）提供持久化的笔记功能。

🌟 主要特性

此服务器实现了模型上下文协议的三个核心原语：

• 🛠️ 工具（动作执行）：

  • 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 环境提示： 如果你的桌面环境没有继承 shell 的交互式 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 服务器开发教程启发。