diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 31c73d4..6740a21 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -29,6 +29,7 @@ jobs: path: docs/.vitepress/dist deploy: + if: github.repository == 'jamubc/gemini-mcp-tool' environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} @@ -36,4 +37,4 @@ jobs: runs-on: ubuntu-latest steps: - id: deployment - uses: actions/deploy-pages@v4 \ No newline at end of file + uses: actions/deploy-pages@v4 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0b21f30 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,28 @@ +# AGENT Guidance + +## Development +- Use TypeScript with an object-oriented approach when adding new features. +- Follow test-driven development. Add or update tests under `tests` and run `npm test`. +- Lint code with `npm run lint` before committing. +- Build with `npm run build` to ensure TypeScript compiles. The compiled output + is written to `dist/`, which is gitignored and should not be committed. +- A `prepare` script builds `dist/` when installing from git, so `npx -y ` + works without committing compiled files. +- Run `ruff` on any Python files with `select = ["ALL"]`. Only ignore rules with a strong justification. +- Keep `@modelcontextprotocol/sdk` and `zod` listed as both peer and dev dependencies. Their versions should match across sections of `package.json`. +- Ensure `@types/node` is installed and referenced via `tsconfig.json` under `compilerOptions.types`. + +## Windows Compatibility +- The command executor uses `shell: process.platform === "win32"` to avoid ENOENT errors. +- Documented in `docs/resources/troubleshooting.md`. +- Prompts passed to the Gemini CLI on Windows are automatically quoted and escaped. +- Unit tests verify quoting for multi-line prompts with special characters, including embedded double quotes, on Windows. + +## Repository Scripts +- `npm test` – runs the Vitest suite. +- `npm run lint` – checks TypeScript types via `tsc --noEmit`. +- `npm run build` – compiles TypeScript to `dist/`. + +## Package.json Integrity +- Ensure `package.json` is valid JSON. Running `npm install` or `npm run lint` will fail fast if syntax errors are present. + diff --git a/CHANGELOG.md b/CHANGELOG.md index 4680616..fc2b032 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,9 @@ ## [Unreleased] +## [1.1.5] +- Bump version to 1.1.5 + ## [1.1.3] - "gemini reads, claude edits" - Added `changeMode` parameter to ask-gemini tool for structured edit responses using claude edit diff. diff --git a/README.md b/README.md index 715ef16..fc9da7d 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,12 @@ Before using this tool, ensure you have: claude mcp add gemini-cli -- npx -y gemini-mcp-tool ``` +To run the latest development version from GitHub without installing from npm: + +```bash +npx -y https://github.com/jamubc/gemini-mcp-tool +``` + ### Verify Installation Type `/mcp` inside Claude Code to verify the gemini-cli MCP is active. @@ -133,6 +139,16 @@ The sandbox mode allows you to safely test code changes, run scripts, or execute - `use gemini sandbox to install numpy and create a data visualization` - `test this code safely: Create a script that makes HTTP requests to an API` +### Brainstorming Sessions + +- `brainstorm ways to improve developer onboarding using design-thinking` +- `generate 5 marketing campaign ideas with constraints: budget under $500` + +### Handling Large Edit Suggestions + +- `ask gemini to refactor @src/**/*.ts changeMode:true` +- `/gemini-cli:fetch-chunk cacheKey= chunkIndex=2` + ### Tools (for the AI) These tools are designed to be used by the AI assistant. @@ -141,6 +157,18 @@ These tools are designed to be used by the AI assistant. - **`prompt`** (required): The analysis request. Use the `@` syntax to include file or directory references (e.g., `@src/main.js explain this code`) or ask general questions (e.g., `Please use a web search to find the latest news stories`). - **`model`** (optional): The Gemini model to use. Defaults to `gemini-2.5-pro`. - **`sandbox`** (optional): Set to `true` to run in sandbox mode for safe code execution. + - **`changeMode`** (optional): When `true`, returns structured edit suggestions that can be applied directly. Large change-mode responses can be retrieved in chunks using `fetch-chunk`. +- **`brainstorm`**: Generates structured brainstorming ideas using frameworks like SCAMPER or design thinking. + - **`prompt`** (required): The challenge or question to explore. + - **`methodology`** (optional): The creative framework to use (e.g., `scamper`, `design-thinking`). + - **`domain`** (optional): The subject area for context (e.g., `software`, `marketing`). + - **`constraints`** (optional): Any limitations to consider (e.g., `budget under $500`). + - **`existingContext`** (optional): Background information to build upon. + - **`ideaCount`** (optional): The number of ideas to generate. + - **`includeAnalysis`** (optional): Whether to include analysis for each idea. +- **`fetch-chunk`**: Retrieves cached chunks from a previous `ask-gemini` changeMode response. + - **`cacheKey`** (required): Provided in the initial changeMode response. + - **`chunkIndex`** (required): Which chunk to fetch (1-based index). - **`sandbox-test`**: Safely executes code or commands in Gemini's sandbox environment. Always runs in sandbox mode. - **`prompt`** (required): Code testing request (e.g., `Create and run a Python script that...` or `@script.py Run this safely`). - **`model`** (optional): The Gemini model to use. @@ -151,12 +179,17 @@ These tools are designed to be used by the AI assistant. You can use these commands directly in Claude Code's interface (compatibility with other clients has not been tested). -- **/analyze**: Analyzes files or directories using Gemini, or asks general questions. - - **`prompt`** (required): The analysis prompt. Use `@` syntax to include files (e.g., `/analyze prompt:@src/ summarize this directory`) or ask general questions (e.g., `/analyze prompt:Please use a web search to find the latest news stories`). -- **/sandbox**: Safely tests code or scripts in Gemini's sandbox environment. - - **`prompt`** (required): Code testing request (e.g., `/sandbox prompt:Create and run a Python script that processes CSV data` or `/sandbox prompt:@script.py Test this script safely`). -- **/help**: Displays the Gemini CLI help information. -- **/ping**: Tests the connection to the server. +- **/gemini-cli:analyze**: Analyzes files or directories using Gemini, or asks general questions. + - **`prompt`** (required): The analysis request. Use `@` syntax to include files (e.g., `/gemini-cli:analyze @src/ summarize this directory`) or ask general questions (e.g., `/gemini-cli:analyze Please use a web search to find the latest news stories`). Prefixing the request with `prompt:` is optional. + - **`changeMode`** (optional): Returns structured edit suggestions. Large change-mode responses will include a `cacheKey` for use with `/gemini-cli:fetch-chunk`. +- **/gemini-cli:sandbox**: Safely tests code or scripts in Gemini's sandbox environment. + - **`prompt`** (required): Code testing request (e.g., `/gemini-cli:sandbox Create and run a Python script that processes CSV data` or `/gemini-cli:sandbox @script.py Test this script safely`). Prefix with `prompt:` if your client requires it. +- **/gemini-cli:brainstorm**: Generates structured ideas using creative methodologies. + - **`prompt`** (required): The challenge to explore. + - Optional arguments: `methodology`, `domain`, `constraints`, `existingContext`, `ideaCount`, `includeAnalysis`. +- **/gemini-cli:fetch-chunk**: Retrieves additional change-mode edits using a provided `cacheKey` and `chunkIndex`. +- **/gemini-cli:help**: Displays the Gemini CLI help information. +- **/gemini-cli:ping**: Tests the connection to the server. - **`message`** (optional): A message to echo back. ## Contributing diff --git a/docs/.vitepress/theme/Layout.vue b/docs/.vitepress/theme/Layout.vue index 7185c30..67d56a6 100644 --- a/docs/.vitepress/theme/Layout.vue +++ b/docs/.vitepress/theme/Layout.vue @@ -6,7 +6,7 @@