moai-adk 0.8.0__py3-none-any.whl → 0.34.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-mcp-notion/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: moai-mcp-notion
+description: Notion MCP integration specialist for workspace management, database operations, page creation, and knowledge extraction. Use when integrating Notion workspaces, managing databases, or automating documentation workflows.
+version: 1.0.0
+category: integration
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+tags:
+ - mcp
+ - notion
+ - workspace
+ - database
+ - knowledge-management
+ - documentation
+related-skills:
+ - moai-docs-generation
+ - moai-workflow-project
+ - moai-domain-backend
+updated: 2025-12-07
+status: active
+author: MoAI-ADK Team
+---
+
+# 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/` 디렉터리를 참조하세요.*