@socketsecurity/mcp 0.0.17 → 0.0.19
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 +36 -0
- package/README.md +331 -181
- package/dist/index.cjs +58212 -0
- package/hooks/socket-gate/README.md +117 -0
- package/hooks/socket-gate/index.mts +296 -0
- package/hooks/socket-gate/socket-gate.cjs +1047 -0
- package/package.json +95 -65
- package/index.d.ts +0 -3
- package/index.d.ts.map +0 -1
- package/index.js +0 -460
- package/mock-client/debug-client.d.ts +0 -3
- package/mock-client/debug-client.d.ts.map +0 -1
- package/mock-client/debug-client.js +0 -134
- package/mock-client/http-client.d.ts +0 -3
- package/mock-client/http-client.d.ts.map +0 -1
- package/mock-client/http-client.js +0 -123
- package/mock-client/stdio-client.d.ts +0 -3
- package/mock-client/stdio-client.d.ts.map +0 -1
- package/mock-client/stdio-client.js +0 -52
package/README.md
CHANGED
|
@@ -4,41 +4,38 @@
|
|
|
4
4
|
[](https://opensource.org/licenses/MIT)
|
|
5
5
|
[](https://socket.dev/npm/package/@socketsecurity/mcp)
|
|
6
6
|
|
|
7
|
-
A Model Context Protocol (MCP) server for Socket integration
|
|
7
|
+
A Model Context Protocol (MCP) server for Socket integration — lets AI assistants query dependency vulnerability scores and security metadata.
|
|
8
|
+
|
|
9
|
+
## Why this repo exists
|
|
10
|
+
|
|
11
|
+
Socket MCP exposes Socket.dev's package-scoring API through the Model Context Protocol, so any MCP-aware AI assistant (Claude, VS Code Copilot, Cursor, Windsurf) can score a package, audit a `package.json`, or flag risky dependencies as part of a conversation. It ships as both a hosted public server (`https://mcp.socket.dev/`, no setup) and a self-hostable npm package, so you can choose between zero-friction and full data isolation.
|
|
8
12
|
|
|
9
13
|
## ✨ Features
|
|
10
14
|
|
|
11
|
-
- 🔍 **Dependency Security Scanning** - Get comprehensive security scores for npm, PyPI, and
|
|
12
|
-
- 🌐 **Public Hosted Service** - Use our public server at `https://mcp.socket.dev
|
|
15
|
+
- 🔍 **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/`; sign in once via OAuth, no self-hosting
|
|
13
17
|
- 🚀 **Multiple Deployment Options** - Run locally via stdio, HTTP, or use our service
|
|
14
18
|
- 🤖 **AI Assistant Integration** - Works seamlessly with Claude, VS Code Copilot, Cursor, and other MCP clients
|
|
15
19
|
- 📊 **Batch Processing** - Check multiple dependencies in a single request
|
|
16
|
-
- 🔒 **
|
|
20
|
+
- 🔒 **OAuth Sign-In** - Public server authenticates through your MCP client's OAuth flow; no API key to copy or manage
|
|
17
21
|
|
|
18
22
|
🛠️ This project is in early development and rapidly evolving.
|
|
19
23
|
|
|
20
|
-
##
|
|
24
|
+
## Install
|
|
21
25
|
|
|
22
|
-
### Option 1: Use the
|
|
23
|
-
|
|
24
|
-
The easiest way to get started is to use our public Socket MCP server. **No API key or authentication required!** Click a button below to install the public server in your favorite AI assistant.
|
|
26
|
+
### Option 1: Use the public Socket MCP server (recommended)
|
|
25
27
|
|
|
28
|
+
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.
|
|
26
29
|
|
|
27
30
|
[](https://vscode.dev/redirect/mcp/install?name=socket-mcp&config={"url":"https://mcp.socket.dev/","type":"http"})
|
|
28
31
|
[](https://cursor.com/en/install-mcp?name=socket-mcp&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vbWNwLnNvY2tldC5kZXYvIn0%3D)
|
|
29
32
|
|
|
30
|
-
|
|
31
|
-
<details><summary><b>Manual Installation Instructions & more MCP Clients</b></summary>
|
|
32
|
-
|
|
33
|
-
<details><summary><b>Install in Claude Desktop or Claude Code</b></summary>
|
|
33
|
+
<details><summary><b>Manual install — Claude Desktop / Claude Code</b></summary>
|
|
34
34
|
|
|
35
35
|
> [!NOTE]
|
|
36
36
|
> Custom integrations are not available to all paid versions of Claude. Check [here](https://support.anthropic.com/en/articles/11175166-about-custom-integrations-using-remote-mcp) for more information.
|
|
37
37
|
|
|
38
|
-
To use the public Socket MCP server with Claude Desktop:
|
|
39
|
-
|
|
40
38
|
1. In Claude Desktop, go to Settings > Developer > Edit Config.
|
|
41
|
-
|
|
42
39
|
2. Add the Socket MCP server configuration:
|
|
43
40
|
|
|
44
41
|
```json
|
|
@@ -53,29 +50,24 @@ To use the public Socket MCP server with Claude Desktop:
|
|
|
53
50
|
```
|
|
54
51
|
|
|
55
52
|
3. Save the configuration and restart Claude Desktop.
|
|
53
|
+
4. Now you can ask Claude "Check the security score for express version 4.18.2".
|
|
56
54
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
The process is similar for Claude Code. See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/mcp) for more details. Here's an example command to add the Socket MCP server:
|
|
55
|
+
For Claude Code:
|
|
60
56
|
|
|
61
|
-
```
|
|
57
|
+
```sh
|
|
62
58
|
claude mcp add --transport http socket-mcp https://mcp.socket.dev/
|
|
63
59
|
```
|
|
64
60
|
|
|
65
61
|
</details>
|
|
66
62
|
|
|
67
|
-
<details><summary><b>
|
|
68
|
-
|
|
69
|
-
You can install the Socket MCP server using the VS Code CLI:
|
|
63
|
+
<details><summary><b>Manual install — VS Code</b></summary>
|
|
70
64
|
|
|
71
|
-
```
|
|
65
|
+
```sh
|
|
72
66
|
# For VS Code with GitHub Copilot
|
|
73
|
-
code --add-mcp '{"name":"socket-mcp","type":"http","url":"https://mcp.socket.dev/}'
|
|
67
|
+
code --add-mcp '{"name":"socket-mcp","type":"http","url":"https://mcp.socket.dev/"}'
|
|
74
68
|
```
|
|
75
69
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
Alternatively, you can manually add it to your VS Code MCP configuration in `.vscode/mcp.json`:
|
|
70
|
+
Or add to `.vscode/mcp.json`:
|
|
79
71
|
|
|
80
72
|
```json
|
|
81
73
|
{
|
|
@@ -90,9 +82,9 @@ Alternatively, you can manually add it to your VS Code MCP configuration in `.vs
|
|
|
90
82
|
|
|
91
83
|
</details>
|
|
92
84
|
|
|
93
|
-
<details><summary><b>
|
|
85
|
+
<details><summary><b>Manual install — Cursor</b></summary>
|
|
94
86
|
|
|
95
|
-
|
|
87
|
+
`Cursor Settings` → `MCP` → `Add new MCP Server`. Name `socket-mcp`, `http` type, URL `https://mcp.socket.dev/`.
|
|
96
88
|
|
|
97
89
|
```json
|
|
98
90
|
{
|
|
@@ -107,274 +99,432 @@ Go to `Cursor Settings` -> `MCP` -> `Add new MCP Server`. Name it "socket-mcp",
|
|
|
107
99
|
|
|
108
100
|
</details>
|
|
109
101
|
|
|
110
|
-
<details><summary><b>
|
|
102
|
+
<details><summary><b>Manual install — Windsurf</b></summary>
|
|
111
103
|
|
|
112
104
|
> [!WARNING]
|
|
113
|
-
> Windsurf does not support `http` type MCP servers yet. Use the
|
|
114
|
-
|
|
115
|
-
To use the Socket MCP server in Windsurf:
|
|
116
|
-
|
|
117
|
-
1. Open Windsurf Settings
|
|
118
|
-
2. Navigate to MCP Servers section
|
|
119
|
-
3. Add a new server with the following configuration:
|
|
105
|
+
> Windsurf does not support `http` type MCP servers yet. Use the stdio configuration in Option 2 below.
|
|
120
106
|
|
|
121
107
|
```json
|
|
122
108
|
{
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
}
|
|
109
|
+
"mcpServers": {
|
|
110
|
+
"socket-mcp": {
|
|
111
|
+
"serverUrl": "https://mcp.socket.dev/mcp"
|
|
127
112
|
}
|
|
113
|
+
}
|
|
128
114
|
}
|
|
129
115
|
```
|
|
130
116
|
|
|
131
|
-
4. Save the configuration and restart Windsurf if needed.
|
|
132
|
-
|
|
133
117
|
</details>
|
|
134
118
|
|
|
135
|
-
|
|
119
|
+
<details><summary><b>Manual install — Factory</b></summary>
|
|
136
120
|
|
|
137
|
-
|
|
121
|
+
[Factory](https://factory.ai) is an AI-powered software engineering platform. Install the Socket MCP server with the Factory CLI:
|
|
138
122
|
|
|
139
|
-
|
|
123
|
+
```bash
|
|
124
|
+
droid mcp add socket https://mcp.socket.dev/ --type http
|
|
125
|
+
```
|
|
140
126
|
|
|
141
|
-
|
|
127
|
+
To self-host with an API key instead, see Option 2 below and register the stdio command with `droid mcp add`.
|
|
142
128
|
|
|
143
|
-
|
|
129
|
+
Alternatively, type `/mcp` within the Factory droid to manage MCP servers from an interactive UI. Learn more in the [Factory MCP documentation](https://docs.factory.ai/cli/configuration/mcp).
|
|
144
130
|
|
|
145
|
-
|
|
131
|
+
</details>
|
|
146
132
|
|
|
147
|
-
|
|
133
|
+
### Option 2: Self-host the Socket MCP server
|
|
148
134
|
|
|
149
|
-
|
|
135
|
+
To run your own instance, create an API key first (only the `packages:list` permission scope is needed; see [creating-and-managing-api-tokens](https://docs.socket.dev/reference/creating-and-managing-api-tokens)).
|
|
150
136
|
|
|
151
|
-
|
|
152
|
-
[](https://cursor.com/en/install-mcp?name=socket-mcp&config=eyJjb21tYW5kIjoibnB4IEBzb2NrZXRzZWN1cml0eS9tY3BAbGF0ZXN0IiwiZW52Ijp7IlNPQ0tFVF9BUElfS0VZIjoieW91ci1hcGkta2V5LWhlcmUifX0%3D)
|
|
137
|
+
<details><summary><b>Option 2a — Stdio mode (default)</b></summary>
|
|
153
138
|
|
|
154
|
-
Claude Code
|
|
139
|
+
Claude Code:
|
|
155
140
|
|
|
156
|
-
```
|
|
157
|
-
claude mcp add socket-mcp -e
|
|
141
|
+
```sh
|
|
142
|
+
claude mcp add socket-mcp -e SOCKET_API_TOKEN="your-api-token-here" -- npx -y @socketsecurity/mcp@latest # socket-hook: allow npx
|
|
158
143
|
```
|
|
159
|
-
|
|
144
|
+
|
|
145
|
+
Most other MCP clients:
|
|
160
146
|
|
|
161
147
|
```json
|
|
162
148
|
{
|
|
163
149
|
"mcpServers": {
|
|
164
150
|
"socket-mcp": {
|
|
165
|
-
"command": "npx",
|
|
151
|
+
"command": "npx", // socket-hook: allow npx
|
|
166
152
|
"args": ["@socketsecurity/mcp@latest"],
|
|
167
153
|
"env": {
|
|
168
|
-
"
|
|
154
|
+
"SOCKET_API_TOKEN": "your-api-token-here"
|
|
169
155
|
}
|
|
170
156
|
}
|
|
171
157
|
}
|
|
172
158
|
}
|
|
173
159
|
```
|
|
174
160
|
|
|
175
|
-
|
|
161
|
+
</details>
|
|
176
162
|
|
|
163
|
+
<details><summary><b>Option 2b — HTTP mode</b></summary>
|
|
177
164
|
|
|
178
|
-
|
|
165
|
+
Run the server in HTTP mode using npx:
|
|
179
166
|
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
```
|
|
167
|
+
```sh
|
|
168
|
+
MCP_HTTP_MODE=true SOCKET_API_TOKEN=your-api-token npx @socketsecurity/mcp@latest --http # socket-hook: allow npx
|
|
169
|
+
```
|
|
184
170
|
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
171
|
+
Environment variables for HTTP mode:
|
|
172
|
+
|
|
173
|
+
| Variable | Required | Default | Description |
|
|
174
|
+
| ------------------------------------------ | ------------------------------------------------------------ | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
175
|
+
| `SOCKET_API_TOKEN` | Required unless OAuth is enabled | None | Socket API token used for outbound API calls. Legacy aliases (`SOCKET_API_KEY`, `SOCKET_CLI_API_TOKEN`, `SOCKET_CLI_API_KEY`, `SOCKET_SECURITY_API_TOKEN`, `SOCKET_SECURITY_API_KEY`) are accepted via the fleet's `getSocketApiToken()` helper. If unset in OAuth-enabled HTTP mode, the validated incoming bearer token is forwarded upstream instead. |
|
|
176
|
+
| `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
|
+
| `SOCKET_OAUTH_INTROSPECTION_CLIENT_ID` | With OAuth | None | Client ID used for token introspection. |
|
|
178
|
+
| `SOCKET_OAUTH_INTROSPECTION_CLIENT_SECRET` | With OAuth | None | Client secret used for token introspection. |
|
|
179
|
+
| `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
|
+
| `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
|
+
| `SOCKET_DEBUG` | No | `false` | Switches the default upstream Socket API endpoint to localhost when `SOCKET_API_URL` is unset. |
|
|
182
|
+
| `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. |
|
|
183
|
+
| `MCP_PORT` | HTTP mode only | `3000` | Port to bind the HTTP server to. |
|
|
184
|
+
|
|
185
|
+
`SOCKET_API_URL` and `SOCKET_DEBUG` also apply in stdio mode.
|
|
186
|
+
|
|
187
|
+
To enable OAuth-backed auth for incoming MCP requests:
|
|
188
|
+
|
|
189
|
+
```sh
|
|
190
|
+
MCP_HTTP_MODE=true \
|
|
191
|
+
SOCKET_OAUTH_ISSUER=https://issuer.example.com \
|
|
192
|
+
SOCKET_OAUTH_INTROSPECTION_CLIENT_ID=your-client-id \
|
|
193
|
+
SOCKET_OAUTH_INTROSPECTION_CLIENT_SECRET=your-client-secret \
|
|
194
|
+
npx @socketsecurity/mcp@latest --http # socket-hook: allow npx
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
Add `TRUST_PROXY=true` only when the server is deployed behind a trusted reverse proxy or load balancer that normalizes the forwarded host and protocol headers.
|
|
198
|
+
|
|
199
|
+
Configure your MCP client to connect to the HTTP server:
|
|
200
|
+
|
|
201
|
+
```json
|
|
202
|
+
{
|
|
203
|
+
"mcpServers": {
|
|
204
|
+
"socket-mcp": {
|
|
205
|
+
"type": "http",
|
|
206
|
+
"url": "http://localhost:3000"
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
</details>
|
|
196
213
|
|
|
197
|
-
##
|
|
214
|
+
## Usage
|
|
198
215
|
|
|
199
|
-
|
|
216
|
+
Once installed, ask your AI assistant questions like:
|
|
200
217
|
|
|
201
|
-
|
|
218
|
+
- "Check the security score for express version 4.18.2"
|
|
219
|
+
- "Analyze the security of my package.json dependencies"
|
|
220
|
+
- "What are the vulnerability scores for react, lodash, and axios?"
|
|
202
221
|
|
|
203
|
-
|
|
222
|
+
### Tools exposed
|
|
204
223
|
|
|
205
|
-
|
|
206
|
-
|-----------|------|----------|---------|-------------|
|
|
207
|
-
| `packages` | Array | ✅ Yes | - | Array of package objects to analyze |
|
|
208
|
-
| `packages[].ecosystem` | String | No | `"npm"` | Package ecosystem (`npm`, `pypi`, `cargo`, etc.) |
|
|
209
|
-
| `packages[].depname` | String | ✅ Yes | - | Name of the dependency/package |
|
|
210
|
-
| `packages[].version` | String | No | `"unknown"` | Version of the dependency |
|
|
224
|
+
#### depscore
|
|
211
225
|
|
|
212
|
-
|
|
226
|
+
Query the Socket API for dependency scoring information. Returns supply chain, quality, maintenance, vulnerability, and license scores per package.
|
|
227
|
+
|
|
228
|
+
| Parameter | Type | Required | Default | Description |
|
|
229
|
+
| ---------------------- | ------ | -------- | ----------- | -------------------------------------------------- |
|
|
230
|
+
| `packages` | Array | ✅ Yes | - | Array of package objects to analyze |
|
|
231
|
+
| `packages[].ecosystem` | String | No | `"npm"` | Package ecosystem. See Supported ecosystems below. |
|
|
232
|
+
| `packages[].depname` | String | ✅ Yes | - | Name of the dependency/package |
|
|
233
|
+
| `packages[].version` | String | No | `"unknown"` | Version of the dependency |
|
|
234
|
+
|
|
235
|
+
**Supported ecosystems**
|
|
236
|
+
|
|
237
|
+
Based on [Socket's language support](https://docs.socket.dev/docs/language-support). The `ecosystem` parameter maps to PURL types:
|
|
238
|
+
|
|
239
|
+
| Ecosystem | PURL type | Package managers | Maturity |
|
|
240
|
+
| ----------------------- | ---------- | ------------------------- | --------------------------------------------------- |
|
|
241
|
+
| JavaScript & TypeScript | `npm` | npm, yarn, pnpm, Bun, VLT | GA |
|
|
242
|
+
| Python | `pypi` | uv, pip, Poetry, Anaconda | GA |
|
|
243
|
+
| Go | `golang` | Go Modules | GA |
|
|
244
|
+
| Java / Scala / Kotlin | `maven` | Maven, Gradle, sbt | GA |
|
|
245
|
+
| Ruby | `gem` | Bundler | GA |
|
|
246
|
+
| .NET (C#, F#, VB) | `nuget` | NuGet | GA |
|
|
247
|
+
| Rust | `cargo` | cargo | GA |
|
|
248
|
+
| PHP | `composer` | Composer | Experimental |
|
|
249
|
+
| GitHub Actions | `actions` | GitHub Actions workflows | Experimental (workflow scanning, not package-level) |
|
|
250
|
+
|
|
251
|
+
Example request:
|
|
213
252
|
|
|
214
253
|
```json
|
|
215
254
|
{
|
|
216
255
|
"packages": [
|
|
217
|
-
{
|
|
218
|
-
|
|
219
|
-
"depname": "express",
|
|
220
|
-
"version": "4.18.2"
|
|
221
|
-
},
|
|
222
|
-
{
|
|
223
|
-
"ecosystem": "pypi",
|
|
224
|
-
"depname": "fastapi",
|
|
225
|
-
"version": "0.100.0"
|
|
226
|
-
}
|
|
256
|
+
{ "ecosystem": "npm", "depname": "express", "version": "4.18.2" },
|
|
257
|
+
{ "ecosystem": "pypi", "depname": "fastapi", "version": "0.100.0" }
|
|
227
258
|
]
|
|
228
259
|
}
|
|
229
260
|
```
|
|
230
261
|
|
|
231
|
-
|
|
262
|
+
Sample response:
|
|
263
|
+
|
|
232
264
|
```
|
|
233
265
|
pkg:npm/express@4.18.2: supply_chain: 1.0, quality: 0.9, maintenance: 1.0, vulnerability: 1.0, license: 1.0
|
|
266
|
+
Report: https://socket.dev/npm/package/express
|
|
234
267
|
pkg:pypi/fastapi@0.100.0: supply_chain: 1.0, quality: 0.95, maintenance: 0.98, vulnerability: 1.0, license: 1.0
|
|
268
|
+
Report: https://socket.dev/pypi/package/fastapi
|
|
235
269
|
```
|
|
236
270
|
|
|
237
|
-
|
|
271
|
+
#### organizations
|
|
238
272
|
|
|
239
|
-
|
|
240
|
-
- "Check the security score for express version 4.18.2"
|
|
241
|
-
- "Analyze the security of my package.json dependencies"
|
|
242
|
-
- "What are the vulnerability scores for react, lodash, and axios?"
|
|
273
|
+
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.
|
|
243
274
|
|
|
244
|
-
|
|
275
|
+
This tool needs a Socket API token. See [Authentication for organization-scoped tools](#authentication-for-organization-scoped-tools) below.
|
|
245
276
|
|
|
246
|
-
|
|
277
|
+
#### alerts
|
|
247
278
|
|
|
248
|
-
|
|
279
|
+
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.
|
|
249
280
|
|
|
250
|
-
|
|
|
251
|
-
|
|
252
|
-
|
|
|
253
|
-
|
|
|
254
|
-
|
|
|
281
|
+
| Parameter | Type | Required | Default | Description |
|
|
282
|
+
| --------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------- |
|
|
283
|
+
| `org_slug` | String | ✅ Yes | - | Organization slug (get it from the `organizations` tool) |
|
|
284
|
+
| `severity` | String | No | - | Comma-separated subset of `low,medium,high,critical` |
|
|
285
|
+
| `status` | String | No | - | `open` or `cleared` |
|
|
286
|
+
| `category` | String | No | - | Comma-separated subset of `supplyChainRisk,maintenance,quality,license,vulnerability` |
|
|
287
|
+
| `artifact_type` | String | No | - | Comma-separated ecosystems: `npm,pypi,gem,maven,golang,nuget,cargo,chrome,openvsx` |
|
|
288
|
+
| `artifact_name` | String | No | - | Restrict to a single package name |
|
|
289
|
+
| `alert_type` | String | No | - | Comma-separated Socket alert types (e.g. `usesEval,unmaintained`) |
|
|
290
|
+
| `repo_slug` | String | No | - | Comma-separated repository slugs |
|
|
291
|
+
| `per_page` | Integer | No | `100` | Results per page (1–5000) |
|
|
292
|
+
| `cursor` | String | No | - | Pagination cursor — the `endCursor` from a previous response |
|
|
255
293
|
|
|
294
|
+
#### threat_feed
|
|
256
295
|
|
|
257
|
-
|
|
296
|
+
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.
|
|
258
297
|
|
|
259
|
-
|
|
260
|
-
|
|
298
|
+
| Parameter | Type | Required | Default | Description |
|
|
299
|
+
| ------------------- | ------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------- |
|
|
300
|
+
| `org_slug` | String | ✅ Yes | - | Organization slug (get it from the `organizations` tool) |
|
|
301
|
+
| `filter` | String | No | `mal` | Threat category: `mal` (malware), `vuln`, `typ` (typosquat), `obf` (obfuscated), `mjo`, `kes`, `spy`, etc. |
|
|
302
|
+
| `ecosystem` | String | No | - | Ecosystem: `npm`, `pypi`, `gem`, `maven`, `golang`, `nuget`, `cargo`, `chrome`, `openvsx`, `huggingface` |
|
|
303
|
+
| `name` | String | No | - | Filter by package name |
|
|
304
|
+
| `version` | String | No | - | Filter by package version |
|
|
305
|
+
| `is_human_reviewed` | Boolean | No | `false` | Only return human-reviewed items |
|
|
306
|
+
| `sort` | String | No | `updated_at` | Sort field: `id`, `created_at`, `updated_at` |
|
|
307
|
+
| `direction` | String | No | `desc` | Sort direction: `asc`, `desc` |
|
|
308
|
+
| `updated_after` | String | No | - | ISO timestamp; only items updated after this |
|
|
309
|
+
| `created_after` | String | No | - | ISO timestamp; only items created after this |
|
|
310
|
+
| `per_page` | Integer | No | `30` | Results per page (1–100) |
|
|
311
|
+
| `cursor` | String | No | - | Pagination cursor — the `nextPageCursor` from a previous response |
|
|
312
|
+
|
|
313
|
+
#### package_files
|
|
314
|
+
|
|
315
|
+
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.
|
|
316
|
+
|
|
317
|
+
| Parameter | Type | Required | Default | Description |
|
|
318
|
+
| ------------ | ------ | -------- | ------- | --------------------------------------------------------------------------------------- |
|
|
319
|
+
| `ecosystem` | String | No | `npm` | `npm`, `pypi`, `gem`, `cargo`, `maven`, `golang`, `nuget`, `chrome`, `openvsx` |
|
|
320
|
+
| `depname` | String | ✅ Yes | - | Package name (e.g. `lodash`, `@babel/core`, `org.springframework:spring-core`) |
|
|
321
|
+
| `version` | String | ✅ Yes | - | Package version |
|
|
322
|
+
| `artifactId` | String | No | - | Per-version disambiguator (PyPI filename, Maven artifact id, NuGet asset) |
|
|
323
|
+
| `platform` | String | No | - | Platform qualifier for per-OS/arch artifacts (e.g. openvsx `linux-x64`, `darwin-arm64`) |
|
|
324
|
+
|
|
325
|
+
#### package_file_contents
|
|
326
|
+
|
|
327
|
+
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.
|
|
328
|
+
|
|
329
|
+
| Parameter | Type | Required | Default | Description |
|
|
330
|
+
| --------- | ------ | -------- | ------- | ------------------------------------------------------- |
|
|
331
|
+
| `hash` | String | ✅ Yes | - | Blob hash from `package_files` |
|
|
332
|
+
| `path` | String | No | - | File path, for display only; does not affect the lookup |
|
|
333
|
+
|
|
334
|
+
#### package_file_grep
|
|
335
|
+
|
|
336
|
+
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.
|
|
337
|
+
|
|
338
|
+
| Parameter | Type | Required | Default | Description |
|
|
339
|
+
| ----------------- | ------- | -------- | ------- | ------------------------------------------------------- |
|
|
340
|
+
| `hash` | String | ✅ Yes | - | Blob hash from `package_files` |
|
|
341
|
+
| `pattern` | String | ✅ Yes | - | JavaScript regular expression (plain literals work too) |
|
|
342
|
+
| `caseInsensitive` | Boolean | No | `false` | Match case-insensitively |
|
|
343
|
+
| `contextLines` | Integer | No | `0` | Lines of context before and after each match (0–5) |
|
|
344
|
+
| `maxMatches` | Integer | No | `100` | Cap on matching lines returned (1–500) |
|
|
345
|
+
| `path` | String | No | - | File path, for display only; does not affect the lookup |
|
|
346
|
+
|
|
347
|
+
### Authentication for organization-scoped tools
|
|
348
|
+
|
|
349
|
+
`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.
|
|
350
|
+
|
|
351
|
+
How the server resolves a token depends on the transport:
|
|
352
|
+
|
|
353
|
+
- **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.
|
|
354
|
+
- **HTTP mode** scopes the organization tools to the caller, never to the server's own token. Send your Socket API token as an `Authorization: Bearer <token>` header on each request, or use an OAuth access token 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.
|
|
355
|
+
|
|
356
|
+
Generate a token from the [Socket dashboard](https://socket.dev/) under API tokens, then export it before launching the server:
|
|
357
|
+
|
|
358
|
+
```sh
|
|
359
|
+
export SOCKET_API_TOKEN="your-socket-api-token"
|
|
261
360
|
```
|
|
262
361
|
|
|
263
|
-
|
|
362
|
+
When no token is available, these tools return an authentication-required error explaining how to supply one for each transport.
|
|
264
363
|
|
|
364
|
+
### Worked example: organization details and alerts
|
|
265
365
|
|
|
266
|
-
|
|
366
|
+
With `SOCKET_API_KEY` (or `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:
|
|
367
|
+
|
|
368
|
+
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`.
|
|
369
|
+
|
|
370
|
+
2. **Fetch alerts for that org.** Call `alerts` with the slug and any filters:
|
|
371
|
+
|
|
372
|
+
```json
|
|
373
|
+
{
|
|
374
|
+
"org_slug": "my-org",
|
|
375
|
+
"severity": "high,critical",
|
|
376
|
+
"status": "open"
|
|
377
|
+
}
|
|
378
|
+
```
|
|
267
379
|
|
|
268
|
-
|
|
380
|
+
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`.
|
|
269
381
|
|
|
270
|
-
|
|
271
|
-
1. **Public server**: `https://mcp.socket.dev/` (no setup required)
|
|
272
|
-
2. **NPX command**: `npx @socketsecurity/mcp@latest` (always latest version)
|
|
382
|
+
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.
|
|
273
383
|
|
|
274
|
-
###
|
|
384
|
+
### Adjusting tool usage via client rules
|
|
275
385
|
|
|
276
|
-
|
|
386
|
+
You can customize how the MCP server interacts with your AI assistant by editing your client's rules file:
|
|
277
387
|
|
|
278
|
-
|
|
388
|
+
| MCP Client | Rules File Location |
|
|
389
|
+
| ------------------- | --------------------------------- |
|
|
390
|
+
| Claude Desktop/Code | `CLAUDE.md` |
|
|
391
|
+
| VSCode Copilot | `.github/copilot-instructions.md` |
|
|
392
|
+
| Cursor | `.cursor/rules` |
|
|
279
393
|
|
|
280
|
-
|
|
394
|
+
Example rule:
|
|
395
|
+
|
|
396
|
+
```md
|
|
397
|
+
Always check dependency scores with the depscore tool when you add a new dependency. If the score is low, consider using an alternative library or writing the code yourself.
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
## Claude Code Hook (Optional)
|
|
401
|
+
|
|
402
|
+
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.
|
|
403
|
+
|
|
404
|
+
Supported ecosystems and package managers:
|
|
405
|
+
|
|
406
|
+
| Ecosystem | Commands |
|
|
407
|
+
| --------- | ----------------------------------------------------------------------------------------- |
|
|
408
|
+
| npm | `npm install`, `npm i`, `npm add`, `yarn add`, `pnpm add`, `bun add` |
|
|
409
|
+
| PyPI | `pip install`, `pip3 install`, `uv add`, `uv pip install`, `poetry add`, `pipenv install` |
|
|
410
|
+
| Cargo | `cargo add`, `cargo install` |
|
|
411
|
+
| RubyGems | `gem install`, `bundle add` |
|
|
412
|
+
| Go | `go get`, `go install` |
|
|
413
|
+
| NuGet | `dotnet add package`, `nuget install` |
|
|
414
|
+
|
|
415
|
+
### Setup
|
|
416
|
+
|
|
417
|
+
**Prerequisites:** Node.js 22+.
|
|
418
|
+
|
|
419
|
+
1. Copy the whole `socket-gate` directory into your hooks folder. The bundled
|
|
420
|
+
`socket-gate.cjs` is self-contained, so it runs without any dependencies
|
|
421
|
+
beside it. From a checkout, run `pnpm run build` first to produce it; from a
|
|
422
|
+
published install, copy from `node_modules/@socketsecurity/mcp/`:
|
|
281
423
|
|
|
282
424
|
```bash
|
|
283
|
-
|
|
425
|
+
mkdir -p ~/.claude/hooks
|
|
426
|
+
cp -R hooks/socket-gate ~/.claude/hooks/
|
|
284
427
|
```
|
|
285
428
|
|
|
286
|
-
|
|
429
|
+
2. Add to `~/.claude/settings.json`:
|
|
430
|
+
|
|
287
431
|
```json
|
|
288
432
|
{
|
|
289
|
-
"
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
433
|
+
"hooks": {
|
|
434
|
+
"PreToolUse": [
|
|
435
|
+
{
|
|
436
|
+
"matcher": "Bash",
|
|
437
|
+
"hooks": [
|
|
438
|
+
{
|
|
439
|
+
"type": "command",
|
|
440
|
+
"command": "node ~/.claude/hooks/socket-gate/socket-gate.cjs"
|
|
441
|
+
}
|
|
442
|
+
]
|
|
443
|
+
}
|
|
444
|
+
]
|
|
445
|
+
}
|
|
293
446
|
}
|
|
294
447
|
```
|
|
295
448
|
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
- Docker health checks
|
|
299
|
-
- Load balancer health monitoring
|
|
300
|
-
- General service monitoring
|
|
301
|
-
|
|
449
|
+
See [`hooks/socket-gate/README.md`](hooks/socket-gate/README.md) for the full
|
|
450
|
+
reference.
|
|
302
451
|
|
|
303
|
-
|
|
452
|
+
### How it works
|
|
304
453
|
|
|
305
|
-
|
|
306
|
-
- npm or yarn
|
|
454
|
+
The hook denies installation when `supplyChain < 20`, allows it otherwise — e.g. `express`/`lodash`/`react` (75–97) allow, `browserlist` (typosquat of `browserslist`, 15) and confirmed malware (0) block. Network, timeout, or parse errors all fail open, so a Socket outage will not block legitimate work.
|
|
307
455
|
|
|
308
|
-
|
|
456
|
+
### Limitations
|
|
309
457
|
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
```bash
|
|
313
|
-
git clone https://github.com/SocketDev/socket-mcp.git
|
|
314
|
-
cd socket-mcp
|
|
315
|
-
npm install
|
|
316
|
-
```
|
|
458
|
+
A best-effort guardrail, not a complete defense. Known gaps:
|
|
317
459
|
|
|
318
|
-
|
|
460
|
+
- **Manifest edits + lockfile installs.** If Claude edits a manifest directly (`package.json`, `requirements.txt`, `Cargo.toml`, `Gemfile`, `go.mod`, `*.csproj`) then runs a bare install (`npm install`, `pip install -r requirements.txt`, `cargo build`, `bundle install`, `go mod tidy`, `dotnet restore`), there is no package name on the command line to check.
|
|
461
|
+
- **Package-manager invocations only.** Direct downloads (`curl | sh`, `wget`), post-install scripts of already-accepted packages, and transitive dependencies are not re-checked.
|
|
462
|
+
- **Indirect Claude paths.** Sub-agents, MCP tools that shell out, and non-`Bash` tool calls are not covered unless the `matcher` is broadened.
|
|
319
463
|
|
|
320
|
-
|
|
321
|
-
If you are on Node.js 22, run with `node --experimental-strip-types index.ts`.
|
|
322
|
-
On any later versions of Node.js, you can simply run `node index.ts`.
|
|
323
|
-
In either version you can also run the npm run scripts which include the correct flags.
|
|
464
|
+
Inspired by [Jimmy Vo's dependency hook](https://blog.jimmyvo.com/posts/claudes-dependency-hook/).
|
|
324
465
|
|
|
325
|
-
|
|
466
|
+
## Development
|
|
326
467
|
|
|
327
|
-
|
|
468
|
+
<details>
|
|
469
|
+
<summary>Contributor commands</summary>
|
|
328
470
|
|
|
329
|
-
```
|
|
471
|
+
```sh
|
|
472
|
+
git clone https://github.com/SocketDev/socket-mcp.git
|
|
473
|
+
cd socket-mcp
|
|
474
|
+
npm install
|
|
330
475
|
npm run build
|
|
331
476
|
```
|
|
332
477
|
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
To run the Socket MCP server from source:
|
|
478
|
+
Run from source (stdio mode):
|
|
336
479
|
|
|
337
|
-
```
|
|
338
|
-
export
|
|
480
|
+
```sh
|
|
481
|
+
export SOCKET_API_TOKEN=your_api_token_here
|
|
339
482
|
node --experimental-strip-types index.ts
|
|
340
483
|
```
|
|
341
484
|
|
|
342
485
|
Or in HTTP mode:
|
|
343
486
|
|
|
344
|
-
```
|
|
345
|
-
MCP_HTTP_MODE=true
|
|
487
|
+
```sh
|
|
488
|
+
MCP_HTTP_MODE=true SOCKET_API_TOKEN=your_api_token_here node --experimental-strip-types index.ts --http
|
|
346
489
|
```
|
|
347
490
|
|
|
348
|
-
|
|
491
|
+
### Health check endpoint
|
|
349
492
|
|
|
350
|
-
|
|
493
|
+
When running in HTTP mode, `GET /health` returns:
|
|
351
494
|
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
-
|
|
495
|
+
```json
|
|
496
|
+
{
|
|
497
|
+
"status": "healthy",
|
|
498
|
+
"service": "socket-mcp",
|
|
499
|
+
"version": "0.0.18",
|
|
500
|
+
"timestamp": "2025-06-17T20:45:22.059Z"
|
|
501
|
+
}
|
|
502
|
+
```
|
|
356
503
|
|
|
357
|
-
|
|
358
|
-
- Ensure you have Node.js v16+ installed
|
|
359
|
-
- Check that your `SOCKET_API_KEY` environment variable is set
|
|
360
|
-
- Verify the API key has `packages:list` permission
|
|
504
|
+
Suitable for Kubernetes liveness/readiness probes, Docker health checks, load balancers.
|
|
361
505
|
|
|
362
|
-
|
|
363
|
-
- Double-check your Socket API key is valid
|
|
364
|
-
- Ensure the key has the required `packages:list` scope
|
|
365
|
-
- Try regenerating your API key from the Socket dashboard
|
|
506
|
+
### Troubleshooting
|
|
366
507
|
|
|
367
|
-
**Q:
|
|
368
|
-
- Restart your MCP client after configuration changes
|
|
369
|
-
- Verify the server configuration is saved correctly
|
|
370
|
-
- Check that the MCP server is running (for local deployments)
|
|
508
|
+
**Q: The public server isn't responding** — Check the URL `https://mcp.socket.dev/`, verify your MCP client configuration, restart your MCP client.
|
|
371
509
|
|
|
372
|
-
|
|
510
|
+
**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.
|
|
511
|
+
|
|
512
|
+
**Q: Getting authentication errors with local server** — Double-check your API key is valid, ensure `packages:list` scope, regenerate if needed.
|
|
513
|
+
|
|
514
|
+
**Q: AI assistant can't find the depscore tool** — Restart your MCP client after configuration changes, verify config is saved, check the server is running.
|
|
515
|
+
|
|
516
|
+
### Getting help
|
|
373
517
|
|
|
374
518
|
- 📖 [Socket Documentation](https://docs.socket.dev)
|
|
375
519
|
- 🐛 [Report Issues](https://github.com/SocketDev/socket-mcp/issues)
|
|
376
520
|
- 💬 [Community Support](https://github.com/SocketDev/socket-mcp/discussions)
|
|
377
521
|
|
|
522
|
+
</details>
|
|
523
|
+
|
|
524
|
+
## License
|
|
525
|
+
|
|
526
|
+
MIT
|
|
527
|
+
|
|
378
528
|
<br/>
|
|
379
529
|
<div align="center">
|
|
380
530
|
<picture>
|