KnowledgeHub Mobile Capture

「云飞随手记」のモバイル向け書き込みサービスと OpenAI プラグインパッケージです。スマートフォンの ChatGPT 内のテキスト、音声文字起こし、添付ファイルを、新規追加のみ・上書きなしの形で、ユーザー自身の GitHub プライベート KnowledgeHub リポジトリに書き込みます。

現在の状態: コードとローカルテストのベースラインは整っています。公開デプロイ、OAuth 設定、モバイル実機での受入検証を完了して初めて、個人の KnowledgeHub は「モバイルクイックキャプチャ」を有効済みとしてマークできます。

システム境界

flowchart LR
    A["手机 ChatGPT\n云飞随手记"] -->|"OAuth + MCP"| B["Mobile Capture 服务"]
    B -->|"仅创建新文件"| C["GitHub 私有 KnowledgeHub"]
    C -->|"git pull"| D["本地 KnowledgeHub"]
    D --> E["Obsidian"]
    D --> F["Codex"]

このサービスは書き込みツールを1つだけ登録します: create_quick_capture。パスはサーバー側で生成され、クライアントは指定できません:

00-Inbox/Human/Quick-Captures/YYYY/MM/<时间戳>-<随机标识>.md
10-Sources/Attachments/Quick-Captures/YYYY/MM/<capture-key>/<文件名>

記録内容はコマンドとして実行されることはなく、自動整理、アーカイブ、タスク作成も行われません。成功時には stored: true、ナレッジベースのパス、Git commit SHA を返す必要があります。

Related MCP server: brain-mcp

リポジトリ構成

• src/: MCP HTTP サービス、OAuth/API Key バリデーション、GitHub の create-only 書き込み。

• plugins/knowledgehub-mobile-capture/: インストール可能なプラグインマニフェストとモバイルキャプチャ用 Skill。

• test/: パス境界、添付ファイル制限、create-only、失敗のセマンティクスのテスト。

• docs/DEPLOYMENT.md: 本番モバイル向けのデプロイと接続手順。

• docs/ACCEPTANCE.md: 有効化する前に行う必要のある受入確認。

ローカル開発での検証

ローカル API Key モードは開発と Codex デバッグのみを目的としており、ChatGPT モバイル向けの本番認証方式としては使用できません。

Copy-Item .env.example .env
# 编辑 .env 后，把变量导入当前终端
npm install
npm test
npm start

ヘルスチェック: GET http://localhost:8787/health。MCP 入口: POST http://localhost:8787/mcp、リクエストヘッダーに Authorization: Bearer <CAPTURE_API_KEY> を指定します。

本番モバイル

本番モードでは AUTH_MODE=oauth-jwt を設定し、MCP OAuth 2.1 をサポートする ID プロバイダーを利用して、パブリックな HTTPS にデプロイする必要があります。ChatGPT は、この認証フローをユーザー定義の API Key に置き換えることをサポートしていません。完全な手順は デプロイ手順 を参照してください。

OpenAI 公式ドキュメント:

• プラグイン MCP 認証

• プラグインの接続とテスト

• プラグインアーキテクチャ

セキュリティ原則

• GitHub トークンはデプロイプラットフォームの Secret にのみ保存され、リポジトリ、プラグイン、チャットに入れません。

• トークンは対象のプライベート KnowledgeHub リポジトリの Contents に対する読み取り書き込みのみを許可します。

• このサービスは編集、移動、上書き、削除の各ツールを提供しません。

• OAuth モードでは、発行者、オーディエンス、権限スコープ、ユーザーの sub ホワイトリストを強制的に検証します。

• 添付ファイルはデフォルトで最大5個、1個あたり10 MiB、合計20 MiBです。テキストはデフォルトで最大1 MiBです。

• 添付ファイルが作成された後、最終的なメモが失敗しても自動削除されません。受領には手動確認が必要なパスが一覧表示されます。

KnowledgeHub との関係

• KnowledgeHub-Framework が契約を定義します。

• KnowledgeHub-Setup がオプションのインストールとオンボーディングを担当します。

• 本リポジトリはモバイルからのリモート入口を実装しますが、ユーザーデータや資格情報を保存しません。

• ユーザー自身のプライベートな KnowledgeHub が、データの唯一の権限です。

ライセンス

MIT