moai-mcp-notion

# Notion MCP Integration Specialist

## Quick Reference (30 seconds)

Notion MCP Integration - 전문화된 MCP (Model Context Protocol) 기반 Notion 워크스페이스 통합 전문가입니다. 데이터베이스 쿼리, 페이지 관리, 지식 추출, 그리고 문서화 자동화를 제공합니다.

핵심 기능:
- Notion API 통합: MCP 서버 설정, 인증, 워크스페이스 접근
- 데이터베이스 작업: 쿼리, 필터링, 생성, 업데이트, 관계 관리
- 페이지 관리: 페이지 생성/업데이트, 블록 작업, 콘텐츠 추출
- 지식 추출: 자동화된 분석, 구조화, 문서 생성
- 템플릿 자동화: 재사용 가능한 페이지 템플릿, 워크플로우 자동화

사용 시점:
- Notion 워크스페이스와 외부 시스템 통합
- 데이터베이스 쿼리 및 자동화된 콘텐츠 관리
- 지식 베이스 추출 및 문서 생성
- 페이지 템플릿 자동화 및 배치 작업

---

## Implementation Guide (5 minutes)

### Quick Start Workflow

Notion MCP 서버 설정:
```python
from moai_mcp_notion import NotionMCPServer, NotionConnector

# Notion MCP 서버 초기화
notion_server = NotionMCPServer("notion-integration")

# Notion 커넥터 설정
connector = NotionConnector({
 'api_key': os.getenv('NOTION_TOKEN'),
 'api_version': '2022-06-28'
})

# 서버에 커넥터 등록
notion_server.register_connector(connector)

# 도구 등록 및 서버 시작
connector.register_tools(notion_server)
notion_server.start(port=3001)
```

기본 데이터베이스 작업:
```bash
# 데이터베이스 쿼리
mcp-tools query_notion_database --database-id "abc123" --filter '{"property": "Status", "select": {"equals": "Active"}}'

# 페이지 생성
mcp-tools create_notion_page --database-id "abc123" --properties '{"Title": {"title": [{"text": {"content": "New Page"}}]}}'

# 페이지 업데이트
mcp-tools update_notion_page --page-id "xyz789" --properties '{"Status": {"select": {"name": "Completed"}}}'

# 블록 추가
mcp-tools append_blocks --page-id "xyz789" --blocks '{"type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Content"}}]}}'
```

### 핵심 컴포넌트

1. Notion API 통합 (`modules/notion-api-integration.md`)
- MCP 서버 설정 및 초기화
- Notion API 인증 (OAuth 2.0, Integration Token)
- 워크스페이스 및 데이터베이스 접근 권한 관리
- API 버전 관리 및 호환성 보장

2. 데이터베이스 작업 (`modules/database-operations.md`)
- 고급 쿼리: 필터, 정렬, 페이지네이션
- 데이터베이스 생성 및 스키마 정의
- 속성 관리: 텍스트, 숫자, 선택, 날짜, 관계
- 관계 및 롤업 설정
- 배치 작업 및 대량 데이터 처리

3. 페이지 관리 (`modules/page-management.md`)
- 페이지 생성: 속성 설정, 초기 콘텐츠
- 페이지 업데이트: 속성 변경, 콘텐츠 추가/삭제
- 블록 레벨 작업: 단락, 제목, 목록, 코드 블록
- 중첩 블록 구조 관리
- 페이지 메타데이터 추출

4. 지식 추출 및 자동화 (`modules/knowledge-extraction.md`)
- 자동화된 콘텐츠 분석
- 구조화된 지식 베이스 생성
- AI 기반 요약 및 인사이트 추출
- 문서 생성 및 템플릿 적용

---

## Advanced Patterns (10+ minutes)

고급 구현 패턴 (복잡한 쿼리, 페이지 구조, 지식 추출, 템플릿 자동화, 배치 작업)은 별도 파일에서 제공됩니다:

자세한 내용: [Advanced Patterns](advanced-patterns.md)

### 주요 고급 패턴 요약

데이터베이스 쿼리:
- 복잡한 필터 조건 (and, or 연산자)
- 페이지네이션 처리
- 정렬 및 검색 최적화

페이지 및 블록 관리:
- 구조화된 페이지 생성 (헤딩, 단락, 목록)
- 중첩 블록 구조 (토글, 칼럼)
- 블록 레벨 조작

지식 베이스 워크플로우:
- 자동화된 콘텐츠 추출
- AI 기반 분석 및 구조화
- 문서 자동 생성

템플릿 자동화:
- 재사용 가능한 페이지 템플릿
- 변수 기반 콘텐츠 생성
- 템플릿 관리 시스템

배치 작업:
- 대량 페이지 업데이트
- 데이터베이스 동기화
- 실시간 이벤트 처리 (Webhook)

---

## Works Well With

보완 스킬:
- `moai-docs-generation` - 자동화된 문서 생성 워크플로우
- `moai-workflow-project` - 프로젝트 관리 및 문서화
- `moai-domain-backend` - 백엔드 API 통합 패턴
- `moai-foundation-claude` - Claude Code 통합 패턴

외부 서비스:
- Notion API (워크스페이스, 데이터베이스, 페이지)
- OAuth 2.0 인증 제공자
- REST API 통합
- 클라우드 스토리지 서비스

통합 플랫폼:
- FastMCP 서버 프레임워크
- AsyncIO 비동기 작업
- Pydantic 데이터 검증
- HTTPX HTTP 클라이언트

---

## 사용 예시

### 데이터베이스 쿼리 및 분석

기본 쿼리:
```python
# 활성 상태 항목 쿼리
active_items = await notion_server.invoke_tool("query_notion_database", {
 "database_id": "project-db",
 "filter": {
 "property": "Status",
 "select": {"equals": "Active"}
 }
})

# 우선순위 높은 작업 쿼리
high_priority = await notion_server.invoke_tool("query_notion_database", {
 "database_id": "tasks-db",
 "filter": {
 "and": [
 {"property": "Priority", "select": {"equals": "High"}},
 {"property": "Assignee", "people": {"is_not_empty": True}}
 ]
 },
 "sorts": [{"property": "Due Date", "direction": "ascending"}]
})
```

### 페이지 생성 및 업데이트

새 페이지 생성:
```python
# 프로젝트 문서 페이지 생성
project_page = await notion_server.invoke_tool("create_notion_page", {
 "database_id": "documentation-db",
 "properties": {
 "Title": {"title": [{"text": {"content": "API Documentation"}}]},
 "Category": {"select": {"name": "Technical"}},
 "Status": {"select": {"name": "In Progress"}},
 "Tags": {"multi_select": [{"name": "API"}, {"name": "Backend"}]}
 }
})

# 콘텐츠 블록 추가
await notion_server.invoke_tool("append_blocks", {
 "page_id": project_page["id"],
 "blocks": [
 {
 "type": "heading_1",
 "heading_1": {"rich_text": [{"text": {"content": "API Documentation"}}]}
 },
 {
 "type": "paragraph",
 "paragraph": {"rich_text": [{"text": {"content": "Comprehensive API reference"}}]}
 },
 {
 "type": "code",
 "code": {
 "rich_text": [{"text": {"content": "GET /api/users\nPOST /api/users"}}],
 "language": "bash"
 }
 }
 ]
})
```

### 지식 베이스 관리

지식 추출 및 구조화:
```python
# 지식 베이스 추출
knowledge = await notion_server.invoke_tool("knowledge_extraction_workflow", {
 "database_id": "knowledge-base",
 "analysis_goals": ["best_practices", "patterns", "lessons_learned"],
 "output_format": "structured_json"
})

# 분석 결과를 새 페이지로 저장
summary_page = await notion_server.invoke_tool("create_notion_page", {
 "database_id": "summaries-db",
 "properties": {
 "Title": {"title": [{"text": {"content": "Knowledge Base Summary"}}]},
 "Type": {"select": {"name": "Analysis"}}
 }
})

# 분석 결과 블록 추가
await notion_server.invoke_tool("append_blocks", {
 "page_id": summary_page["id"],
 "blocks": knowledge["structured_blocks"]
})
```

---

## 기술 스택

핵심 프레임워크:
- FastMCP (Python MCP 서버 프레임워크)
- AsyncIO (비동기 작업 처리)
- Pydantic (데이터 검증 및 스키마 관리)
- HTTPX (HTTP 클라이언트 작업)

Notion 통합:
- Notion API (공식 REST API)
- OAuth 2.0 (인증 및 권한 관리)
- Webhook (실시간 이벤트 수신)
- Rich Text 객체 (복잡한 콘텐츠 구조)

보안 및 인증:
- OAuth 2.0 구현
- Integration Token 관리
- JWT 토큰 처리
- 안전한 자격 증명 저장

오류 처리 및 신뢰성:
- 재시도 메커니즘 (지수 백오프)
- 속도 제한 처리 (Rate Limiting)
- 포괄적인 오류 분류
- 모니터링 및 관찰 가능성

개발 도구:
- 타입 힌트 및 검증
- 포괄적인 로깅
- 성능 모니터링
- 디버깅 및 프로파일링 도구

---

*자세한 구현 패턴, 커넥터 개발, 고급 워크플로우는 `modules/` 디렉터리를 참조하세요.*