🚀 GoogleUnlimited Google Workspace 플랫폼

GoogleUnlimited는 고급 미들웨어 아키텍처를 통해 Google Workspace와의 원활한 통합을 제공하는 포괄적인 MCP 프레임워크입니다. AI 어시스턴트와 MCP 클라이언트가 Gmail, Google Drive, Sheets, Docs, Slides, Calendar, Forms, Chat, Photos, Contacts(People API) 서비스를 통합된 보안 API로 상호작용할 수 있게 해줍니다.

차별화된 특징:

• ⚡ 기본 코드 모드(Code Mode) — 90개 이상의 도구 스키마로 클라이언트를 채우는 대신, 서버는 7개의 경량 메타 도구만 노출합니다. AI는 필요 시 도구를 발견하고 단일 샌드박스 execute 블록 내에서 실제 API 호출을 연결합니다.

• 🚀 제로 구성 시작 — .env 파일 없이도 서버가 즉시 실행됩니다. OAuth는 최초 사용 시 지연 처리됩니다.

• 🔧 세션별 도구 제어 — URL 기반 서비스 필터링과 세션 범위 활성화/비활성화를 통해 각 연결된 클라이언트는 필요한 도구만 정확히 볼 수 있습니다.

• 🎨 템플릿 및 카드 DSL 시스템 — Jinja2 매크로와 간결한 카드 표기법으로 원시 API 데이터를 풍부한 이메일, 대시보드, Google Chat 카드로 변환합니다.

• 🧠 시맨틱 메모리 — 모든 도구 응답이 Qdrant에 임베딩되어, 이후 자연어로 검색할 수 있습니다.

📋 목차

• 빠른 설치 안내

• 코드 모드(기본값)

• 서비스 기능

• 미들웨어 아키텍처

• 도구 관리 대시보드

• 템플릿 시스템

• 리소스 탐색

• 테스트 프레임워크

• 보안 및 인증

Related MCP server: mcp-google-workspace

⚡ 빠른 설치 안내

GoogleUnlimited란?

GoogleUnlimited는 Model Context Protocol(MCP)을 통해 AI 어시스턴트에게 Google Workspace 서비스에 대한 액세스를 제공합니다. 9개의 Google 서비스에서 92개 이상의 도구를 지원하며, AI 워크플로우와 Google Workspace 애플리케이션 간의 혁신적인 성능 향상을 가능하게 합니다.

🛠️ 설치 방법

방법 1: uvx로 빠른 설치(권장)

가장 빠르게 시작하는 방법 — PyPI에서 직접 설치:

{
  "mcpServers": {
    "google-workspace-unlimited": {
      "command": "uvx",
      "args": ["google-workspace-unlimited"],
      "disabled": false,
      "timeout": 300
    }
  }
}

⚡ 끝입니다! 서버는 기본적으로 stdio 모드로 실행되며, Claude Desktop, Cursor, Roo 등의 MCP 클라이언트에 적합합니다. 코드 모드가 기본적으로 활성화되어 있어, 클라이언트는 90개 이상의 스키마 대신 7개의 간결한 메타 도구를 확인할 수 있습니다.

방법 1b: Claude Code 플러그인(서버 + 스킬)

Claude Code 사용자는 두 가지 명령만으로 서버 및 Claude에게 카드/이메일 DSL, 코드 모드, Qdrant 검색을 가르치는 스킬을 설치할 수 있습니다:

/plugin marketplace add dipseth/google_workspace_fastmcp2
/plugin install google-workspace-unlimited@riversunlimited

자세한 내용은 plugins/google-workspace-unlimited를 참조하세요.

방법 2: 클론 및 개발 환경 설정

개발 또는 커스터마이징을 위한 방법:

1. 클론 및 설정:

   git clone https://github.com/dipseth/google_workspace_fastmcp2.git
   cd google_workspace_fastmcp2
   uv sync

2. 서버 시작:

   uv run python server.py

   서버는 구성 없이 즉시 시작됩니다. OAuth 자격 증명은 Google 서비스와 처음 상호작용할 때 지연 처리되므로 시작 시 필요하지 않습니다.

3. 인증 준비:

   Google Workspace 도구를 호출하면 서버가 start_google_auth 도구를 통해 인증을 요청합니다. 브라우저 기반 OAuth 흐름이 시작되며, 완료 후 자격 증명은 로컬에 저장되어 이후 세션에서 재사용됩니다.

   OAuth 자격 증명을 사전 구성하려면(선택 사항), .env 파일을 생성하세요:

   cp .env.example .env

   그런 다음 Google Cloud Console 자격 증명을 추가하세요:

   # Option A: Client ID + Secret
   GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
   GOOGLE_CLIENT_SECRET=your-client-secret
   
   # Option B: Downloaded JSON credentials file
   GOOGLE_CLIENT_SECRETS_FILE=credentials.json

   OAuth 자격 증명 생성 및 API 활성화 방법은 Google Cloud Console 설정 단계를 참조하세요.

📚 구성 리소스:

• 🔧 전체 구성 가이드 — 포괄적인 환경 변수 및 설정 참조

• 🤖 Claude.ai 통합 가이드 — Claude.ai 원격 MCP 서버 사용 설정

• 🔒 HTTPS 설정 가이드 — 보안 연결을 위한 SSL 인증서 구성

• ⚙️ MCP JSON 구성 가이드 — 호환 가능한 모든 클라이언트를 위한 표준 MCP 구성

📋 환경 변수 참조

모든 환경 변수는 선택 사항입니다 — 서버는 합리적인 기본값으로 시작하며 .env 파일이 필요 없습니다. OAuth 자격 증명은 start_google_auth를 통한 최초 인증 흐름에서만 필요합니다.

Google OAuth(최초 인증 시 필요):

최초 OAuth 흐름 전에 GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET 또는 GOOGLE_CLIENT_SECRETS_FILE 중 하나를 제공하세요. 인증이 완료되면 자격 증명은 로컬에 저장되며 더 이상 이 변수가 필요하지 않습니다.

서버:

보안 및 세션:

도구 관리:

Qdrant 벡터 데이터베이스:

기타:

🔗 클라이언트 연결

GoogleUnlimited는 여러 연결 방법을 지원합니다. 시작하는 가장 인기 있는 두 가지 방법은 다음과 같습니다:

🎯 빠른 설정 옵션

옵션 1: Cursor IDE (STDIO - 커뮤니티 검증 완료 ✅):

{
  "mcpServers": {
    "google-workspace": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/google_workspace_fastmcp2",
        "run", "python", "server.py"
      ],
      "env": {
        "GOOGLE_CLIENT_SECRETS_FILE": "/path/to/client_secrets.json",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

옵션 2: HTTP Streamable (VS Code Roo, Claude Code, Claude Desktop 등):

# Start server in HTTP mode
uv run python server.py --transport http --port 8002

기본 단일 연결 구성:

{
  "google-workspace": {
    "type": "streamable-http",
    "url": "https://localhost:8002/mcp",
    "disabled": false
  }
}

다중 연결 설정 — 동일한 클라이언트(또는 여러 클라이언트)를 URL 쿼리 매개변수를 사용하여 서로 다른 도구 세트로 동일한 서버에 연결:

{
  "google-email": {
    "type": "streamable-http",
    "url": "https://localhost:8002/mcp?service=gmail"
  },
  "google-chat": {
    "type": "streamable-http",
    "url": "https://localhost:8002/mcp?service=chat"
  },
  "google-productivity": {
    "type": "streamable-http",
    "url": "https://localhost:8002/mcp?service=drive,docs,sheets,slides"
  }
}

각 연결은 요청된 서비스 도구만 활성화된 격리된 세션을 갖습니다. ?uuid=로 세션 ID를 고정하여 재연결 시 동일한 세션 상태를 재개할 수도 있습니다:

{
  "google-workspace": {
    "type": "streamable-http",
    "url": "https://localhost:8002/mcp?uuid=my-workspace&service=gmail,drive,calendar"
  }
}

전체 쿼리 매개변수 목록은 URL 기반 서비스 필터링을 참조하세요.

🤖 Claude Code 및 Claude Desktop

Claude Code (CLI) — 게시된 PyPI 패키지를 사용하는 단일 명령:

# Local stdio (recommended): uvx fetches and runs the server on demand
claude mcp add google-workspace -- uvx google-workspace-unlimited

# Or connect to an already-running HTTP server
claude mcp add --transport http google-workspace https://localhost:8002/mcp

Claude Desktop (로컬 개발 경로) — claude_desktop_config.json에 추가 (설정 → 개발자 → 구성 편집):

{
  "mcpServers": {
    "google-workspace-unlimited": {
      "command": "uvx",
      "args": ["google-workspace-unlimited"]
    }
  }
}

Claude.ai / Claude Desktop (호스팅 커넥터) — 공개 HTTPS 엔드포인트(예: Cloudflare 또는 ngrok 터널) 뒤에서 서버를 실행한 다음, 설정 → 커넥터 → 사용자 지정 커넥터 추가에서 https://your-domain/mcp URL로 추가합니다. 서버의 OAuth 2.1 + PKCE 흐름이 https://claude.ai/api/mcp/auth_callback 리디렉션을 포함한 인증을 처리합니다. 전체 안내는 Claude.ai 통합 가이드를 참조하세요.

📚 전체 연결 가이드

지원되는 모든 클라이언트에 대한 자세한 설정 지침, 문제 해결 및 구성:

• Claude Code CLI (HTTP 및 STDIO)

• Claude Desktop

• VS Code / Roo / GitHub Copilot

• Cloudflare Tunnel을 사용한 Claude.ai

• 그 외...

🔗 전체 클라이언트 연결 가이드 - 지원되는 모든 AI 클라이언트 및 개발 환경에 대한 종합적인 설정 지침, 문제 해결 및 고급 구성

⚡ 코드 모드 (기본값)

코드 모드는 GoogleUnlimited의 대표 기능이며 기본적으로 활성화되어 있습니다. 90개 이상의 도구 스키마를 미리 로드하는 대신(토큰 비용이 높음), MCP 클라이언트는 7개의 메타 도구만 볼 수 있습니다. AI는 필요에 따라 도구를 발견한 다음, 샌드박스 처리된 단일 Python execute 블록 내에서 여러 실제 API 호출을 연결합니다.

중요한 이유:

• 💰 대규모 토큰 절약 — 90개 이상 대신 7개 스키마, 실제 사용된 도구에 대해서만 전체 스키마 가져오기

• 🔗 여러 왕복 대신 단일 왕복 — 검색 → 필터 → 실행이 클라이언트 왕복 체인이 아닌 단일 execute 블록 내에서 발생

• 🧰 완비된 샌드박스 — 40개 이상의 내장 헬퍼(now(), days_ago(), to_json(), re_find(), gather_tools() 등)가 가져오기 없이 날짜, JSON, URL, 정규식, 수학 및 일괄 호출을 처리

# One execute block: find a Drive file, then email its link
files = await call_tool("search_drive_files", {"query": "Q4 report"})
link = files["files"][0]["webViewLink"]
result = await call_tool("send_gmail_message", {
    "to": "manager@company.com",
    "subject": "Q4 Report",
    "body": "Here's the Q4 report: " + link,
})
return result

클래식 카탈로그를 선호하시나요? 옵트아웃하면 모든 도구가 클라이언트에 직접 노출됩니다:

ENABLE_CODE_MODE=false   # expose the full 90+ tool catalog instead

코드 모드와 클래식 카탈로그는 상호 배타적입니다 — 코드 모드가 활성화되면 직접 도구 호출이 검색 + execute 패턴으로 대체됩니다. 검색 도구는 세션 수준 필터링과 관계없이 항상 전체 카탈로그를 볼 수 있습니다.

🎯 서비스 기능

GoogleUnlimited는 10개의 Google Workspace 서비스와 90개 이상의 전문 도구를 지원합니다:

📚 API 문서 리소스:

• 🔗 전체 API 참조 - 10개 서비스의 92개 이상 도구에 대한 종합 문서

• 📧 Gmail API 가이드 - 이메일 관리, 라벨, 필터 및 검색 작업

• 📁 Drive API 가이드 - 파일 작업, 공유 및 Office 문서 처리

• 📊 Sheets API 가이드 - 스프레드시트 데이터 조작 및 서식

• 📅 Calendar API 가이드 - 이벤트 일정 및 시간대 관리

🧠 미들웨어 아키텍처

GoogleUnlimited는 원활한 서비스 통합, 지능형 리소스 관리 및 강력한 템플릿 기능을 제공하는 미들웨어 아키텍처를 사용합니다.

🔧 핵심 미들웨어 구성 요소

• 🏷️ TagBasedResourceMiddleware: URI 패턴(service://gmail/messages, user://current/email)을 사용한 지능형 리소스 검색

• 🧠 QdrantUnifiedMiddleware: 벡터 임베딩을 통한 모든 도구 응답의 AI 기반 의미론적 검색

• 🎨 TemplateMiddleware: 아름답고 구조화된 출력 서식을 위한 고급 Jinja2 템플릿 시스템

✨ 아키텍처 이점

• 🔄 통합 리소스 액세스: API 호출 없이 서비스 데이터에 대한 URI 기반 액세스

• 🧠 의미론적 지능: 저장된 모든 응답에 대한 자연어 검색

• 🎨 시각적 우수성: 최적의 AI 소비를 위한 일관되고 아름다운 출력 서식

• 💰 토큰 효율성: 템플릿 매크로가 구조화된 데이터 렌더링을 통해 토큰 사용량을 60-80% 절감

• ⚡ 성능: 지능형 캐싱을 통해 기존 방식보다 30배 빠름

📚 미들웨어 문서 리소스:

• 📖 미들웨어 아키텍처 가이드 - 완전한 미들웨어 시스템 문서 및 구현 세부 정보

• 🏷️ TagBasedResourceMiddleware - URI 패턴 리소스 검색 및 관리

• 🧠 QdrantUnifiedMiddleware - AI 기반 의미론적 검색 및 벡터 임베딩

• 🎨 TemplateMiddleware - 출력 서식을 위한 고급 Jinja2 템플릿 시스템

• 🔧 SessionToolFilteringMiddleware - 세션별 도구 활성화/비활성화 관리

🚀 최소 도구 시작

기본적으로 GoogleUnlimited는 최적의 성능과 보안을 위해 5개의 보호 도구만 활성화한 상태로 시작합니다. 이를 통해 클라이언트는 필요한 도구만 활성화할 수 있습니다.

보호 도구 (항상 사용 가능):

• manage_tools - 전역 또는 세션별 도구 활성화/비활성화

• manage_tools_by_analytics - 분석 기반 도구 관리

• health_check - 서버 상태 및 구성 확인

• start_google_auth - OAuth 인증 시작

• check_drive_auth - 인증 상태 확인

구성:

# Default: Start with minimal tools (only 5 protected tools)
MINIMAL_TOOLS_STARTUP=true

# Optional: Pre-enable specific services at startup
MINIMAL_STARTUP_SERVICES=drive,gmail,calendar

# Disable minimal startup (enable all 92+ tools immediately)
MINIMAL_TOOLS_STARTUP=false

런타임 시 도구 활성화:

# Enable all tools globally
manage_tools(action="enable_all")

# Enable specific tools
manage_tools(action="enable", tool_names=["search_drive_files", "list_gmail_labels"])

# List all registered tools (shows enabled/disabled status)
manage_tools(action="list")

🔧 세션 범위 도구 관리

GoogleUnlimited는 세션별 도구 활성화/비활성화 기능을 지원하여, 다른 연결된 클라이언트에 영향을 주지 않고 서로 다른 MCP 클라이언트가 서로 다른 도구 가용성을 가질 수 있게 합니다.

주요 기능:

• 세션 격리: 다른 클라이언트에 영향을 주지 않고 한 클라이언트 세션의 도구 비활성화

• 비침습적: 세션 범위 작업은 전역 도구 레지스트리를 수정하지 않음

• 보호 도구: 핵심 관리 도구(manage_tools, health_check 등)는 항상 사용 가능

• 미들웨어 기반: 프로토콜 수준 필터링을 위해 SessionToolFilteringMiddleware 사용

사용 예시:

# Disable tools for this session only (other clients unaffected)
manage_tools(action="disable", tool_names=["send_gmail_message"], scope="session")

# Disable all except specific tools for this session
manage_tools(action="disable_all_except", tool_names=["search_drive_files", "list_events"], scope="session")

# Re-enable all tools for this session
manage_tools(action="enable_all", scope="session")

# Global operations (original behavior, affects all clients)
manage_tools(action="disable", tool_names=["send_gmail_message"], scope="global")

응답 구조:

{
  "success": true,
  "action": "disable_all_except",
  "scope": "session",
  "enabledCount": 94,
  "disabledCount": 0,
  "toolsAffected": ["tool1", "tool2", "..."],
  "sessionState": {
    "sessionId": "f725be09...",
    "sessionAvailable": true,
    "sessionDisabledTools": ["tool1", "tool2"],
    "sessionDisabledCount": 89
  },
  "message": "Kept 5 tools, disabled 89 tools for this session"
}

📚 스킬 제공자

ENABLE_SKILLS_PROVIDER=true로 활성화하면 GoogleUnlimited는 ModuleWrapper 인스턴스에서 스킬 문서를 생성하고 FastMCP의 SkillsDirectoryProvider를 통해 제공합니다. 스킬은 LLM이 복잡한 다단계 작업에 참조할 수 있는 구조화된 지식을 제공합니다.

현재 지원되는 모듈:

• card_framework → gchat-cards 스킬 (Google Chat 카드 DSL 참조, 구성 요소 계층, 예제)

구성:

ENABLE_SKILLS_PROVIDER=true     # Enable skill generation
SKILLS_DIRECTORY=~/.claude/skills  # Output directory (default)

스킬은 각 시작 시 자동으로 재생성되며 FastMCP 스킬 시스템을 통해 즉시 사용할 수 있습니다.

🖥️ 도구 관리 대시보드

GoogleUnlimited는 MCP Apps ui:// 리소스 스킴을 통해 제공되는 내장 도구 관리 대시보드를 포함합니다. 이는 세션 전반의 도구 가용성을 모니터링하고 관리하기 위한 시각적 인터페이스를 제공합니다.

기능:

• 서비스 그룹별 도구 보기 — Google 서비스(Gmail, Drive, Sheets 등)별로 도구를 개수와 함께 구성

• 세션 상태 가시성 — 활성화, 비활성화 또는 세션 비활성화된 도구를 한눈에 확인

• 필터 칩 — 서비스별로 빠르게 필터링하여 관련 도구에 집중

• 실시간 데이터 — 인스턴트 ui://data-dashboard 리소스 액세스를 위해 list-tool 결과를 캐시하는 DashboardCacheMiddleware 기반

대시보드는 wire_dashboard_to_list_tools()를 통해 모든 목록 도구에 자동으로 연결됩니다 — 도구별 구성이 필요 없습니다.

🔗 URL 기반 서비스 필터링 (HTTP 전송)

HTTP/SSE 전송을 사용할 때 코드 없이 URL 쿼리 매개변수를 통해 서비스별로 도구를 필터링할 수 있습니다:

# Enable only Gmail tools
http://localhost:8002/mcp?service=gmail

# Enable Gmail + Drive + Calendar
http://localhost:8002/mcp?service=gmail,drive,calendar

# Resume a previous session
http://localhost:8002/mcp?uuid=your-session-id

# Resume session with specific services
http://localhost:8002/mcp?uuid=abc123&service=gmail,drive

# Disable minimal startup (enable all tools)
http://localhost:8002/mcp?minimal=false

사용 가능한 URL 매개변수:

사용 가능한 서비스: gmail, drive, calendar, docs, sheets, slides, photos, chat, forms, people

📚 세션 도구 관리 리소스:

• 🔧 SessionToolFilteringMiddleware 가이드 - 세션별 도구 관리에 대한 전체 문서

🎨 템플릿 시스템

GoogleUnlimited는 강력한 Jinja2 템플릿 매크로를 제공하여 원시 Google Workspace 데이터를 시각적으로 뛰어나고 AI에 최적화된 형식으로 변환합니다.

🎯 사용 가능한 템플릿 매크로

💡 템플릿 매크로 예시

Gmail 라벨 시각화 - 라벨 목록을 아름다운 인터랙티브 칩으로 변환:

{{ render_gmail_labels_chips( service://gmail/labels , 'Label summary for: ' + user://current/email ) }}

캘린더 대시보드 - 포괄적인 캘린더 개요 생성:

{{ render_calendar_dashboard( service://calendar/calendars, service://calendar/events, 'My Calendar Overview' ) }}

캘린더 이벤트 대시보드 - 캘린더 이벤트를 아름답고 인터랙티브한 이벤트 카드로 변환:

{{ render_calendar_events_dashboard( service://calendar/events , 'Upcoming Events for: ' + user://current/email.email ) }}

이 매크로는 멋진 다크 테마 대시보드를 생성하며 다음과 같은 기능을 제공합니다:

• 📅 인터랙티브 이벤트 카드: 각 이벤트는 Google 캘린더에서 열리는 클릭 가능한 카드로 렌더링됩니다

• 🕐 스마트 시간 표시: 시간대 지원과 함께 종일 이벤트와 시간 지정 이벤트를 자동으로 구분합니다

• 📍 위치 통합: 회의 위치와 가상 회의 링크를 표시합니다

• 👥 참석자 정보: 참석자 수와 참가자 세부정보를 표시합니다

• ✅ 상태 표시기: 색상으로 구분된 상태(확정, 예정, 취소)와 시각적 피드백 제공

• 📱 반응형 디자인: 터치 친화적인 상호작용이 포함된 모바일 최적화 레이아웃

• 🎨 다크 테마 스타일링: 그라데이션 배경과 호버 효과가 있는 전문적인 외관

전문 문서 - 지표와 차트가 포함된 보고서 생성:

{{ generate_report_doc(
    report_title='Q4 Performance Report',
    metrics=[{'value': '$1.2M', 'label': 'Revenue', 'change': 15}],
    company_name='Your Company'
) }}

🔍 매크로 검색 및 동적 생성

템플릿 리소스 시스템을 사용하여 사용 가능한 모든 매크로를 탐색하세요:

# Access the template://macros resource to discover all available macros
macros = await access_resource("template://macros")
# Returns comprehensive macro information with usage examples

# Access specific macro details
macro_details = await access_resource("template://macros/render_gmail_labels_chips")

🎯 동적 매크로 생성

create_template_macro 도구를 사용하여 런타임에 사용자 정의 매크로를 생성하세요:

# Create a new macro dynamically
await create_template_macro(
    macro_name="render_task_status_badge",
    macro_content='''
    {% macro render_task_status_badge(status, size='small') %}
    {% if status == 'completed' %}
    <span class="status-badge status-completed {{ size }}">✅ Complete</span>
    {% elif status == 'in_progress' %}
    <span class="status-badge status-in-progress {{ size }}">🔄 In Progress</span>
    {% else %}
    <span class="status-badge status-pending {{ size }}">⏳ {{ status|title }}</span>
    {% endif %}
    {% endmacro %}
    ''',
    description="Renders visual status badges for task states with appropriate icons",
    usage_example="{{ render_task_status_badge('completed', 'large') }}",
    persist_to_file=True
)

# Immediately use the newly created macro
await send_gmail_message(
    html_body="Task Status: {{ render_task_status_badge('completed', 'large') }}"
)

DSL 기반 매크로 — 동적 매크로는 Google Chat 카드 DSL 표기법을 포함하여 풍부하고 구조화된 카드를 생성할 수도 있습니다. DSL 기호는 카드 레이아웃을 정의하고 Jinja2는 동적 콘텐츠를 처리합니다:

{# workspace_dashboard.j2 — a dynamic macro that outputs a Google Chat card #}
{% macro workspace_dashboard(user_email, stats=None, quick_actions=None) %}
{% set username = user_email.split('@')[0] if user_email else 'User' %}
{% set default_stats = stats or [
    {'label': 'Emails', 'value': '12 unread'},
    {'label': 'Calendar', 'value': '3 meetings today'},
    {'label': 'Tasks', 'value': '5 pending'}
] %}

§[δ×3, ℊ[ǵ×4], §[δ×2, Ƀ[ᵬ×3]]]

Welcome back, {{ username | title }}!

Your Workspace Overview:
{% for stat in default_stats %}
- {{ stat.label }}: {{ stat.value }}
{% endfor %}

Actions:
- Button: Open Gmail → https://mail.google.com
- Button: Open Calendar → https://calendar.google.com
- Button: Open Drive → https://drive.google.com
{% endmacro %}

DSL 라인 §[δ×3, ℊ[ǵ×4], §[δ×2, Ƀ[ᵬ×3]]]은 카드 구조를 정의합니다: 3개의 DecoratedText 위젯이 있는 섹션, 4개 항목이 있는 그리드, 2개의 DecoratedText 위젯과 3개의 버튼이 있는 ButtonList가 있는 중첩 섹션입니다. Jinja2 템플릿이 콘텐츠를 동적으로 채웁니다 — 그리고 templates/dynamic/에 저장되므로 send_dynamic_card 및 기타 도구에서 즉시 사용할 수 있습니다.

주요 기능:

• ⚡ 즉시 사용 가능: 생성 후 매크로를 즉시 사용할 수 있습니다

• 🎯 리소스 통합: template://macros/macro_name을 통해 자동으로 사용 가능

• 💾 선택적 저장: 매크로를 디스크에 저장하여 영구적으로 사용 가능

• 🔄 템플릿 처리: 전체 Jinja2 구문 검증 및 오류 처리

• 💬 DSL 통합: 매크로는 풍부한 Google Chat 카드를 위한 카드 DSL 표기법을 출력할 수 있습니다

🚀 실제 사용 사례

템플릿은 아름답고 구조화된 출력을 위해 도구 호출에서 직접 사용할 수 있습니다:

# Send a beautiful email with calendar dashboard
await send_gmail_message(
    to="manager@company.com",
    subject="Weekly Schedule Update",
    html_body="{{ render_calendar_events_dashboard( service://calendar/events, 'My upcoming events') }}",
    content_type="mixed"
)

# Generate and send a professional report
await create_doc(
    title="Q4 Performance Report",
    content="{{ generate_report_doc( report_title='Quarterly Results', company_name='GoogleUnlimited' ) }}"
)

📚 템플릿 시스템 리소스:

• 🎨 템플릿 디렉토리 - Jinja2 템플릿 및 매크로의 전체 모음

• 💌 아름다운 이메일 템플릿 - 리치 HTML 이메일 스타일링 및 테마

• 🏷️ Gmail 라벨 카드 - 칩이 포함된 인터랙티브 라벨 시각화

• 📅 캘린더 대시보드 - 이벤트 타임라인 및 일정 보기

• 📄 문서 템플릿 - 구조화된 문서 서식

🗂️ 리소스 검색

GoogleUnlimited는 지능적인 URI 패턴을 통해 API 호출 없이 초고속 데이터 액세스를 가능하게 하는 강력한 MCP 리소스 시스템을 제공합니다.

🎯 리소스 URI 패턴

🏗️ 주요 리소스 파일

• resources/user_resources.py: 인증, 프로필, 세션 관리 (1,812줄)

• resources/service_list_resources.py: TagBasedResourceMiddleware를 통한 서비스 검색 (446줄)

• middleware/qdrant_core/resources.py: AI 기반 검색 및 분석 (319줄)

⚡ 초고속 액세스

# Instant Gmail labels (no API call needed)
labels = await access_resource("service://gmail/labels")

# Current user info from session
user = await access_resource("user://current/email")

# Semantic search across all tool responses
results = await access_resource("qdrant://search/gmail errors today")

# Recent calendar events
events = await access_resource("recent://calendar")

📚 리소스 시스템 문서:

• 🗂️ 사용자 리소스 - 인증, 프로필, 세션 관리 (1,812줄)

• 🏷️ 서비스 목록 리소스 - TagBasedResourceMiddleware를 통한 서비스 검색 (446줄)

• 🧠 Qdrant 코어 리소스 - AI 기반 검색 및 분석 (319줄)

• 📋 리소스 패턴 가이드 - 전체 URI 패턴 참조 및 사용 예시

🧪 테스트 프레임워크

GoogleUnlimited는 LLM이 경험하는 것과 정확히 동일한 방식으로 MCP 사용을 검증하는 클라이언트 테스트와 추가 테스트 스위트를 포함한 포괄적인 테스트를 제공합니다. 559개의 테스트가 100% 통과율로 통과합니다.

🎯 클라이언트 테스트 중점

클라이언트 테스트는 가장 중요한 구성 요소입니다. 실제 리소스 통합과 92개 이상의 도구 및 9개 Google 서비스 전반에 걸친 표준화된 패턴을 사용하여 MCP 작업의 결정론적 테스트를 제공합니다. 이러한 테스트는 명시적 이메일 인증과 미들웨어 주입 패턴을 모두 검증합니다.

🚀 빠른 테스트 명령

# 🧪 Run all client tests (primary test suite)
uv run pytest tests/client/ -v

# 📧 Test specific service
uv run pytest tests/client/ -k "gmail" -v

# 🔐 Authentication required tests
uv run pytest tests/client/ -m "auth_required" -v

🔬 실제 리소스 ID 통합

테스트 프레임워크는 현실적인 테스트를 위해 서비스 리소스에서 실제 ID를 가져옵니다:

# Available fixtures for real resource testing
real_gmail_message_id      # From service://gmail/messages
real_drive_document_id     # From service://drive/items
real_calendar_event_id     # From service://calendar/events
real_photos_album_id       # From service://photos/albums
real_forms_form_id         # From service://forms/forms
real_chat_space_id         # From service://chat/spaces

🔄 CI/CD 파이프라인

GitHub Actions를 통한 자동화된 테스트 및 게시:

• CI 워크플로우: 모든 PR 및 main 푸시 시 실행

  • Python 3.11 및 3.12 매트릭스 테스트

  • ruff check를 통한 린팅 및 ruff format을 통한 포맷팅

  • 전체 테스트 스위트 실행

• TestPyPI 게시: 테스트를 위한 자동화된 패키지 게시

📚 테스트 리소스:

• 📋 클라이언트 테스트 프레임워크 가이드 - 전체 클라이언트 테스트 문서 및 패턴

• 🧪 클라이언트 테스트 디렉토리 - 결정론적 MCP 검증을 위한 실제 리소스 통합 테스트

• 🤖 MCP 클라이언트 통합 - MCP 클라이언트 패턴 및 사용법 자세히 알아보기

• 🔐 인증 패턴 - 이메일 vs 미들웨어 주입 검증 테스트

🔒 보안 및 인증

GoogleUnlimited는 OAuth 2.1 + PKCE, 고급 세션 관리, 포괄적인 감사 기능을 갖춘 엔터프라이즈급 보안을 구현합니다.

🛡️ 인증 흐름

1. 🌐 MCP Inspector OAuth: 동적 클라이언트 등록을 지원하는 MCP Spec 준수

2. 🖥️ 직접 서버 OAuth: 직접 액세스를 위한 웹 기반 인증

3. 🔧 개발 JWT: 생성된 토큰을 사용한 테스트 모드

4. 📁 향상된 파일 자격 증명: 암호화 옵션이 포함된 영구 저장

5. 🔑 사용자 정의 OAuth 클라이언트: 자동 폴백과 함께 자체 OAuth 자격 증명 사용

6. 🪪 사용자별 API 키: 자격 증명 격리와 함께 OAuth 완료 시 개별 키 생성

✨ 보안 기능

• 🔐 OAuth 2.1 + PKCE: 키 교환 증명을 통한 현대적인 인증(공개 클라이언트 지원)

• 🔑 사용자별 API 키: 사용자별 고유하고 취소 가능한 키, 해시 전용 저장 및 타이밍 안전 조회

• 🛡️ 자격 증명 격리: 인증 출처 기반 액세스 제어로 사용자 간 자격 증명 상속 방지

• 🔗 계정 연결: 사용자별 키에 대한 다중 계정 액세스를 위한 양방향 계정 연결

• 🔒 암호화 기반 암호화: MCP_API_KEY에 바인딩된 HKDF-SHA256 파생 암호화 키

• 🔒 세션 격리: 데이터 유출을 방지하는 멀티테넌트 지원

• 🏷️ 27개 이상의 API 범위: 모든 서비스에 걸친 세분화된 권한 관리

• 📊 감사 로깅: 인증 출처가 포함된 완전한 보안 이벤트 추적

• 🔐 AES-256 암호화: 레거시 키 마이그레이션을 지원하는 자격 증명 저장

• 🔄 3계층 폴백: 서버 재시작 시 견고한 자격 증명 유지(State Map → UnifiedSession → Context Storage)

• 🧹 민감 데이터 제거: 저장 전 Qdrant 임베딩에서 인증 메타데이터 제거

⚙️ 보안 구성

# 🔒 Security settings in .env
CREDENTIAL_STORAGE_MODE=FILE_ENCRYPTED
SESSION_SECRET_KEY=your-secret-key
SESSION_TIMEOUT_MINUTES=30
ENABLE_AUDIT_LOGGING=true
GMAIL_ALLOW_LIST=trusted@example.com

📚 보안 문서 리소스:

• 🛡️ 통합 OAuth 아키텍처 - 전체 보안 아키텍처 및 인증 설계

• 🔐 OAuth 2.1 + PKCE 구현 - 키 교환 증명을 통한 현대적인 인증

• 🏠 세션 관리 가이드 - 멀티테넌트 지원 및 세션 격리

• 🔒 암호화 및 저장 - AES-256 자격 증명 암호화 및 시스템별 키

• 📊 감사 로깅 시스템 - 완전한 보안 이벤트 추적 및 모니터링

🚀 Google Workspace 통합을 혁신할 준비가 되셨나요?

📚 문서 • 🔧 설정 • 🎯 API 참조 • 🧪 테스트