@헵타베이스/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