google-drive-forge 0.2.0__tar.gz

google_drive_forge-0.2.0/.gitignore

@@ -0,0 +1,32 @@
+# General
+__pycache__/
+*.py[cod]
+*$py.class
+.DS_Store
+
+# Virtual environments
+venv/
+venv_new/
+.env
+.venv
+
+# Distribution / Build
+dist/
+build/
+*.egg-info/
+
+# Sensitive Data / Credentials
+credentials.json
+token.json
+client_secret*.json
+service_account.json
+
+# Logs
+*.log
+logs/
+audit_logs/
+
+# Backups and temporary files
+src_backup/
+*.bak
+*.swp

google_drive_forge-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Google Drive Forge Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

google_drive_forge-0.2.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include LICENSE
+include SKILL.md
+include pyproject.toml
+recursive-include docs *
+recursive-include google_drive_forge/assets *

google_drive_forge-0.2.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: google-drive-forge
+Version: 0.2.0
+Summary: Autonomous Google Drive MCP with Skill Forge Capabilities
+Project-URL: Homepage, https://github.com/traylinx/google_drive_forge
+Project-URL: Repository, https://github.com/traylinx/google_drive_forge
+Project-URL: Documentation, https://github.com/traylinx/google_drive_forge#readme
+Author-email: Sebastian Velandia <sebastian@traylinx.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agentic,ai,automation,google-drive,mcp,skill-forge
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: google-api-python-client
+Requires-Dist: google-auth
+Requires-Dist: google-auth-httplib2
+Requires-Dist: google-auth-oauthlib
+Requires-Dist: mcp
+Requires-Dist: pyyaml
+Requires-Dist: tenacity
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img src="assets/banner.png" width="250" alt="Google Drive Forge Icon">
+  <h1>Google Drive Forge</h1>
+</div>
+
+[![MCP](https://img.shields.io/badge/MCP-Protocol-blue.svg)](https://modelcontextprotocol.io)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+Transform your AI agent from a simple file explorer into an **Autonomous Power-User**. This isn't just a Google Drive connector; it's a cognitive layer for your cloud storage.
+
+---
+
+## 💎 The "Intelligent" Edge
+
+Most MCP servers just list files. This one **reasons** about them.
+
+| Feature             | Description                                               | Benefit                                                         |
+| :------------------ | :-------------------------------------------------------- | :-------------------------------------------------------------- |
+| **🔨 The Forge**     | On-the-fly Python "Skill" creation and execution.         | Solve complex tasks like "Archive all PDFs older than 30 days". |
+| **🩹 Path Healing**  | Fuzzy, human-like path resolution (e.g., `/Work/Drafts`). | No more hunting for obscure File IDs.                           |
+| **🧠 Auto-Recovery** | Intercepts 404s and suggests correct paths/files.         | Agent remains autonomous even when it makes mistakes.           |
+| **🔍 Smart Read**    | Auto-detection of MIME types and content conversion.      | Seamless interaction with Sheets, Docs, and PDFs.               |
+| **📜 Audit Log**     | Transparent tracking of all autonomous decisions.         | Complete visibility into what your agent is doing.              |
+
+---
+
+## 🛠 Features Breakdown
+
+### 📂 Standard Operations
+- **Discovery**: `list_files`, `search_files`, `list_folder`.
+- **Management**: `create_folder`, `upload_file`, `trash_file`.
+- **Metadata**: Deep metadata inspection for any file object.
+
+### ⚡ The Forge (Agent Skills)
+Empower your agent to expand its own capabilities. Using the [Agent Skills](https://agentskills.io) standard, the agent can:
+- **`create_skill`**: Write Python logic to perform multi-step Drive operations.
+- **`list_skills`**: Browse its library of forged capabilities.
+- **`run_skill`**: Execute its custom logic with full API access.
+
+### 🧭 Autonomous Navigation
+- **`resolve_path`**: Converts `/Project/2026/Budget.xlsx` into a working ID, healing broken paths automatically.
+- **`smart_read`**: A high-level tool that handles resolution, downloading, and decoding in one step.
+
+---
+
+## � Getting Started
+
+### 1. Requirements
+- Python 3.10 or higher.
+- A Google Cloud Project with the **Drive API** enabled.
+
+### 2. Deep Dive Into Setup
+For a step-by-step walkthrough on generating your `credentials.json` and `token.json`, please refer to our:
+👉 **[Comprehensive Setup Guide](docs/setup.md)**
+
+### 3. Quick Configuration
+Add this to your MCP host configuration (e.g., Antigravity):
+
+```json
+"google-drive": {
+  "command": "python",
+  "args": ["/path/to/server.py"],
+  "env": {
+    "GOOGLE_DRIVE_CREDENTIALS": "/path/to/credentials.json",
+    "GOOGLE_DRIVE_HEADLESS_AUTH": "false",
+    "GOOGLE_DRIVE_PYTHON_PATH": "/usr/bin/python3"
+  }
+}
+```
+
+#### ⚙️ Environment Variables
+| Variable                     | Description                                       | Default              |
+| :--------------------------- | :------------------------------------------------ | :------------------- |
+| `GOOGLE_DRIVE_CREDENTIALS`   | Path to your `credentials.json`.                  | `./credentials.json` |
+| `GOOGLE_DRIVE_HEADLESS_AUTH` | Set to `true` for console-based OAuth on servers. | `false`              |
+| `GOOGLE_DRIVE_PYTHON_PATH`   | Path to a specific Python executable or venv.     | `sys.executable`     |
+| `GOOGLE_DRIVE_SKILLS_DIR`    | Where to store forged AI Skills.                  | `./skills`           |
+
+---
+
+## 🛡️ Security Implications
+
+**Please Read Carefully:**
+This MCP server implements **The Forge**, which allows AI agents to write and execute arbitrary Python code on your machine. 
+*   **Local Use Only**: This tool is designed for local power-users. 
+*   **Sandbox**: It does not currently implement a sandbox for executed scripts. Only use it with agents you trust to handle your local filesystem.
+
+---
+
+##  Contributing & Extension
+
+We believe in open autonomy. If you have ideas for new core skills or improvements to the path-healing engine:
+1. Check the [Contributing Guide](CONTRIBUTING.md).
+2. Explore the `skills/` directory for examples of forged logic.
+3. Submit a PR!
+
+---
+
+## ⚖️ License
+
+Distributed under the **MIT License**. See `LICENSE` for more information.
+
+---
+<p align="center">
+  Built with ❤️ for the next generation of AI Agents.
+</p>

google_drive_forge-0.2.0/README.md

@@ -0,0 +1,107 @@
+<div align="center">
+  <img src="assets/banner.png" width="250" alt="Google Drive Forge Icon">
+  <h1>Google Drive Forge</h1>
+</div>
+
+[![MCP](https://img.shields.io/badge/MCP-Protocol-blue.svg)](https://modelcontextprotocol.io)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+Transform your AI agent from a simple file explorer into an **Autonomous Power-User**. This isn't just a Google Drive connector; it's a cognitive layer for your cloud storage.
+
+---
+
+## 💎 The "Intelligent" Edge
+
+Most MCP servers just list files. This one **reasons** about them.
+
+| Feature             | Description                                               | Benefit                                                         |
+| :------------------ | :-------------------------------------------------------- | :-------------------------------------------------------------- |
+| **🔨 The Forge**     | On-the-fly Python "Skill" creation and execution.         | Solve complex tasks like "Archive all PDFs older than 30 days". |
+| **🩹 Path Healing**  | Fuzzy, human-like path resolution (e.g., `/Work/Drafts`). | No more hunting for obscure File IDs.                           |
+| **🧠 Auto-Recovery** | Intercepts 404s and suggests correct paths/files.         | Agent remains autonomous even when it makes mistakes.           |
+| **🔍 Smart Read**    | Auto-detection of MIME types and content conversion.      | Seamless interaction with Sheets, Docs, and PDFs.               |
+| **📜 Audit Log**     | Transparent tracking of all autonomous decisions.         | Complete visibility into what your agent is doing.              |
+
+---
+
+## 🛠 Features Breakdown
+
+### 📂 Standard Operations
+- **Discovery**: `list_files`, `search_files`, `list_folder`.
+- **Management**: `create_folder`, `upload_file`, `trash_file`.
+- **Metadata**: Deep metadata inspection for any file object.
+
+### ⚡ The Forge (Agent Skills)
+Empower your agent to expand its own capabilities. Using the [Agent Skills](https://agentskills.io) standard, the agent can:
+- **`create_skill`**: Write Python logic to perform multi-step Drive operations.
+- **`list_skills`**: Browse its library of forged capabilities.
+- **`run_skill`**: Execute its custom logic with full API access.
+
+### 🧭 Autonomous Navigation
+- **`resolve_path`**: Converts `/Project/2026/Budget.xlsx` into a working ID, healing broken paths automatically.
+- **`smart_read`**: A high-level tool that handles resolution, downloading, and decoding in one step.
+
+---
+
+## � Getting Started
+
+### 1. Requirements
+- Python 3.10 or higher.
+- A Google Cloud Project with the **Drive API** enabled.
+
+### 2. Deep Dive Into Setup
+For a step-by-step walkthrough on generating your `credentials.json` and `token.json`, please refer to our:
+👉 **[Comprehensive Setup Guide](docs/setup.md)**
+
+### 3. Quick Configuration
+Add this to your MCP host configuration (e.g., Antigravity):
+
+```json
+"google-drive": {
+  "command": "python",
+  "args": ["/path/to/server.py"],
+  "env": {
+    "GOOGLE_DRIVE_CREDENTIALS": "/path/to/credentials.json",
+    "GOOGLE_DRIVE_HEADLESS_AUTH": "false",
+    "GOOGLE_DRIVE_PYTHON_PATH": "/usr/bin/python3"
+  }
+}
+```
+
+#### ⚙️ Environment Variables
+| Variable                     | Description                                       | Default              |
+| :--------------------------- | :------------------------------------------------ | :------------------- |
+| `GOOGLE_DRIVE_CREDENTIALS`   | Path to your `credentials.json`.                  | `./credentials.json` |
+| `GOOGLE_DRIVE_HEADLESS_AUTH` | Set to `true` for console-based OAuth on servers. | `false`              |
+| `GOOGLE_DRIVE_PYTHON_PATH`   | Path to a specific Python executable or venv.     | `sys.executable`     |
+| `GOOGLE_DRIVE_SKILLS_DIR`    | Where to store forged AI Skills.                  | `./skills`           |
+
+---
+
+## 🛡️ Security Implications
+
+**Please Read Carefully:**
+This MCP server implements **The Forge**, which allows AI agents to write and execute arbitrary Python code on your machine. 
+*   **Local Use Only**: This tool is designed for local power-users. 
+*   **Sandbox**: It does not currently implement a sandbox for executed scripts. Only use it with agents you trust to handle your local filesystem.
+
+---
+
+##  Contributing & Extension
+
+We believe in open autonomy. If you have ideas for new core skills or improvements to the path-healing engine:
+1. Check the [Contributing Guide](CONTRIBUTING.md).
+2. Explore the `skills/` directory for examples of forged logic.
+3. Submit a PR!
+
+---
+
+## ⚖️ License
+
+Distributed under the **MIT License**. See `LICENSE` for more information.
+
+---
+<p align="center">
+  Built with ❤️ for the next generation of AI Agents.
+</p>

google_drive_forge-0.2.0/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: google-drive-mcp
+description: "Autonomous Google Drive management with intelligent path resolution, auto-recovery, and custom skill forging. Use when Claude needs to work with cloud storage for tasks like: (1) Navigating complex folder structures with human-like paths (/Work/Projects/2026), (2) Reading and converting content from Docs, Sheets, and PDFs, (3) Automating multi-step Drive operations by creating and running custom Python 'Skills', (4) Managing files (upload, search, trash)."
+---
+
+# Google Drive Forge - The Autonomous Skill System
+
+**Google Drive Forge** (formerly google-drive-mcp) is an advanced autonomous system for interacting with Google Drive.
+It goes beyond simple file storage by implementing **AI-Forged Skills**—short, single-purpose Python scripts that can be created, executed, and refined by the AI itself.
+
+## 1. System Components
+
+*   **Google Drive Forge Server**: The core MCP process.
+*   **The Forge (Skill System)**: A runtime for creating (`create_skill`) and running (`run_skill`) Python scripts.
+*   **IntelligentDriveClient (ForgeClient)**: A smart wrapper around the Drive API that handles:
+    *   **Self-Healing Paths**: Automatically finds files even if your path is slightly wrong (e.g., misremembered folder name).
+    *   **Autonomous MIME Handling**: Automatically exports Google Docs to Markdown/Text when you try to read them.
+    *   **Error Recovery**: Retries transient faults.spelled, it attempts "Self-Healing" to find the closest match.
+- **`smart_read`**: A high-level tool that resolves a path, downloads the content, and converts it to text (Decodes Google Docs, Sheets, and PDFs automatically) in one step.
+
+### 2. Standard File Management
+
+Comprehensive control over the Drive filesystem.
+
+- **`list_files` / `list_folder`**: Discover recent files or explore specific directories.
+- **`search_files`**: Finds files by name or content properties.
+- **`create_folder` / `upload_file` / `trash_file`**: Manage the lifecycle of your storage.
+
+### 3. The Forge (Autonomous Skills)
+
+Empower Claude to expand its own capabilities by writing and executing Python logic directly on the Drive API.
+
+- **`create_skill`**: Design a custom script for complex tasks (e.g., "Archive all files older than 30 days").
+- **`run_skill`**: Execute a forged capability with parameters.
+- **`list_skills`**: View the library of existing capabilities Claude has learned.
+
+## Common Workflows
+
+### Organizing Files
+
+When a user asks to "Organize the social media folder", use `list_folder` to find the content, `create_folder` for new categories, and `run_skill` (or basic `update`) to move them.
+
+### Reading Complex Documents
+
+For Google Docs or PDFs, always prefer `smart_read`. It handles the export MIME-types automatically so you get clean markdown/text. If `smart_read` returns binary content for a PDF, you may need to download it to process it locally.
+
+### Downloading Files to Project
+
+To save a file from Drive to the user's local project (e.g., to `jevelabsblog/drafts/skills`), use **`download_to_local`**.
+- It automatically converts Google Docs to Markdown/Text.
+- It accepts an absolute path (e.g., `/Users/sebastian/Projects/...`).
+- **Usage**: `download_to_local(file_id="...", local_path="/absolute/path/to/blog_post.md")`
+
+### Creating Automations
+
+If a task is repetitive (like "Sync all new PDFs to a specific folder"), use `create_skill` to write a Python script that uses the `IntelligentDriveClient`. This is more token-efficient than doing it step-by-step for every file.
+
+## Resources
+
+### scripts/
+
+The `scripts/` directory contains utility examples that can be used as templates for "The Forge". They are now dynamic and can be adapted for any workflow:
+
+- **`move_files.py`**: Generic bulk mover.
+  - Usage: `python scripts/move_files.py <source_folder> <dest_folder> [--create-dest]`
+  - Example: `python scripts/move_files.py "Downloads" "Archive/2025" --create-dest`
+
+- **`batch_download.py`**: Generic folder syncer.
+  - Usage: `python scripts/batch_download.py <drive_folder_name> <local_dest_path>`
+  - Example: `python scripts/batch_download.py "Project Assets" "./assets"`
+
+- **`download_file.py`**: Single file downloader (Auto-converts Docs to Markdown).
+  - Usage: `python scripts/download_file.py <file_id> <dest_path>`
+  - Example: `python scripts/download_file.py "12345abcde" "./docs/spec.md"`
+
+### references/
+
+- `api_reference.md`: Detailed documentation of the internal `IntelligentDriveClient` used by the AI-forged skills.

google_drive_forge-0.2.0/docs/agentic_integration.md

@@ -0,0 +1,114 @@
+# Agentic App Integration Guide
+
+This guide explains how to use `google_drive_forge` as a library in your own Python applications and agents.
+
+---
+
+## Installation
+
+```bash
+# From source
+pip install -e /path/to/mcp/google_drive/
+
+# From git
+pip install git+https://github.com/your-org/google-drive-forge.git
+```
+
+---
+
+## Example: Simple File Lister
+
+```python
+from google_drive_forge import ForgeClient
+
+def main():
+    client = ForgeClient()
+    
+    print("Recent files:")
+    for f in client.list_files(limit=5):
+        print(f"  - {f['name']} ({f['id']})")
+
+if __name__ == "__main__":
+    main()
+```
+
+---
+
+## Example: Downloading Docs to Local
+
+```python
+from google_drive_forge import IntelligentDriveClient
+import os
+
+def download_folder_as_markdown(folder_path: str, local_dir: str):
+    """
+    Downloads all Google Docs from a Drive folder to a local directory as Markdown.
+    """
+    client = IntelligentDriveClient()
+    os.makedirs(local_dir, exist_ok=True)
+    
+    # Resolve the folder path to an ID
+    folder_id = client.find_and_heal_path(folder_path)
+    if not folder_id:
+        print(f"Error: Could not find folder '{folder_path}'")
+        return
+    
+    # List files in the folder
+    files = client.list_folder_children(folder_id)
+    
+    for f in files:
+        if f['mimeType'] == 'application/vnd.google-apps.document':
+            content = client.download_file(f['id'], export_mime_type='text/plain')
+            local_path = os.path.join(local_dir, f['name'] + ".md")
+            with open(local_path, 'wb') as out:
+                out.write(content)
+            print(f"Saved: {local_path}")
+
+if __name__ == "__main__":
+    download_folder_as_markdown("/socialMedia/skills", "./local_skills")
+```
+
+---
+
+## Example: Running a Forged Skill
+
+```python
+from google_drive_forge import ScriptExecutor
+
+def main():
+    executor = ScriptExecutor(
+        python_path="/path/to/venv/bin/python",
+        skills_dir="/path/to/mcp/google_drive/skills"
+    )
+    
+    # Run an existing skill
+    output = executor.run_skill("auto_archive", args=["--days", "30"])
+    print(output)
+
+if __name__ == "__main__":
+    main()
+```
+
+---
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      Your Agentic App                       │
+│  (e.g., chatbot, automation script, AI workflow)            │
+└───────────────────────────┬─────────────────────────────────┘
+                            │ imports
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    google_drive_forge                         │
+│  ┌───────────────────┐  ┌───────────────┐  ┌─────────────┐  │
+│  │ IntelligentClient │  │ ScriptExecutor│  │ SkillLoader │  │
+│  │ (Drive API)       │  │ (The Forge)   │  │ (Discovery) │  │
+│  └─────────┬─────────┘  └───────┬───────┘  └──────┬──────┘  │
+│            │                    │                 │         │
+│            └───────────────────┼─────────────────┘         │
+│                               ▼                             │
+│                        Google Drive API                     │
+└─────────────────────────────────────────────────────────────┘
+```

google_drive_forge-0.2.0/docs/api_reference.md

@@ -0,0 +1,71 @@
+# API Reference
+
+This document describes the public Python API for the `google_drive_forge` package.
+
+---
+
+## `ForgeClient` (alias: `IntelligentDriveClient`)
+
+The primary client for interacting with Google Drive. Extends `DriveClient` with autonomous features.
+
+```python
+from google_drive_forge import ForgeClient
+
+client = ForgeClient(audit=None)  # audit: Optional[AuditLogger]
+```
+
+### Methods
+
+| Method                                          | Description                                                                               |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `list_files(query=None, limit=10)`              | List files. Returns `List[Dict]`.                                                         |
+| `search(text, limit=20)`                        | Search files by name. Returns `List[Dict]`.                                               |
+| `get_file_metadata(file_id)`                    | Get detailed metadata. Returns `Dict`.                                                    |
+| `download_file(file_id, export_mime_type=None)` | Download file content. Returns `bytes`.                                                   |
+| `create_folder(name, parent_id='root')`         | Create a folder. Returns `Dict`.                                                          |
+| `upload_file(name, content, parent_id='root')`  | Upload a file. Returns `Dict`.                                                            |
+| `trash_file(file_id)`                           | Move file to trash. Returns `Dict`.                                                       |
+| `list_folder_children(folder_id, limit=100)`    | List children of a folder. Returns `List[Dict]`.                                          |
+| `find_and_heal_path(path)`                      | Resolve a human-readable path to a file ID with auto-correction. Returns `str` or `None`. |
+
+---
+
+## `ScriptExecutor`
+
+Runs Python scripts (skills) in a subprocess.
+
+```python
+from google_drive_forge import ScriptExecutor
+
+executor = ScriptExecutor(python_path="/path/to/python", skills_dir="/path/to/skills")
+```
+
+### Methods
+
+| Method                             | Description                                     |
+| ---------------------------------- | ----------------------------------------------- |
+| `run_skill(skill_name, args=None)` | Execute a skill script. Returns `str` (stdout). |
+
+---
+
+## `SkillLoader`
+
+Discovers and manages AI-forged skills.
+
+```python
+from google_drive_forge import SkillLoader
+
+loader = SkillLoader(skills_dir="/path/to/skills")
+```
+
+### Methods
+
+| Method              | Description                                          |
+| ------------------- | ---------------------------------------------------- |
+| `discover_skills()` | Returns a `List[SkillMeta]` of all available skills. |
+
+---
+
+## `DriveClient`
+
+The base client without autonomous features. Use `IntelligentDriveClient` for most cases.

google_drive_forge-0.2.0/docs/index.md

@@ -0,0 +1,25 @@
+# Google Drive Forge Documentation
+
+Welcome to the documentation for **Google Drive Forge** (formerly Google Drive MCP).
+
+## Contents
+
+| Document                                      | Description                                    |
+| --------------------------------------------- | ---------------------------------------------- |
+| [Quick Start](quickstart.md)                  | Setup guide for MCP Server and Python library. |
+| [API Reference](api_reference.md)             | Python classes and methods for library usage.  |
+| [Tool Reference](tool_reference.md)           | MCP tools exposed to AI agents.                |
+| [Agentic Integration](agentic_integration.md) | Examples for embedding in your own apps.       |
+
+## Overview
+
+This project provides two ways to interact with Google Drive:
+
+1.  **MCP Server**: Exposes tools for AI IDEs like Cursor and Claude Desktop.
+2.  **Agentic Library**: Embed `google_drive_forge` into your own agentic workflows.
+
+## Quick Links
+
+-   **Main Entry Point (MCP)**: `server.py` or `python -m google_drive_forge`
+-   **Package Name**: `google_drive_forge`
+-   **Key Classes**: `ForgeClient`, `ScriptExecutor`, `SkillLoader`

google_drive_forge-0.2.0/docs/quickstart.md

@@ -0,0 +1,63 @@
+# Google Drive Forge - Quick Start
+
+## Overview
+
+**Google Drive Forge** provides two integration modes:
+
+1.  **MCP Server**: For AI IDEs like Cursor and Claude Desktop.
+2.  **Agentic Library**: For embedding into your own Python apps.
+
+---
+
+## 1. MCP Server Setup
+
+Add the following to your MCP configuration file:
+
+```json
+{
+  "mcpServers": {
+    "google-drive-forge": {
+      "command": "/path/to/venv/bin/python3",
+      "args": [
+        "-m",
+        "google_drive_forge"
+      ],
+      "env": {
+        "GOOGLE_DRIVE_CREDENTIALS": "/path/to/credentials.json",
+        "GOOGLE_DRIVE_HEADLESS_AUTH": "true"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable                     | Description                           |
+| ---------------------------- | ------------------------------------- |
+| `GOOGLE_DRIVE_CREDENTIALS`   | Path to `credentials.json`.           |
+| `GOOGLE_DRIVE_HEADLESS_AUTH` | Set to `"true"` for headless servers. |
+
+---
+
+## 2. Python Library Setup
+
+Install the package:
+
+```bash
+pip install git+https://github.com/your-org/google-drive-forge.git
+```
+
+### Basic Usage
+
+```python
+from google_drive_forge import ForgeClient
+
+# Initialize
+client = ForgeClient()
+
+# List files
+files = client.list_files(limit=10)
+```
+
+See [api_reference.md](api_reference.md) for full API details.