KnowledgeHub Mobile Capture

The mobile write service and OpenAI plugin pack for “云飞随手记”. It writes text, voice transcriptions, and attachments from the ChatGPT mobile app into the user's own private KnowledgeHub repository on GitHub in an append-only, never overwrite manner.

Current status: the code and the local test baseline are in place. Only after public deployment, OAuth configuration, and acceptance testing on a physical phone are complete will the personal KnowledgeHub be able to mark “Mobile Quick Capture” as enabled.

System boundaries

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"]

The service registers only one write tool: create_quick_capture. The path is generated by the server; the client cannot specify it:

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

Recorded content is never treated as a command, and it is not automatically organized, archived, or turned into tasks. On success, the service must return stored: true, the knowledge-base path, and the Git commit SHA.

Related MCP server: brain-mcp

Repository layout

• src/: MCP HTTP service, OAuth/API Key validation, GitHub create-only writes.

• plugins/knowledgehub-mobile-capture/: installable plugin manifest and the mobile capture Skill.

• test/: path boundary, attachment limit, create-only, and failure semantics tests.

• docs/DEPLOYMENT.md: production mobile deployment and connection steps.

• docs/ACCEPTANCE.md: acceptance steps that must be completed before enabling.

Local development verification

Local API Key mode is for development and Codex debugging only; it cannot serve as the production authentication scheme for the ChatGPT mobile app.

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

Health check: GET http://localhost:8787/health. MCP endpoint: POST http://localhost:8787/mcp with the request header Authorization: Bearer <CAPTURE_API_KEY>.

Production mobile setup

Production mode must set AUTH_MODE=oauth-jwt, use an identity provider that supports MCP OAuth 2.1, and be deployed to a public HTTPS endpoint. ChatGPT does not support replacing this authentication flow with a user-defined API Key. See the deployment guide for the complete steps.

Official OpenAI resources:

• Plugin MCP authentication

• Connecting and testing your plugin

• Plugin architecture

Security principles

• The GitHub Token lives only in the deployment platform's Secrets; it never enters the repository, plugin, or chat.

• The Token is scoped only to Contents read/write on the target private KnowledgeHub repository.

• The service does not provide modify, move, overwrite, or delete tools.

• OAuth mode strictly validates the issuer, audience, scopes, and the user sub allow list.

• Attachments default to at most 5 per request, 10 MiB each, and 20 MiB in total; text defaults to at most 1 MiB.

• If attachments were created but the final note failed, they are not deleted automatically; the receipt lists the paths for manual review.

Relationship with KnowledgeHub

• KnowledgeHub-Framework defines the contract.

• KnowledgeHub-Setup is responsible for the optional installation and onboarding.

• This repository implements the mobile remote entry point and does not store user data or credentials.

• The user's own private KnowledgeHub repository is the sole data authority.

License

MIT