better-gemini-mcp 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/CHANGELOG.md +57 -0
  2. package/LICENSE.md +13 -0
  3. package/README.md +291 -0
  4. package/dist/constants.d.ts +148 -0
  5. package/dist/constants.d.ts.map +1 -0
  6. package/dist/constants.js +295 -0
  7. package/dist/constants.js.map +1 -0
  8. package/dist/index.d.ts +11 -0
  9. package/dist/index.d.ts.map +1 -0
  10. package/dist/index.js +280 -0
  11. package/dist/index.js.map +1 -0
  12. package/dist/setup/index.d.ts +7 -0
  13. package/dist/setup/index.d.ts.map +1 -0
  14. package/dist/setup/index.js +6 -0
  15. package/dist/setup/index.js.map +1 -0
  16. package/dist/setup/wizard.d.ts +39 -0
  17. package/dist/setup/wizard.d.ts.map +1 -0
  18. package/dist/setup/wizard.js +222 -0
  19. package/dist/setup/wizard.js.map +1 -0
  20. package/dist/tools/analyze-directory.tool.d.ts +8 -0
  21. package/dist/tools/analyze-directory.tool.d.ts.map +1 -0
  22. package/dist/tools/analyze-directory.tool.js +195 -0
  23. package/dist/tools/analyze-directory.tool.js.map +1 -0
  24. package/dist/tools/deep-research.tool.d.ts +8 -0
  25. package/dist/tools/deep-research.tool.d.ts.map +1 -0
  26. package/dist/tools/deep-research.tool.js +153 -0
  27. package/dist/tools/deep-research.tool.js.map +1 -0
  28. package/dist/tools/fetch-chunk.tool.d.ts +8 -0
  29. package/dist/tools/fetch-chunk.tool.d.ts.map +1 -0
  30. package/dist/tools/fetch-chunk.tool.js +123 -0
  31. package/dist/tools/fetch-chunk.tool.js.map +1 -0
  32. package/dist/tools/health-check.tool.d.ts +8 -0
  33. package/dist/tools/health-check.tool.d.ts.map +1 -0
  34. package/dist/tools/health-check.tool.js +113 -0
  35. package/dist/tools/health-check.tool.js.map +1 -0
  36. package/dist/tools/index.d.ts +16 -0
  37. package/dist/tools/index.d.ts.map +1 -0
  38. package/dist/tools/index.js +35 -0
  39. package/dist/tools/index.js.map +1 -0
  40. package/dist/tools/quick-query.tool.d.ts +8 -0
  41. package/dist/tools/quick-query.tool.d.ts.map +1 -0
  42. package/dist/tools/quick-query.tool.js +154 -0
  43. package/dist/tools/quick-query.tool.js.map +1 -0
  44. package/dist/tools/registry.d.ts +52 -0
  45. package/dist/tools/registry.d.ts.map +1 -0
  46. package/dist/tools/registry.js +95 -0
  47. package/dist/tools/registry.js.map +1 -0
  48. package/dist/tools/validate-paths.tool.d.ts +8 -0
  49. package/dist/tools/validate-paths.tool.d.ts.map +1 -0
  50. package/dist/tools/validate-paths.tool.js +64 -0
  51. package/dist/tools/validate-paths.tool.js.map +1 -0
  52. package/dist/types.d.ts +221 -0
  53. package/dist/types.d.ts.map +1 -0
  54. package/dist/types.js +5 -0
  55. package/dist/types.js.map +1 -0
  56. package/dist/utils/commandExecutor.d.ts +28 -0
  57. package/dist/utils/commandExecutor.d.ts.map +1 -0
  58. package/dist/utils/commandExecutor.js +105 -0
  59. package/dist/utils/commandExecutor.js.map +1 -0
  60. package/dist/utils/geminiExecutor.d.ts +71 -0
  61. package/dist/utils/geminiExecutor.d.ts.map +1 -0
  62. package/dist/utils/geminiExecutor.js +281 -0
  63. package/dist/utils/geminiExecutor.js.map +1 -0
  64. package/dist/utils/ignorePatterns.d.ts +69 -0
  65. package/dist/utils/ignorePatterns.d.ts.map +1 -0
  66. package/dist/utils/ignorePatterns.js +178 -0
  67. package/dist/utils/ignorePatterns.js.map +1 -0
  68. package/dist/utils/index.d.ts +11 -0
  69. package/dist/utils/index.d.ts.map +1 -0
  70. package/dist/utils/index.js +18 -0
  71. package/dist/utils/index.js.map +1 -0
  72. package/dist/utils/logger.d.ts +39 -0
  73. package/dist/utils/logger.d.ts.map +1 -0
  74. package/dist/utils/logger.js +160 -0
  75. package/dist/utils/logger.js.map +1 -0
  76. package/dist/utils/pathValidator.d.ts +55 -0
  77. package/dist/utils/pathValidator.d.ts.map +1 -0
  78. package/dist/utils/pathValidator.js +137 -0
  79. package/dist/utils/pathValidator.js.map +1 -0
  80. package/dist/utils/responseCache.d.ts +80 -0
  81. package/dist/utils/responseCache.d.ts.map +1 -0
  82. package/dist/utils/responseCache.js +179 -0
  83. package/dist/utils/responseCache.js.map +1 -0
  84. package/dist/utils/responseChunker.d.ts +36 -0
  85. package/dist/utils/responseChunker.d.ts.map +1 -0
  86. package/dist/utils/responseChunker.js +96 -0
  87. package/dist/utils/responseChunker.js.map +1 -0
  88. package/package.json +62 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,57 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [1.0.0] - 2026-01-08
9
+
10
+ ### Added
11
+
12
+ - **Core MCP Server**: Stateless MCP server with stdio transport for Claude Code and VS Code Copilot integration
13
+ - **6 MCP Tools**:
14
+ - `quick_query`: Fast analysis using Gemini flash models
15
+ - `deep_research`: In-depth analysis using Gemini pro models
16
+ - `analyze_directory`: Directory structure summarization with ignore patterns
17
+ - `validate_paths`: Preflight path validation for security
18
+ - `health_check`: Server and Gemini CLI diagnostics
19
+ - `fetch_chunk`: Retrieve chunked response segments for large outputs
20
+ - **3-Tier Model Fallback**: Automatic fallback from Gemini 3 → Gemini 2.5 → auto-select on quota errors
21
+ - **Response Chunking**: Automatic chunking of responses exceeding 10KB with cache-based retrieval
22
+ - **Path Security**: Project root restriction, directory traversal prevention, @path validation
23
+ - **Ignore Patterns**: Respects `.gitignore` plus hard-coded exclusions (node_modules, .git, dist, etc.)
24
+ - **Setup Wizard**: `npx better-gemini-mcp init` for guided environment validation
25
+ - **Progress Notifications**: Keepalive updates every 25 seconds for long-running operations
26
+ - **Structured JSON Responses**: All tools return parseable JSON with consistent error format
27
+
28
+ ### Security
29
+
30
+ - Read-only enforcement: Gemini CLI invoked without `--yolo` flag
31
+ - System prompt enforces read-only analysis constraints
32
+ - Path validation prevents access outside project root
33
+ - API keys never logged
34
+
35
+ ### Technical
36
+
37
+ - TypeScript with strict mode, ES2022 target
38
+ - Node.js 18+ with ES Modules
39
+ - Zod schemas for input validation
40
+ - 1-hour TTL cache for chunked responses
41
+
42
+ ### Documentation
43
+
44
+ - Comprehensive README with installation, configuration, and usage
45
+ - Product Requirements Document (PRD)
46
+
47
+ ---
48
+
49
+ ## [Unreleased]
50
+
51
+ ### Planned for Future Releases?
52
+
53
+ - Docker distribution
54
+ - Custom allowlist configuration
55
+ - Sandbox mode support
56
+ - Session support for multi-turn conversations
57
+ - Custom `.geminiignore` pattern files
package/LICENSE.md ADDED
@@ -0,0 +1,13 @@
1
+ BSD 3-Clause License
2
+
3
+ Copyright 2025 capyBearista
4
+
5
+ Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
6
+
7
+ 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
8
+
9
+ 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
10
+
11
+ 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
12
+
13
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ā€œAS ISā€ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
package/README.md ADDED
@@ -0,0 +1,291 @@
1
+ # Better Gemini MCP
2
+
3
+ A lightweight, stateless MCP (Model Context Protocol) server that lets developer agents (Claude Code, GitHub Copilot) delegate deep repository analysis to the Gemini CLI. The server is read-only, returns structured JSON, and is optimized to reduce the calling agent's context and model usage.
4
+
5
+ **Status:** v1 complete. Core features are stable, but still early days. Feedback welcome!
6
+
7
+ **Primary goals:**
8
+ - Reduce agent context usage by letting Gemini CLI read large codebases locally and do its own research
9
+ - Reduce calling-agent model usage by offloading heavy analysis to Gemini
10
+ - Keep the server stateless and read-only for safety
11
+
12
+ **Quick links:**
13
+ - Product requirements doc: [docs/project-overview-PRD.md](docs/project-overview-PRD.md)
14
+
15
+ **Verified clients:** Claude Code, VS Code (GitHub Copilot), Cursor
16
+
17
+ **Important constraints:** stateless, read-only (no code patches), server-owned model selection, project-root path restriction.
18
+
19
+ **Table of contents**
20
+ - [Better Gemini MCP](#better-gemini-mcp)
21
+ - [Overview](#overview)
22
+ - [Prerequisites](#prerequisites)
23
+ - [Quickstart](#quickstart)
24
+ - [Tools (overview \& examples)](#tools-overview--examples)
25
+ - [Troubleshooting (common issues)](#troubleshooting-common-issues)
26
+ - [Developer notes](#developer-notes)
27
+ - [Running tests \& development](#running-tests--development)
28
+ - [Contributing](#contributing)
29
+ - [Guidelines](#guidelines)
30
+ - [License](#license)
31
+
32
+ ## Overview
33
+
34
+ Better Gemini MCP accepts research-style queries over the MCP protocol and spawns the Gemini CLI in headless, read-only mode to perform large-context analysis on local files referenced with `@path`. Results are returned as pretty-printed JSON strings suitable for programmatic consumption by agent clients.
35
+
36
+ ## Prerequisites
37
+ - Node.js 18+ installed
38
+ - Gemini CLI installed: `npm install -g @google/gemini-cli`
39
+ - Gemini CLI authenticated (recommended: `gemini` → Login with Google) or set `GEMINI_API_KEY`
40
+
41
+ Quick checks:
42
+ ```bash
43
+ node --version
44
+ gemini --version
45
+ ```
46
+
47
+ ## Quickstart
48
+ 1. Validate environment (recommended):
49
+ ```bash
50
+ npx @capybearista/better-gemini-mcp init
51
+ ```
52
+ This runs the setup wizard to check `gemini` is available, authentication is configured, and that a minimal headless invocation succeeds.
53
+
54
+ 2. Start the MCP server (stdio transport):
55
+ Or install globally:
56
+ ```bash
57
+ npm install -g @capybearista/better-gemini-mcp
58
+ better-gemini-mcp
59
+ ```
60
+
61
+ 3. Configure your MCP client (VS Code, Claude Code, etc.)
62
+
63
+ **Standard config** works in most of the tools:
64
+ ```json
65
+ {
66
+ "mcpServers": {
67
+ "better-gemini": {
68
+ "command": "npx",
69
+ "args": [
70
+ "@capybearista/better-gemini-mcp"
71
+ ]
72
+ }
73
+ }
74
+ }
75
+ ```
76
+
77
+ <details>
78
+ <summary>VS Code</summary>
79
+
80
+ Add to your VS Code MCP settings (create `.vscode/mcp.json` if needed):
81
+ ```json
82
+ {
83
+ "servers": {
84
+ "better-gemini-mcp": {
85
+ "command": "npx",
86
+ "args": [
87
+ "@capybearista/better-gemini-mcp"
88
+ ]
89
+ }
90
+ }
91
+ }
92
+ ```
93
+
94
+ </details>
95
+
96
+ <details>
97
+ <summary>Claude Code</summary>
98
+
99
+ **Option 1: Command line (recommended)**
100
+
101
+ Local (user-wide) scope
102
+ ```bash
103
+ # Add the MCP server via CLI
104
+ claude mcp add --transport stdio better-gemini-mcp -- npx better-gemini-mcp
105
+
106
+ # Verify it was added
107
+ claude mcp list
108
+ ```
109
+
110
+ Project scope
111
+
112
+ Navigate to your project directory, then run:
113
+ ```bash
114
+ # Add the MCP server via CLI
115
+ claude mcp add --scope project --transport stdio better-gemini-mcp -- npx better-gemini-mcp
116
+
117
+ # Verify it was added
118
+ claude mcp list
119
+ ```
120
+
121
+ **Option 2: Manual configuration**
122
+
123
+ Add to `.mcp.json` in your project root (project scope):
124
+ ```json
125
+ {
126
+ "mcpServers": {
127
+ "better-gemini-mcp": {
128
+ "command": "npx",
129
+ "args": [
130
+ "@capybearista/better-gemini-mcp"
131
+ ]
132
+ }
133
+ }
134
+ }
135
+ ```
136
+
137
+ Or add to `~/.claude/settings.json` for local scope.
138
+
139
+ After adding the server, restart Claude Code and use `/mcp` to verify the connection.
140
+
141
+ </details>
142
+
143
+ <details>
144
+ <summary>Cursor</summary>
145
+
146
+ Go to `Cursor Settings` -> `Tools & MCP` -> `Add a Custom MCP Server`. Add the following configuration:
147
+ ```json
148
+ {
149
+ "mcpServers": {
150
+ "better-gemini-mcp": {
151
+ "type": "stdio",
152
+ "command": "node",
153
+ "args": [
154
+ "@capybearista/better-gemini-mcp"
155
+ ]
156
+ }
157
+ }
158
+ }
159
+ ```
160
+
161
+ </details>
162
+
163
+ > [!NOTE]
164
+ > The server automatically uses the directory where the IDE opened your workspace as the project root or where your terminal is. To analyze a different directory, optionally set `PROJECT_ROOT`:
165
+
166
+ Example
167
+ ```json
168
+ {
169
+ "mcpServers": {
170
+ "better-gemini-mcp": {
171
+ "command": "npx",
172
+ "args": [
173
+ "@capybearista/better-gemini-mcp"
174
+ ],
175
+ "env": {
176
+ "PROJECT_ROOT": "/path/to/your/project"
177
+ }
178
+ }
179
+ }
180
+ }
181
+ ```
182
+
183
+ 4. Restart your MCP client
184
+ 5. Test with your agent: Try asking "Use better-gemini-mcp to analyze the project."
185
+
186
+ ## Tools (overview & examples)
187
+ - **quick_query** — Fast, focused analysis (flash model). Example:
188
+ ```json
189
+ {
190
+ "prompt": "Explain @src/auth.ts login flow",
191
+ "focus": "security",
192
+ "responseStyle": "concise"
193
+ }
194
+ ```
195
+ - **deep_research** — Heavy-duty analysis across many files (pro model). Example:
196
+ ```json
197
+ {
198
+ "prompt": "Analyze authentication across @src/auth and @src/middleware",
199
+ "focus": "architecture",
200
+ "citationMode": "paths_only" }
201
+ ```
202
+ - **analyze_directory** — Map a directory and summarize files. Example:
203
+ ```json
204
+ {
205
+ "path": "src",
206
+ "depth": 3,
207
+ "maxFiles": 200
208
+ }
209
+ ```
210
+ - **validate_paths** — Preflight `@path` checks. Example:
211
+ ```json
212
+ {
213
+ "paths": ["src/auth.ts", "README.md"]
214
+ }
215
+ ```
216
+ - **health_check** — Server + Gemini diagnostics. Example:
217
+ ```json
218
+ {
219
+ "includeDiagnostics": true
220
+ }
221
+ ```
222
+ - **fetch_chunk** — Retrieve chunked responses. Example:
223
+ ```json
224
+ {
225
+ "cacheKey": "cache_abc123", "chunkIndex": 2
226
+ }
227
+ ```
228
+
229
+ Each tool returns a pretty-printed JSON string in the MCP `text` content. When large outputs are produced, responses are chunked (default ~10KB chunks), cached for 1 hour, and the initial response contains `chunks` metadata with a `cacheKey`.
230
+
231
+ ## Troubleshooting (common issues)
232
+ - `GEMINI_CLI_NOT_FOUND`: Install Gemini CLI: `npm install -g @google/gemini-cli`
233
+ - `AUTH_MISSING`: Run `gemini`, and authenticate or set `GEMINI_API_KEY`
234
+ - `.gitignore` blocking files: Gemini respects `.gitignore` by default; toggle `fileFiltering.respectGitIgnore` in `gemini /settings` if you intentionally want ignored files included (note: this changes Gemini behavior globally)
235
+ - `PATH_NOT_ALLOWED`: All `@path` references must resolve inside the configured project root (`process.cwd()` by default). Use `validate_paths` to pre-check paths.
236
+ - `QUOTA_EXCEEDED`: Server retries with fallback models; if all tiers are exhausted, reduce scope (use `quick_query`) or wait for quota reset.
237
+
238
+ ## Developer notes
239
+ - The authoritative system prompt and constants live in `src/constants.ts`.
240
+ - The Gemini CLI integration and model fallback logic live in `src/utils/geminiExecutor.ts`.
241
+ - Tools are registered under `src/tools/*.tool.ts` and follow the UnifiedTool pattern in `src/tools/registry.ts`.
242
+ - Key design rules: stateless operation, read-only enforcement, server-managed model tiers, project-root path restriction.
243
+
244
+ ### Running tests & development
245
+
246
+ ```bash
247
+ npm run dev
248
+
249
+ # Run tests
250
+ npm test
251
+
252
+ # Run unit tests only
253
+ npm run test:unit
254
+
255
+ # Run integration tests
256
+ npm run test:integration
257
+
258
+ # Lint
259
+ npm run lint
260
+ ```
261
+
262
+ ## Contributing
263
+
264
+ Contributions are welcome! Please:
265
+
266
+ 1. Fork the repository
267
+ 2. Create a feature branch (`git switch -c feature/amazing-feature`)
268
+ 3. Make your changes
269
+ 4. Run tests (`npm test`)
270
+ 5. Commit (`git commit -m 'Add amazing feature'`)
271
+ 6. Push (`git push origin feature/amazing-feature`)
272
+ 7. Open a Pull Request
273
+
274
+ ### Guidelines
275
+
276
+ - **TypeScript strict mode**: All code uses TypeScript with strict type checking
277
+ - **ES Modules**: All imports must use `.js` extension (not `.ts`) for Node16 module resolution
278
+ - **Code style**: Follow existing patterns in `src/tools/*.tool.ts` (use UnifiedTool pattern)
279
+ - **Stateless design**: No session files, persistent storage, or server-managed state
280
+ - **Read-only enforcement**: Never modify files; all Gemini CLI calls must be read-only
281
+ - **Testing**: Add unit/integration tests in `tests/` directory
282
+
283
+ ## License
284
+
285
+ [BSD-3-Clause License](./LICENSE.md)
286
+
287
+ ---
288
+
289
+ <p align="center">
290
+ Made with ā™” for the AI-assisted dev community
291
+ </p>
@@ -0,0 +1,148 @@
1
+ /**
2
+ * Constants for Better Gemini MCP Server
3
+ * Error codes, model configurations, system prompt, and protocol constants
4
+ */
5
+ export declare const LOG_PREFIX = "[BGMCP]";
6
+ export declare const ERROR_CODES: {
7
+ /** Tool called with invalid parameters */
8
+ readonly INVALID_ARGUMENT: "INVALID_ARGUMENT";
9
+ /** Path is outside project root */
10
+ readonly PATH_NOT_ALLOWED: "PATH_NOT_ALLOWED";
11
+ /** gemini binary not on PATH */
12
+ readonly GEMINI_CLI_NOT_FOUND: "GEMINI_CLI_NOT_FOUND";
13
+ /** Gemini CLI execution failed */
14
+ readonly GEMINI_CLI_ERROR: "GEMINI_CLI_ERROR";
15
+ /** Gemini CLI authentication not configured */
16
+ readonly AUTH_MISSING: "AUTH_MISSING";
17
+ /** Gemini API quota exhausted (after fallback) */
18
+ readonly QUOTA_EXCEEDED: "QUOTA_EXCEEDED";
19
+ /** Chunk cache key not found or expired */
20
+ readonly CACHE_EXPIRED: "CACHE_EXPIRED";
21
+ /** Requested chunk index out of range */
22
+ readonly INVALID_CHUNK_INDEX: "INVALID_CHUNK_INDEX";
23
+ /** Unexpected server error */
24
+ readonly INTERNAL: "INTERNAL";
25
+ };
26
+ export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
27
+ export declare const ERROR_MESSAGES: {
28
+ readonly QUOTA_EXCEEDED: "Quota exceeded for quota metric";
29
+ readonly QUOTA_EXCEEDED_SHORT: "āš ļø Gemini API quota exceeded. Falling back to alternative model...";
30
+ readonly TOOL_NOT_FOUND: "not found in registry";
31
+ readonly NO_PROMPT_PROVIDED: "Please provide a prompt for analysis. Use @ syntax to include files (e.g., '@src/auth.ts explain what this does') or ask general questions";
32
+ readonly GEMINI_CLI_NOT_FOUND: "Gemini CLI not found on PATH. Install with: npm install -g @google/gemini-cli";
33
+ readonly AUTH_MISSING: "Gemini CLI authentication not configured. Run 'gemini' and select 'Login with Google', or set GEMINI_API_KEY environment variable.";
34
+ readonly PATH_NOT_ALLOWED: "Path is outside project root";
35
+ readonly CACHE_EXPIRED: "Cache key not found or expired. Re-run original query to regenerate response.";
36
+ readonly INVALID_CHUNK_INDEX: "Requested chunk index out of range";
37
+ };
38
+ export declare const STATUS_MESSAGES: {
39
+ readonly QUOTA_SWITCHING: "🚫 Primary model quota exceeded, switching to fallback model...";
40
+ readonly FALLBACK_RETRY: "⚔ Retrying with fallback model...";
41
+ readonly FALLBACK_SUCCESS: "āœ… Fallback model completed successfully";
42
+ readonly AUTO_SELECT_RETRY: "šŸ”„ Retrying with auto-selected model...";
43
+ readonly PROCESSING_START: "šŸ” Starting analysis (may take 5-15 minutes for large codebases)";
44
+ readonly PROCESSING_CONTINUE: "ā³ Still processing... Gemini is working on your request";
45
+ readonly PROCESSING_COMPLETE: "āœ… Analysis completed successfully";
46
+ };
47
+ export declare const MODELS: {
48
+ readonly FLASH_DEFAULT: "gemini-3-flash-preview";
49
+ readonly PRO_DEFAULT: "gemini-3-pro-preview";
50
+ readonly FLASH_FALLBACK: "gemini-2.5-flash";
51
+ readonly PRO_FALLBACK: "gemini-2.5-pro";
52
+ readonly AUTO_SELECT: null;
53
+ };
54
+ /**
55
+ * Model selection configuration per tool
56
+ */
57
+ export declare const MODEL_TIERS: {
58
+ readonly quick_query: {
59
+ readonly tier1: "gemini-3-flash-preview";
60
+ readonly tier2: "gemini-2.5-flash";
61
+ readonly tier3: null;
62
+ };
63
+ readonly deep_research: {
64
+ readonly tier1: "gemini-3-pro-preview";
65
+ readonly tier2: "gemini-2.5-pro";
66
+ readonly tier3: null;
67
+ };
68
+ readonly analyze_directory: {
69
+ readonly tier1: "gemini-3-flash-preview";
70
+ readonly tier2: "gemini-2.5-flash";
71
+ readonly tier3: null;
72
+ };
73
+ };
74
+ export declare const PROTOCOL: {
75
+ readonly ROLES: {
76
+ readonly USER: "user";
77
+ readonly ASSISTANT: "assistant";
78
+ };
79
+ readonly CONTENT_TYPES: {
80
+ readonly TEXT: "text";
81
+ };
82
+ readonly STATUS: {
83
+ readonly SUCCESS: "success";
84
+ readonly ERROR: "error";
85
+ readonly FAILED: "failed";
86
+ };
87
+ readonly NOTIFICATIONS: {
88
+ readonly PROGRESS: "notifications/progress";
89
+ };
90
+ readonly KEEPALIVE_INTERVAL: 25000;
91
+ };
92
+ export declare const CLI: {
93
+ readonly COMMANDS: {
94
+ readonly GEMINI: "gemini";
95
+ readonly WHICH: "which";
96
+ readonly WHERE: "where";
97
+ };
98
+ readonly FLAGS: {
99
+ readonly MODEL: "-m";
100
+ readonly PROMPT: "-p";
101
+ readonly YES: "-y";
102
+ readonly OUTPUT_FORMAT: "--output-format";
103
+ readonly VERSION: "--version";
104
+ readonly HELP: "--help";
105
+ };
106
+ readonly OUTPUT_FORMATS: {
107
+ readonly JSON: "json";
108
+ readonly STREAM_JSON: "stream-json";
109
+ };
110
+ };
111
+ export declare const DEFAULTS: {
112
+ /** Maximum files to enumerate in analyze_directory */
113
+ readonly MAX_FILES: 500;
114
+ /** Response chunk size in KB (for chunking large responses) */
115
+ readonly RESPONSE_CHUNK_SIZE_KB: 10;
116
+ /** Cache TTL in milliseconds (1 hour) */
117
+ readonly CACHE_TTL_MS: 3600000;
118
+ /** Maximum response size before truncation (50KB) */
119
+ readonly MAX_RESPONSE_SIZE: number;
120
+ };
121
+ export declare const DEFAULT_IGNORE_PATTERNS: readonly [".git/", "node_modules/", "dist/", "build/", "out/", ".next/", "coverage/", ".venv/", "venv/", "__pycache__/"];
122
+ export declare const SYSTEM_PROMPT = "\nYou are analyzing a codebase on behalf of an AI coding agent.\n\nWHEN TO USE THIS TOOL:\n- The calling agent should use MCP tools (quick_query, deep_research, analyze_directory) FIRST when questions involve repository files or code analysis\n- This reduces the calling agent's context and model usage by offloading heavy reading/analysis to Gemini CLI's large context window\n- Prefer using tools over asking the agent to read files directly\n\nCRITICAL CONSTRAINTS:\n- Read-only analysis ONLY (no write/edit tools available without --yolo flag)\n- Do NOT suggest code changes, patches, or file modifications\n- Do NOT attempt to use run_shell_command or write_file (not available)\n\nOPTIMIZATION FOR TOKEN EFFICIENCY:\n- The calling agent has limited context - be concise but thorough\n- Prioritize KEY findings over exhaustive details\n- Include file paths for all referenced code\n- Use bullet points and structured formatting for clarity\n- If asked about security/architecture/performance, focus ONLY on that dimension\n\nOUTPUT FORMAT:\n- Start with a 2-3 sentence executive summary\n- Provide detailed findings with file path references\n- End with a \"## Files Referenced\" section listing all paths examined\n";
123
+ export declare const SERVER_INFO: {
124
+ readonly NAME: "better-gemini-mcp";
125
+ readonly VERSION: "1.0.0";
126
+ readonly DESCRIPTION: "Stateless MCP server that proxies research queries to Gemini CLI";
127
+ };
128
+ export declare const WIZARD_MESSAGES: {
129
+ readonly HEADER: "\nBetter Gemini MCP — Setup Wizard\n================================\n";
130
+ readonly SUCCESS_HEADER: "\nSetup Complete! šŸŽ‰\n==================\n";
131
+ readonly STEP_GEMINI_INSTALL: "[1/2] Checking Gemini CLI installation...";
132
+ readonly STEP_AUTH: "[2/3] Checking authentication...";
133
+ readonly STEP_TEST: "[2/2] Testing Gemini CLI...";
134
+ readonly GEMINI_FOUND: (path: string, version: string) => string;
135
+ readonly GEMINI_NOT_FOUND: " āœ— Gemini CLI not found\n\n Install Gemini CLI:\n npm install -g @google/gemini-cli\n \n Documentation:\n https://github.com/google-gemini/gemini-cli";
136
+ readonly AUTH_GOOGLE: " āœ“ Authenticated session detected (Login with Google)";
137
+ readonly AUTH_API_KEY: " āœ“ GEMINI_API_KEY environment variable set";
138
+ readonly AUTH_VERTEX: " āœ“ Vertex AI credentials detected";
139
+ readonly AUTH_NOT_FOUND: " āœ— No authentication configured\n\n Option 1: Login with Google (Recommended)\n - Run: gemini\n - Select \"Login with Google\" and follow prompts\n - Your credentials will be cached for future sessions\n - Works seamlessly in headless mode after initial setup\n\n Option 2: Use Gemini API Key (Alternative for automation)\n - Get API key: https://aistudio.google.com/app/apikey\n - Set in terminal: export GEMINI_API_KEY=\"your-key-here\"\n - Make persistent: Add to ~/.bashrc or ~/.zshrc\n\n Option 3: Vertex AI (For enterprise users)\n - See: https://github.com/google-gemini/gemini-cli/blob/main/docs/get-started/authentication.md#vertex-ai";
140
+ readonly TEST_SUCCESS: " āœ“ Test invocation successful";
141
+ readonly TEST_FAILED: (error: string) => string;
142
+ readonly NEXT_STEPS: "\nNext steps:\n1. Configure your MCP client (Claude Desktop, VS Code)\n2. Add this server to your MCP config:\n\n For Claude Desktop (~/.config/Claude/claude_desktop_config.json):\n {\n \"mcpServers\": {\n \"better-gemini-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"better-gemini-mcp\"]\n }\n }\n }\n\n For VS Code (settings.json or mcp-settings.json):\n {\n \"mcp.servers\": {\n \"better-gemini-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"better-gemini-mcp\"]\n }\n }\n }\n\n3. Restart your MCP client\n4. Test with: \"Can you list your available tools?\"\n\nDocumentation: https://github.com/YOUR_ORG/better-gemini-mcp\n";
143
+ readonly FIX_ISSUES: "\nPlease fix the issues above and run 'npx better-gemini-mcp init' again.\n";
144
+ readonly STARTUP_SUCCESS: "āœ… All checks passed! Server starting...";
145
+ readonly STARTUP_GEMINI_NOT_FOUND: "āŒ Gemini CLI not found on PATH\n→ Install: npm install -g @google/gemini-cli\n→ Docs: https://github.com/google-gemini/gemini-cli\n→ Run 'npx better-gemini-mcp init' for guided setup";
146
+ readonly STARTUP_AUTH_MISSING: "āŒ Gemini CLI authentication not configured\n→ Recommended: Run 'gemini' and select \"Login with Google\"\n→ Alternative: Set GEMINI_API_KEY environment variable\n - Get API key: https://aistudio.google.com/app/apikey\n - Set in terminal: export GEMINI_API_KEY=\"your-key-here\"\n→ Run 'npx better-gemini-mcp init' for guided setup";
147
+ };
148
+ //# sourceMappingURL=constants.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,eAAO,MAAM,UAAU,YAAY,CAAC;AAMpC,eAAO,MAAM,WAAW;IACtB,0CAA0C;;IAE1C,mCAAmC;;IAEnC,gCAAgC;;IAEhC,kCAAkC;;IAElC,+CAA+C;;IAE/C,kDAAkD;;IAElD,2CAA2C;;IAE3C,yCAAyC;;IAEzC,8BAA8B;;CAEtB,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAMvE,eAAO,MAAM,cAAc;;;;;;;;;;CAUjB,CAAC;AAMX,eAAO,MAAM,eAAe;;;;;;;;CAQlB,CAAC;AAMX,eAAO,MAAM,MAAM;;;;;;CAWT,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;CAgBd,CAAC;AAMX,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;CAsBX,CAAC;AAMX,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;;CAqBN,CAAC;AAMX,eAAO,MAAM,QAAQ;IACnB,sDAAsD;;IAEtD,+DAA+D;;IAE/D,yCAAyC;;IAEzC,qDAAqD;;CAE7C,CAAC;AAMX,eAAO,MAAM,uBAAuB,0HAW1B,CAAC;AAMX,eAAO,MAAM,aAAa,0sCAwBzB,CAAC;AAMF,eAAO,MAAM,WAAW;;;;CAId,CAAC;AAMX,eAAO,MAAM,eAAe;;;;;;kCAaL,MAAM,WAAW,MAAM;;;;;;;kCA6BvB,MAAM;;;;;;CAiDnB,CAAC"}