MCP Server Flomo Python

🚀 MCPプロトコルベースのFlomo Webサーバーとコマンドラインツール

このプロジェクトは、MCP（モデルコンテキストプロトコル）に基づくWebサーバーとコマンドラインツールを提供し、Flomo APIとのインタラクションを可能にします。これにより、Flomoに簡単にノートを追加し、様々な環境で利用できるようになります。

🚀 クイックスタート

このプロジェクトは、Flomo APIとのやり取りを容易にするためのWebサーバーとコマンドラインツールを提供します。以下のセクションでは、インストール、設定、使用方法などの詳細を説明します。

✨ 主な機能

• 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. mainブランチにPull Requestを提出し、チーム内でコードレビューを行います。

問題の報告

問題が見つかった場合は、以下の方法で報告してください。

1. GitHubのIssuesに新しい問題を作成します。
2. 詳細なエラー情報と再現手順を提供します。

📄 ライセンス

このプロジェクトはMIT Licenseに従い、具体的な内容は以下の通りです。

MIT License

Copyright © [Year] [Name or Organization]

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.

以上のドキュメントを参考にすることで、このプロジェクトを簡単にインストール、設定、使用することができます。使用中に問題が発生した場合は、このガイドを参照するか、開発チームに問い合わせてください。