Skip to content

Repository navigation

fix: satisfy ChatGPT plugin CI checks #224

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
John-David Dalton (jdalton) wants to merge 1 commit into
base: chatgpt-plugin-prep
Choose a base branch
from
Open

fix: satisfy ChatGPT plugin CI checks #224

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .config/repo/root-files.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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."
}
}
16 changes: 7 additions & 9 deletions docs/commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,6 @@ Configure your MCP client to connect to the HTTP server:

</details>


## 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.
Expand Down Expand Up @@ -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.
39 changes: 19 additions & 20 deletions docs/service.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

<details><summary>The full tool roster - names, arguments, and what each returns</summary>

#### 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`.

Expand All @@ -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.

Expand All @@ -59,7 +59,7 @@ pkg:pypi/<package>@<version>: 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.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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`.

Expand All @@ -137,7 +137,7 @@ pkg:npm/<package>@<version> - <file-count> files, <size> KB
│ ├── <file-name> <size> <blob-hash>
```

#### 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.

Expand All @@ -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.

Expand Down Expand Up @@ -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.
Expand Down