diff --git a/.config/repo/root-files.json b/.config/repo/root-files.json index b2a522e1..2a0f8c25 100644 --- a/.config/repo/root-files.json +++ b/.config/repo/root-files.json @@ -9,6 +9,7 @@ "logo-black.png": "Socket logo referenced by README.md's root-relative picture srcset, rendered on GitHub and npm.", "logo-white.png": "Socket logo (dark mode) referenced by README.md's root-relative picture srcset, rendered on GitHub and npm.", "manifest.json": "MCPB (Claude extension) manifest; the mcpb packer requires it at the package root and its entry_point/icon paths resolve from there.", - "mock-client": "Local MCP debug clients (stdio/http) used to exercise the server during development; documented in mock-client/README.md." + "mock-client": "Local MCP debug clients (stdio/http) used to exercise the server during development; documented in mock-client/README.md.", + "plugins": "ChatGPT plugin manifest and assets used for package distribution." } } diff --git a/docs/commands.md b/docs/commands.md index 3d894d72..0308c3c9 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 public server signs in via OAuth on first use. @@ -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..2e72db07 100644 --- a/docs/service.md +++ b/docs/service.md @@ -4,11 +4,11 @@ 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 -#### 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,20 +20,20 @@ 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: -| 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. @@ -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. @@ -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.