@socketsecurity/mcp 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Socket Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,197 @@
+# Socket MCP Server
+
+A Model Context Protocol (MCP) server for Socket integration, allowing AI assistants to efficiently check dependency vulnerability scores and security information.
+
+🛠️ This project is in early development and rapidly evolving.
+
+## Tools
+
+### depscore
+
+The `depscore` tool allows AI assistants to query the Socket API for dependency scoring information. It provides security and quality metrics for packages across different ecosystems.
+
+**Parameters:**
+
+- `ecosystem`: The package ecosystem (e.g., npm, PyPI). Defaults to "npm".
+- `depname`: The name of the dependency.
+- `version`: The version of the dependency. Defaults to "unknown".
+
+## Configuration
+
+### Getting an API key
+
+To use the Socket MCP Server, you need to create an API key. You can do this by following [these steps](https://docs.socket.dev/reference/creating-and-managing-api-tokens).
+
+
+### Usage with Claude Desktop
+
+> [!NOTE]
+> 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.
+
+To use this MCP server with Claude Desktop:
+
+1. Install the Socket MCP server:
+
+   ```bash
+   npm install -g @socketsecurity/mcp
+   ```
+
+2. Set the API key in your environment:
+
+   ```bash
+   export SOCKET_API_KEY=your_api_key_here
+   ```
+
+3. In Claude Desktop, go to Settings > Developer > Edit Config.
+
+
+```js
+{
+  "mcpServers": {
+    "socket-mcp": {
+        "command": "socket-mcp",
+        "args": [],
+      "env": {
+        "SOCKET_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+4. Enter the following:
+   - Name: Socket
+   - Command: `socket-mcp`
+   - Save the configuration.
+
+5. Now you can ask Claude questions like "Check the security score for express version 4.18.2".
+
+The process is similar for Claude Code. See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/tutorials#set-up-model-context-protocol-mcp) for more details.
+
+### Usage with VS Code
+
+For quick installation, you can use the following link to install the Socket MCP server in VS Code:
+
+
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Socket_MCP-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=socket-mcp&inputs=[{"type":"promptString","id":"socket_api_key","description":"Socket%20API%20key","password":true}]&config={"command":"depscore","type":"stdio","env":{"SOCKET_API_KEY":"${input:socket_api_key}"}})
+
+
+To use this MCP server in VS Code:
+
+1. Set the API key in your environment:
+
+   ```bash
+   export SOCKET_API_KEY=your_api_key_here
+   ```
+
+2. In VS Code settings, add the Socket MCP server to your configuration `.vscode/mcp.json` file:
+
+   ```json
+    {
+        "inputs": [
+            {
+                "type": "promptString",
+                "id": "socket_api_key",
+                "description": "Socket API Key",
+                "password": true
+            }
+        ],
+        "servers": {
+            "socket-mcp": {
+                "type": "stdio",
+                "command": "socket-mcp",
+                "args": [],
+                    "env": {
+                        "SOCKET_API_KEY": "${input:socket_api_key}"
+                    },
+            }
+        }
+    }
+   ```
+
+3. Now you can ask questions about dependency security within your VS Code environment.
+4. Feel free to add the following to your `.github/copilot-instructions.md` file to control better how the tools is used by your agent:
+
+   ```markdown
+   ## Socket MCP Server
+    Always check the dependencies 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. If you decide to use a library with a low score, make sure to document the reasons for your choice. If you are unsure about the score, ask for a review from someone with more experience.
+
+    When checking dependencies, make sure to also check the imports not just the pyproject.toml/package.json/dependency file.
+   ```
+
+## Development
+
+### Prerequisites
+
+- Node.js v16 or higher
+- npm or yarn
+
+### Installation
+
+Clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/SocketDev/socket-mcp.git
+cd socket-mcp
+npm install
+```
+
+## Build
+
+To build the project:
+
+```bash
+npm run build
+```
+
+This compiles the TypeScript files and makes the binary executable called `socket-mcp`.
+
+## Run
+
+To run the Socket MCP server locally:
+
+```bash
+export SOCKET_API_KEY=your_api_key_here
+node build/index.js
+```
+
+After installing globally, you can run the executable directly:
+
+```bash
+export SOCKET_API_KEY=your_api_key_here
+socket-mcp
+```
+
+### Global Installation
+
+To install the tool globally and make the `socket-mcp` command available system-wide:
+
+```bash
+npm install -g .
+```
+
+After global installation, you can use the `socket-mcp` command from anywhere:
+
+```bash
+export SOCKET_API_KEY=your_api_key_here
+socket-mcp
+```
+
+## Adjust tool usage with custom rules
+
+You can further customize how the Socket MCP server interacts with your AI assistant by modifying your client rules. The rules are usually a markdown file and its location depends on the AI assistant you are using.
+
+| MCP Client | Rules File Location |
+|---|---|
+| Claude Desktop/Code | `CLAUDE.md`  |
+| VSCode Copilot | `.github/copilot-instructions.md`  |
+| Cursor | `.cursor/rules` |
+
+
+Rules that can be added to the client rules file include the following:
+
+```md
+Always check dependency scores with the debscore tool when you add a new dependency. If the score is low, consider using an alternative library or writing the code yourself. If you are unsure about the score, ask for a review from someone with more experience. When checking dependencies, make sure to also check the imports not just the pyproject.toml file.
+```
+
+You can adjust the rules to fit your needs. For example, you can add rules to include specific manifest files, or guide the AI assistant on how to handle low scores. The rules are flexible and can be tailored to your workflow.

package/build/index.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import fetch from 'node-fetch';
+import winston from 'winston';
+const VERSION = "0.0.1"; // Version of the MCP server
+// Configure winston logger
+const logger = winston.createLogger({
+    level: 'info',
+    format: winston.format.combine(winston.format.timestamp(), winston.format.errors({ stack: true }), winston.format.json()),
+    transports: [
+        new winston.transports.File({ filename: 'socket-mcp-error.log', level: 'error' }),
+        new winston.transports.File({ filename: 'socket-mcp.log' })
+    ]
+});
+const SOCKET_API_URL = "https://api.socket.dev/v0/purl?alerts=false&compact=false&fixable=false&licenseattrib=false&licensedetails=false";
+const SOCKET_API_KEY = process.env.SOCKET_API_KEY || "";
+if (!SOCKET_API_KEY) {
+    logger.error("SOCKET_API_KEY environment variable is not set");
+    process.exit(1);
+}
+const SOCKET_HEADERS = {
+    "user-agent": `socket-mcp/${VERSION}`,
+    "accept": "application/x-ndjson",
+    "content-type": "application/json",
+    "authorization": `Bearer ${SOCKET_API_KEY}`
+};
+// Create server instance
+const server = new McpServer({
+    name: "socket",
+    version: VERSION,
+    description: "Socket MCP server",
+    capabilities: {
+        resources: {},
+        tools: {},
+    },
+});
+server.tool("depscore", "Get the dependency score of a package with the `depscore` tool from Socket. Use 'unknown' for version if not known. Use this tool to scan dependencies for their quality and security on existing code or when code is generated. Stop generating code and ask the user how to proceed when any of the scores are low. When checking dependencies, make sure to also check the imports in the code, not just the manifest files (pyproject.toml, package.json, etc).", {
+    ecosystem: z.string().describe("The package ecosystem (e.g., npm, pypi)").default("npm"),
+    depname: z.string().describe("The name of the dependency"),
+    version: z.string().describe("The version of the dependency, use 'unknown' if not known").default("unknown"),
+}, async ({ ecosystem, depname, version }) => {
+    logger.info(`Received request for ${depname} (${version}) in ${ecosystem} ecosystem`);
+    // cleanup version
+    let purl;
+    const cleanedVersion = version.replace(/[\^~]/g, ''); // Remove ^ and ~ from version
+    if (cleanedVersion === "1.0.0" || cleanedVersion === "unknown" || !cleanedVersion) {
+        purl = `pkg:${ecosystem}/${depname}`;
+    }
+    else {
+        logger.info(`Using version ${cleanedVersion} for ${depname}`);
+        purl = `pkg:${ecosystem}/${depname}@${cleanedVersion}`;
+    }
+    try {
+        // Make a POST request to the Socket API
+        const response = await fetch(SOCKET_API_URL, {
+            method: 'POST',
+            headers: SOCKET_HEADERS,
+            body: JSON.stringify({ components: [{ purl }] })
+        });
+        const responseText = await response.text();
+        if (response.status !== 200) {
+            const errorMsg = `Error processing ${purl}: [${response.status}] ${responseText}`;
+            logger.error(errorMsg);
+            return {
+                content: [{ type: "text", text: errorMsg }],
+                isError: false
+            };
+        }
+        else if (!responseText.trim()) {
+            const errorMsg = `${purl} was not found.`;
+            logger.error(errorMsg);
+            return {
+                content: [{ type: "text", text: errorMsg }],
+                isError: false
+            };
+        }
+        try {
+            // Handle NDJSON (multiple JSON objects, one per line)
+            let jsonData;
+            if ((response.headers.get('content-type') || '').includes('x-ndjson')) {
+                const jsonLines = responseText.split('\n')
+                    .filter(line => line.trim())
+                    .map(line => JSON.parse(line));
+                if (!jsonLines.length) {
+                    const errorMsg = `No valid JSON objects found in NDJSON response for ${purl}`;
+                    return {
+                        content: [{ type: "text", text: errorMsg }],
+                        isError: true
+                    };
+                }
+                jsonData = jsonLines[0];
+            }
+            else {
+                jsonData = JSON.parse(responseText);
+            }
+            if (jsonData.score && jsonData.score.overall !== undefined) {
+                // Unroll the jsonData.score object into key-value pairs
+                const scoreEntries = Object.entries(jsonData.score)
+                    .filter(([key]) => key !== "overall" && key !== "uuid")
+                    .map(([key, value]) => `${key}: ${value}`)
+                    .join(', ');
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Dependency scores for ${purl}: ${scoreEntries}`
+                        }
+                    ]
+                };
+            }
+            else {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No score found for ${purl}`
+                        }
+                    ]
+                };
+            }
+        }
+        catch (e) {
+            const error = e;
+            const errorMsg = `JSON parsing error for ${purl}: ${error.message} -- Response: ${responseText}`;
+            logger.error(errorMsg);
+            const llmResponse = `Package ${purl} not found.`;
+            return {
+                content: [{ type: "text", text: llmResponse }],
+                isError: true
+            };
+        }
+    }
+    catch (e) {
+        const error = e;
+        const errorMsg = `Error processing ${purl}: ${error.message}`;
+        logger.error(errorMsg);
+        const llmResponse = `Package ${purl} not found.`;
+        return {
+            content: [{ type: "text", text: llmResponse }],
+            isError: true
+        };
+    }
+});
+// Create a stdio transport and start the server
+const transport = new StdioServerTransport();
+server.connect(transport)
+    .then(() => {
+    logger.info("Socket MCP server started successfully");
+})
+    .catch((error) => {
+    logger.error(`Failed to start Socket MCP server: ${error.message}`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@socketsecurity/mcp",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "./build/index.js",
+  "bin": {
+    "socket-mcp": "./build/index.js"
+  },
+  "scripts": {
+    "build": "tsc && chmod 755 ./build/index.js",
+    "postinstall": "npm run build"
+  },
+  "files": [
+    "build"
+  ],
+  "keywords": [],
+  "author": "Alexandros Kapravelos",
+  "description": "Socket MCP server for scanning dependencies",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.11.3",
+    "@types/node-fetch": "^2.6.12",
+    "node-fetch": "^3.3.2",
+    "semver": "^7.7.2",
+    "winston": "^3.17.0",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.19",
+    "@types/semver": "^7.7.0",
+    "@types/triple-beam": "^1.3.5",
+    "typescript": "^5.8.3"
+  }
+}