From 989867875baf1ef78ecd989f210554d94f9c519c Mon Sep 17 00:00:00 2001 From: Allen Hutchison Date: Fri, 14 Nov 2025 15:29:15 -0800 Subject: [PATCH 1/7] docs: Improve documentation and README This commit introduces a number of changes to improve the documentation and README of the project. - A `docs` directory has been added with an `index.md` file that documents all the available tools and a `development.md` file that contains detailed instructions for setting up the development environment. - The `README.md` file has been updated to be more user-friendly, with natural language examples of how to use the extension and documentation for the available commands. - The development instructions have been moved from the `CONTRIBUTING.md` file to the new `docs/development.md` file. --- CONTRIBUTING.md | 109 +----------------------------------- README.md | 56 +++++++++++++------ docs/development.md | 133 ++++++++++++++++++++++++++++++++++++++++++++ docs/index.md | 79 ++++++++++++++++++++++++++ 4 files changed, 252 insertions(+), 125 deletions(-) create mode 100644 docs/development.md create mode 100644 docs/index.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9a683562..b962f35f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -80,111 +80,4 @@ In the PR description, explain the "why" behind your changes and link to the rel ## Development Setup and Workflow -This section guides contributors on how to build, modify, and understand the development setup of this project. - -### Setting Up the Development Environment - -**Prerequisites:** - -1. **Node.js**: - - **Development:** Please use Node.js `~20.19.0`. This specific version is required due to an upstream development dependency issue. You can use a tool like [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions. - - **Production:** For running the CLI in a production environment, any version of Node.js `>=20` is acceptable. -2. **Git** - -### Build Process - -To clone the repository: - -```bash -git clone https://github.com/google-gemini/gemini-cli-workspace.git # Or your fork's URL -cd gemini-cli-workspace -``` - -To install dependencies defined in `package.json` as well as root dependencies: - -```bash -npm install -``` - -To build the entire project (all packages): - -```bash -npm run build -``` - -This command typically compiles TypeScript to JavaScript, bundles assets, and prepares the packages for execution. Refer to `scripts/build.js` and `package.json` scripts for more details on what happens during the build. - -### Running Tests - -This project contains unit tests. - -#### Unit Tests - -To execute the unit test suite for the project: - -```bash -npm run test -``` - -This will run tests located in the `workspace-mcp-server/src/__tests__` directory. Ensure tests pass before submitting any changes. For a more comprehensive check, it is recommended to run `npm run test && npm run lint`. - -### Linting and Style Checks - -To ensure code quality and formatting consistency, run the linter and tests: - -```bash -npm run test && npm run lint -``` - -This command will run ESLint, Prettier, all tests, and other checks as defined in the project's `package.json`. - -_ProTip_ - -after cloning create a git precommit hook file to ensure your commits are always clean. - -```bash -echo " -# Run npm build and check for errors -#!/bin/sh -# Run tests and linting before commit -if ! (npm run test && npm run lint); then - echo "Pre-commit checks failed. Commit aborted." - exit 1 -fi -" > .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit -``` - -#### Formatting - -To separately format the code in this project by running the following command from the root directory: - -```bash -npm run format -``` - -This command uses Prettier to format the code according to the project's style guidelines. - -#### Linting - -To separately lint the code in this project, run the following command from the root directory: - -```bash -npm run lint -``` - -### Coding Conventions - -- Please adhere to the coding style, patterns, and conventions used throughout the existing codebase. -- Consult [GEMINI.md](https://github.com/google-gemini/gemini-cli-workspace/blob/main/GEMINI.md) (typically found in the project root) for specific instructions related to AI-assisted development, including conventions for comments, and Git usage. -- **Imports:** Pay special attention to import paths. The project uses ESLint to enforce restrictions on relative imports between packages. - -### Project Structure - -- `workspace-mcp-server/`: The main workspace for the MCP server. - - `src/`: Contains the source code for the server. - - `__tests__/`: Contains all the tests. - - `auth/`: Handles authentication. - - `services/`: Contains the business logic for each service. - - `utils/`: Contains utility functions. - - `config/`: Contains configuration files. -- `scripts/`: Utility scripts for building, testing, and development tasks. \ No newline at end of file +For information on how to build, modify, and understand the development setup of this project, please see the [development documentation](docs/development.md). \ No newline at end of file diff --git a/README.md b/README.md index f9779ffa..ff2919e3 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,59 @@ -# Gemini Workspace Extension +# Google Workspace Extension for Gemini CLI [![Build Status](https://github.com/google-gemini/gemini-cli-workspace/actions/workflows/ci.yml/badge.svg)](https://github.com/google-gemini/gemini-cli-workspace/actions/workflows/ci.yml) -Google Workspace MCP Server Extension. +The Google Workspace extension for Gemini CLI brings the power of your Google Workspace apps to your command line. Manage your documents, spreadsheets, presentations, emails, chat, and calendar events without leaving your terminal. -This project is a Gemini extension that provides tools for interacting with Google Workspace services like Google Docs, Google Sheets, Google Slides, Google Calendar, Gmail, and Google Drive. +## Prerequisites + +Before using the Google Workspace extension, you need to be logged into your Google account. ## Installation -To install the dependencies, run the following command: +Install the Google Workspace extension by running the following command from your terminal: ```bash -npm install +gemini extensions install https://github.com/gemini-cli-extensions/workspace ``` + + ## Usage -To build the project, run the following command: +Once the extension is installed, you can use it to interact with your Google Workspace apps. Here are a few examples: -```bash -npm run build -``` +**Create a new Google Doc:** -To run the tests, run the following command: +> "Create a new Google Doc with the title 'My New Doc' and the content '# My New Document\n\nThis is a new document created from the command line.'" -```bash -npm run test -``` +**List your upcoming calendar events:** -To start the server, run the following command: +> "What's on my calendar for today?" -```bash -npm start -``` +**Search for a file in Google Drive:** + +> "Find the file named 'my-file.txt' in my Google Drive." + +## Commands + +This extension provides the following commands: + +### Get Schedule + +**Command:** `/calendar:get-schedule [date]` + +Shows your schedule for today or a specified date. + +### Search Drive + +**Command:** `/drive:search ` + +Searches your Google Drive for files matching the given query. + +## Resources + +- [Documentation](docs/index.md): Detailed documentation on all the available tools. +- [GitHub Issues](https://github.com/gemini-cli-extensions/workspace/issues): Report bugs or request features. ## Important security consideration: Indirect Prompt Injection Risk @@ -55,3 +76,4 @@ Contributions are welcome! Please read the [CONTRIBUTING.md](CONTRIBUTING.md) fi - **Terms of Service**: [Terms of Service](https://policies.google.com/terms) - **Privacy Policy**: [Privacy Policy](https://policies.google.com/privacy) - **Security**: [Security Policy](SECURITY.md) + diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 00000000..6e7076b3 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,133 @@ +# Development + +This document provides instructions for developing the Google Workspace extension. + +## Development Setup and Workflow + +This section guides contributors on how to build, modify, and understand the development setup of this project. + +### Setting Up the Development Environment + +**Prerequisites:** + +1. **Node.js**: + - **Development:** Please use Node.js `~20.19.0`. This specific version is required due to an upstream development dependency issue. You can use a tool like [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions. + - **Production:** For running the CLI in a production environment, any version of Node.js `>=20` is acceptable. +2. **Git** + +### Build Process + +To clone the repository: + +```bash +git clone https://github.com/google-gemini/gemini-cli-workspace.git # Or your fork's URL +cd gemini-cli-workspace +``` + +To install dependencies defined in `package.json` as well as root dependencies: + +```bash +npm install +``` + +To build the entire project (all packages): + +```bash +npm run build +``` + +This command typically compiles TypeScript to JavaScript, bundles assets, and prepares the packages for execution. Refer to `scripts/build.js` and `package.json` scripts for more details on what happens during the build. + +### Running Tests + +This project contains unit tests. + +#### Unit Tests + +To execute the unit test suite for the project: + +```bash +npm run test +``` + +This will run tests located in the `workspace-mcp-server/src/__tests__` directory. Ensure tests pass before submitting any changes. For a more comprehensive check, it is recommended to run `npm run test && npm run lint`. + +### Linting and Style Checks + +To ensure code quality and formatting consistency, run the linter and tests: + +```bash +npm run test && npm run lint +``` + +This command will run ESLint, Prettier, all tests, and other checks as defined in the project's `package.json`. + +_ProTip_ + +after cloning create a git precommit hook file to ensure your commits are always clean. + +```bash +echo " +# Run npm build and check for errors +#!/bin/sh +# Run tests and linting before commit +if ! (npm run test && npm run lint); then + echo "Pre-commit checks failed. Commit aborted." + exit 1 +fi +" > .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit +``` + +#### Formatting + +To separately format the code in this project by running the following command from the root directory: + +```bash +npm run format +``` + +This command uses Prettier to format the code according to the project's style guidelines. + +#### Linting + +To separately lint the code in this project, run the following command from the root directory: + +```bash +npm run lint +``` + +### Coding Conventions + +- Please adhere to the coding style, patterns, and conventions used throughout the existing codebase. +- Consult [GEMINI.md](https://github.com/google-gemini/gemini-cli-workspace/blob/main/GEMINI.md) (typically found in the project root) for specific instructions related to AI-assisted development, including conventions for comments, and Git usage. +- **Imports:** Pay special attention to import paths. The project uses ESLint to enforce restrictions on relative imports between packages. + +### Project Structure + +- `workspace-mcp-server/`: The main workspace for the MCP server. + - `src/`: Contains the source code for the server. + - `__tests__/`: Contains all the tests. + - `auth/`: Handles authentication. + - `services/`: Contains the business logic for each service. + - `utils/`: Contains utility functions. + - `config/`: Contains configuration files. +- `scripts/`: Utility scripts for building, testing, and development tasks. + +## Authentication + +The extension uses OAuth 2.0 to authenticate with Google Workspace APIs. The `scripts/auth-utils.js` script provides a command-line interface to manage authentication credentials. + +### Usage + +To use the script, run the following command: + +```bash +node scripts/auth-utils.js +``` + +### Commands + +- `clear`: Clear all authentication credentials. +- `expire`: Force the access token to expire (for testing refresh). +- `status`: Show current authentication status. +- `help`: Show the help message. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..8ff301e9 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,79 @@ +# Google Workspace Extension Documentation + +This document provides an overview of the Google Workspace extension for Gemini CLI. + +## Available Tools + +The extension provides the following tools: + +### Google Docs +- `docs.create`: Creates a new Google Doc. +- `docs.insertText`: Inserts text at the beginning of a Google Doc. +- `docs.find`: Finds Google Docs by searching for a query in their title. +- `docs.move`: Moves a document to a specified folder. +- `docs.getText`: Retrieves the text content of a Google Doc. +- `docs.appendText`: Appends text to the end of a Google Doc. +- `docs.replaceText`: Replaces all occurrences of a given text with new text in a Google Doc. +- `docs.extractIdFromUrl`: Extracts the document ID from a Google Workspace URL. + +### Google Slides +- `slides.getText`: Retrieves the text content of a Google Slides presentation. +- `slides.find`: Finds Google Slides presentations by searching for a query. +- `slides.getMetadata`: Gets metadata about a Google Slides presentation. + +### Google Sheets +- `sheets.getText`: Retrieves the content of a Google Sheets spreadsheet. +- `sheets.getRange`: Gets values from a specific range in a Google Sheets spreadsheet. +- `sheets.find`: Finds Google Sheets spreadsheets by searching for a query. +- `sheets.getMetadata`: Gets metadata about a Google Sheets spreadsheet. + +### Google Drive +- `drive.search`: Searches for files and folders in Google Drive. +- `drive.findFolder`: Finds a folder by name in Google Drive. + +### Google Calendar +- `calendar.list`: Lists all of the user's calendars. +- `calendar.createEvent`: Creates a new event in a calendar. +- `calendar.listEvents`: Lists events from a calendar. +- `calendar.getEvent`: Gets the details of a specific calendar event. +- `calendar.findFreeTime`: Finds a free time slot for multiple people to meet. +- `calendar.updateEvent`: Updates an existing event in a calendar. +- `calendar.respondToEvent`: Responds to a meeting invitation (accept, decline, or tentative). + +### Google Chat +- `chat.listSpaces`: Lists the spaces the user is a member of. +- `chat.findSpaceByName`: Finds a Google Chat space by its display name. +- `chat.sendMessage`: Sends a message to a Google Chat space. +- `chat.getMessages`: Gets messages from a Google Chat space. +- `chat.sendDm`: Sends a direct message to a user. +- `chat.findDmByEmail`: Finds a Google Chat DM space by a user's email address. +- `chat.listThreads`: Lists threads from a Google Chat space in reverse chronological order. +- `chat.setUpSpace`: Sets up a new Google Chat space with a display name and a list of members. + +### Gmail +- `gmail.search`: Search for emails in Gmail using query parameters. +- `gmail.get`: Get the full content of a specific email message. +- `gmail.modify`: Modify a Gmail message. +- `gmail.send`: Send an email message. +- `gmail.createDraft`: Create a draft email message. +- `gmail.sendDraft`: Send a previously created draft email. +- `gmail.listLabels`: List all Gmail labels in the user's mailbox. + +### Time +- `time.getCurrentDate`: Gets the current date. +- `time.getCurrentTime`: Gets the current time. +- `time.getTimeZone`: Gets the local timezone. + +### People +- `people.getUserProfile`: Gets a user's profile information. +- `people.getMe`: Gets the profile information of the authenticated user. + +## Example Usage + +Here is an example of how to use the `docs.create` tool to create a new Google Doc: + +``` +docs.create(title="My New Doc", markdown="This is the content of my new doc.") +``` + +This will create a new Google Doc with the title "My New Doc" and the specified content. From b6da793652b2f5e79d054dcc1dcd1a1005fb8b2c Mon Sep 17 00:00:00 2001 From: Allen Hutchison Date: Fri, 14 Nov 2025 15:51:54 -0800 Subject: [PATCH 2/7] Update docs/development.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- docs/development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development.md b/docs/development.md index 6e7076b3..f3ef2430 100644 --- a/docs/development.md +++ b/docs/development.md @@ -20,7 +20,7 @@ This section guides contributors on how to build, modify, and understand the dev To clone the repository: ```bash -git clone https://github.com/google-gemini/gemini-cli-workspace.git # Or your fork's URL +git clone https://github.com/gemini-cli-extensions/workspace.git # Or your fork's URL cd gemini-cli-workspace ``` From e9cc507cf06580ec35bdb40905590a2a48d24b93 Mon Sep 17 00:00:00 2001 From: Allen Hutchison Date: Fri, 14 Nov 2025 15:52:14 -0800 Subject: [PATCH 3/7] Update docs/development.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- docs/development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development.md b/docs/development.md index f3ef2430..ec2854fd 100644 --- a/docs/development.md +++ b/docs/development.md @@ -99,7 +99,7 @@ npm run lint ### Coding Conventions - Please adhere to the coding style, patterns, and conventions used throughout the existing codebase. -- Consult [GEMINI.md](https://github.com/google-gemini/gemini-cli-workspace/blob/main/GEMINI.md) (typically found in the project root) for specific instructions related to AI-assisted development, including conventions for comments, and Git usage. +- Consult [GEMINI.md](https://github.com/gemini-cli-extensions/workspace/blob/main/GEMINI.md) (typically found in the project root) for specific instructions related to AI-assisted development, including conventions for comments, and Git usage. - **Imports:** Pay special attention to import paths. The project uses ESLint to enforce restrictions on relative imports between packages. ### Project Structure From fe5c6992d6c95d26053ac51a30d42cba402fabcd Mon Sep 17 00:00:00 2001 From: Allen Hutchison Date: Fri, 14 Nov 2025 15:52:27 -0800 Subject: [PATCH 4/7] Update README.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ff2919e3..02b05580 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ Once the extension is installed, you can use it to interact with your Google Wor ## Commands -This extension provides the following commands: +This extension provides a variety of commands. Here are a few examples: ### Get Schedule From cf6a72c7471b08c95a000cb349fcc0bc28f411a4 Mon Sep 17 00:00:00 2001 From: Allen Hutchison Date: Fri, 14 Nov 2025 15:52:49 -0800 Subject: [PATCH 5/7] Update docs/development.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- docs/development.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/development.md b/docs/development.md index ec2854fd..13c23f93 100644 --- a/docs/development.md +++ b/docs/development.md @@ -66,17 +66,15 @@ _ProTip_ after cloning create a git precommit hook file to ensure your commits are always clean. -```bash -echo " -# Run npm build and check for errors +cat <<'EOF' > .git/hooks/pre-commit #!/bin/sh # Run tests and linting before commit if ! (npm run test && npm run lint); then echo "Pre-commit checks failed. Commit aborted." exit 1 fi -" > .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit -``` +EOF +chmod +x .git/hooks/pre-commit #### Formatting From 4c053b1e2e0c7317ddbe0187867f665feaaee538 Mon Sep 17 00:00:00 2001 From: Allen Hutchison Date: Fri, 14 Nov 2025 15:53:07 -0800 Subject: [PATCH 6/7] Update docs/development.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- docs/development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development.md b/docs/development.md index 13c23f93..d724e0bc 100644 --- a/docs/development.md +++ b/docs/development.md @@ -128,4 +128,4 @@ node scripts/auth-utils.js - `clear`: Clear all authentication credentials. - `expire`: Force the access token to expire (for testing refresh). - `status`: Show current authentication status. -- `help`: Show the help message. \ No newline at end of file +- `help`: Show the help message. From e0e2249d06c9de49dbbea8cfc272b31dbd300937 Mon Sep 17 00:00:00 2001 From: Allen Hutchison Date: Mon, 17 Nov 2025 13:45:25 -0800 Subject: [PATCH 7/7] docs: update repository URLs and local clone path in documentation --- CONTRIBUTING.md | 2 +- README.md | 4 +--- docs/development.md | 2 +- docs/index.md | 9 --------- 4 files changed, 3 insertions(+), 14 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b962f35f..39a7af03 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -33,7 +33,7 @@ for this purpose. ### Self Assigning Issues -If you're looking for an issue to work on, check out our list of issues that are labeled ["help wanted"](https://github.com/google-gemini/gemini-cli-workspace/issues?q=is%3Aissue+state%3Aopen+label%3A%22help+wanted%22). +If you're looking for an issue to work on, check out our list of issues that are labeled ["help wanted"](https://github.com/gemini-cli-extensions/workspace/issues?q=is%3Aissue+state%3Aopen+label%3A%22help+wanted%22). To assign an issue to yourself, simply add a comment with the text `/assign`. The comment must contain only that text and nothing else. This command will assign the issue to you, provided it is not already assigned. diff --git a/README.md b/README.md index 02b05580..8744edbe 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Google Workspace Extension for Gemini CLI -[![Build Status](https://github.com/google-gemini/gemini-cli-workspace/actions/workflows/ci.yml/badge.svg)](https://github.com/google-gemini/gemini-cli-workspace/actions/workflows/ci.yml) +[![Build Status](https://github.com/gemini-cli-extensions/workspace/actions/workflows/ci.yml/badge.svg)](https://github.com/gemini-cli-extensions/workspace/actions/workflows/ci.yml) The Google Workspace extension for Gemini CLI brings the power of your Google Workspace apps to your command line. Manage your documents, spreadsheets, presentations, emails, chat, and calendar events without leaving your terminal. @@ -16,8 +16,6 @@ Install the Google Workspace extension by running the following command from you gemini extensions install https://github.com/gemini-cli-extensions/workspace ``` - - ## Usage Once the extension is installed, you can use it to interact with your Google Workspace apps. Here are a few examples: diff --git a/docs/development.md b/docs/development.md index d724e0bc..1413602c 100644 --- a/docs/development.md +++ b/docs/development.md @@ -21,7 +21,7 @@ To clone the repository: ```bash git clone https://github.com/gemini-cli-extensions/workspace.git # Or your fork's URL -cd gemini-cli-workspace +cd workspace ``` To install dependencies defined in `package.json` as well as root dependencies: diff --git a/docs/index.md b/docs/index.md index 8ff301e9..3f08b11c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -68,12 +68,3 @@ The extension provides the following tools: - `people.getUserProfile`: Gets a user's profile information. - `people.getMe`: Gets the profile information of the authenticated user. -## Example Usage - -Here is an example of how to use the `docs.create` tool to create a new Google Doc: - -``` -docs.create(title="My New Doc", markdown="This is the content of my new doc.") -``` - -This will create a new Google Doc with the title "My New Doc" and the specified content.