KnowledgeHub Mobile Capture

“云飞随手记”의 모바일 작성 서비스이자 OpenAI 플러그인 패키지입니다. 모바일 ChatGPT의 텍스트, 음성 전사, 첨부 파일을 추가 전용(create-only), 덮어쓰기 없음 방식으로 사용자 본인의 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"]

서비스는 쓰기 도구 하나만 등록합니다: 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을 지원하는 자격 증명 발급자를 사용하며, 공개 HTTPS로 배포해야 합니다. ChatGPT는 사용자 지정 API Key로 이 인증 프로세스를 대체하는 것을 지원하지 않습니다. 전체 절차는 배포 설명을 참조하세요.

OpenAI 공식 문서:

• 플러그인 MCP 인증

• 플러그인 연결 및 테스트

• 플러그인 아키텍처

보안 원칙

• GitHub Token은 배포 플랫폼의 Secret에만 저장되며, 저장소, 플러그인 또는 채팅에 포함되지 않습니다.

• Token은 대상 개인 KnowledgeHub 저장소의 Contents 읽기/쓰기에만 권한이 부여됩니다.

• 서비스는 수정, 이동, 덮어쓰기 또는 삭제 도구를 제공하지 않습니다.

• OAuth 모드는 발급자(issuer), 대상(audience), 권한 범위, 사용자 sub 허용 목록을 강제 검증합니다.

• 첨부 파일은 기본 최대 5개, 개별 10MiB, 합계 20MiB입니다. 텍스트는 기본 최대 1MiB입니다.

• 첨부 파일이 생성되었는데 최종 노트 저장이 실패하면 자동 삭제되지 않으며, 응답에 수동 검사가 필요한 경로가 나열됩니다.

KnowledgeHub와의 관계

• KnowledgeHub-Framework가 계약을 정의합니다.

• KnowledgeHub-Setup이 선택적 설치와 초기 안내를 담당합니다.

• 이 저장소는 모바일 원격 진입점을 구현하며, 사용자 데이터나 자격 증명을 저장하지 않습니다.

• 사용자 자신의 개인 KnowledgeHub가 유일한 데이터 원본입니다.

License

MIT