@j0hanz/code-review-analyst-mcp 0.1.0 → 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/README.md +197 -41
- package/dist/index.js +0 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,11 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
<!-- mcp-name: io.github.j0hanz/code-review-analyst -->
|
|
4
4
|
|
|
5
|
-
[](package.json) [](package.json) [](https://www.npmjs.com/package/@j0hanz/code-review-analyst-mcp) [](package.json) [](package.json) [](package.json) [](package.json)
|
|
6
6
|
|
|
7
|
-
[](https://insiders.vscode.dev/redirect/mcp/install?name=Code
|
|
7
|
+
[](https://insiders.vscode.dev/redirect/mcp/install?name=Code+Review+Analyst&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fcode-review-analyst-mcp%40latest%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=Code+Review+Analyst&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fcode-review-analyst-mcp%40latest%22%5D%7D&quality=insiders) [](https://vs-open.link/mcp-install?%7B%22name%22%3A%22code-review-analyst%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fcode-review-analyst-mcp%40latest%22%5D%7D)
|
|
8
8
|
|
|
9
|
-
[](https://cursor.com/en/install-mcp?name=Code%20Review%20Analyst&
|
|
9
|
+
[](https://cursor.com/en/install-mcp?name=Code+Review+Analyst&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovY29kZS1yZXZpZXctYW5hbHlzdC1tY3BAbGF0ZXN0Il19) [](https://block.github.io/goose/extension?cmd=npx&arg=-y%20%40j0hanz%2Fcode-review-analyst-mcp%40latest&id=code-review-analyst&name=Code%20Review%20Analyst&description=Gemini-powered%20MCP%20server%20for%20code%20review%20analysis.)
|
|
10
10
|
|
|
11
11
|
Gemini-powered MCP server for pull request analysis with structured outputs for findings, release risk, and focused patch suggestions.
|
|
12
12
|
|
|
@@ -22,6 +22,7 @@ This server runs over **stdio transport** and exposes three review-focused tools
|
|
|
22
22
|
- Optional task execution support (`execution.taskSupport: "optional"`) with in-memory task store.
|
|
23
23
|
- Progress notifications when clients provide `_meta.progressToken`.
|
|
24
24
|
- Shared Gemini adapter with timeout, retries, safety thresholds, and structured observability logs to `stderr`.
|
|
25
|
+
- Docker image available via GitHub Container Registry.
|
|
25
26
|
|
|
26
27
|
## Requirements
|
|
27
28
|
|
|
@@ -38,7 +39,7 @@ Standard config for most MCP clients:
|
|
|
38
39
|
"mcpServers": {
|
|
39
40
|
"code-review-analyst": {
|
|
40
41
|
"command": "npx",
|
|
41
|
-
"args": ["-y", "code-review-analyst-mcp@latest"],
|
|
42
|
+
"args": ["-y", "@j0hanz/code-review-analyst-mcp@latest"],
|
|
42
43
|
"env": {
|
|
43
44
|
"GEMINI_API_KEY": "YOUR_API_KEY"
|
|
44
45
|
}
|
|
@@ -55,8 +56,8 @@ Standard config for most MCP clients:
|
|
|
55
56
|
<details>
|
|
56
57
|
<summary><b>Install in VS Code</b></summary>
|
|
57
58
|
|
|
58
|
-
[](https://insiders.vscode.dev/redirect/mcp/install?name=Code
|
|
59
|
-
[](https://insiders.vscode.dev/redirect/mcp/install?name=Code
|
|
59
|
+
[](https://insiders.vscode.dev/redirect/mcp/install?name=Code+Review+Analyst&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fcode-review-analyst-mcp%40latest%22%5D%7D)
|
|
60
|
+
[](https://insiders.vscode.dev/redirect/mcp/install?name=Code+Review+Analyst&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fcode-review-analyst-mcp%40latest%22%5D%7D&quality=insiders)
|
|
60
61
|
|
|
61
62
|
`.vscode/mcp.json`
|
|
62
63
|
|
|
@@ -65,7 +66,7 @@ Standard config for most MCP clients:
|
|
|
65
66
|
"servers": {
|
|
66
67
|
"code-review-analyst": {
|
|
67
68
|
"command": "npx",
|
|
68
|
-
"args": ["-y", "code-review-analyst-mcp@latest"],
|
|
69
|
+
"args": ["-y", "@j0hanz/code-review-analyst-mcp@latest"],
|
|
69
70
|
"env": {
|
|
70
71
|
"GEMINI_API_KEY": "YOUR_API_KEY"
|
|
71
72
|
}
|
|
@@ -77,15 +78,17 @@ Standard config for most MCP clients:
|
|
|
77
78
|
CLI install:
|
|
78
79
|
|
|
79
80
|
```bash
|
|
80
|
-
code --add-mcp '{"name":"code-review-analyst","command":"npx","args":["-y","code-review-analyst-mcp@latest"]}'
|
|
81
|
+
code --add-mcp '{"name":"code-review-analyst","command":"npx","args":["-y","@j0hanz/code-review-analyst-mcp@latest"]}'
|
|
81
82
|
```
|
|
82
83
|
|
|
84
|
+
For more info, see [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).
|
|
85
|
+
|
|
83
86
|
</details>
|
|
84
87
|
|
|
85
88
|
<details>
|
|
86
89
|
<summary><b>Install in Cursor</b></summary>
|
|
87
90
|
|
|
88
|
-
[](https://cursor.com/en/install-mcp?name=Code
|
|
91
|
+
[](https://cursor.com/en/install-mcp?name=Code+Review+Analyst&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovY29kZS1yZXZpZXctYW5hbHlzdC1tY3BAbGF0ZXN0Il19)
|
|
89
92
|
|
|
90
93
|
`~/.cursor/mcp.json`
|
|
91
94
|
|
|
@@ -94,7 +97,7 @@ code --add-mcp '{"name":"code-review-analyst","command":"npx","args":["-y","code
|
|
|
94
97
|
"mcpServers": {
|
|
95
98
|
"code-review-analyst": {
|
|
96
99
|
"command": "npx",
|
|
97
|
-
"args": ["-y", "code-review-analyst-mcp@latest"],
|
|
100
|
+
"args": ["-y", "@j0hanz/code-review-analyst-mcp@latest"],
|
|
98
101
|
"env": {
|
|
99
102
|
"GEMINI_API_KEY": "YOUR_API_KEY"
|
|
100
103
|
}
|
|
@@ -103,6 +106,8 @@ code --add-mcp '{"name":"code-review-analyst","command":"npx","args":["-y","code
|
|
|
103
106
|
}
|
|
104
107
|
```
|
|
105
108
|
|
|
109
|
+
For more info, see [Cursor MCP docs](https://cursor.com/docs/context/mcp).
|
|
110
|
+
|
|
106
111
|
</details>
|
|
107
112
|
|
|
108
113
|
<details>
|
|
@@ -115,7 +120,7 @@ code --add-mcp '{"name":"code-review-analyst","command":"npx","args":["-y","code
|
|
|
115
120
|
"mcpServers": {
|
|
116
121
|
"code-review-analyst": {
|
|
117
122
|
"command": "npx",
|
|
118
|
-
"args": ["-y", "code-review-analyst-mcp@latest"],
|
|
123
|
+
"args": ["-y", "@j0hanz/code-review-analyst-mcp@latest"],
|
|
119
124
|
"env": {
|
|
120
125
|
"GEMINI_API_KEY": "YOUR_API_KEY"
|
|
121
126
|
}
|
|
@@ -124,15 +129,122 @@ code --add-mcp '{"name":"code-review-analyst","command":"npx","args":["-y","code
|
|
|
124
129
|
}
|
|
125
130
|
```
|
|
126
131
|
|
|
132
|
+
For more info, see [Claude Desktop MCP docs](https://modelcontextprotocol.io/docs/develop/connect-local-servers).
|
|
133
|
+
|
|
127
134
|
</details>
|
|
128
135
|
|
|
129
136
|
<details>
|
|
130
137
|
<summary><b>Install in Claude Code</b></summary>
|
|
131
138
|
|
|
132
139
|
```bash
|
|
133
|
-
claude mcp add code-review-analyst -- npx -y code-review-analyst-mcp@latest
|
|
140
|
+
claude mcp add code-review-analyst -- npx -y @j0hanz/code-review-analyst-mcp@latest
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
For more info, see [Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp).
|
|
144
|
+
|
|
145
|
+
</details>
|
|
146
|
+
|
|
147
|
+
<details>
|
|
148
|
+
<summary><b>Install in Windsurf</b></summary>
|
|
149
|
+
|
|
150
|
+
MCP config:
|
|
151
|
+
|
|
152
|
+
```json
|
|
153
|
+
{
|
|
154
|
+
"mcpServers": {
|
|
155
|
+
"code-review-analyst": {
|
|
156
|
+
"command": "npx",
|
|
157
|
+
"args": ["-y", "@j0hanz/code-review-analyst-mcp@latest"],
|
|
158
|
+
"env": {
|
|
159
|
+
"GEMINI_API_KEY": "YOUR_API_KEY"
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
}
|
|
134
164
|
```
|
|
135
165
|
|
|
166
|
+
For more info, see [Windsurf MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp).
|
|
167
|
+
|
|
168
|
+
</details>
|
|
169
|
+
|
|
170
|
+
<details>
|
|
171
|
+
<summary><b>Install in Amp</b></summary>
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
amp mcp add code-review-analyst -- npx -y @j0hanz/code-review-analyst-mcp@latest
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
For more info, see [Amp MCP docs](https://ampcode.com/manual).
|
|
178
|
+
|
|
179
|
+
</details>
|
|
180
|
+
|
|
181
|
+
<details>
|
|
182
|
+
<summary><b>Install in Cline</b></summary>
|
|
183
|
+
|
|
184
|
+
`cline_mcp_settings.json`
|
|
185
|
+
|
|
186
|
+
```json
|
|
187
|
+
{
|
|
188
|
+
"mcpServers": {
|
|
189
|
+
"code-review-analyst": {
|
|
190
|
+
"command": "npx",
|
|
191
|
+
"args": ["-y", "@j0hanz/code-review-analyst-mcp@latest"],
|
|
192
|
+
"env": {
|
|
193
|
+
"GEMINI_API_KEY": "YOUR_API_KEY"
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
For more info, see [Cline MCP docs](https://docs.cline.bot/mcp/adding-and-configuring-servers).
|
|
201
|
+
|
|
202
|
+
</details>
|
|
203
|
+
|
|
204
|
+
<details>
|
|
205
|
+
<summary><b>Install in Zed</b></summary>
|
|
206
|
+
|
|
207
|
+
`settings.json`
|
|
208
|
+
|
|
209
|
+
```json
|
|
210
|
+
{
|
|
211
|
+
"context_servers": {
|
|
212
|
+
"code-review-analyst": {
|
|
213
|
+
"command": "npx",
|
|
214
|
+
"args": ["-y", "@j0hanz/code-review-analyst-mcp@latest"]
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
}
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
For more info, see [Zed MCP docs](https://zed.dev/docs/ai/mcp).
|
|
221
|
+
|
|
222
|
+
</details>
|
|
223
|
+
|
|
224
|
+
<details>
|
|
225
|
+
<summary><b>Install with Docker</b></summary>
|
|
226
|
+
|
|
227
|
+
```json
|
|
228
|
+
{
|
|
229
|
+
"mcpServers": {
|
|
230
|
+
"code-review-analyst": {
|
|
231
|
+
"command": "docker",
|
|
232
|
+
"args": [
|
|
233
|
+
"run",
|
|
234
|
+
"-i",
|
|
235
|
+
"--rm",
|
|
236
|
+
"-e",
|
|
237
|
+
"GEMINI_API_KEY",
|
|
238
|
+
"ghcr.io/j0hanz/code-review-analyst-mcp:latest"
|
|
239
|
+
]
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
> [!NOTE]
|
|
246
|
+
> Set `GEMINI_API_KEY` in your shell environment before running. Docker passes it through via `-e GEMINI_API_KEY`.
|
|
247
|
+
|
|
136
248
|
</details>
|
|
137
249
|
|
|
138
250
|
## MCP Surface
|
|
@@ -229,26 +341,40 @@ Returns (inside `result`):
|
|
|
229
341
|
|
|
230
342
|
### Runtime Mode
|
|
231
343
|
|
|
232
|
-
| Mode | Supported | Notes
|
|
233
|
-
| ------------------------ | --------- |
|
|
234
|
-
| `stdio` | Yes | Active transport in `src/index.ts`.
|
|
235
|
-
| HTTP/SSE/Streamable HTTP | No | Not implemented
|
|
344
|
+
| Mode | Supported | Notes |
|
|
345
|
+
| ------------------------ | --------- | ----------------------------------- |
|
|
346
|
+
| `stdio` | Yes | Active transport in `src/index.ts`. |
|
|
347
|
+
| HTTP/SSE/Streamable HTTP | No | Not implemented. |
|
|
348
|
+
|
|
349
|
+
### CLI Arguments
|
|
350
|
+
|
|
351
|
+
The server binary accepts optional command-line flags:
|
|
352
|
+
|
|
353
|
+
| Option | Short | Description | Env Override |
|
|
354
|
+
| ------------------ | ----- | ---------------------------------------- | ---------------- |
|
|
355
|
+
| `--model` | `-m` | Override the Gemini model id at startup. | `GEMINI_MODEL` |
|
|
356
|
+
| `--max-diff-chars` | — | Override the runtime diff-size budget. | `MAX_DIFF_CHARS` |
|
|
357
|
+
|
|
358
|
+
Example:
|
|
359
|
+
|
|
360
|
+
```bash
|
|
361
|
+
npx @j0hanz/code-review-analyst-mcp@latest --model gemini-2.5-pro --max-diff-chars 200000
|
|
362
|
+
```
|
|
236
363
|
|
|
237
364
|
### Environment Variables
|
|
238
365
|
|
|
239
366
|
| Variable | Description | Default | Required |
|
|
240
367
|
| ----------------------------- | --------------------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------- |
|
|
241
|
-
| `GEMINI_API_KEY` | Gemini API key (preferred)
|
|
242
|
-
| `GOOGLE_API_KEY` | Alternate Gemini API key env
|
|
243
|
-
| `GEMINI_MODEL` | Gemini model id
|
|
368
|
+
| `GEMINI_API_KEY` | Gemini API key (preferred). | — | One of `GEMINI_API_KEY` or `GOOGLE_API_KEY` |
|
|
369
|
+
| `GOOGLE_API_KEY` | Alternate Gemini API key env. | — | One of `GEMINI_API_KEY` or `GOOGLE_API_KEY` |
|
|
370
|
+
| `GEMINI_MODEL` | Gemini model id. | `gemini-2.5-flash` | No |
|
|
244
371
|
| `GEMINI_HARM_BLOCK_THRESHOLD` | Safety threshold (`BLOCK_NONE`, `BLOCK_ONLY_HIGH`, `BLOCK_MEDIUM_AND_ABOVE`, `BLOCK_LOW_AND_ABOVE`) | `BLOCK_NONE` | No |
|
|
245
|
-
| `MAX_DIFF_CHARS` | Runtime diff-size budget
|
|
246
|
-
| `TASK_TIMEOUT_MS` | Task-runner timeout for build/test scripts | unset | No |
|
|
372
|
+
| `MAX_DIFF_CHARS` | Runtime diff-size budget (chars). | `120000` | No |
|
|
247
373
|
|
|
248
374
|
## Security
|
|
249
375
|
|
|
250
376
|
- Stdio transport avoids HTTP exposure in the current runtime path.
|
|
251
|
-
- Runtime logs and warnings are written to `stderr`;
|
|
377
|
+
- Runtime logs and warnings are written to `stderr`; no non-protocol output is written to `stdout`.
|
|
252
378
|
- Input and output contracts use strict Zod schemas (`z.strictObject`) with explicit bounds.
|
|
253
379
|
- Oversized diffs are rejected early with `E_INPUT_TOO_LARGE`.
|
|
254
380
|
- Tool metadata marks calls as `readOnlyHint: true` and `openWorldHint: true` (external model call, no local state mutation).
|
|
@@ -265,33 +391,63 @@ npm start
|
|
|
265
391
|
|
|
266
392
|
Useful scripts:
|
|
267
393
|
|
|
268
|
-
| Script | Command
|
|
269
|
-
| ------------ |
|
|
270
|
-
| `build` | `node scripts/tasks.mjs build`
|
|
271
|
-
| `dev` | `tsc --watch --preserveWatchOutput`
|
|
272
|
-
| `dev:run` | `node --env-file=.env --watch dist
|
|
273
|
-
| `test` | `node scripts/tasks.mjs test`
|
|
274
|
-
| `test:fast` | `node --test --import tsx/esm ...`
|
|
275
|
-
| `type-check` | `node scripts/tasks.mjs type-check`
|
|
276
|
-
| `lint` | `eslint .`
|
|
277
|
-
| `
|
|
278
|
-
| `
|
|
394
|
+
| Script | Command | Purpose |
|
|
395
|
+
| ------------ | ------------------------------------ | ----------------------------------------------------------------------- |
|
|
396
|
+
| `build` | `node scripts/tasks.mjs build` | Clean, compile, validate instructions, copy assets, set executable bit. |
|
|
397
|
+
| `dev` | `tsc --watch --preserveWatchOutput` | TypeScript watch mode. |
|
|
398
|
+
| `dev:run` | `node --env-file=.env --watch dist/` | Run built server with watch and `.env`. |
|
|
399
|
+
| `test` | `node scripts/tasks.mjs test` | Full build + Node test runner. |
|
|
400
|
+
| `test:fast` | `node --test --import tsx/esm ...` | Fast test path on TS sources (no build step). |
|
|
401
|
+
| `type-check` | `node scripts/tasks.mjs type-check` | TypeScript no-emit checks. |
|
|
402
|
+
| `lint` | `eslint .` | ESLint checks. |
|
|
403
|
+
| `lint:fix` | `eslint . --fix` | ESLint auto-fix. |
|
|
404
|
+
| `format` | `prettier --write .` | Prettier formatting. |
|
|
405
|
+
| `inspector` | `npm run build && npx ... inspector` | MCP Inspector for the stdio server. |
|
|
406
|
+
|
|
407
|
+
> [!TIP]
|
|
408
|
+
> Set `TASK_TIMEOUT_MS` (env var) to enforce a timeout on build/test script tasks in `scripts/tasks.mjs`.
|
|
279
409
|
|
|
280
|
-
Inspector
|
|
410
|
+
Debugging with MCP Inspector:
|
|
281
411
|
|
|
282
412
|
```bash
|
|
283
|
-
# stdio
|
|
284
413
|
npx @modelcontextprotocol/inspector node dist/index.js
|
|
285
414
|
```
|
|
286
415
|
|
|
416
|
+
### Docker
|
|
417
|
+
|
|
418
|
+
Build and run locally with Docker:
|
|
419
|
+
|
|
420
|
+
```bash
|
|
421
|
+
docker build -t code-review-analyst-mcp .
|
|
422
|
+
docker run -i --rm -e GEMINI_API_KEY code-review-analyst-mcp
|
|
423
|
+
```
|
|
424
|
+
|
|
425
|
+
Or use Docker Compose:
|
|
426
|
+
|
|
427
|
+
```bash
|
|
428
|
+
docker compose up --build
|
|
429
|
+
```
|
|
430
|
+
|
|
431
|
+
## Build & Release
|
|
432
|
+
|
|
433
|
+
Releases are managed via the `Release` GitHub Actions workflow (manual dispatch):
|
|
434
|
+
|
|
435
|
+
1. **Version bump** — increments `package.json` and `server.json`, commits and tags.
|
|
436
|
+
2. **npm publish** — publishes `@j0hanz/code-review-analyst-mcp` with OIDC provenance.
|
|
437
|
+
3. **MCP Registry** — publishes `io.github.j0hanz/code-review-analyst` to the [MCP Registry](https://registry.modelcontextprotocol.io).
|
|
438
|
+
4. **Docker image** — builds and pushes multi-arch (`linux/amd64`, `linux/arm64`) to `ghcr.io/j0hanz/code-review-analyst-mcp`.
|
|
439
|
+
|
|
287
440
|
## Troubleshooting
|
|
288
441
|
|
|
289
|
-
- **`E_INPUT_TOO_LARGE`**:
|
|
290
|
-
- **`E_REVIEW_DIFF` / `E_RISK_SCORE` / `E_SUGGEST_PATCH`**:
|
|
291
|
-
- **`Gemini request timed out after ...ms.`**:
|
|
292
|
-
- **`Gemini returned an empty response body.`**:
|
|
293
|
-
- **Malformed model JSON response**:
|
|
442
|
+
- **`E_INPUT_TOO_LARGE`**: Split diff into smaller chunks or increase `MAX_DIFF_CHARS`.
|
|
443
|
+
- **`E_REVIEW_DIFF` / `E_RISK_SCORE` / `E_SUGGEST_PATCH`**: Verify API key env vars and retry with narrower input.
|
|
444
|
+
- **`Gemini request timed out after ...ms.`**: Reduce diff/prompt size or increase timeout in caller.
|
|
445
|
+
- **`Gemini returned an empty response body.`**: Retry and check upstream model health.
|
|
446
|
+
- **Malformed model JSON response**: Retry with same schema and inspect `stderr` logs.
|
|
447
|
+
- **Inspector not connecting**: Ensure the server is built (`npm run build`) before running the inspector.
|
|
448
|
+
- **Claude Desktop logs**: Check `~/Library/Logs/Claude/mcp*.log` (macOS) for server communication issues.
|
|
294
449
|
|
|
295
450
|
## Contributing & License
|
|
296
451
|
|
|
297
|
-
-
|
|
452
|
+
- Contributions are welcome. Please open an issue or pull request on [GitHub](https://github.com/j0hanz/code-review-analyst-mcp).
|
|
453
|
+
- License: **MIT** (see `package.json`).
|
package/dist/index.js
CHANGED
|
File without changes
|