TaskNote Bridge - Swift MCP Server with Things 3 & Apple Notes ✅

TaskNote Bridge - Things 3 と Apple Notes に対応した Swift MCP サーバー ✅

Things 3 と Apple Notes を統合する、Model Context Protocol（MCP）](https://modelcontextprotocol.io/introduction)サーバーを完全に実装したネイティブ macOS Swift アプリケーションです。

ステータス：✅ 本番環境で利用可能 - GUI モニタリング機能を備えた完全な MCP サーバー

🚀 クイックインストール

📥 ダウンロードとインストール

1. 最新リリースをダウンロード
2. DMG を開き、TaskNote Bridge を「アプリケーション」にドラッグします
3. アプリを起動します - MCP サーバーが自動的に起動します
4. 以下の設定で VS Code を設定します

⚙️ Claude Desktop の設定

Claude Desktop の MCP サーバー設定に以下を追加します：

{
    "mcpServers": {
        "tasknote-bridge": {
            "command": "/path/to/tasknote-bridge/launch_swift_mcp_stdio.sh"
        }
    }
}

📝 注記：/path/to/tasknote-bridge/ を実際のインストール先ディレクトリに置き換えてください。例：

• リリースをダウンロードした場合：/Users/[username]/Downloads/tasknote-bridge/
• リポジトリをクローンした場合：/Users/[username]/Projects/tasknote-bridge/
• 「アプリケーション」に移動した場合：/Applications/TaskNote Bridge/

⚙️ VS Code の設定

VS Code の settings.json に以下を追加します：

{
    "mcp": {
        "inputs": [],
        "servers": {
            "things-swift": {
                "command": "/path/to/tasknote-bridge/launch_swift_mcp_stdio.sh",
                "args": []
            }
        }
    }
}

これで完了です！ 🎉 AI アシスタント経由でタスクやノートを作成できます。

📋 必要条件

• macOS：12.0 以降（Monterey 以降）
• Things 3：Mac App Store からインストールしてください
• Apple Notes：macOS に標準搭載されています
• VS Code：MCP 拡張機能が必要です

🎯 現在利用できる機能

# Test the stdio server (creates task in Things 3!)
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "bb7_add-todo", "arguments": {"title": "Hello from VS Code!", "tags": ["test"]}}}' | ./launch_swift_mcp_stdio.sh

# Expected output:
{"jsonrpc":"2.0","id":1,"result":{"content":[{"text":"✅ Task 'Hello from VS Code!' created in Things 3","type":"text"}],"isError":false}}

# ✅ Check Things 3 - your task will be there!

GUI モニタリング

# Build and run the macOS app
xcodebuild -project "TaskNote Bridge.xcodeproj" -scheme "TaskNote Bridge" build
open "TaskNote Bridge.app"
# Server auto-starts with monitoring interface

🛠 完全な機能一覧

ネイティブ macOS MCP サーバーアプリケーション

• 完全な MCP サーバー：Things 3 と Apple Notes のツールを備えた、MCP プロトコルの完全な Swift 実装
• リアルタイムモニタリング：ライブのアクティビティ追跡機能を備えたサーバーステータスダッシュボード
• TCP トランスポート：あらゆる MCP クライアントとの互換性を実現する、ネットワークベースのトランスポートプロトコル
• ログストリーミング：フィルタリングと検索機能を備えた、サーバーログのライブ表示
• 接続管理：アクティブなクライアント接続とリクエスト／レスポンスのアクティビティを監視
• SwiftUI インターフェース：サーバーのモニタリングと制御のための、最新の macOS インターフェース

Things 3 との統合

• 主な Things リスト（Inbox、Today、Upcoming など）へのアクセス
• プロジェクトとエリアの管理
• タグ操作
• 高度な検索機能
• 最近の項目の追跡
• チェックリストを含む、項目の詳細情報
• ネストされたデータに対応（エリア内のプロジェクト、プロジェクト内の ToDo）
• Things 3 アプリで特定のタスクを直接開く

Apple Notes との統合

• タイトル、内容、タグを指定して新しいノートを作成
• タイトルでノートを検索
• ノートの内容を取得
• すべてのノートを一覧表示
• Apple Notes アプリでノートを直接開く
• ノートを削除
• macOS とシームレスに連携する、AppleScript の完全な統合

インストール

オプション 1：アプリをダウンロード（推奨）

リリースページから最新の TaskNote Bridge.app をダウンロードします

オプション 2：ソースからビルド

ソースからビルドする場合は、以下が必要です：

• Xcode 14.0 以降
• macOS 13.0 以降

リポジトリをクローンしてビルドします：

# Clone the repository
git clone https://github.com/ragdollKB/taskNote-bridge-mcp.git
cd taskNote-bridge-mcp

# Open in Xcode and build
open "TaskNote Bridge.xcodeproj"

設定

前提条件

• MCP 対応の AI アシスタントまたはツール（Claude Desktop、MCP 拡張機能を備えた VS Code、Cursor、Continue、Zed など）
• Things 3（「設定」->「一般」で「Enable Things URLs」をオンにする必要があります）
• Apple Notes（ノート管理機能を使用する場合）
• macOS 13.0 以降（SwiftUI と AppleScript の統合に必要）

🏗️ プロジェクトアーキテクチャ

このプロジェクトでは、用途に応じて 2 種類の MCP サーバー実装を提供します：

📱 TaskNote Bridge.app（GUI アプリケーション）

• 目的：視覚的なモニタリングインターフェースを備えた macOS アプリ
• トランスポート：ネットワーク経由の接続に使用する TCP サーバー（ポート 8000）
• 機能：リアルタイムダッシュボード、接続モニタリング、ログビューアー
• 用途：サーバーの動作を視覚的にモニタリングしたい場合
• 起動方法：Applications フォルダーからアプリを開きます

📟 swift_mcp_stdio.swift（コマンドラインサーバー）

• 目的：軽量な stdio ベースの MCP サーバー
• トランスポート：標準入出力による通信
• 機能：JSON-RPC メッセージの直接処理、最小限のオーバーヘッド
• 用途：Claude Desktop およびほとんどの MCP クライアントに推奨
• 起動方法：launch_swift_mcp_stdio.sh スクリプト経由

🔧 どちらを使うべきですか？

MCP クライアント	推奨サーバー	設定
Claude Desktop	✅ stdio スクリプト	command: "/path/to/launch_swift_mcp_stdio.sh"
VS Code MCP	✅ stdio スクリプト	Claude Desktop と同じ
カスタム TCP クライアント	📱 GUI アプリ	localhost:8000 に接続
開発／テスト	📱 GUI アプリ	視覚的なモニタリング + TCP アクセス

💡 ポイント：Claude Desktop を含むほとんどの MCP クライアントは、TCP 接続ではなく stdio ベースの通信を想定しています。

🔗 MCP クライアント接続ガイド

TaskNote Bridge は、さまざまな MCP クライアントに対応するため、複数の接続方法をサポートしています。お使いのクライアントに最適な方法を選択してください。

🎯 Claude Desktop

stdio ベースの MCP サーバーを使用するように Claude Desktop を設定します。

1. Claude Desktop を開きます
2. 左下の設定ギア（⚙️）をクリックします
3. 「Developer」を選択します
4. 「MCP Servers」セクションで、「Edit Config」をクリックします
5. 次の設定を追加します：

{
    "mcpServers": {
        "tasknote-bridge": {
            "command": "/path/to/tasknote-bridge/launch_swift_mcp_stdio.sh"
        }
    }
}

📝 注記：/path/to/tasknote-bridge/ を実際のインストールディレクトリに置き換えてください。一般的なパスは次のとおりです。

• ダウンロードしたリリース：/Users/[username]/Downloads/tasknote-bridge/launch_swift_mcp_stdio.sh
• クローンしたリポジトリ：/Users/[username]/Projects/tasknote-bridge/launch_swift_mcp_stdio.sh
• アプリバンドルへのインストール：/Applications/TaskNote Bridge.app/Contents/Resources/launch_swift_mcp_stdio.sh ```

6. 設定を保存します
7. Claude Desktop を再起動して変更を適用します

✅ 成功：Claude Desktop は stdio トランスポート経由で接続するようになります。これは MCP 通信で推奨される、最も信頼性の高い方法です。

🔧 MCP 拡張機能を使った VS Code

1. VS Code 用の MCP 拡張機能をインストールします。

   • VS Code の拡張機能を開きます（Cmd+Shift+X）
   • 「Model Context Protocol」を検索してインストールします

2. VS Code の設定（settings.json）を構成します。

{
    "mcp": {
        "servers": {
            "tasknote-bridge": {
                "command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh",
                "args": []
            }
        }
    }
}

3. VS Code を再起動して MCP サーバーを読み込みます

🖱️ Cursor IDE

1. Cursor の設定を開きます（Cmd+,）
2. 「Extensions」→「Model Context Protocol」に移動します
3. サーバー設定を追加します：

{
    "command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh",
    "args": []
}

⚡ Continue（VS Code 拡張機能）

1. VS Code に Continue 拡張機能をインストールします
2. Continue の設定ファイルを開きます（通常は ~/.continue/config.json）
3. MCP サーバーを追加します：

{
    "mcpServers": [
        {
            "name": "tasknote-bridge",
            "command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh",
            "args": []
        }
    ]
}

🚀 Zed Editor

1. Zed の設定を開きます（Cmd+,）
2. settings.json に次の設定を追加します：

{
    "assistant": {
        "mcp_servers": {
            "tasknote-bridge": {
                "command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh"
            }
        }
    }
}

🛠️ カスタム MCP クライアント

カスタム MCP クライアントやアプリケーションを使用する場合：

TCP 接続

• ホスト：localhost
• ポート：8000（デフォルト。TaskNote Bridge アプリで変更できます）
• プロトコル：JSON-RPC 2.0 を使用した TCP

Stdio 接続

• コマンド：/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh
• トランスポート：JSON-RPC 2.0 を使用した標準入出力

📋 確認手順

任意のクライアントの設定後、次の手順を実行します。

1. 接続をテストします：

   # For stdio testing
   echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
   
   # For TCP testing (if server is running)
   echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | nc localhost 8000
   

2. 利用可能なツールを確認します。次のようなツールが表示されます。

   • bb7_add-todo
   • bb7_add-project
   • bb7_get-today
   • bb7_notes-create
   • その他多数...

3. タスク作成をテストします：

   echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "bb7_add-todo", "arguments": {"title": "Test from MCP!", "tags": ["test"]}}}' | /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
   

4. Things 3 で確認します。テストタスクが受信トレイに表示されるはずです。

🔍 接続問題のトラブルシューティング

Claude Desktop に接続できない場合

• 設定ファイルが有効な JSON であることを確認してください
• ファイルパスが存在することを確認してください：/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh
• Claude Desktop を完全に再起動してください
• Claude のログを確認してください：~/Library/Logs/Claude/mcp*.log

TCP 接続の問題

• TaskNote Bridge アプリが起動していることを確認してください
• ポート 8000 が使用可能か確認してください：lsof -i :8000
• TaskNote Bridge の設定で別のポートを試してください
• ファイアウォールの設定でローカル接続が許可されていることを確認してください

Stdio 接続の問題

• スクリプトの権限を確認してください：ls -la /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
• ターミナルでスクリプトを直接テストしてください
• Things 3 → Settings → General で Things 3 の URL が有効になっていることを確認してください

VS Code（MCP 拡張機能を使用）の場合

1. まず、TaskNote Bridge アプリがインストールされ、起動していることを確認してください。

2. VS Code 用の MCP 拡張機能をインストールします：

   • VS Code を開きます
   • 拡張機能を開きます（Cmd+Shift+X）
   • 「MCP」を検索し、公式の MCP 拡張機能をインストールします

3. VS Code の設定を行います：

   • 設定を開きます（Cmd+,）
   • 右上の「Open Settings (JSON)」をクリックします
   • 次の設定を追加します：

{
    "mcp": {
        "inputs": [],
        "servers": {
            "things-swift": {
                "command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh",
                "args": []
            }
        }
    }
}

注：パスはアプリをインストールした実際の場所に置き換えてください。Applications フォルダーに移動した場合は、次のパスを使用してください：/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh

4. VS Code を再起動して、MCP サーバーを読み込みます。

使用方法

使用方法

TaskNote Bridge アプリでの使用

1. Applications フォルダーから TaskNote Bridge アプリを起動します。
2. アプリでは、macOS のネイティブインターフェースを使用して、次の操作を行えます：
   • Things 3 のタスク、プロジェクト、エリアを表示する
   • Apple Notes を管理する
   • MCP サーバーの接続状況を監視する
   • アクティビティログをリアルタイムで確認する

Claude Desktop での使用

接続すると、自然な言葉で TaskNote Bridge を操作できます：

Things 3 の例：

• 「今日の To Do リストには何がありますか？」
• 「来週のビーチ旅行の荷造りをする To Do を作成してください」
• 「メモリアルデーのバーベキュー用に、計画タスクを含むプロジェクトを作成してください」
• 「仕事関連のタスクをすべて表示してください」
• 「食料品の買い物タスクを完了済みにしてください」
• 「明日、母に電話するタスクを追加してください」

Apple Notes の例：

• 「今日の朝会の議事録を含むメモを作成してください」
• 「四半期レビューに関するメモを検索してください」
• 「試してみたい新しいレストランについてメモを作成してください」
• 「旅行情報を含むメモをすべて表示してください」

VS Code での使用

MCP 拡張機能をインストールして設定したら、次の操作を行います：

1. コマンドパレットを開きます（Cmd+Shift+P）
2. 「MCP」と入力して、使用できる MCP コマンドを確認します
3. 「MCP: Call Tool」を使用して Things のツールを操作します
4. または、MCP に対応した任意の AI アシスタントを使用して Things のデータにアクセスします

MCP 対応ツールでの使用

このサーバーは標準の MCP プロトコルに準拠しており、MCP 対応のあらゆるアプリケーションや AI アシスタントで動作します。上記のいずれかの方法で、Swift MCP サーバーに接続するようツールを設定してください。

対応アプリケーション：

• Claude Desktop
• MCP 拡張機能を備えた VS Code
• Cursor
• Continue
• Zed
• Sourcegraph Cody
• カスタム MCP クライアントの実装

💡 連携をさらに活用するためのヒント

Claude Desktop の最適化

• Claude でカスタムプロジェクトを作成し、Things 3 の使い方やエリア、プロジェクト、タグなどの整理方法を指示します。
• タスク作成時に含める情報を Claude に伝えます（例：タスクの説明に含める関連情報）。
• カレンダーの MCP サーバーと連携し、タスクの時間を確保したり、カレンダーの予定から To Do を作成したりできるようにします。

複数クライアントでの使用

• TCP モードを使用して、複数のクライアントを同時に接続します。
• TaskNote Bridge アプリを開いたままにし、すべての MCP アクティビティをリアルタイムで監視します。
• ツール呼び出しに問題が発生した場合は、アプリのログを確認してください。

高度なワークフロー

• 「現在の ToDo をアイゼンハワーマトリクスを使って評価してください」
• 「Things を使って、GTD 形式の週次レビューを実施するのを手伝ってください」
• 「[プロジェクト名] のサブタスクと期限を含むプロジェクト計画を作成してください」
• 「タスクの完了パターンを分析し、改善案を提案してください」

プロジェクト構成

TaskNote Bridge.app/          # The macOS Swift application
├── Contents/
│   ├── MacOS/                # Native Swift executable containing MCP server
│   │   └── TaskNote Bridge   # Main app with embedded MCP server
│   ├── Resources/            # Application resources
│   └── Info.plist            # App bundle configuration
├── TaskNote Bridge.xcodeproj/ # Xcode project
├── SwiftMCPServer.swift      # Core MCP server implementation
├── ThingsIntegration.swift   # Things 3 integration layer
├── NotesIntegration.swift    # Apple Notes integration layer
└── README.md                 # This documentation

利用可能なツール

リスト表示

• get-inbox - Inbox の ToDo を取得
• get-today - 今日が期限の ToDo を取得
• get-upcoming - 今後の ToDo を取得
• get-anytime - Anytime リストの ToDo を取得
• get-someday - Someday リストの ToDo を取得
• get-logbook - 完了した ToDo を取得
• get-trash - ゴミ箱に入れた ToDo を取得

基本操作

• get-todos - ToDo を取得。プロジェクトによる絞り込みも可能
• get-projects - すべてのプロジェクトを取得
• get-areas - すべてのエリアを取得

タグ操作

• get-tags - すべてのタグを取得
• get-tagged-items - 特定のタグが付いたアイテムを取得

検索操作

• search-todos - タイトル／メモで簡易検索
• search-advanced - 複数のフィルターを使った高度な検索
• open-todo - タイトルで ToDo を検索し、Things アプリで開く

時間ベースの操作

• get-recent - 最近作成されたアイテムを取得

ツールのパラメーター

get-todos

• project_uuid （任意） - プロジェクトで ToDo を絞り込む
• include_items （任意、デフォルト：true） - チェックリストの項目を含める

get-projects / get-areas / get-tags

• include_items （任意、デフォルト：false） - 含まれるアイテムを含める

search-advanced

• status - ステータスで絞り込む（未完了／完了／キャンセル）
• start_date - 開始日で絞り込む（YYYY-MM-DD）
• deadline - 期限で絞り込む（YYYY-MM-DD）
• tag - タグで絞り込む
• area - エリア UUID で絞り込む
• type - アイテムの種類で絞り込む（ToDo／プロジェクト／見出し）

get-recent

• period - 期間（例：'3d'、'1w'、'2m'、'1y'）

open-todo

• title - 検索して開く ToDo のタイトルまたはタイトルの一部

notes-open

• title - Apple Notes で開くメモの正確なタイトル

トラブルシューティング

接続の問題

Claude Desktop

• 設定ファイルを確認する：JSON 設定が有効で、正しくフォーマットされていることを確認します
• ファイルパスを確認する：/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh が存在することを確認します
• Claude を再起動する：設定変更後、Claude Desktop を完全に終了して再起動します
• ログを確認する：Claude のログ ~/Library/Logs/Claude/mcp*.log を確認します

TCP 接続の問題

• アプリが起動していることを確認する：TCP サーバーを起動した状態で TaskNote Bridge アプリが実行されていることを確認します
• ポートの使用状況を確認する：lsof -i :8000 を使ってポート 8000 が利用可能か確認します
• ファイアウォール設定を確認する：macOS ファイアウォールがローカル接続を許可していることを確認します
• 別のポートを試す：必要に応じて TaskNote Bridge アプリの設定でポートを変更します

Stdio 接続の問題

• スクリプトの権限を確認する：スクリプトが実行可能であることを確認します：ls -la /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
• 直接テストする：Terminal でスクリプトをテストし、動作することを確認します
• Things 3 の URL を確認する：Things 3 → Settings → General で「Enable Things URLs」がオンになっていることを確認します

ツール実行の問題

サーバーには、以下に対する包括的なエラー処理が含まれています：

• 無効な UUID と不正な形式のリクエスト
• 必須パラメーターの不足
• Things 3 のデータベースへのアクセスエラー
• Apple Notes の AppleScript 実行エラー
• データのフォーマットおよびシリアライズエラー

すべてのエラーは、内容を説明するメッセージとともにログに記録されます。MCP ログを確認するには：

# Follow Claude Desktop logs in real-time
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

# Check TaskNote Bridge app logs
# Open TaskNote Bridge app and view the built-in log viewer

# Test server directly
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh

よくあるエラーの解決方法

「Permission denied」エラー

• 実行：chmod +x /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
• System Preferences → Security & Privacy で TaskNote Bridge アプリに必要な権限を付与します

「Things 3 not responding」エラー

• Things 3 がインストールされ、少なくとも一度は起動されていることを確認します
• Things 3 の設定で「Enable Things URLs」が有効になっていることを確認します
• Things 3 を再起動してみます

「Apple Notes へのアクセスが拒否されました」というエラー

• 「システム環境設定」→「セキュリティとプライバシー」→「オートメーション」で、TaskNote Bridge に Apple Notes の制御を許可します
• Apple Notes アプリがセキュリティソフトウェアによって制限されていないことを確認します

🚨 トラブルシューティング

Claude Desktop の接続に関する問題

「リクエストがタイムアウトしました」／サーバーが応答しない

Claude Desktop にタイムアウトエラーが表示される、または応答が届かない場合：

❌ 誤った設定（タイムアウトの原因）：

{
    "mcpServers": {
        "tasknote-bridge": {
            "command": "nc",
            "args": ["localhost", "8000"]
        }
    }
}

✅ 正しい設定：

{
    "mcpServers": {
        "tasknote-bridge": {
            "command": "/path/to/tasknote-bridge/launch_swift_mcp_stdio.sh"
        }
    }
}

この設定が重要な理由：

• Claude Desktop は stdio ベースの通信（サブプロセスの起動）を想定しています
• nc localhost 8000 の方法では netcat 経由で TCP を使用しようとしますが、MCP プロトコルの初期化を適切に処理できません
• stdio スクリプトは、Claude Desktop が必要とする適切な JSON-RPC メッセージ処理を提供します

修正方法：

1. Claude Desktop の設定を更新し、stdio スクリプトを使用します
2. Claude Desktop を再起動します
3. これでタイムアウトせずに接続できるはずです

サーバーの動作を確認する

stdio サーバーを直接テストします：

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | /path/to/tasknote-bridge/launch_swift_mcp_stdio.sh

次のような応答がすぐに表示されます：

{"jsonrpc":"2.0","id":1,"result":{"serverInfo":{"name":"things-mcp-swift","version":"1.0.0"},"protocolVersion":"2024-11-05","capabilities":{"tools":{}}}}