@socketsecurity/mcp 0.0.17 → 0.0.18

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to `@socketsecurity/mcp` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.0.18]
+
+### Fixed
+
+- The `package_files` and `organizations` tools no longer fail with
+  `Unexpected token` JSON errors against the live Socket API.
+
+## [0.0.17]
+
+Initial tracked release.

package/README.md

@@ -4,11 +4,15 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Socket Badge](https://socket.dev/api/badge/npm/package/@socketsecurity/mcp)](https://socket.dev/npm/package/@socketsecurity/mcp)
 
-A Model Context Protocol (MCP) server for Socket integration, allowing AI assistants to efficiently check dependency vulnerability scores and security information.
+A Model Context Protocol (MCP) server for Socket integration — lets AI assistants query dependency vulnerability scores and security metadata.
+
+## Why this repo exists
+
+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.
 
 ## ✨ Features
 
-- 🔍 **Dependency Security Scanning** - Get comprehensive security scores for npm, PyPI, and other package ecosystems
+- 🔍 **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))
 - 🌐 **Public Hosted Service** - Use our public server at `https://mcp.socket.dev/` with no setup required
 - 🚀 **Multiple Deployment Options** - Run locally via stdio, HTTP, or use our service
 - 🤖 **AI Assistant Integration** - Works seamlessly with Claude, VS Code Copilot, Cursor, and other MCP clients
@@ -17,28 +21,21 @@ A Model Context Protocol (MCP) server for Socket integration, allowing AI assist
 
 🛠️ This project is in early development and rapidly evolving.
 
-## 🚀 Quick Start
-
-### Option 1: Use the Public Socket MCP Server (Recommended)
+## Install
 
-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.
+### Option 1: Use the public Socket MCP server (recommended)
 
+The easiest way to get started. **No API key or authentication required!** Click a button below to install in your favorite AI assistant.
 
 [![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&config={"url":"https://mcp.socket.dev/","type":"http"})
 [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=socket-mcp&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vbWNwLnNvY2tldC5kZXYvIn0%3D)
 
-
-<details><summary><b>Manual Installation Instructions & more MCP Clients</b></summary>
-
-<details><summary><b>Install in Claude Desktop or Claude Code</b></summary>
+<details><summary><b>Manual install — Claude Desktop / Claude Code</b></summary>
 
 > [!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 the public Socket MCP server with Claude Desktop:
-
 1. In Claude Desktop, go to Settings > Developer > Edit Config.
-
 2. Add the Socket MCP server configuration:
 
 ```json
@@ -53,29 +50,24 @@ To use the public Socket MCP server with Claude Desktop:
 ```
 
 3. Save the configuration and restart Claude Desktop.
+4. Now you can ask Claude "Check the security score for express version 4.18.2".
 
-4. 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/mcp) for more details. Here's an example command to add the Socket MCP server:
+For Claude Code:
 
-```bash
+```sh
 claude mcp add --transport http socket-mcp https://mcp.socket.dev/
 ```
 
 </details>
 
-<details><summary><b>Install in VS Code</b></summary>
+<details><summary><b>Manual install — VS Code</b></summary>
 
-You can install the Socket MCP server using the VS Code CLI:
-
-```bash
+```sh
 # For VS Code with GitHub Copilot
-code --add-mcp '{"name":"socket-mcp","type":"http","url":"https://mcp.socket.dev/}'
+code --add-mcp '{"name":"socket-mcp","type":"http","url":"https://mcp.socket.dev/"}'
 ```
 
-After installation, the Socket MCP server will be available for use with your GitHub Copilot agent in VS Code.
-
-Alternatively, you can manually add it to your VS Code MCP configuration in `.vscode/mcp.json`:
+Or add to `.vscode/mcp.json`:
 
 ```json
 {
@@ -90,9 +82,9 @@ Alternatively, you can manually add it to your VS Code MCP configuration in `.vs
 
 </details>
 
-<details><summary><b>Install in Cursor</b></summary>
+<details><summary><b>Manual install — Cursor</b></summary>
 
-Go to `Cursor Settings` -> `MCP` -> `Add new MCP Server`. Name it "socket-mcp", use `http` type with URL `https://mcp.socket.dev/`.
+`Cursor Settings` → `MCP` → `Add new MCP Server`. Name `socket-mcp`, `http` type, URL `https://mcp.socket.dev/`.
 
 ```json
 {
@@ -107,274 +99,319 @@ Go to `Cursor Settings` -> `MCP` -> `Add new MCP Server`. Name it "socket-mcp",
 
 </details>
 
-<details><summary><b>Install in Windsurf</b></summary>
+<details><summary><b>Manual install — Windsurf</b></summary>
 
 > [!WARNING]
-> Windsurf does not support `http` type MCP servers yet. Use the `stdio` configuration [below](#option-2a-stdio-mode-default).
-
-To use the Socket MCP server in Windsurf:
-
-1. Open Windsurf Settings
-2. Navigate to MCP Servers section
-3. Add a new server with the following configuration:
+> Windsurf does not support `http` type MCP servers yet. Use the stdio configuration in Option 2 below.
 
 ```json
 {
-    "mcpServers": {
-        "socket-mcp": {
-            "serverUrl": "https://mcp.socket.dev/mcp"
-        }
+  "mcpServers": {
+    "socket-mcp": {
+      "serverUrl": "https://mcp.socket.dev/mcp"
     }
+  }
 }
 ```
 
-4. Save the configuration and restart Windsurf if needed.
-
 </details>
 
-</details>
+<details><summary><b>Manual install — Factory</b></summary>
 
-### Option 2: Deploy Socket MCP Server on your machine
+[Factory](https://factory.ai) is an AI-powered software engineering platform. Install the Socket MCP server with the Factory CLI:
 
-If you prefer to run your own instance, you can deploy the Socket MCP server locally using either stdio or HTTP modes.
+```bash
+droid mcp add socket https://mcp.socket.dev/ --type http
+```
 
-### Getting an API key
+To self-host with an API key instead, see Option 2 below and register the stdio command with `droid mcp add`.
 
-To use a local 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). The only required permission scope is `packages:list`, which allows the MCP server to query package metadata for dependency scores.
+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).
 
-For local deployment, you have two options:
+</details>
 
-##### Option 2a: Stdio Mode (Default)
+### Option 2: Self-host the Socket MCP server
 
-Click a button below to install the self-hosted stdio server in your favorite AI assistant.
+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)).
 
-[![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&config={"command":"npx","args":["@socketsecurity/mcp@latest"],"type":"stdio"})
-[![Install in Cursor (stdio)](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=socket-mcp&config=eyJjb21tYW5kIjoibnB4IEBzb2NrZXRzZWN1cml0eS9tY3BAbGF0ZXN0IiwiZW52Ijp7IlNPQ0tFVF9BUElfS0VZIjoieW91ci1hcGkta2V5LWhlcmUifX0%3D)
+<details><summary><b>Option 2a — Stdio mode (default)</b></summary>
 
-Claude Code (stdio mode) can be set up with the following command:
+Claude Code:
 
-```bash
-claude mcp add socket-mcp -e SOCKET_API_KEY="your-api-key-here" -- npx -y @socketsecurity/mcp@latest
+```sh
+claude mcp add socket-mcp -e SOCKET_API_TOKEN="your-api-token-here" -- npx -y @socketsecurity/mcp@latest # socket-hook: allow npx
 ```
-This is how the configuration looks like on most MCP clients:
+
+Most other MCP clients:
 
 ```json
 {
   "mcpServers": {
     "socket-mcp": {
-      "command": "npx",
+      "command": "npx", // socket-hook: allow npx
       "args": ["@socketsecurity/mcp@latest"],
       "env": {
-        "SOCKET_API_KEY": "your-api-key-here"
+        "SOCKET_API_TOKEN": "your-api-token-here"
       }
     }
   }
 }
 ```
 
-This approach automatically uses the latest version without requiring global installation.
+</details>
+
+<details><summary><b>Option 2b — HTTP mode</b></summary>
+
+Run the server in HTTP mode using npx:
+
+```sh
+MCP_HTTP_MODE=true SOCKET_API_TOKEN=your-api-token npx @socketsecurity/mcp@latest --http # socket-hook: allow npx
+```
+
+Environment variables for HTTP mode:
+
+| Variable                                   | Required                                                     | Default                                                          | Description                                                                                                                                                                                                                                                                                                                                              |
+| ------------------------------------------ | ------------------------------------------------------------ | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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. |
+| `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.                                                                                                                                                                                                                                                                       |
+| `SOCKET_OAUTH_INTROSPECTION_CLIENT_ID`     | With OAuth                                                   | None                                                             | Client ID used for token introspection.                                                                                                                                                                                                                                                                                                                  |
+| `SOCKET_OAUTH_INTROSPECTION_CLIENT_SECRET` | With OAuth                                                   | None                                                             | Client secret used for token introspection.                                                                                                                                                                                                                                                                                                              |
+| `SOCKET_OAUTH_REQUIRED_SCOPES`             | No                                                           | `packages:list`                                                  | Space-delimited scopes required on incoming access tokens.                                                                                                                                                                                                                                                                                               |
+| `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.                                                                                                                                                                                                                                                                     |
+| `SOCKET_DEBUG`                             | No                                                           | `false`                                                          | Switches the default upstream Socket API endpoint to localhost when `SOCKET_API_URL` is unset.                                                                                                                                                                                                                                                           |
+| `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.                                                                                                                                                                                 |
+| `MCP_PORT`                                 | HTTP mode only                                               | `3000`                                                           | Port to bind the HTTP server to.                                                                                                                                                                                                                                                                                                                         |
+
+`SOCKET_API_URL` and `SOCKET_DEBUG` also apply in stdio mode.
+
+To enable OAuth-backed auth for incoming MCP requests:
+
+```sh
+MCP_HTTP_MODE=true \
+SOCKET_OAUTH_ISSUER=https://issuer.example.com \
+SOCKET_OAUTH_INTROSPECTION_CLIENT_ID=your-client-id \
+SOCKET_OAUTH_INTROSPECTION_CLIENT_SECRET=your-client-secret \
+npx @socketsecurity/mcp@latest --http # socket-hook: allow npx
+```
+
+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.
+
+Configure your MCP client to connect to the HTTP server:
+
+```json
+{
+  "mcpServers": {
+    "socket-mcp": {
+      "type": "http",
+      "url": "http://localhost:3000"
+    }
+  }
+}
+```
+
+</details>
+
+## Usage
 
+Once installed, ask your AI assistant questions like:
 
-##### Option 2b: HTTP Mode
+- "Check the security score for express version 4.18.2"
+- "Analyze the security of my package.json dependencies"
+- "What are the vulnerability scores for react, lodash, and axios?"
 
-1. Run the server in HTTP mode using npx:
-   ```bash
-   MCP_HTTP_MODE=true SOCKET_API_KEY=your-api-key npx @socketsecurity/mcp@latest --http
-   ```
+### Tools exposed
 
-2. Configure your MCP client to connect to the HTTP server:
-   ```json
-   {
-     "mcpServers": {
-       "socket-mcp": {
-         "type": "http",
-         "url": "http://localhost:3000"
-       }
-     }
-   }
-   ```
+#### depscore
 
-## Tools exposed by the Socket MCP Server
+Query the Socket API for dependency scoring information. Returns supply chain, quality, maintenance, vulnerability, and license scores per package.
 
-### depscore
+| Parameter              | Type   | Required | Default     | Description                                        |
+| ---------------------- | ------ | -------- | ----------- | -------------------------------------------------- |
+| `packages`             | Array  | ✅ Yes   | -           | Array of package objects to analyze                |
+| `packages[].ecosystem` | String | No       | `"npm"`     | Package ecosystem. See Supported ecosystems below. |
+| `packages[].depname`   | String | ✅ Yes   | -           | Name of the dependency/package                     |
+| `packages[].version`   | String | No       | `"unknown"` | Version of the dependency                          |
 
-The `depscore` tool allows AI assistants to query the Socket API for dependency scoring information. It provides comprehensive security and quality metrics for packages across different ecosystems.
+**Supported ecosystems**
 
-**Parameters:**
+Based on [Socket's language support](https://docs.socket.dev/docs/language-support). The `ecosystem` parameter maps to PURL types:
 
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `packages` | Array | ✅ Yes | - | Array of package objects to analyze |
-| `packages[].ecosystem` | String | No | `"npm"` | Package ecosystem (`npm`, `pypi`, `cargo`, etc.) |
-| `packages[].depname` | String | ✅ Yes | - | Name of the dependency/package |
-| `packages[].version` | String | No | `"unknown"` | Version of the dependency |
+| Ecosystem               | PURL type  | Package managers          | Maturity                                            |
+| ----------------------- | ---------- | ------------------------- | --------------------------------------------------- |
+| JavaScript & TypeScript | `npm`      | npm, yarn, pnpm, Bun, VLT | GA                                                  |
+| Python                  | `pypi`     | uv, pip, Poetry, Anaconda | GA                                                  |
+| Go                      | `golang`   | Go Modules                | GA                                                  |
+| Java / Scala / Kotlin   | `maven`    | Maven, Gradle, sbt        | GA                                                  |
+| Ruby                    | `gem`      | Bundler                   | GA                                                  |
+| .NET (C#, F#, VB)       | `nuget`    | NuGet                     | GA                                                  |
+| Rust                    | `cargo`    | cargo                     | GA                                                  |
+| PHP                     | `composer` | Composer                  | Experimental                                        |
+| GitHub Actions          | `actions`  | GitHub Actions workflows  | Experimental (workflow scanning, not package-level) |
 
-**Example Usage:**
+Example request:
 
 ```json
 {
   "packages": [
-    {
-      "ecosystem": "npm",
-      "depname": "express",
-      "version": "4.18.2"
-    },
-    {
-      "ecosystem": "pypi",
-      "depname": "fastapi",
-      "version": "0.100.0"
-    }
+    { "ecosystem": "npm", "depname": "express", "version": "4.18.2" },
+    { "ecosystem": "pypi", "depname": "fastapi", "version": "0.100.0" }
   ]
 }
 ```
 
-**Sample Response:**
+Sample response:
+
 ```
 pkg:npm/express@4.18.2: supply_chain: 1.0, quality: 0.9, maintenance: 1.0, vulnerability: 1.0, license: 1.0
+  Report: https://socket.dev/npm/package/express
 pkg:pypi/fastapi@0.100.0: supply_chain: 1.0, quality: 0.95, maintenance: 0.98, vulnerability: 1.0, license: 1.0
+  Report: https://socket.dev/pypi/package/fastapi
 ```
 
-### How to Use the Socket MCP Server
-
-1. **Ask your AI assistant** to check dependencies:
-   - "Check the security score for express version 4.18.2"
-   - "Analyze the security of my package.json dependencies"
-   - "What are the vulnerability scores for react, lodash, and axios?"
-
-2. **Get comprehensive security insights** including supply chain, quality, maintenance, vulnerability, and license scores.
-
-### 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.
+### Adjusting tool usage via client rules
 
-| MCP Client | Rules File Location |
-|---|---|
-| Claude Desktop/Code | `CLAUDE.md`  |
-| VSCode Copilot | `.github/copilot-instructions.md`  |
-| Cursor | `.cursor/rules` |
+You can customize how the MCP server interacts with your AI assistant by editing your client's rules file:
 
+| 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:
+Example rule:
 
 ```md
-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. 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.
+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.
 ```
 
-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.
+## Claude Code Hook (Optional)
 
+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 API key, no CLI, no registration — copy the file and wire it up.
 
-## Development
-
-### For End Users
-
-For most users, we recommend using either:
-1. **Public server**: `https://mcp.socket.dev/` (no setup required)
-2. **NPX command**: `npx @socketsecurity/mcp@latest` (always latest version)
+Supported ecosystems and package managers:
 
-### For Contributors
+| Ecosystem | Commands                                                                                  |
+| --------- | ----------------------------------------------------------------------------------------- |
+| npm       | `npm install`, `npm i`, `npm add`, `yarn add`, `pnpm add`, `bun add`                      |
+| PyPI      | `pip install`, `pip3 install`, `uv add`, `uv pip install`, `poetry add`, `pipenv install` |
+| Cargo     | `cargo add`, `cargo install`                                                              |
+| RubyGems  | `gem install`, `bundle add`                                                               |
+| Go        | `go get`, `go install`                                                                    |
+| NuGet     | `dotnet add package`, `nuget install`                                                     |
 
-If you want to contribute to the Socket MCP server development:
+### Setup
 
-### Health Check Endpoint
+**Prerequisites:** Node.js 22+.
 
-When running in HTTP mode, the server provides a health check endpoint for Kubernetes and Docker deployments:
+1. Copy the whole `socket-gate` directory into your hooks folder. The bundled
+   `socket-gate.cjs` is self-contained, so it runs without any dependencies
+   beside it. From a checkout, run `pnpm run build` first to produce it; from a
+   published install, copy from `node_modules/@socketsecurity/mcp/`:
 
 ```bash
-GET /health
+mkdir -p ~/.claude/hooks
+cp -R hooks/socket-gate ~/.claude/hooks/
 ```
 
-**Response:**
+2. Add to `~/.claude/settings.json`:
+
 ```json
 {
-  "status": "healthy",
-  "service": "socket-mcp",
-  "version": "0.0.3",
-  "timestamp": "2025-06-17T20:45:22.059Z"
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ~/.claude/hooks/socket-gate/socket-gate.cjs"
+          }
+        ]
+      }
+    ]
+  }
 }
 ```
 
-This endpoint can be used for:
-- Kubernetes liveness and readiness probes
-- Docker health checks
-- Load balancer health monitoring
-- General service monitoring
-
-
-#### Prerequisites
+See [`hooks/socket-gate/README.md`](hooks/socket-gate/README.md) for the full
+reference.
 
-- Node.js v16 or higher
-- npm or yarn
+### How it works
 
-#### Installation
+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.
 
-Clone the repository and install dependencies:
+### Limitations
 
-```bash
-git clone https://github.com/SocketDev/socket-mcp.git
-cd socket-mcp
-npm install
-```
+A best-effort guardrail, not a complete defense. Known gaps:
 
-#### Build
+- **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.
+- **Package-manager invocations only.** Direct downloads (`curl | sh`, `wget`), post-install scripts of already-accepted packages, and transitive dependencies are not re-checked.
+- **Indirect Claude paths.** Sub-agents, MCP tools that shell out, and non-`Bash` tool calls are not covered unless the `matcher` is broadened.
 
-This project is a directly runnable Node.js project using [Type stripping](https://nodejs.org/docs/latest/api/typescript.html).
-If you are on Node.js 22, run with `node --experimental-strip-types index.ts`.
-On any later versions of Node.js, you can simply run `node index.ts`.
-In either version you can also run the npm run scripts which include the correct flags.
+Inspired by [Jimmy Vo's dependency hook](https://blog.jimmyvo.com/posts/claudes-dependency-hook/).
 
-The js files will automatically be build when running `npm publish`, and cleaned up afterwards with `npm run clean`.
+## Development
 
-If you want to preview the build you can run:
+<details>
+<summary>Contributor commands</summary>
 
-```bash
+```sh
+git clone https://github.com/SocketDev/socket-mcp.git
+cd socket-mcp
+npm install
 npm run build
 ```
 
-#### Run from Source
-
-To run the Socket MCP server from source:
+Run from source (stdio mode):
 
-```bash
-export SOCKET_API_KEY=your_api_key_here
+```sh
+export SOCKET_API_TOKEN=your_api_token_here
 node --experimental-strip-types index.ts
 ```
 
 Or in HTTP mode:
 
-```bash
-MCP_HTTP_MODE=true SOCKET_API_KEY=your_api_key_here node --experimental-strip-types index.ts --http
+```sh
+MCP_HTTP_MODE=true SOCKET_API_TOKEN=your_api_token_here node --experimental-strip-types index.ts --http
 ```
 
-## 🔧 Troubleshooting
+### Health check endpoint
 
-### Common Issues
+When running in HTTP mode, `GET /health` returns:
 
-**Q: The public server isn't responding**
-- Check that you're using the correct URL: `https://mcp.socket.dev/`
-- Verify your MCP client configuration is correct
-- Try restarting your MCP client
+```json
+{
+  "status": "healthy",
+  "service": "socket-mcp",
+  "version": "0.0.3",
+  "timestamp": "2025-06-17T20:45:22.059Z"
+}
+```
+
+Suitable for Kubernetes liveness/readiness probes, Docker health checks, load balancers.
+
+### Troubleshooting
 
-**Q: Local server fails to start**
-- Ensure you have Node.js v16+ installed
-- Check that your `SOCKET_API_KEY` environment variable is set
-- Verify the API key has `packages:list` permission
+**Q: The public server isn't responding** — Check the URL `https://mcp.socket.dev/`, verify your MCP client configuration, restart your MCP client.
 
-**Q: Getting authentication errors with local server**
-- Double-check your Socket API key is valid
-- Ensure the key has the required `packages:list` scope
-- Try regenerating your API key from the Socket dashboard
+**Q: Local server fails to start** — Ensure Node.js v16+ is installed, check `SOCKET_API_TOKEN` is set, verify the API token has `packages:list` permission.
 
-**Q: AI assistant can't find the depscore tool**
-- Restart your MCP client after configuration changes
-- Verify the server configuration is saved correctly
-- Check that the MCP server is running (for local deployments)
+**Q: Getting authentication errors with local server** — Double-check your API key is valid, ensure `packages:list` scope, regenerate if needed.
 
-### Getting Help
+**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.
+
+### Getting help
 
 - 📖 [Socket Documentation](https://docs.socket.dev)
 - 🐛 [Report Issues](https://github.com/SocketDev/socket-mcp/issues)
 - 💬 [Community Support](https://github.com/SocketDev/socket-mcp/discussions)
 
+</details>
+
+## License
+
+MIT
+
 <br/>
 <div align="center">
   <picture>