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

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

@@ -1,300 +0,0 @@
----
-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/` 디렉터리를 참조하세요.*