From 436865d5458794f59ea2b8a4a44b97f82ca33cb6 Mon Sep 17 00:00:00 2001 From: Vasco Santos Date: Thu, 1 Oct 2026 15:02:08 +0200 Subject: [PATCH 1/8] docs(readme): clarify hosted MCP client sign-in --- README.md | 34 ++++++++++++++++++++++++++++++++-- 1 file changed, 32 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b4742607..a23dec61 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ Connect your MCP client to the hosted server at `https://mcp.socket.dev/`, or ru ### Option 1: Use the public Socket MCP server (recommended) -The public server uses OAuth. Your MCP client opens a browser to sign in to Socket on first connection. You do not need an API key. +The public server supports anonymous package scoring. Organization tools require Socket sign-in through OAuth; some MCP clients need an explicit sign-in step. You do not need an API key. - [Install in VS Code](https://vscode.dev/redirect/mcp/install?name=socket-mcp&config=%7B%22url%22%3A%22https%3A%2F%2Fmcp.socket.dev%2F%22%2C%22type%22%3A%22http%22%7D). - [Install in Cursor](https://cursor.com/en/install-mcp?name=socket-mcp&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vbWNwLnNvY2tldC5kZXYvIn0%3D). @@ -39,12 +39,42 @@ Add the hosted server through Claude's [custom connector settings](https://suppo 3. Select **Connect** and complete the Socket authorization flow when prompted. 4. Enable the connector for your conversation, then ask Claude "Check the security score for express version 4.18.2". -For Claude Code, one command does all of it: +For Claude Code, add the server: ```sh claude mcp add --transport http socket-mcp https://mcp.socket.dev/ ``` +Then run `/mcp`, select `socket-mcp`, choose **Authenticate** (or **Re-authenticate**, if shown), and approve access in your browser. An "authenticated" status before sign-in does not mean organization tools are ready. + + + +
Manual install - Codex CLI + +Add the server: + +```sh +codex mcp add socket-mcp --url https://mcp.socket.dev/ +``` + +Codex starts sign-in during this command. You may see an `invalid_scope` page before Codex automatically retries with the three MCP read permissions. Complete the browser authorization on the retry. + +To avoid that initial error page, you can instead add the server directly to `~/.codex/config.toml`: + +```toml +[mcp_servers.socket-mcp] +url = "https://mcp.socket.dev/" +scopes = ["packages:list", "alerts:list", "threat-feed:list"] +``` + +Then run: + +```sh +codex mcp login socket-mcp +``` + +Keep the `scopes` setting for later sign-ins. Running `codex mcp add` again replaces this server entry and removes the setting. With dynamic client registration, each sign-in creates a new OAuth client with Socket. +
Manual install - VS Code From c022f3f93011e3e0c9010cae3a94abb0f364a0dd Mon Sep 17 00:00:00 2001 From: Vasco Santos Date: Fri, 2 Oct 2026 12:43:29 +0200 Subject: [PATCH 2/8] docs(readme): limit Codex lifecycle claims to verified steps --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a23dec61..4ac885fe 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ Then run: codex mcp login socket-mcp ``` -Keep the `scopes` setting for later sign-ins. Running `codex mcp add` again replaces this server entry and removes the setting. With dynamic client registration, each sign-in creates a new OAuth client with Socket. +With dynamic client registration, each sign-in creates a new OAuth client with Socket.
From 7e288087647f41df505dd933091d4738d5381647 Mon Sep 17 00:00:00 2001 From: Vasco Santos Date: Mon, 5 Oct 2026 09:09:39 +0200 Subject: [PATCH 3/8] docs(readme): add tested client compatibility matrix (#220) * docs(readme): add tested client compatibility matrix * docs(readme): move compatibility section to end --- README.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4ac885fe..5c41410d 100644 --- a/README.md +++ b/README.md @@ -13,9 +13,9 @@ Connect your MCP client to the hosted server at `https://mcp.socket.dev/`, or ru ### โœจ Features - ๐Ÿ” **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/`; sign in once via OAuth, no self-hosting +- ๐ŸŒ **Public Hosted Service** - Use our public server at `https://mcp.socket.dev/`; package scoring is anonymous and organization tools use OAuth - ๐Ÿš€ **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 +- ๐Ÿค– **AI Assistant Integration** - Connect from MCP-compatible clients; OAuth behavior varies by client - ๐Ÿ“Š **Batch Processing** - Check multiple dependencies in a single request - ๐Ÿ”’ **OAuth Sign-In** - Public server authenticates through your MCP client's OAuth flow; no API key to copy or manage @@ -298,6 +298,22 @@ See [service troubleshooting](docs/service.md#troubleshooting). +## Compatibility + +MCP is still evolving, and client implementations differ in how they handle parts of the protocol. We proactively track compatibility gaps and work to offer the best possible experience with Claude Code, Codex, Cursor, and Zed. The table below summarizes the latest tests and known gaps. + +Snapshot dated October 2, 2026; tests ran September 29โ€“October 1. Each result applies to the listed client version and setup. + +| Client and tested setup | Hosted OAuth result | Verified tools and continuity | Important limit or workaround | +| --- | --- | --- | --- | +| Claude Code 2.1.285, hosted HTTP | First `organizations` call failed with a sign-in request; explicit OAuth then completed. | The 2.1.285 run verified the initial failure and successful login. `organizations` and `depscore` passed after login in a separate 2.1.284 run. | The pre-login โ€œauthenticatedโ€ label was misleading; see [upstream issue #98942](https://github.com/anthropics/claude-code/issues/98942). | +| Codex CLI 0.159.2, hosted HTTP | Works after explicit login. | `organizations` and `depscore` passed after login, including a new conversation and idle checks. | A broad scope request showed `invalid_scope` before Codex retried with the three MCP read permissions; see [upstream issue #15643](https://github.com/openai/codex/issues/15643). | +| Cursor 3.22.12, hosted HTTP OAuth | Fails in tested conditions: `organizations` remained Unauthorized; the Authenticate card did not establish access. | `organizations` only; no successful hosted OAuth call verified. | Cursor 3.20 recurrence was manually reported; no fix version is known. [A related forum reply](https://forum.cursor.com/t/plugin-mcp-oauth-never-reaches-needsauth-authenticate-button-missing-browser-never-opens/170058/8) describes an unsuccessful workaround attempt but identifies a separate Cursor 3.18.9 marketplace-import blocker. | +| Cursor, local stdio with API token (version not recorded) | Not applicable; this setup bypasses hosted OAuth. | `depscore` passed; restart continuity was reported manually. | This does not verify hosted OAuth, `organizations`, or other tools. | +| Zed Agent 1.22.0, hosted HTTP | Works after explicit OAuth. | `organizations` and `depscore` passed after login, restart, and a six-minute idle check. | Intermittent timeouts after idle, cause under investigation; four client timeouts matched fast server HTTP 400 responses. | + +Only `organizations` and `depscore` were tested. Token refresh, server-side revocation, and all-tool coverage were not tested. Claude Desktop, VS Code, Windsurf, and Factory were not tested in this matrix. + ## License MIT From ee95f00e8fdf09f94c6853aa81077b124ea8a921 Mon Sep 17 00:00:00 2001 From: Vasco Santos Date: Tue, 13 Oct 2026 10:24:27 +0200 Subject: [PATCH 4/8] docs(readme): clarify hosted OAuth requirement --- README.md | 8 ++++---- docs/commands.md | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 5c41410d..65179434 100644 --- a/README.md +++ b/README.md @@ -8,12 +8,12 @@ Socket MCP lets AI assistants query Socket's dependency security scores and metadata through the Model Context Protocol (MCP). Use it to score a package, audit a `package.json`, or identify risky dependencies in a conversation. -Connect your MCP client to the hosted server at `https://mcp.socket.dev/`, or run the npm package yourself. +Connect your MCP client to the hosted server at `https://mcp.socket.dev/` and authenticate through OAuth, or run the npm package yourself. ### โœจ Features - ๐Ÿ” **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/`; package scoring is anonymous and organization tools use OAuth +- ๐ŸŒ **Public Hosted Service** - Use our public server at `https://mcp.socket.dev/` and sign in through your MCP client's OAuth flow - ๐Ÿš€ **Multiple Deployment Options** - Run locally via stdio, HTTP, or use our service - ๐Ÿค– **AI Assistant Integration** - Connect from MCP-compatible clients; OAuth behavior varies by client - ๐Ÿ“Š **Batch Processing** - Check multiple dependencies in a single request @@ -25,7 +25,7 @@ Connect your MCP client to the hosted server at `https://mcp.socket.dev/`, or ru ### Option 1: Use the public Socket MCP server (recommended) -The public server supports anonymous package scoring. Organization tools require Socket sign-in through OAuth; some MCP clients need an explicit sign-in step. You do not need an API key. +The public server requires Socket sign-in through OAuth for every tool call, including package scoring. Some MCP clients need an explicit sign-in step. You do not need an API key. - [Install in VS Code](https://vscode.dev/redirect/mcp/install?name=socket-mcp&config=%7B%22url%22%3A%22https%3A%2F%2Fmcp.socket.dev%2F%22%2C%22type%22%3A%22http%22%7D). - [Install in Cursor](https://cursor.com/en/install-mcp?name=socket-mcp&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vbWNwLnNvY2tldC5kZXYvIn0%3D). @@ -220,7 +220,7 @@ See [package_file_contents](docs/service.md#package_file_contents). See [package_file_grep](docs/service.md#package_file_grep). -### Authentication for organization-scoped tools +### Authentication See the [authentication reference](docs/service.md#authentication-for-organization-scoped-tools) for local tokens, per-request HTTP credentials, and hosted OAuth. diff --git a/docs/commands.md b/docs/commands.md index 3d894d72..fedd6666 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -158,7 +158,7 @@ Configure your MCP client to connect to the HTTP server: ## 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 CLI to install - copy the file and wire it up; the public server signs in via OAuth on first use. +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 hook does not configure or initiate OAuth. Supported ecosystems and package managers: From b6b454f602116c7842fc11fb0951116d808f05b1 Mon Sep 17 00:00:00 2001 From: jdalton Date: Tue, 13 Oct 2026 22:27:00 -0400 Subject: [PATCH 5/8] docs: fix MCP documentation gate Fold the README tool links and format the docs checked by CI. Assisted-by: Codex:GPT-6 --- README.md | 18 +++++++++++------- docs/commands.md | 16 +++++++--------- docs/service.md | 21 ++++++++++----------- 3 files changed, 28 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 65179434..2634fcab 100644 --- a/README.md +++ b/README.md @@ -192,6 +192,8 @@ Once installed, ask your AI assistant questions like: The complete tool roster, schemas, parameters, and result examples are in the [service reference](docs/service.md#tools-exposed). +
Tool quick links + #### depscore See [depscore](docs/service.md#depscore). @@ -220,6 +222,8 @@ See [package_file_contents](docs/service.md#package_file_contents). See [package_file_grep](docs/service.md#package_file_grep). +
+ ### Authentication See the [authentication reference](docs/service.md#authentication-for-organization-scoped-tools) for local tokens, per-request HTTP credentials, and hosted OAuth. @@ -304,13 +308,13 @@ MCP is still evolving, and client implementations differ in how they handle part Snapshot dated October 2, 2026; tests ran September 29โ€“October 1. Each result applies to the listed client version and setup. -| Client and tested setup | Hosted OAuth result | Verified tools and continuity | Important limit or workaround | -| --- | --- | --- | --- | -| Claude Code 2.1.285, hosted HTTP | First `organizations` call failed with a sign-in request; explicit OAuth then completed. | The 2.1.285 run verified the initial failure and successful login. `organizations` and `depscore` passed after login in a separate 2.1.284 run. | The pre-login โ€œauthenticatedโ€ label was misleading; see [upstream issue #98942](https://github.com/anthropics/claude-code/issues/98942). | -| Codex CLI 0.159.2, hosted HTTP | Works after explicit login. | `organizations` and `depscore` passed after login, including a new conversation and idle checks. | A broad scope request showed `invalid_scope` before Codex retried with the three MCP read permissions; see [upstream issue #15643](https://github.com/openai/codex/issues/15643). | -| Cursor 3.22.12, hosted HTTP OAuth | Fails in tested conditions: `organizations` remained Unauthorized; the Authenticate card did not establish access. | `organizations` only; no successful hosted OAuth call verified. | Cursor 3.20 recurrence was manually reported; no fix version is known. [A related forum reply](https://forum.cursor.com/t/plugin-mcp-oauth-never-reaches-needsauth-authenticate-button-missing-browser-never-opens/170058/8) describes an unsuccessful workaround attempt but identifies a separate Cursor 3.18.9 marketplace-import blocker. | -| Cursor, local stdio with API token (version not recorded) | Not applicable; this setup bypasses hosted OAuth. | `depscore` passed; restart continuity was reported manually. | This does not verify hosted OAuth, `organizations`, or other tools. | -| Zed Agent 1.22.0, hosted HTTP | Works after explicit OAuth. | `organizations` and `depscore` passed after login, restart, and a six-minute idle check. | Intermittent timeouts after idle, cause under investigation; four client timeouts matched fast server HTTP 400 responses. | +| Client and tested setup | Hosted OAuth result | Verified tools and continuity | Important limit or workaround | +| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Claude Code 2.1.285, hosted HTTP | First `organizations` call failed with a sign-in request; explicit OAuth then completed. | The 2.1.285 run verified the initial failure and successful login. `organizations` and `depscore` passed after login in a separate 2.1.284 run. | The pre-login โ€œauthenticatedโ€ label was misleading; see [upstream issue #98942](https://github.com/anthropics/claude-code/issues/98942). | +| Codex CLI 0.159.2, hosted HTTP | Works after explicit login. | `organizations` and `depscore` passed after login, including a new conversation and idle checks. | A broad scope request showed `invalid_scope` before Codex retried with the three MCP read permissions; see [upstream issue #15643](https://github.com/openai/codex/issues/15643). | +| Cursor 3.22.12, hosted HTTP OAuth | Fails in tested conditions: `organizations` remained Unauthorized; the Authenticate card did not establish access. | `organizations` only; no successful hosted OAuth call verified. | Cursor 3.20 recurrence was manually reported; no fix version is known. [A related forum reply](https://forum.cursor.com/t/plugin-mcp-oauth-never-reaches-needsauth-authenticate-button-missing-browser-never-opens/170058/8) describes an unsuccessful workaround attempt but identifies a separate Cursor 3.18.9 marketplace-import blocker. | +| Cursor, local stdio with API token (version not recorded) | Not applicable; this setup bypasses hosted OAuth. | `depscore` passed; restart continuity was reported manually. | This does not verify hosted OAuth, `organizations`, or other tools. | +| Zed Agent 1.22.0, hosted HTTP | Works after explicit OAuth. | `organizations` and `depscore` passed after login, restart, and a six-minute idle check. | Intermittent timeouts after idle, cause under investigation; four client timeouts matched fast server HTTP 400 responses. | Only `organizations` and `depscore` were tested. Token refresh, server-side revocation, and all-tool coverage were not tested. Claude Desktop, VS Code, Windsurf, and Factory were not tested in this matrix. diff --git a/docs/commands.md b/docs/commands.md index fedd6666..86a59dae 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -155,7 +155,6 @@ Configure your MCP client to connect to the HTTP server: - ## 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 CLI to install - copy the file and wire it up. The hook does not configure or initiate OAuth. @@ -235,17 +234,16 @@ A best-effort guardrail, not a complete defense. Known gaps: Inspired by [Jimmy Vo's dependency hook](https://blog.jimmyvo.com/posts/claudes-dependency-hook/). - ## Development commands From the repository root with Node.js 24 or later: -| Task | Command | -| --- | --- | -| Run the stdio server from source | `pnpm run server-stdio` | -| Run the HTTP server from source | `pnpm run server-http` | -| Enable request tracing | Add `:debug` to either server script | -| Build the package | `pnpm run build` | -| Check the registered MCP schema | `pnpm run mcp:schema:check` | +| Task | Command | +| -------------------------------- | ------------------------------------ | +| Run the stdio server from source | `pnpm run server-stdio` | +| Run the HTTP server from source | `pnpm run server-http` | +| Enable request tracing | Add `:debug` to either server script | +| Build the package | `pnpm run build` | +| Check the registered MCP schema | `pnpm run mcp:schema:check` | Both server scripts read `SOCKET_API_TOKEN`, falling back to `SOCKET_API_KEY`. Debug scripts set `SOCKET_DEBUG=1` and write request traces to stderr. See [mock-client debugging](mock-client-debugging.md) for sending requests to a local server. diff --git a/docs/service.md b/docs/service.md index be35c54a..25bd5079 100644 --- a/docs/service.md +++ b/docs/service.md @@ -24,16 +24,16 @@ Query the Socket API for dependency scores. The result formats the available sco The `ecosystem` value is used as a PURL type. Common values listed in the input schema are: -| Ecosystem | PURL type | -| --- | --- | -| JavaScript and TypeScript | `npm` | -| Python | `pypi` | -| Go | `golang` | -| Java, Scala, and Kotlin | `maven` | -| Ruby | `gem` | -| .NET | `nuget` | -| Rust | `cargo` | -| PHP | `composer` | +| Ecosystem | PURL type | +| ------------------------- | ---------- | +| JavaScript and TypeScript | `npm` | +| Python | `pypi` | +| Go | `golang` | +| Java, Scala, and Kotlin | `maven` | +| Ruby | `gem` | +| .NET | `nuget` | +| Rust | `cargo` | +| PHP | `composer` | `packagist` is accepted as an alias for `composer`, and `openvsx` for the `vscode` PURL type. @@ -220,7 +220,6 @@ Example rule: 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. ``` - ## HTTP service behavior The HTTP transport serves MCP requests at `/`, answers `GET /health` with the running version, and returns `404` for other paths. It is stateless: each request is self-contained. `GET` and `DELETE` on `/` return `405`. Requests with an `Origin` header are checked against the request host; health probes do not need an `Origin` header. From d0dbeb4866413f55554f430505070032d2b3cff1 Mon Sep 17 00:00:00 2001 From: jdalton Date: Tue, 13 Oct 2026 22:28:39 -0400 Subject: [PATCH 6/8] docs: fix MCP heading hierarchy Nest headings consistently in the README and service reference. Assisted-by: Codex:GPT-6 --- README.md | 2 +- docs/service.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2634fcab..f9c399f9 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Socket MCP lets AI assistants query Socket's dependency security scores and meta Use it to score a package, audit a `package.json`, or identify risky dependencies in a conversation. Connect your MCP client to the hosted server at `https://mcp.socket.dev/` and authenticate through OAuth, or run the npm package yourself. -### โœจ Features +## โœจ Features - ๐Ÿ” **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/` and sign in through your MCP client's OAuth flow diff --git a/docs/service.md b/docs/service.md index 25bd5079..72bc49c7 100644 --- a/docs/service.md +++ b/docs/service.md @@ -4,7 +4,7 @@ Socket MCP exposes a stateless MCP server over stdio or HTTP. Its hosted deploym The server registers the tools in `lib/server.mts`; schemas and handlers are defined in the corresponding `lib/tool-*.mts` modules. The tables below list the current tool inputs. See [the command reference](commands.md) for launch modes, environment variables, and self-hosting setup. -### Tools exposed +## Tools exposed
The full tool roster - names, arguments, and what each returns From fa47c12132686a38ac42d81d87975360abbc5849 Mon Sep 17 00:00:00 2001 From: jdalton Date: Tue, 13 Oct 2026 22:29:04 -0400 Subject: [PATCH 7/8] docs: fix tool heading levels Keep tool headings nested under the service reference section. Assisted-by: Codex:GPT-6 --- docs/service.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/service.md b/docs/service.md index 72bc49c7..2e72db07 100644 --- a/docs/service.md +++ b/docs/service.md @@ -8,7 +8,7 @@ The server registers the tools in `lib/server.mts`; schemas and handlers are def
The full tool roster - names, arguments, and what each returns -#### depscore +### depscore Query the Socket API for dependency scores. The result formats the available score components and includes a Socket report URL when the record has an overall score. Records without an overall score are labeled `No score found`. @@ -20,7 +20,7 @@ Query the Socket API for dependency scores. The result formats the available sco | `packages[].version` | String | No | `"unknown"` | Version of the dependency | | `platform` | String | No | - | OS-architecture hint (`linux-x64`, `darwin-arm64`, `win32-x64`) applied to every package in the request. Picks the most relevant artifact when a package ships platform-specific builds. | -##### Supported ecosystems +#### Supported ecosystems The `ecosystem` value is used as a PURL type. Common values listed in the input schema are: @@ -59,7 +59,7 @@ pkg:pypi/@: No score found The API response determines which package records appear. Compare the result with the request when you need to confirm that each requested package had a matching record. -#### organizations +### organizations 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. @@ -80,7 +80,7 @@ The response is the Socket API's JSON, keyed by organization id. The `slug` is w } ``` -#### alerts +### alerts 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. @@ -97,7 +97,7 @@ List the latest security alerts for one Socket organization: supply-chain, vulne | `per_page` | Integer | No | `100` | Results per page (1โ€“5000) | | `cursor` | String | No | - | Pagination cursor - the `endCursor` from a previous response | -#### threat_feed +### threat_feed 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. @@ -116,7 +116,7 @@ Look up items in a Socket organization's threat feed: packages recently flagged | `per_page` | Integer | No | `30` | Results per page (1โ€“100) | | `cursor` | String | No | - | Pagination cursor - the `nextPageCursor` from a previous response | -#### package_files +### package_files List the files published in a package: a tree of file paths, each with its size and blob hash, for any package on a supported ecosystem. Use it to inspect what a dependency ships before installing it. Pass a file's `hash` to `package_file_contents` or `package_file_grep`. @@ -137,7 +137,7 @@ pkg:npm/@ - files, KB โ”‚ โ”œโ”€โ”€ ``` -#### package_file_contents +### package_file_contents 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. @@ -146,7 +146,7 @@ Read a single file from a package. Pass the `hash` printed next to an entry in ` | `hash` | String | โœ… Yes | - | Blob hash from `package_files` | | `path` | String | No | - | File path, for display only; does not affect the lookup | -#### package_file_grep +### package_file_grep Search a single file from a package for lines matching a JavaScript regular expression, returning matches with line numbers (grep -n style). Each blob is fetched once and held in a process-wide cache, so repeated reads and greps of the same hash skip the network. From c72a920b890773e5f3f98cfb6c6c9507a29dffea Mon Sep 17 00:00:00 2001 From: jdalton Date: Tue, 13 Oct 2026 22:38:51 -0400 Subject: [PATCH 8/8] docs: fold long service section Keep the tool schema examples readable in the service guide. Assisted-by: Codex:GPT-6 --- docs/service.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/service.md b/docs/service.md index 2e72db07..4da4032f 100644 --- a/docs/service.md +++ b/docs/service.md @@ -6,10 +6,10 @@ The server registers the tools in `lib/server.mts`; schemas and handlers are def ## Tools exposed -
The full tool roster - names, arguments, and what each returns - ### depscore +
Inputs and examples + Query the Socket API for dependency scores. The result formats the available score components and includes a Socket report URL when the record has an overall score. Records without an overall score are labeled `No score found`. | Parameter | Type | Required | Default | Description | @@ -59,6 +59,8 @@ pkg:pypi/@: No score found The API response determines which package records appear. Compare the result with the request when you need to confirm that each requested package had a matching record. +
+ ### organizations 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. @@ -159,8 +161,6 @@ Search a single file from a package for lines matching a JavaScript regular expr | `maxMatches` | Integer | No | `100` | Cap on matching lines returned (1โ€“500) | | `path` | String | No | - | File path, for display only; does not affect the lookup | -
- ### Authentication for organization-scoped tools The tools that call the Socket API need credentials. `depscore`, `organizations`, `alerts`, `threat_feed`, and `package_files` use a Socket API token. `package_file_contents` and `package_file_grep` use a blob hash and do not take a token.