@헵타베이스/mcp

Heptabase 백업 데이터와 상호 작용하기 위한 모델 컨텍스트 프로토콜(MCP) 서비스입니다. 이 서비스를 통해 Claude와 같은 AI 비서가 Heptabase 화이트보드와 카드를 검색, 불러오기, 분석 및 내보낼 수 있습니다.

특징

🔍 화이트보드와 카드 검색
📁 자동 백업 파일 관리
📄 다양한 포맷(Markdown, JSON, Mermaid)으로 내보내기
🔗 카드 관계 분석
📊 화이트보드 요약 생성
⚡ 성능을 위한 스마트 캐싱

Related MCP server: Supabase MCP Server

빠른 시작

설치 및 설정

복제하고 설치하세요:
지엑스피1
환경 변수를 사용하여 구성:
cp .env.example .env # Edit .env with your actual paths
프로젝트를 빌드하세요:
npm run build
로컬에서 테스트(선택 사항):
npm start

Claude Desktop과 함께 사용

로컬 빌드를 사용하도록 Claude Desktop을 구성하세요.

Claude Desktop 구성 파일을 편집하세요.

macOS : ~/Library/Application\ Support/Claude/claude_desktop_config.json
윈도우 : %APPDATA%\Claude\claude_desktop_config.json
리눅스 : ~/.config/Claude/claude_desktop_config.json

다음 구성을 추가합니다.

{ "mcpServers": { "heptabase": { "command": "/path/to/node", "args": ["/path/to/your/heptabase-mcp/dist/index.js"], "env": { "HEPTABASE_BACKUP_PATH": "/path/to/your/heptabase/backups", "HEPTABASE_AUTO_EXTRACT": "true", "HEPTABASE_WATCH_DIRECTORY": "true" } } } }

중요한:

/path/to/node Node.js 경로로 바꾸세요( which node 찾으세요)
/path/to/your/heptabase-mcp 실제 프로젝트 경로로 바꾸세요.
HEPTABASE_BACKUP_PATH Heptabase 백업 디렉토리로 설정하세요.

자세한 설정 지침은 QUICK_START.md를 참조하세요.

구성

이 프로젝트에서는 개인 정보를 보호하는 구성 시스템을 사용합니다.

예제 파일 (git에 안전): claude-config-example.json , .env.example
개인 파일 (gitignored): claude-config-*personal*.json , .env

자세한 구성 지침은 CONFIG.md를 참조하세요.

기본 사용법

// Configure backup path await mcpClient.callTool({ name: "configureBackupPath", parameters: { path: "/path/to/your/heptabase/backups" } }); // List available backups const backups = await mcpClient.callTool({ name: "listBackups" }); // Search for whiteboards const whiteboards = await mcpClient.callTool({ name: "searchWhiteboards", parameters: { query: "Project Planning" } }); // Get full whiteboard content const whiteboard = await mcpClient.callTool({ name: "getWhiteboard", parameters: { whiteboardId: "your-whiteboard-id", includeCards: true, includeConnections: true } }); // Export to markdown const markdown = await mcpClient.callTool({ name: "exportWhiteboard", parameters: { whiteboardId: "your-whiteboard-id", format: "markdown" } });

사용 가능한 도구

백업 관리

configureBackupPath - 백업 디렉토리 설정
listBackups - 사용 가능한 백업 목록
loadBackup - 특정 백업 로드

검색 작업

searchWhiteboards - 이름이나 콘텐츠로 화이트보드 검색
searchCards - 모든 화이트보드에서 카드 검색

데이터 검색

getWhiteboard - 전체 화이트보드 데이터 가져오기
getCard - 다양한 형식의 카드 콘텐츠 가져오기
getCardContent - 리소스로 카드 콘텐츠 가져오기(크기 제한 우회)
getCardsByArea - 화이트보드에서 위치별로 카드 찾기

내보내기 기능

exportWhiteboard - Markdown, JSON, HTML 형식으로 내보내기
summarizeWhiteboard - AI 기반 요약 생성

분석 도구

analyzeGraph - 카드 관계 및 연결 분석
compareBackups - 다른 백업 버전 비교

디버그 도구

debugInfo - 시스템 상태 및 진단 정보 가져오기

개발

프로젝트 구조

heptabase-mcp/ ├── src/ │ ├── index.ts # Main entry point │ ├── server.ts # MCP server implementation │ ├── services/ # Core business logic │ │ ├── BackupManager.ts # Backup file management │ │ └── HeptabaseDataService.ts # Data querying │ ├── tools/ # MCP tool implementations │ ├── types/ # TypeScript definitions │ └── utils/ # Helper functions ├── tests/ # Test suites ├── docs/ # Documentation └── config files # Configuration templates

테스트

# Run all tests npm test # Run tests in watch mode npm run test:watch # Run with coverage npm run test:coverage # Run integration tests npm run test:integration

건물

# Build for production npm run build # Development mode with auto-reload npm run dev # Type checking only npm run type-check

선적 서류 비치

📚 전체 사양 - 자세한 API 및 아키텍처
🚀 빠른 시작 가이드 - 빠르게 시작하고 실행하세요
⚙️ 구성 가이드 - 안전한 구성 관행
📖 Claude Desktop 설정 - 로컬 개발 설정

개인정보 보호 및 보안

이 프로젝트는 개인정보 보호 원칙을 따릅니다.

✅ 개인 경로는 git에 커밋되지 않습니다.
✅ 백업 데이터는 컴퓨터에 로컬로 저장됩니다.
✅ 구성 템플릿은 안전한 플레이스홀더를 사용합니다.
✅ Gitignore는 민감한 파일을 보호합니다

요구 사항

노드.js 18+
백업 내보내기가 활성화된 Heptabase
Claude Desktop (MCP 통합용)

문제 해결

일반적인 문제

"백업을 찾을 수 없습니다" - HEPTABASE_BACKUP_PATH 가 올바른 디렉토리를 가리키는지 확인하세요.
"명령을 찾을 수 없습니다" - Node.js가 설치되어 있고 경로가 올바른지 확인하세요.
Claude가 도구를 볼 수 없습니다 . 구성 변경 후 Claude Desktop을 완전히 다시 시작하세요.
빌드 오류 - 사용하기 전에 npm install 및 npm run build 실행하세요.

디버그 모드

debugInfo 도구를 사용하여 시스템 상태를 확인하세요.

await mcpClient.callTool({ name: "debugInfo" });

기여하다

기여를 환영합니다! 다음 내용을 알려주세요.

저장소를 포크하세요
기능 브랜치 생성
변경 사항을 만드세요
새로운 기능에 대한 테스트 추가
모든 테스트가 통과되었는지 확인하세요
풀 리퀘스트 제출

아키텍처 세부 사항은 SPECIFICATION.md를 참조하세요.

특허

MIT 라이센스 - 자세한 내용은 라이센스 파일을 참조하세요.

지원하다

🐛 버그 리포트 : GitHub 이슈
💬 질문 : GitHub 토론
📧 보안 문제 : 비공개로 신고해주세요

Heptabase 커뮤니티를 위해 ❤️로 만들었습니다

Heptabase MCP