Business Card MCP

AI 네이티브, 자체 호스팅 가능한 개인 명함 라이브러리. 사용자가 ChatGPT에 명함을 업로드하면 기존 멀티모달 모델이 인식하고 확인하며, Remote MCP가 검증, 개인 저장, 검색, 수정, 보관 및 내보내기를 담당하며 추가 모델 API를 호출하지 않습니다.

기능

• ChatGPT Remote MCP: 명함 생성, 검색, 읽기, 업데이트, 보관 및 내보내기

• 개인 관리 웹사이트: 자체 설정 비밀번호 로그인, 카드 월/목록 보기, 보호된 썸네일

• D1 FTS5: 이름, 회사, 직함, 전화, 이메일, 주소, 태그, 상황 및 메모 검색

• R2: 개인 Markdown 및 480px WebP 썸네일

• KV: 사용자별 독립적인 bc_ Connector Key

• 작성 후 클릭 가능한 명함 확인 페이지 반환

• 썸네일은 명함 생성 시 필수 필드로, 이미지 없는 데이터 생성을 방지

현재는 키워드 전문 검색이며, embedding/벡터 의미론적 검색이 아닙니다.

Related MCP server: DuckPond MCP Server

아키텍처

ChatGPT / Claude
       │ Remote MCP
       ▼
Cloudflare Worker ── WEB_PASSWORD 或可選 Cloudflare Access JWT 驗證
       ├── D1：聯絡人與 FTS5
       ├── R2：Markdown、WebP 縮圖
       ├── KV：MCP Key
       └── Static Assets：私人管理網站

원본 명함 이미지는 기본적으로 저장하지 않습니다. GitHub repo에는 코드, migration 및 합성 테스트 데이터만 포함되며 사용자 연락처는 포함되지 않습니다.

MCP Tools

배포 요구 사항

• Node.js 20+

• Cloudflare 계정

• Wrangler CLI가 올바른 Cloudflare 계정에 로그인

배포

1. 설치 및 로컬 설정 생성

npm install
cp public/config.example.js public/config.js

wrangler.jsonc는 repo에 제로 값 플레이스홀더 버전(SmallGreen 표준은 정적으로 판별 가능한 리소스 선언 필요)으로 제공되며, 다음 단계에서 실제 ID를 채워 넣습니다. 채운 후 git update-index --skip-worktree wrangler.jsonc를 실행하여 실제 ID가 commit되지 않도록 하는 것을 권장합니다. public/config.js는 Git에서 무시되며, 웹 인증에는 프론트엔드 설정이 필요하지 않습니다.

2. Cloudflare 리소스 생성

npx wrangler d1 create business-card-mcp
npx wrangler r2 bucket create business-card-mcp-assets
npx wrangler kv namespace create CARD_KEYS

Cloudflare가 반환한 account, D1 및 KV ID를 wrangler.jsonc에 채우고 다음을 설정합니다:

• PUBLIC_BASE_URL

• R2 bucket 이름

그 다음 웹 로그인용 자체 설정 비밀번호를 설정합니다. 비밀번호는 Wrangler secret으로만 처리되며 wrangler.jsonc에 기록하지 않습니다:

npx wrangler secret put WEB_PASSWORD

CF_ACCESS_TEAM_DOMAIN과 CF_ACCESS_AUD는 기본적으로 비워 두면 됩니다. 비워 두면 웹이 비밀번호 로그인을 사용하며 카드 등록이 필요 없습니다.

3. 선택적 업그레이드: Cloudflare Access email OTP

Cloudflare가 엣지에서 먼저 email One-Time PIN을 수행하도록 변경하려면 이 섹션을 설정합니다. Zero Trust onboarding은 신용카드 등록을 요구할 수 있습니다. 무료 플랜 자체는 $0입니다.

1. Cloudflare Zero Trust에서 이 Worker 도메인을 보호하는 self-hosted Access application을 생성합니다.

2. 로그인 방식으로 One-Time PIN을 활성화하고, email 또는 email domain policy로 로그인 가능한 사용자를 제한합니다.

3. 브라우저 UI와 /api/*가 모두 Access 보호 범위 내에 있는지 확인합니다.

4. /mcp 경로를 Access 로그인 요구에서 제외합니다. 예: path-based Bypass policy를 사용하거나 Access가 적용되지 않는 경로 규칙으로 분리합니다. /mcp는 여전히 bc_ MCP key로 인증되며, ChatGPT/Claude는 Cloudflare Access cookie를 전달하지 않습니다.

5. 해당 Access application의 Audience tag를 CF_ACCESS_AUD에, Zero Trust team domain을 CF_ACCESS_TEAM_DOMAIN에 채운 후 다시 배포합니다. 채운 후 Access를 통과한 웹 요청은 자동으로 허용되며 자체 설정 비밀번호를 묻지 않습니다.

4. Migration, 테스트 및 배포

npx wrangler types
npm run typecheck
npm test
npx wrangler d1 migrations apply business-card-mcp --remote
npx wrangler deploy

5. ChatGPT 연결

1. 배포된 웹사이트를 열고 WEB_PASSWORD로 설정한 자체 비밀번호를 입력합니다. Cloudflare Access로 업그레이드한 경우 email One-Time PIN으로 인증합니다.

2. 명함 MCP Key를 생성합니다.

3. 전체 Connector URL을 복사합니다. URL에 Key가 포함되어 있으므로 비밀번호와 동일하게 취급합니다.

4. ChatGPT 개발자 모드에서 Remote MCP를 추가합니다.

5. 도구를 스캔한 후 "명함 MCP로 OO 검색"으로 테스트합니다.

로컬 개발

npm run migrate:local
npm run dev

헬스 체크: GET /healthz

Remote MCP: POST /mcp

보안 및 개인정보

• 모든 명함 조회는 비밀번호로 로그인한 owner, Cloudflare Access sub 또는 MCP Key 소유자로 제한됩니다.

• R2 bucket은 비공개로 유지됩니다. 썸네일은 로그인으로 보호된 API가 제공합니다.

• MCP는 Bearer token과 Connector URL query token을 모두 허용합니다.

• 전체 Key는 생성 시에만 표시되며 개별 취소를 지원합니다.

• .env, .dev.vars, wrangler.jsonc 또는 public/config.js를 commit하지 마십시오.

보안 문제는 SECURITY.md에 따라 비공개로 신고하고 공개 Issue를 만들지 마십시오.

검증

npm test
npm run typecheck
npm audit --omit=dev

프로젝트에는 현재 단위, MCP protocol, Web API, 권한, 저장소 및 UI 계약 테스트가 있습니다. coverage threshold는 lines/functions/statements 80%, branches 75%입니다.

알려진 제한 사항

• 벡터 의미론적 검색은 아직 제공되지 않습니다.

• 기존 이미지 없는 명함에는 이미지 보충 인터페이스가 아직 제공되지 않습니다. 새 데이터는 썸네일 필수 입력이 강제됩니다.

• 영구 삭제는 기본적으로 허용되지 않으며, 실수 삭제를 방지하기 위해 보관을 사용합니다.

License

Apache-2.0. 자세한 내용은 LICENSE를 참조하십시오.