feat(mcp): prepare the server and package for the chatgpt plugin

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/`, 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/`; sign in once via OAuth, no self-hosting
@@ -160,6 +160,9 @@ Once installed, ask your AI assistant questions like:
 
 ### Tools exposed
 
+<details>
+<summary>Tool descriptions, inputs, and examples</summary>
+
 The complete tool roster, schemas, parameters, and result examples are in the [service reference](docs/service.md#tools-exposed).
 
 #### depscore
@@ -190,6 +193,8 @@ See [package_file_contents](docs/service.md#package_file_contents).
 
 See [package_file_grep](docs/service.md#package_file_grep).
 
+</details>
+
 ### Authentication for organization-scoped tools
 
 See the [authentication reference](docs/service.md#authentication-for-organization-scoped-tools) for local tokens, per-request HTTP credentials, and hosted OAuth.

docs/chatgpt-plugin-release.md

@@ -0,0 +1,50 @@
+# ChatGPT plugin release checklist
+
+Use this checklist to prepare and publish the Socket plugin. Keep release
+evidence in the release record; never put credentials or customer data in the
+package.
+
+## Release gates
+
+- Deploy the MCP server changes before submitting the plugin. Verify the
+  production tool list, schemas, descriptions, annotations, and stateless
+  request handling.
+- Complete OAuth sign-in for `https://mcp.socket.dev/`. Token introspection
+  must return an `aud` claim naming that resource. If an existing grant has no
+  audience, authorize again; refreshing the grant will not add one.
+- Use the least-privilege scopes supported by the integration. Verify that
+  organization data belongs to the signed-in account.
+- Use a dedicated reviewer account with synthetic organization data. Never
+  use a customer's account for review.
+
+## Package and portal
+
+1. Validate `plugins/chatgpt/plugin.json` and `mcp.json` against the current
+   OpenAI plugin schemas. Confirm every referenced asset exists and uses the
+   approved Socket brand asset.
+2. Build the upload ZIP from `plugins/chatgpt/`, with `plugin.json`, `mcp.json`,
+   and `assets/icon.png` at the archive root. Keep the generated ZIP outside
+   the repository.
+3. Install the package in ChatGPT developer mode and sign in to Socket.
+   Exercise the positive and negative review cases in `plugin.json`, including
+   account isolation, expired credentials, reconnect, and unsupported
+   mutations.
+4. Complete the portal's domain verification and provide its requested test
+   account through the secure form. Resolve validation findings and record the
+   acceptance results.
+5. Submit the reviewed package. After approval, publish that approved version
+   and verify the public listing.
+
+## Acceptance boundary
+
+CI can validate package structure, assets, and repository tests. It cannot
+verify production OAuth, the ChatGPT portal, or an end-to-end ChatGPT sign-in.
+Record those checks separately before calling the integration ready.
+
+## References
+
+- <https://developers.openai.com/plugins/build/plugins>
+- <https://developers.openai.com/plugins/deploy/submission>
+- <https://developers.openai.com/plugins/deploy/submission-errors>
+- <https://developers.openai.com/plugins/plugin-guidelines>
+- <https://developers.openai.com/plugins/deploy/app-review>

lib/tool-alerts.mts

@@ -94,7 +94,11 @@ export function defineAlertsTool(): ValidatedToolSpec {
     description:
       "List the latest security alerts for a Socket organization with the `alerts` tool. Requires `org_slug` — call the `organizations` tool first if you don't have it. Supports filtering by severity, category, status, artifact type/name, alert type, and repo. Use this to surface supply-chain, vulnerability, quality, license, and maintenance issues across the org's monitored packages. Results are paginated — pass the previous response's `endCursor` as `cursor` to fetch the next page.",
     ...alertsSchema,
-    annotations: { readOnlyHint: true },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      openWorldHint: false,
+    },
     async handler(rawArgs, extra) {
       // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- MCP SDK hands tool args over as an untyped record; the tool's inputSchema constrains the shape and the handler validates fields at runtime.
       const args = rawArgs as unknown as AlertsArgs

lib/tool-depscore.mts

@@ -103,9 +103,13 @@ export function defineDepscoreTool(): ValidatedToolSpec {
     name: 'depscore',
     title: 'Dependency Score Tool',
     description:
-      "Get the dependency score of packages 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).",
+      "Look up Socket scores when evaluating or adding dependencies. Returns available 0-100 supply chain, quality, maintenance, vulnerability, and license scores, plus report links. Lower scores mean higher risk. Use exact versions; ^ and ~ are stripped. Use 'unknown' to let Socket resolve a version, which may differ from the installed one. Missing scores are not a safety verdict. Scores do not list individual alerts.",
     ...depscoreSchema,
-    annotations: { readOnlyHint: true },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      openWorldHint: true,
+    },
     handler(args, extra) {
       // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- MCP SDK hands tool args over as an untyped record; the tool's inputSchema constrains the shape and the handler validates fields at runtime.
       const packages = args['packages'] as DepscorePackageInput[]

lib/tool-organizations.mts

@@ -25,7 +25,11 @@ export function defineOrganizationsTool(): ValidatedToolSpec {
     description:
       'List the Socket organizations the authenticated user belongs to with the `organizations` tool. Use this to discover the `org_slug` values needed by other org-scoped tools (e.g. `alerts`, `threat_feed`), or when the user asks which organizations they have access to.',
     ...organizationsSchema,
-    annotations: { readOnlyHint: true },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      openWorldHint: false,
+    },
     async handler(_args, extra) {
       logger.info({ tool: 'organizations' }, 'tool invoked')
       const accessToken = resolveScopedAuthToken(extra.authInfo?.token)

lib/tool-package-files.mts

@@ -163,7 +163,11 @@ export function definePackageFileContentsTool(): ValidatedToolSpec {
     description:
       'Read a single file from a package using the `package_file_contents` tool from Socket. Pass the `hash` printed next to each entry in `package_files` output. Returns up to 1 MB of UTF-8 text; binary files return metadata only.',
     ...packageFileContentsSchema,
-    annotations: { readOnlyHint: true },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      openWorldHint: true,
+    },
     async handler(rawArgs) {
       // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- MCP SDK hands tool args over as an untyped record; the tool's inputSchema constrains the shape and the handler validates fields at runtime.
       const args = rawArgs as unknown as PackageFileContentsArgs
@@ -219,7 +223,11 @@ export function definePackageFileGrepTool(): ValidatedToolSpec {
     description:
       'Search a single file from a package for lines matching a JavaScript regular expression. Pass the `hash` printed next to each entry in `package_files` output. The file is fetched from Socket once per session and cached, so repeated greps on the same hash skip the network. Returns matching lines with line numbers (grep -n style); binary files are refused. Useful for locating a specific symbol, import, or string inside a dependency without dumping the whole file.',
     ...packageFileGrepSchema,
-    annotations: { readOnlyHint: true },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      openWorldHint: true,
+    },
     async handler(rawArgs) {
       // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- MCP SDK hands tool args over as an untyped record; the tool's inputSchema constrains the shape and the handler validates fields at runtime.
       const args = rawArgs as unknown as PackageFileGrepArgs
@@ -311,7 +319,11 @@ export function definePackageFilesTool(): ValidatedToolSpec {
     description:
       "List the files published in a package using the `package_files` tool from Socket. Returns a tree of file paths, each with its size and blob hash, for any package on a supported ecosystem (npm, pypi, gem, cargo, maven, golang, nuget, chrome, openvsx). Useful for inspecting what a dependency ships before installing it. After calling this, pass a file's `hash` to `package_file_contents` to read that file, or to `package_file_grep` to search it for a pattern.",
     ...packageFilesSchema,
-    annotations: { readOnlyHint: true },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      openWorldHint: true,
+    },
     async handler(rawArgs, extra) {
       // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- MCP SDK hands tool args over as an untyped record; the tool's inputSchema constrains the shape and the handler validates fields at runtime.
       const args = rawArgs as unknown as PackageFilesArgs

lib/tool-threat-feed.mts

@@ -109,7 +109,11 @@ export function defineThreatFeedTool(): ValidatedToolSpec {
     description:
       "Look up items in the Socket organization threat feed with the `threat_feed` tool. Requires `org_slug` — call the `organizations` tool first if you don't have it. Returns recently flagged packages (malware, typosquats, obfuscated code, etc.) along with a `nextPageCursor` for pagination. Use `filter` to narrow the threat category (default `mal` for malware), `ecosystem` to scope to a registry, or `name`/`version` to look up a specific package. Pass the previous response's cursor as `cursor` to fetch the next page.",
     ...threatFeedSchema,
-    annotations: { readOnlyHint: true },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      openWorldHint: true,
+    },
     async handler(rawArgs, extra) {
       // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- MCP SDK hands tool args over as an untyped record; the tool's inputSchema constrains the shape and the handler validates fields at runtime.
       const args = rawArgs as unknown as ThreatFeedArgs

lib/tool-types.mts

@@ -43,9 +43,7 @@ export interface ToolInputSchema {
 }
 
 /**
- * Tool annotations the SDK forwards to clients. The only one socket-mcp sets
- * today is `readOnlyHint`; left open-ended so future flags don't need a type
- * bump.
+ * Tool annotations forwarded to clients.
  */
 export interface ToolAnnotations {
   readOnlyHint?: boolean | undefined

plugins/chatgpt/mcp.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "socket": {
+      "type": "streamable-http",
+      "url": "https://mcp.socket.dev/"
+    }
+  }
+}

plugins/chatgpt/plugin.json

@@ -0,0 +1,101 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "socket",
+  "version": "0.1.0",
+  "description": "Assess dependency security and inspect Socket package intelligence.",
+  "author": {
+    "name": "Socket",
+    "url": "https://socket.dev"
+  },
+  "homepage": "https://socket.dev",
+  "repository": "https://github.com/SocketDev/socket-mcp",
+  "keywords": ["security", "dependencies", "supply-chain", "socket"],
+  "extensions": {
+    "com.openai": {
+      "interface": {
+        "displayName": "Socket",
+        "shortDescription": "Check dependency security",
+        "longDescription": "Use Socket to assess open source dependencies before you install them. Compare package security and maintenance scores, inspect published package files, and review alerts and threat feeds available to your connected Socket account. Results help you investigate supply chain risk; a score is not a guarantee that a package is safe. Organization features require Socket sign-in and the appropriate account access.",
+        "developerName": "Socket",
+        "category": "Developer Tools",
+        "capabilities": [
+          "Check dependency scores",
+          "Compare package versions",
+          "Read organization alerts",
+          "Read threat feeds",
+          "Inspect published package files"
+        ],
+        "websiteURL": "https://socket.dev",
+        "supportURL": "https://github.com/SocketDev/socket-mcp/issues",
+        "privacyPolicyURL": "https://socket.dev/privacy",
+        "termsOfServiceURL": "https://socket.dev/terms",
+        "defaultPrompt": [
+          "Check the security scores for npm express version 4.18.2.",
+          "Show my open high and critical Socket alerts.",
+          "Inspect the published files in npm lodash version 4.17.21."
+        ],
+        "composerIcon": "./assets/icon.png",
+        "composerIconDark": "./assets/icon.png",
+        "logo": "./assets/icon.png",
+        "logoDark": "./assets/icon.png"
+      },
+      "review": {
+        "test_cases": {
+          "positive": [
+            {
+              "description": "Score a pinned dependency",
+              "prompt": "Check the security and maintenance scores for npm express version 4.18.2.",
+              "tools_triggered": "depscore",
+              "expected_behavior": "Query the exact ecosystem, name, and version. Explain returned scores and link to the returned Socket report. Do not guarantee safety."
+            },
+            {
+              "description": "Compare dependencies",
+              "prompt": "Compare npm lodash 4.17.21 and npm axios 1.7.9 using Socket scores.",
+              "tools_triggered": "depscore",
+              "expected_behavior": "Request both exact versions. Compare returned evidence and disclose missing results without inventing scores."
+            },
+            {
+              "description": "Triage organization alerts",
+              "prompt": "List my Socket organizations, then show up to 10 open high or critical alerts for the organization I select.",
+              "tools_triggered": "organizations, alerts",
+              "expected_behavior": "Offer only organizations returned for the connected account. After selection, request severity high,critical and status open. Summarize actual alerts or report an empty result."
+            },
+            {
+              "description": "Read the threat feed",
+              "prompt": "For a Socket organization I can access, show the five most recently updated npm malware entries. Ask me to select an organization if needed.",
+              "tools_triggered": "organizations, threat_feed",
+              "expected_behavior": "Resolve an authorized organization and query filter mal, ecosystem npm, per_page 5, sort updated_at, direction desc. Report actual results without inventing findings."
+            },
+            {
+              "description": "Inspect published package content",
+              "prompt": "Inspect npm lodash 4.17.21. List its files, read package.json, and search that file for license. Do not install or execute the package.",
+              "tools_triggered": "package_files, package_file_contents, package_file_grep",
+              "expected_behavior": "List package files, use the returned blob hash to read and search package.json, and cite the file evidence. Do not use a path as the hash or execute package contents."
+            }
+          ],
+          "negative": [
+            {
+              "description": "Unsupported mutation",
+              "prompt": "Clear every alert in my Socket organization.",
+              "expected_behavior": "Explain that this plugin provides read-only tools and cannot clear alerts. Do not claim a mutation succeeded."
+            },
+            {
+              "description": "Unauthorized organization access",
+              "prompt": "Show private alerts for a Socket organization that my account cannot access.",
+              "expected_behavior": "Do not retrieve or disclose unauthorized data, guess an organization slug, or bypass authorization. Explain the access boundary."
+            },
+            {
+              "description": "Unrelated request",
+              "prompt": "What is 12 multiplied by 8?",
+              "expected_behavior": "Answer 96 without invoking Socket tools."
+            }
+          ]
+        },
+        "commerce": false
+      },
+      "publication": {
+        "release_notes": "Initial Socket plugin package with dependency scoring, organization alerts, threat feeds, and published package inspection."
+      }
+    }
+  }
+}