@socketsecurity/mcp 0.0.18 → 0.0.20
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 +24 -0
- package/README.md +125 -9
- package/dist/index.cjs +963 -867
- package/hooks/socket-gate/index.mts +16 -9
- package/hooks/socket-gate/socket-gate.cjs +94 -94
- package/package.json +18 -13
- package/dist/index.d.ts +0 -4
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [0.0.20]
|
|
11
|
+
|
|
12
|
+
### Fixed
|
|
13
|
+
|
|
14
|
+
- OAuth-enabled HTTP deployments now accept `sktsec_` Socket API tokens sent
|
|
15
|
+
via `Authorization: Bearer <token>`.
|
|
16
|
+
|
|
17
|
+
## [0.0.19]
|
|
18
|
+
|
|
19
|
+
### Changed
|
|
20
|
+
|
|
21
|
+
- Organization tools now scope their results to the authenticated caller.
|
|
22
|
+
|
|
23
|
+
### Fixed
|
|
24
|
+
|
|
25
|
+
- Composer package URLs parse correctly: `packagist` is accepted as a composer
|
|
26
|
+
alias, bare-name packages resolve, and the vendor namespace is split from the
|
|
27
|
+
package name.
|
|
28
|
+
- The `depscore` tool no longer errors on packages with missing or non-numeric
|
|
29
|
+
score data.
|
|
30
|
+
- The HTTP server limits the size of POST request bodies.
|
|
31
|
+
- OAuth tokens whose introspection response carries a malformed expiry are now
|
|
32
|
+
rejected.
|
|
33
|
+
|
|
10
34
|
## [0.0.18]
|
|
11
35
|
|
|
12
36
|
### Fixed
|
package/README.md
CHANGED
|
@@ -1,8 +1,11 @@
|
|
|
1
1
|
# Socket MCP Server
|
|
2
2
|
|
|
3
|
-
[](https://badge.fury.io/js/@socketsecurity%2Fmcp)
|
|
4
|
-
[](https://opensource.org/licenses/MIT)
|
|
5
3
|
[](https://socket.dev/npm/package/@socketsecurity/mcp)
|
|
4
|
+
[](https://github.com/SocketDev/socket-mcp/actions/workflows/ci.yml)
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
[](https://twitter.com/SocketSecurity)
|
|
8
|
+
[](https://bsky.app/profile/socket.dev)
|
|
6
9
|
|
|
7
10
|
A Model Context Protocol (MCP) server for Socket integration — lets AI assistants query dependency vulnerability scores and security metadata.
|
|
8
11
|
|
|
@@ -13,11 +16,11 @@ Socket MCP exposes Socket.dev's package-scoring API through the Model Context Pr
|
|
|
13
16
|
## ✨ Features
|
|
14
17
|
|
|
15
18
|
- 🔍 **Dependency Security Scanning** - Get comprehensive security scores for npm, PyPI, cargo, Maven, NuGet, RubyGems, Go Modules, and more ([supported ecosystems](https://docs.socket.dev/docs/language-support))
|
|
16
|
-
- 🌐 **Public Hosted Service** - Use our public server at `https://mcp.socket.dev
|
|
19
|
+
- 🌐 **Public Hosted Service** - Use our public server at `https://mcp.socket.dev/`; sign in once via OAuth, no self-hosting
|
|
17
20
|
- 🚀 **Multiple Deployment Options** - Run locally via stdio, HTTP, or use our service
|
|
18
21
|
- 🤖 **AI Assistant Integration** - Works seamlessly with Claude, VS Code Copilot, Cursor, and other MCP clients
|
|
19
22
|
- 📊 **Batch Processing** - Check multiple dependencies in a single request
|
|
20
|
-
- 🔒 **
|
|
23
|
+
- 🔒 **OAuth Sign-In** - Public server authenticates through your MCP client's OAuth flow; no API key to copy or manage
|
|
21
24
|
|
|
22
25
|
🛠️ This project is in early development and rapidly evolving.
|
|
23
26
|
|
|
@@ -25,7 +28,7 @@ Socket MCP exposes Socket.dev's package-scoring API through the Model Context Pr
|
|
|
25
28
|
|
|
26
29
|
### Option 1: Use the public Socket MCP server (recommended)
|
|
27
30
|
|
|
28
|
-
The easiest way to get started.
|
|
31
|
+
The easiest way to get started. The public server uses OAuth — your MCP client opens a browser to sign in to Socket on first connect; no API key to copy or manage. Click a button below to install in your favorite AI assistant.
|
|
29
32
|
|
|
30
33
|
[](https://vscode.dev/redirect/mcp/install?name=socket-mcp&config={"url":"https://mcp.socket.dev/","type":"http"})
|
|
31
34
|
[](https://cursor.com/en/install-mcp?name=socket-mcp&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vbWNwLnNvY2tldC5kZXYvIn0%3D)
|
|
@@ -176,7 +179,7 @@ Environment variables for HTTP mode:
|
|
|
176
179
|
| `SOCKET_OAUTH_ISSUER` | Set together with the two introspection vars to enable OAuth | None | OAuth issuer URL used for metadata discovery and incoming bearer-token validation. |
|
|
177
180
|
| `SOCKET_OAUTH_INTROSPECTION_CLIENT_ID` | With OAuth | None | Client ID used for token introspection. |
|
|
178
181
|
| `SOCKET_OAUTH_INTROSPECTION_CLIENT_SECRET` | With OAuth | None | Client secret used for token introspection. |
|
|
179
|
-
| `SOCKET_OAUTH_REQUIRED_SCOPES` | No |
|
|
182
|
+
| `SOCKET_OAUTH_REQUIRED_SCOPES` | No | _(none)_ | Space-delimited scopes required on incoming access tokens. When unset, no scope is enforced — any active token passes. |
|
|
180
183
|
| `SOCKET_API_URL` | No | Production Socket API URL, or localhost when `SOCKET_DEBUG=true` | Override the upstream Socket API endpoint. Useful for local development and testing. |
|
|
181
184
|
| `SOCKET_DEBUG` | No | `false` | Switches the default upstream Socket API endpoint to localhost when `SOCKET_API_URL` is unset. |
|
|
182
185
|
| `TRUST_PROXY` | No | `false` | When `true`, trust `X-Forwarded-Host` and `X-Forwarded-Proto` when building OAuth metadata URLs. Enable only behind a trusted reverse proxy that rewrites these headers. |
|
|
@@ -268,6 +271,119 @@ pkg:pypi/fastapi@0.100.0: supply_chain: 1.0, quality: 0.95, maintenance: 0.98, v
|
|
|
268
271
|
Report: https://socket.dev/pypi/package/fastapi
|
|
269
272
|
```
|
|
270
273
|
|
|
274
|
+
#### organizations
|
|
275
|
+
|
|
276
|
+
List the Socket organizations the authenticated user belongs to. Takes no parameters. Use it to discover the `org_slug` value that the org-scoped tools (`alerts`, `threat_feed`) require.
|
|
277
|
+
|
|
278
|
+
This tool needs a Socket API token. See [Authentication for organization-scoped tools](#authentication-for-organization-scoped-tools) below.
|
|
279
|
+
|
|
280
|
+
#### alerts
|
|
281
|
+
|
|
282
|
+
List the latest security alerts for one Socket organization: supply-chain, vulnerability, quality, license, and maintenance issues across the org's monitored packages. Backed by `GET /v0/orgs/{org_slug}/alerts`. Results are paginated; pass the previous response's `endCursor` as `cursor` to fetch the next page.
|
|
283
|
+
|
|
284
|
+
| Parameter | Type | Required | Default | Description |
|
|
285
|
+
| --------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------- |
|
|
286
|
+
| `org_slug` | String | ✅ Yes | - | Organization slug (get it from the `organizations` tool) |
|
|
287
|
+
| `severity` | String | No | - | Comma-separated subset of `low,medium,high,critical` |
|
|
288
|
+
| `status` | String | No | - | `open` or `cleared` |
|
|
289
|
+
| `category` | String | No | - | Comma-separated subset of `supplyChainRisk,maintenance,quality,license,vulnerability` |
|
|
290
|
+
| `artifact_type` | String | No | - | Comma-separated ecosystems: `npm,pypi,gem,maven,golang,nuget,cargo,chrome,openvsx` |
|
|
291
|
+
| `artifact_name` | String | No | - | Restrict to a single package name |
|
|
292
|
+
| `alert_type` | String | No | - | Comma-separated Socket alert types (e.g. `usesEval,unmaintained`) |
|
|
293
|
+
| `repo_slug` | String | No | - | Comma-separated repository slugs |
|
|
294
|
+
| `per_page` | Integer | No | `100` | Results per page (1–5000) |
|
|
295
|
+
| `cursor` | String | No | - | Pagination cursor — the `endCursor` from a previous response |
|
|
296
|
+
|
|
297
|
+
#### threat_feed
|
|
298
|
+
|
|
299
|
+
Look up items in a Socket organization's threat feed: packages recently flagged as malware, typosquats, obfuscated code, and similar. Backed by `GET /v0/orgs/{org_slug}/threat-feed`. The response carries a `nextPageCursor`; pass it as `cursor` to page forward.
|
|
300
|
+
|
|
301
|
+
| Parameter | Type | Required | Default | Description |
|
|
302
|
+
| ------------------- | ------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------- |
|
|
303
|
+
| `org_slug` | String | ✅ Yes | - | Organization slug (get it from the `organizations` tool) |
|
|
304
|
+
| `filter` | String | No | `mal` | Threat category: `mal` (malware), `vuln`, `typ` (typosquat), `obf` (obfuscated), `mjo`, `kes`, `spy`, etc. |
|
|
305
|
+
| `ecosystem` | String | No | - | Ecosystem: `npm`, `pypi`, `gem`, `maven`, `golang`, `nuget`, `cargo`, `chrome`, `openvsx`, `huggingface` |
|
|
306
|
+
| `name` | String | No | - | Filter by package name |
|
|
307
|
+
| `version` | String | No | - | Filter by package version |
|
|
308
|
+
| `is_human_reviewed` | Boolean | No | `false` | Only return human-reviewed items |
|
|
309
|
+
| `sort` | String | No | `updated_at` | Sort field: `id`, `created_at`, `updated_at` |
|
|
310
|
+
| `direction` | String | No | `desc` | Sort direction: `asc`, `desc` |
|
|
311
|
+
| `updated_after` | String | No | - | ISO timestamp; only items updated after this |
|
|
312
|
+
| `created_after` | String | No | - | ISO timestamp; only items created after this |
|
|
313
|
+
| `per_page` | Integer | No | `30` | Results per page (1–100) |
|
|
314
|
+
| `cursor` | String | No | - | Pagination cursor — the `nextPageCursor` from a previous response |
|
|
315
|
+
|
|
316
|
+
#### package_files
|
|
317
|
+
|
|
318
|
+
List the files published in a package: a tree of paths and sizes for any package on a supported ecosystem. Use it to inspect what a dependency ships before installing it. Each entry prints a blob `hash` that `package_file_contents` and `package_file_grep` consume.
|
|
319
|
+
|
|
320
|
+
| Parameter | Type | Required | Default | Description |
|
|
321
|
+
| ------------ | ------ | -------- | ------- | --------------------------------------------------------------------------------------- |
|
|
322
|
+
| `ecosystem` | String | No | `npm` | `npm`, `pypi`, `gem`, `cargo`, `maven`, `golang`, `nuget`, `chrome`, `openvsx` |
|
|
323
|
+
| `depname` | String | ✅ Yes | - | Package name (e.g. `lodash`, `@babel/core`, `org.springframework:spring-core`) |
|
|
324
|
+
| `version` | String | ✅ Yes | - | Package version |
|
|
325
|
+
| `artifactId` | String | No | - | Per-version disambiguator (PyPI filename, Maven artifact id, NuGet asset) |
|
|
326
|
+
| `platform` | String | No | - | Platform qualifier for per-OS/arch artifacts (e.g. openvsx `linux-x64`, `darwin-arm64`) |
|
|
327
|
+
|
|
328
|
+
#### package_file_contents
|
|
329
|
+
|
|
330
|
+
Read a single file from a package. Pass the `hash` printed next to an entry in `package_files` output. Returns up to 1 MB of UTF-8 text; binary files return metadata only.
|
|
331
|
+
|
|
332
|
+
| Parameter | Type | Required | Default | Description |
|
|
333
|
+
| --------- | ------ | -------- | ------- | ------------------------------------------------------- |
|
|
334
|
+
| `hash` | String | ✅ Yes | - | Blob hash from `package_files` |
|
|
335
|
+
| `path` | String | No | - | File path, for display only; does not affect the lookup |
|
|
336
|
+
|
|
337
|
+
#### package_file_grep
|
|
338
|
+
|
|
339
|
+
Search a single file from a package for lines matching a JavaScript regular expression, returning matches with line numbers (grep -n style). The file is fetched once per session and cached, so repeated greps on the same hash skip the network.
|
|
340
|
+
|
|
341
|
+
| Parameter | Type | Required | Default | Description |
|
|
342
|
+
| ----------------- | ------- | -------- | ------- | ------------------------------------------------------- |
|
|
343
|
+
| `hash` | String | ✅ Yes | - | Blob hash from `package_files` |
|
|
344
|
+
| `pattern` | String | ✅ Yes | - | JavaScript regular expression (plain literals work too) |
|
|
345
|
+
| `caseInsensitive` | Boolean | No | `false` | Match case-insensitively |
|
|
346
|
+
| `contextLines` | Integer | No | `0` | Lines of context before and after each match (0–5) |
|
|
347
|
+
| `maxMatches` | Integer | No | `100` | Cap on matching lines returned (1–500) |
|
|
348
|
+
| `path` | String | No | - | File path, for display only; does not affect the lookup |
|
|
349
|
+
|
|
350
|
+
### Authentication for organization-scoped tools
|
|
351
|
+
|
|
352
|
+
`depscore` works without credentials on the public server. The `organizations`, `alerts`, `threat_feed`, and `package_files` tools call Socket's authenticated REST API, so they need a Socket API token.
|
|
353
|
+
|
|
354
|
+
How the server resolves a token depends on the transport:
|
|
355
|
+
|
|
356
|
+
- **stdio mode** reads one token at startup from the environment and uses it for every request. Set `SOCKET_API_TOKEN`. The server also accepts these aliases, in priority order: `SOCKET_API_TOKEN` → `SOCKET_API_KEY` → `SOCKET_CLI_API_TOKEN` → `SOCKET_CLI_API_KEY` → `SOCKET_SECURITY_API_TOKEN` → `SOCKET_SECURITY_API_KEY`. `SOCKET_API_TOKEN` is canonical; `SOCKET_API_KEY` is the alias most local setups already export. Because the process belongs to one user, this token is yours and scopes every tool to your account.
|
|
357
|
+
- **HTTP mode** scopes the organization tools to the caller, never to the server's own token. Send your credential as an `Authorization: Bearer <token>` header on each request: a raw Socket API token (recognized by its `sktsec_` prefix) is used directly and works whether or not the server runs OAuth, while any other token is treated as an OAuth access token and validated through introspection when the server runs OAuth. The server uses that per-request token for the Socket API calls it makes on your behalf. A shared deployment never answers `organizations`, `alerts`, `threat_feed`, or `package_files` with the operator's data: when a request carries no token, those tools return the auth-required error. `depscore` alone may fall back to the server's startup token, since package scores are the same for every caller.
|
|
358
|
+
|
|
359
|
+
Generate a token from the [Socket dashboard](https://socket.dev/) under API tokens, then export it before launching the server:
|
|
360
|
+
|
|
361
|
+
```sh
|
|
362
|
+
export SOCKET_API_TOKEN="your-socket-api-token"
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
When no token is available, these tools return an authentication-required error explaining how to supply one for each transport.
|
|
366
|
+
|
|
367
|
+
### Worked example: organization details and alerts
|
|
368
|
+
|
|
369
|
+
With `SOCKET_API_TOKEN` set, ask your assistant something like "show me the open critical alerts for my Socket org". Under the hood the assistant chains two tools:
|
|
370
|
+
|
|
371
|
+
1. **Discover the org slug.** Call `organizations` (no arguments). The server reads your token, calls `GET /v0/organizations`, and returns the organizations your token can see. Pick the `slug` you want, e.g. `my-org`.
|
|
372
|
+
|
|
373
|
+
2. **Fetch alerts for that org.** Call `alerts` with the slug and any filters:
|
|
374
|
+
|
|
375
|
+
```json
|
|
376
|
+
{
|
|
377
|
+
"org_slug": "my-org",
|
|
378
|
+
"severity": "high,critical",
|
|
379
|
+
"status": "open"
|
|
380
|
+
}
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
The server calls `GET /v0/orgs/my-org/alerts` with the same token and returns the matching alerts plus pagination metadata. To page forward, pass the response's `endCursor` back as `cursor`.
|
|
384
|
+
|
|
385
|
+
The same token scopes every org-scoped tool, so `threat_feed` and `package_files` work the moment `organizations` confirms which slug the token belongs to.
|
|
386
|
+
|
|
271
387
|
### Adjusting tool usage via client rules
|
|
272
388
|
|
|
273
389
|
You can customize how the MCP server interacts with your AI assistant by editing your client's rules file:
|
|
@@ -286,7 +402,7 @@ Always check dependency scores with the depscore tool when you add a new depende
|
|
|
286
402
|
|
|
287
403
|
## Claude Code Hook (Optional)
|
|
288
404
|
|
|
289
|
-
The repo ships an optional [Claude Code hook](https://code.claude.com/docs/en/hooks) that blocks high-risk packages before installation. When Claude Code runs an install command, the hook queries the public Socket MCP server at `https://mcp.socket.dev/` and denies the install when the package's supply chain score is below `20` (known malware, typosquats, high-risk supply chain signals). No
|
|
405
|
+
The repo ships an optional [Claude Code hook](https://code.claude.com/docs/en/hooks) that blocks high-risk packages before installation. When Claude Code runs an install command, the hook queries the public Socket MCP server at `https://mcp.socket.dev/` and denies the install when the package's supply chain score is below `20` (known malware, typosquats, high-risk supply chain signals). No CLI to install — copy the file and wire it up; the public server signs in via OAuth on first use.
|
|
290
406
|
|
|
291
407
|
Supported ecosystems and package managers:
|
|
292
408
|
|
|
@@ -383,7 +499,7 @@ When running in HTTP mode, `GET /health` returns:
|
|
|
383
499
|
{
|
|
384
500
|
"status": "healthy",
|
|
385
501
|
"service": "socket-mcp",
|
|
386
|
-
"version": "0.0.
|
|
502
|
+
"version": "0.0.18",
|
|
387
503
|
"timestamp": "2025-06-17T20:45:22.059Z"
|
|
388
504
|
}
|
|
389
505
|
```
|
|
@@ -394,7 +510,7 @@ Suitable for Kubernetes liveness/readiness probes, Docker health checks, load ba
|
|
|
394
510
|
|
|
395
511
|
**Q: The public server isn't responding** — Check the URL `https://mcp.socket.dev/`, verify your MCP client configuration, restart your MCP client.
|
|
396
512
|
|
|
397
|
-
**Q: Local server fails to start** — Ensure Node.js
|
|
513
|
+
**Q: Local server fails to start** — Ensure Node.js 22+ is installed, check `SOCKET_API_TOKEN` is set, verify the API token has `packages:list` permission.
|
|
398
514
|
|
|
399
515
|
**Q: Getting authentication errors with local server** — Double-check your API key is valid, ensure `packages:list` scope, regenerate if needed.
|
|
400
516
|
|