MCP Server Flomo Python

🚀 基於MCP協議的Flomo Web服務器和命令行工具

本項目提供了基於MCP（模型上下文協議）的Web服務器與命令行工具，用於和Flomo API進行交互。其目的在於方便地將筆記添加到Flomo中，並且支持在不同環境下使用。

🚀 快速開始

本項目提供了便捷的方式與Flomo API交互，以下是使用前的快速指引。

✨ 主要特性

• 提供命令行工具和Web服務器兩種使用方式，滿足不同場景需求。
• 方便快捷地將筆記添加到Flomo中。

📦 安裝指南

從PyPI安裝（推薦）

# 安裝基本包
pip install mcp-server-flomo

# 安裝開發依賴（可選）
pip install mcp-server-flomo[dev]

從源碼安裝

git clone https://github.com/yourusername/mcp-server-flomo-python.git
cd mcp-server-flomo-python
pip install -r requirements.txt

📚 詳細文檔

項目結構

.
├── flomo_cli.py         # 命令行工具的主入口腳本
├── flomo_server.py      # Web服務器的主入口腳本
├── src                  # 源代碼目錄
│   ├── cli              # 命令行工具模塊
│   │   ├── __init__.py
│   │   ├── __main__.py  # CLI程序的主要實現
│   │   └── commands.py  # 定義具體的命令
│   ├── server           # Web服務器模塊
│   │   ├── __init__.py
│   │   ├── __main__.py  # 服務器的主實現
│   │   └── app.py       # 基於Flask的應用實現
│   └── utils            # 工具函數模塊
│       ├── __init__.py
│       ├── config.py    # 配置管理工具
│       └── flomo_client.py  # Flomo API客戶端的實現
├── tests                # 測試用例目錄
└── docs                 # 文檔目錄

配置指南

1. 在項目根目錄下創建一個.env文件：

FLOMO_API_URL=https://flomoapp.com/iwh/你的ID/你的API密鑰/

⚠️ 重要提示

FLOMO_API_URL是必需的配置，可以從Flomo官網的“設置 > API”頁面獲取。

💻 使用示例

命令行工具

安裝完成後，可以直接使用flomo-cli命令：

# 測試連接狀態
flomo-cli test

# 發送一條筆記到Flomo
flomo-cli send "今天是個好天氣"

# 從文件中讀取內容併發送到Flomo
flomo-cli file path/to/note.txt

Web服務器

使用flomo-server啟動Web服務：

flomo-server run

默認情況下，Web服務器將在http://localhost:12345上運行，並提供以下接口：

• /test：測試連接狀態。
• /send：發送一條筆記到Flomo。
• /file：從指定文件中讀取內容併發送到Flomo。

🔧 技術細節

開發指南

安裝依賴

要進行開發，首先安裝所有必要的包和工具：

pip install -r requirements.txt
pip install black pytest mypy

運行測試

使用以下命令運行測試用例：

pytest tests/

代碼格式化

在項目中使用black來保持一致的代碼風格：

black .

類型檢查

使用mypy進行靜態類型檢查：

mypy src/

故障排除

1. 無法連接Flomo API：
   • 確保FLOMO_API_URL配置正確。
   • 檢查網絡連接，確保可以訪問外部服務。
2. 端口被佔用：
   • 如果flomo-server run提示端口被佔用，嘗試使用不同的端口號：

     flomo-server run --port 12346
     

3. 權限問題：
   • 確保運行程序的用戶有權限訪問所需的文件和網絡資源。

貢獻指南

提交代碼

1. 創建一個分支用於功能開發：

git checkout -b feature/新功能名稱

2. 完成代碼修改後，提交到該分支並推送到遠程倉庫：

git add .
git commit -m "添加新功能：描述"
git push origin feature/新功能名稱

3. 提交Pull Request到main分支，並在團隊內部進行代碼審查。

問題報告

發現任何問題，請通過以下方式提交：

1. 在GitHub Issues中創建一個新的問題。
2. 提供詳細的錯誤信息和復現步驟。

📄 許可證

本項目遵循MIT License協議，具體內容如下：

MIT License

版權 © [年份] [姓名或組織名稱]

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

通過以上文檔，您可以輕鬆地安裝、配置和使用這個項目。如果在使用過程中遇到任何問題，請隨時參考本指南或聯繫開發團隊尋求幫助。