Tasknote Bridge MCP

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

TaskNote Bridgeは、Things 3とApple Notesを統合するための、完全なModel Context Protocol (MCP)サーバーを実装したネイティブmacOS Swiftアプリケーションです。このアプリを使えば、AIアシスタントを通じてタスクやメモを簡単に作成できます。

🚀 クイックスタート

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

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拡張機能付き

🎯 現状での動作確認

標準入出力サーバーのテスト

# 標準入出力サーバーをテストする (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

# 期待される出力:
{"jsonrpc":"2.0","id":1,"result":{"content":[{"text":"✅ Task 'Hello from VS Code!' created in Things 3","type":"text"}],"isError":false}}

# ✅ Things 3を確認する - タスクが表示されているはずです！

GUIモニタリングの場合

# macOSアプリをビルドして実行
xcodebuild -project "TaskNote Bridge.xcodeproj" -scheme "TaskNote Bridge" build
open "TaskNote Bridge.app"
# サーバーはモニタリングインターフェイスとともに自動起動します

✨ 主な機能

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

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

Things 3統合

• 主要なThingsリスト (インボックス、今日、予定、など) へのアクセス
• プロジェクトとエリアの管理
• タグ操作
• 高度な検索機能
• 最近の項目の追跡
• チェックリストを含む詳細な項目情報
• ネストされたデータ (エリア内のプロジェクト、プロジェクト内のタスク) のサポート
• Things 3アプリで直接特定のタスクを開く

Apple Notes統合

• タイトル、内容、タグ付きの新しいメモの作成
• タイトルでメモを検索
• メモの内容を取得
• すべてのメモをリスト表示
• Apple Notesアプリで直接メモを開く
• メモの削除
• シームレスなmacOS体験のための完全なAppleScript統合

📦 インストール

オプション1: アプリをダウンロードする (おすすめ)

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

オプション2: ソースからビルドする

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

• Xcode 14.0以上
• macOS 13.0以上

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

# リポジトリをクローン
git clone https://github.com/ragdollKB/taskNote-bridge-mcp.git
cd taskNote-bridge-mcp

# Xcodeで開いてビルド
open "TaskNote Bridge.xcodeproj"

設定

前提条件

• MCP互換のAIアシスタントまたはツール (Claude Desktop、MCP拡張機能付きのVS Code、Cursor、Continue、Zedなど)
• Things 3 (設定 -> 全般で "Things URLを有効にする" をオンにする必要があります)
• Apple Notes (メモ管理機能のため)
• macOS 13.0以上 (SwiftUIとAppleScript統合に必要)

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

このプロジェクトは、異なるユースケースに対応する 2つのMCPサーバー実装 を提供します。

📱 TaskNote Bridge.app (GUIアプリケーション)

• 目的: 視覚的なモニタリングインターフェイス付きのmacOSアプリ
• トランスポート: ネットワークベースの接続のためのTCPサーバー (ポート8000)
• 機能: リアルタイムダッシュボード、接続監視、ログビューア
• ユースケース: サーバーアクティビティの視覚的なモニタリングが必要な場合
• 起動方法: アプリケーションフォルダからアプリを開く

📟 swift_mcp_stdio.swift (コマンドラインサーバー)

• 目的: 軽量な標準入出力ベースのMCPサーバー
• トランスポート: 標準入出力通信
• 機能: 直接的なJSON-RPCメッセージの処理、最小限のオーバーヘッド
• ユースケース: Claude Desktop やほとんどのMCPクライアントにおすすめ
• 起動方法: launch_swift_mcp_stdio.sh スクリプトを介して起動

🔧 どちらを使うべきか？

💡 ポイント: ほとんどのMCPクライアント (Claude Desktopを含む) は、TCP接続ではなく標準入出力ベースの通信を期待しています。

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

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

🎯 Claude Desktop

Claude Desktopを標準入出力ベースのMCPサーバーを使用するように構成します。

1. Claude Desktopを開く
2. 左下の設定アイコン (⚙️) をクリック
3. "開発者" を選択
4. "MCPサーバー" セクションで "設定を編集" をクリック
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は、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. 拡張機能 → 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

標準入出力接続

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

📋 検証手順

任意のクライアントを構成した後:

1. 接続をテスト:

   # 標準入出力テスト
   echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
   
   # TCPテスト (サーバーが実行中の場合)
   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の設定で別のポートを試す
• ファイアウォール設定がローカル接続を許可していることを確認

標準入出力接続問題

• スクリプトのパーミッションを確認: ls -la /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
• スクリプトをターミナルで直接テスト
• Things 3 → 設定 → 全般で "Things URLを有効にする" がオンになっていることを確認

VS Code (MCP拡張機能付き)

1. まず、TaskNote Bridgeアプリがインストールされて実行中であることを確認します。
2. VS Code用のMCP拡張機能をインストールします。
   • VS Codeを開きます。
   • 拡張機能 (Cmd+Shift+X) を開きます。
   • "MCP" を検索し、公式のMCP拡張機能をインストールします。
3. VS Codeの設定を構成します。
   • 設定 (Cmd+,) を開きます。
   • 右上の "設定をJSONで開く" をクリックします。
   • 以下の構成を追加します。

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

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

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

💻 使用例

TaskNote Bridgeアプリでの使用

1. アプリケーションフォルダからTaskNote Bridgeアプリを起動します。
2. アプリは、以下の機能を提供するネイティブmacOSインターフェイスを備えています。
   • Things 3のタスク、プロジェクト、エリアを表示する
   • Apple Notesを管理する
   • MCPサーバーの接続を監視する
   • アクティビティログをリアルタイムで表示する

Claude Desktopでの使用

接続後、自然言語を使用してTaskNote Bridgeと対話できます。

Things 3の例:

• "今日のTODOリストに何がありますか？"
• "来週のビーチバケーションのために荷物を詰めるTODOを作成して"
• "メモリアルデーのバーベキュー用のプロジェクトを作成し、計画タスクを追加する"
• "すべての仕事関連のタスクを表示して"
• "食料品の買い物タスクを完了としてマークする"
• "明日母に電話するタスクを追加する"

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サーバーと組み合わせて、Claudeにタスクの時間を割り当て、カレンダーイベントからTODOを作成させます。

複数クライアントの使用

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

高度なワークフロー

• "アイゼンハワー行列を使用して現在のTODOを評価する"
• "Thingsを使用してGTDスタイルの週次レビューを行うのを支援する"
• "[プロジェクト名] のプロジェクト計画を作成し、サブタスクと期限を設定する"
• "タスクの完了パターンを分析し、改善策を提案する"

🔧 技術詳細

プロジェクト構造

TaskNote Bridge.app/          # macOS Swiftアプリケーション
├── Contents/
│   ├── MacOS/                # MCPサーバーを含むネイティブSwift実行可能ファイル
│   │   └── TaskNote Bridge   # 埋め込みMCPサーバー付きのメインアプリ
│   ├── Resources/            # アプリケーションリソース
│   └── Info.plist            # アプリバンドル構成
├── TaskNote Bridge.xcodeproj/ # Xcodeプロジェクト
├── SwiftMCPServer.swift      # コアMCPサーバー実装
├── ThingsIntegration.swift   # Things 3統合レイヤー
├── NotesIntegration.swift    # Apple Notes統合レイヤー
└── README.md                 # このドキュメント

利用可能なツール

リストビュー

• get-inbox - インボックスからTODOを取得
• get-today - 今日の期限のTODOを取得
• get-upcoming - 予定のTODOを取得
• get-anytime - いつでものTODOリストからTODOを取得
• get-someday - いつかのTODOリストから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 - 項目タイプでフィルタリング (タスク/プロジェクト/見出し)

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を完全に終了して再起動
• ログを確認: ~/Library/Logs/Claude/mcp*.log のClaudeログを確認

TCP接続問題

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

標準入出力接続問題

• スクリプトのパーミッション: ls -la /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh でスクリプトのパーミッションを確認
• 直接テスト: ターミナルでスクリプトを直接テスト
• Things 3のURLを有効化: Things 3 → 設定 → 全般で "Things URLを有効にする" がオンになっていることを確認

ツール実行問題

サーバーには、以下の問題に対する包括的なエラーハンドリングが含まれています。

• 無効なUUIDと不正なリクエスト
• 必須パラメータの欠落
• Things 3データベースへのアクセスエラー
• Apple NotesのAppleScript実行エラー
• データのフォーマットとシリアル化エラー

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

# Claude Desktopのログをリアルタイムで追跡
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

# TaskNote Bridgeアプリのログを確認
# TaskNote Bridgeアプリを開き、組み込みのログビューアを表示

# サーバーを直接テスト
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
• システム環境設定 → セキュリティとプライバシーでTaskNote Bridgeアプリに必要なパーミッションを付与

"Things 3 not responding" エラー

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

"Apple Notes access denied" エラー

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

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

Claude Desktop接続問題

"Request timed out" / サーバーが応答しない

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は 標準入出力ベースの通信 (サブプロセスの起動) を期待しています。
• nc localhost 8000 のアプローチは、netcatを通じてTCPを使用しようとしますが、MCPプロトコルの初期化を適切に処理しません。
• 標準入出力スクリプトは、Claude Desktopが必要とする適切なJSON-RPCメッセージ処理を提供します。

修正方法:

1. Claude Desktopの設定を標準入出力スクリプトを使用するように更新
2. Claude Desktopを再起動
3. これでタイムアウトなしで接続が機能するはずです。

サーバーが機能することを確認

標準入出力サーバーを直接テストします。

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":{}}}}