@ship-safe/mcp 0.2.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 +90 -0
- package/dist/index.js +4508 -0
- package/package.json +56 -0
package/README.md
ADDED
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# @ship-safe/mcp
|
|
2
|
+
|
|
3
|
+
A [Model Context Protocol](https://modelcontextprotocol.io) server that lets your AI coding agent (Cursor, Claude Code, Claude Desktop, Windsurf, …) scan the code it writes for security vulnerabilities — **in-loop, without leaving the editor**.
|
|
4
|
+
|
|
5
|
+
It runs ShipSafe's fast local pattern scan for free (secrets, injection, broken auth/IDOR, misconfig) plus a **dependency CVE scan** of your lockfiles (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `requirements.txt`, `go.sum`, `Gemfile.lock`) via the OSV database. With a Growth or Shield login it also runs **AI deep analysis** and can generate a one‑paste fix prompt. Your code is never stored.
|
|
6
|
+
|
|
7
|
+
## Tools
|
|
8
|
+
|
|
9
|
+
| Tool | What it does | Auth |
|
|
10
|
+
|------|--------------|------|
|
|
11
|
+
| `shipsafe_scan` | Scan a directory; returns plain‑English findings with the exact fix for each, plus structured output (see below). | Free (local). AI analysis needs Growth/Shield. |
|
|
12
|
+
| `shipsafe_fix_prompt` | Scan, then return one paste‑ready prompt that fixes everything, tailored to the detected AI builder. | Growth / Shield |
|
|
13
|
+
| `shipsafe_status` | Show login state, plan, and remaining AI scan quota. | — |
|
|
14
|
+
|
|
15
|
+
### `shipsafe_scan` inputs
|
|
16
|
+
|
|
17
|
+
| Input | Type | Purpose |
|
|
18
|
+
|-------|------|---------|
|
|
19
|
+
| `path` | string | Directory to scan (defaults to cwd). |
|
|
20
|
+
| `severity` | `critical`\|`high`\|`medium`\|`low` | Only return findings at or above this severity. |
|
|
21
|
+
| `ai` | boolean | Run AI deep analysis (needs Growth/Shield). On by default for paid users. |
|
|
22
|
+
| `paths` | string[] | Scan only these files/dirs (inside the project) — e.g. the files you just edited. Fast inner loop. |
|
|
23
|
+
| `changedOnly` | boolean | Scan only files changed vs git HEAD + new untracked files. Falls back to a full scan if not a git repo. |
|
|
24
|
+
|
|
25
|
+
### Structured output
|
|
26
|
+
|
|
27
|
+
Alongside the human‑readable report, `shipsafe_scan` returns machine‑readable `structuredContent` an agent can branch on:
|
|
28
|
+
|
|
29
|
+
- `clean` (boolean) and `counts` (by severity) — a greppable pass/fail, so you never have to parse prose.
|
|
30
|
+
- `findings[]` — each with `key`, `severity`, `file`, `line`, `cwe`, `plainEnglish`, `fixDescription`, `fixSuggestion`.
|
|
31
|
+
- `scanned` — `{ mode: "full" | "targeted", sourceFiles, dependencyFiles }`.
|
|
32
|
+
- `diff` (full‑project scans only) — `{ resolved, stillOpen, introduced }` vs your previous scan of the same directory, so a `scan → fix → re-scan` loop can confirm a fix actually worked. The diff state is kept locally under `~/.shipsafe/mcp-history` and never leaves your machine.
|
|
33
|
+
|
|
34
|
+
Failures (no source files, generation errors, not logged in) are returned with `isError: true`, so "couldn't run" is never mistaken for "ran clean".
|
|
35
|
+
|
|
36
|
+
## Login (for AI analysis)
|
|
37
|
+
|
|
38
|
+
The server reuses the ShipSafe CLI's session. Once, in a terminal:
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
npx @ship-safe/cli login
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
That writes `~/.shipsafe/token.json`, which this MCP server reads. The free local scan works without it.
|
|
45
|
+
|
|
46
|
+
## Setup
|
|
47
|
+
|
|
48
|
+
### Cursor — `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global)
|
|
49
|
+
|
|
50
|
+
```json
|
|
51
|
+
{
|
|
52
|
+
"mcpServers": {
|
|
53
|
+
"shipsafe": { "command": "npx", "args": ["-y", "@ship-safe/mcp"] }
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### Claude Code
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
claude mcp add shipsafe -- npx -y @ship-safe/mcp
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### Claude Desktop — `claude_desktop_config.json`
|
|
65
|
+
|
|
66
|
+
```json
|
|
67
|
+
{
|
|
68
|
+
"mcpServers": {
|
|
69
|
+
"shipsafe": { "command": "npx", "args": ["-y", "@ship-safe/mcp"] }
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Then ask the agent: *"scan this project with ShipSafe and fix what it finds."*
|
|
75
|
+
|
|
76
|
+
## Configuration
|
|
77
|
+
|
|
78
|
+
| Env var | Default | Purpose |
|
|
79
|
+
|---------|---------|---------|
|
|
80
|
+
| `SHIPSAFE_API_URL` | `https://ship-safe.co` | Point at a local/staging backend (e.g. `http://localhost:3000`). |
|
|
81
|
+
|
|
82
|
+
## Local development
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
pnpm install
|
|
86
|
+
pnpm --filter @shipsafe/shared --filter @shipsafe/scanner build
|
|
87
|
+
pnpm --filter @ship-safe/mcp build
|
|
88
|
+
# run the built server directly (stdio):
|
|
89
|
+
node apps/mcp/dist/index.js
|
|
90
|
+
```
|