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.
- package/CHANGELOG.md +57 -0
- package/LICENSE.md +13 -0
- package/README.md +291 -0
- package/dist/constants.d.ts +148 -0
- package/dist/constants.d.ts.map +1 -0
- package/dist/constants.js +295 -0
- package/dist/constants.js.map +1 -0
- package/dist/index.d.ts +11 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +280 -0
- package/dist/index.js.map +1 -0
- package/dist/setup/index.d.ts +7 -0
- package/dist/setup/index.d.ts.map +1 -0
- package/dist/setup/index.js +6 -0
- package/dist/setup/index.js.map +1 -0
- package/dist/setup/wizard.d.ts +39 -0
- package/dist/setup/wizard.d.ts.map +1 -0
- package/dist/setup/wizard.js +222 -0
- package/dist/setup/wizard.js.map +1 -0
- package/dist/tools/analyze-directory.tool.d.ts +8 -0
- package/dist/tools/analyze-directory.tool.d.ts.map +1 -0
- package/dist/tools/analyze-directory.tool.js +195 -0
- package/dist/tools/analyze-directory.tool.js.map +1 -0
- package/dist/tools/deep-research.tool.d.ts +8 -0
- package/dist/tools/deep-research.tool.d.ts.map +1 -0
- package/dist/tools/deep-research.tool.js +153 -0
- package/dist/tools/deep-research.tool.js.map +1 -0
- package/dist/tools/fetch-chunk.tool.d.ts +8 -0
- package/dist/tools/fetch-chunk.tool.d.ts.map +1 -0
- package/dist/tools/fetch-chunk.tool.js +123 -0
- package/dist/tools/fetch-chunk.tool.js.map +1 -0
- package/dist/tools/health-check.tool.d.ts +8 -0
- package/dist/tools/health-check.tool.d.ts.map +1 -0
- package/dist/tools/health-check.tool.js +113 -0
- package/dist/tools/health-check.tool.js.map +1 -0
- package/dist/tools/index.d.ts +16 -0
- package/dist/tools/index.d.ts.map +1 -0
- package/dist/tools/index.js +35 -0
- package/dist/tools/index.js.map +1 -0
- package/dist/tools/quick-query.tool.d.ts +8 -0
- package/dist/tools/quick-query.tool.d.ts.map +1 -0
- package/dist/tools/quick-query.tool.js +154 -0
- package/dist/tools/quick-query.tool.js.map +1 -0
- package/dist/tools/registry.d.ts +52 -0
- package/dist/tools/registry.d.ts.map +1 -0
- package/dist/tools/registry.js +95 -0
- package/dist/tools/registry.js.map +1 -0
- package/dist/tools/validate-paths.tool.d.ts +8 -0
- package/dist/tools/validate-paths.tool.d.ts.map +1 -0
- package/dist/tools/validate-paths.tool.js +64 -0
- package/dist/tools/validate-paths.tool.js.map +1 -0
- package/dist/types.d.ts +221 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +5 -0
- package/dist/types.js.map +1 -0
- package/dist/utils/commandExecutor.d.ts +28 -0
- package/dist/utils/commandExecutor.d.ts.map +1 -0
- package/dist/utils/commandExecutor.js +105 -0
- package/dist/utils/commandExecutor.js.map +1 -0
- package/dist/utils/geminiExecutor.d.ts +71 -0
- package/dist/utils/geminiExecutor.d.ts.map +1 -0
- package/dist/utils/geminiExecutor.js +281 -0
- package/dist/utils/geminiExecutor.js.map +1 -0
- package/dist/utils/ignorePatterns.d.ts +69 -0
- package/dist/utils/ignorePatterns.d.ts.map +1 -0
- package/dist/utils/ignorePatterns.js +178 -0
- package/dist/utils/ignorePatterns.js.map +1 -0
- package/dist/utils/index.d.ts +11 -0
- package/dist/utils/index.d.ts.map +1 -0
- package/dist/utils/index.js +18 -0
- package/dist/utils/index.js.map +1 -0
- package/dist/utils/logger.d.ts +39 -0
- package/dist/utils/logger.d.ts.map +1 -0
- package/dist/utils/logger.js +160 -0
- package/dist/utils/logger.js.map +1 -0
- package/dist/utils/pathValidator.d.ts +55 -0
- package/dist/utils/pathValidator.d.ts.map +1 -0
- package/dist/utils/pathValidator.js +137 -0
- package/dist/utils/pathValidator.js.map +1 -0
- package/dist/utils/responseCache.d.ts +80 -0
- package/dist/utils/responseCache.d.ts.map +1 -0
- package/dist/utils/responseCache.js +179 -0
- package/dist/utils/responseCache.js.map +1 -0
- package/dist/utils/responseChunker.d.ts +36 -0
- package/dist/utils/responseChunker.d.ts.map +1 -0
- package/dist/utils/responseChunker.js +96 -0
- package/dist/utils/responseChunker.js.map +1 -0
- 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"}
|