soup-chop 1.0.2 → 1.0.3

package/README.md

@@ -19,6 +19,7 @@
   <a href="#available-tools">Tools</a> •
   <a href="#how-it-works">How It Works</a> •
   <a href="#configuration">Configuration</a> •
+  <a href="#for-mcp-providers">For MCP Providers</a> •
   <a href="#for-library-authors">For Library Authors</a> •
   <a href="#examples">Examples</a> •
   <a href="#faq">FAQ</a>
@@ -68,6 +69,25 @@ npm install -g soup-chop
 soup-chop serve
 ```
 
+### Option 2.5 — Use as a library
+
+The published package also exposes a library entry point alongside the CLI.
+MCP server providers can use it to register their server with any supported AI client programmatically.
+
+**ESM:**
+
+```js
+import { setupClient, installMcp } from 'soup-chop';
+```
+
+**CommonJS:**
+
+```js
+const { setupClient, installMcp } = require('soup-chop');
+```
+
+Bundled TypeScript declarations are included, so editors and consumers resolve types without needing internal `dist/` paths.
+
 ### Option 3 — Inspect the supported clients
 
 ```bash
@@ -85,11 +105,14 @@ npx soup-chop configure cursor
 npx soup-chop configure cursor --project
 npx soup-chop configure vscode-copilot
 npx soup-chop configure firebase-studio
+npx soup-chop configure claude-code
 npx soup-chop configure cursor --project --dry-run
 npx soup-chop configure cursor --print
 npx soup-chop configure cursor --project --local-build --dry-run
 ```
 
+For clients that register via their own CLI (like Claude Code), `soup-chop configure` runs the appropriate command automatically — no manual file editing needed. Use `--dry-run` to preview the command that would be executed, or `--print` to emit the command line for use in scripts.
+
 Use `--project` or `--global` when a client supports more than one writable scope. Without a flag, `soup-chop` uses that client's default writable scope.
 
 On Linux today, the exact auto-config targets exposed by `soup-chop help` depend on the current platform and writable config paths.
@@ -134,7 +157,7 @@ The ecosystem is moving quickly, so `soupChop` documents both implemented auto-c
 | Client | Status | Scope | Verified config path / flow | Notes |
 | :----- | :----- | :---- | :-------------------------- | :---- |
 | Claude Desktop | Auto-config on macOS and Windows | Global | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`<br>Windows: `%APPDATA%\Claude\claude_desktop_config.json` | Official MCP docs expose this file via Claude > Settings > Developer > Edit Config; Linux remains documented-only in CLI output |
-| Claude Code | Documented | Project / user | `claude mcp add soup-chop npx -- soup-chop serve` | Official docs favor CLI / plugin flows rather than direct file editing |
+| Claude Code | Auto-configure (CLI) | Project / user | `claude mcp add <name> npx -- soup-chop serve` | `soup-chop configure claude-code` runs the `claude mcp add` command automatically |
 | Cursor | Auto-config | Global / project | Global: `~/.cursor/mcp.json`<br>Project: `.cursor/mcp.json` | Use `npx soup-chop configure cursor` for the global file or `npx soup-chop configure cursor --project` for the project file |
 | Windsurf | Auto-config | Global | `~/.codeium/windsurf/mcp_config.json` | Official docs also expose MCP management from the MCP Marketplace / Settings UI |
 | Antigravity | Documented | UI-managed | Agent pane → `MCP Servers` / `MCP Store` / `View raw config` | Official docs describe the flow but do not publish a stable file path |
@@ -150,6 +173,8 @@ The ecosystem is moving quickly, so `soupChop` documents both implemented auto-c
 
  When `configure` cannot write a client automatically, it now reports the documented target and points you back to `soup-chop clients` for the full matrix instead of failing with a generic message.
 
+ In the examples below, `soup-chop` is just the default registered server name. For manual JSON edits or client-specific CLI registration, you can replace that key with any local name you prefer. The public `soup-chop configure` CLI currently writes the default `soup-chop` name.
+
 #### Claude Desktop / Cursor / Windsurf / Gemini / Firebase Studio
 
 ```json
@@ -183,6 +208,13 @@ The ecosystem is moving quickly, so `soupChop` documents both implemented auto-c
 claude mcp add soup-chop npx -- soup-chop serve
 ```
 
+The first `soup-chop` token is the registered MCP server name inside Claude Code.
+You can replace it with another local label if you want, for example:
+
+```bash
+claude mcp add my-docs npx -- soup-chop serve
+```
+
 #### Antigravity manual registration
 
 Open the Agent pane, then go to `MCP Servers` or `MCP Store`, add a custom stdio server, and point it to:
@@ -201,6 +233,100 @@ The server is primarily tool-oriented, but it also exposes a small capability
 resource at `soup-chop://capabilities` so MCP clients that inspect resources
 have a useful entry point.
 
+Target selection is explicit:
+
+- use `package` plus `version` for published npm docs
+- use `local_path` for a direct local package checkout
+- use `workspace_path` plus `package` for a package resolved from a local monorepo
+
+`soupChop` does **not** merge local and published corpora implicitly. When you
+select a local target, the server stays on that filesystem corpus only.
+
+`compare_versions` and `get_upgrade_guide` currently remain **npm-only**.
+
+### `get_capabilities`
+
+> **Get a concise overview of the server surface.**
+
+Returns the current tool inventory, the recommended usage flow, and the current
+source-selection policy in a short text response.
+
+Use it when a client needs a quick MCP entry point before choosing a more
+specific tool.
+
+### `list_sources`
+
+> **Inspect the exact markdown corpus that was indexed.**
+
+Returns the exact markdown files indexed for a target together with corpus debug
+metadata such as source precedence, cache freshness, and the resolved local
+package root.
+
+This is the best tool to call when you want to verify which files were actually
+analyzed before following up with `search_docs`, `get_toc`, or the Mincer tools.
+
+**Parameters:**
+
+| Name      | Type     | Required | Description                                                             |
+| :-------- | :------- | :------- | :---------------------------------------------------------------------- |
+| `package` | `string` | No       | NPM package name, or workspace package name when using `workspace_path` |
+| `version` | `string` | No       | NPM version string for remote usage, or optional exact local-version check |
+| `local_path` | `string` | No    | Local package directory or local `package.json` path |
+| `workspace_path` | `string` | No | Local monorepo / workspace root; requires `package` |
+
+**Example call using a local package path:**
+
+```json
+{
+  "name": "list_sources",
+  "arguments": {
+    "local_path": "/home/me/dev/acme/packages/docs-pkg"
+  }
+}
+```
+
+**Example response:**
+
+```json
+{
+  "package": "@acme/docs-pkg",
+  "version": "1.5.0",
+  "sources": [
+    {
+      "sourceId": "api__md",
+      "sourceKind": "top_level_doc",
+      "origin": "API.md",
+      "title": "API.md",
+      "lineCount": 12
+    },
+    {
+      "sourceId": "docs__guide__md",
+      "sourceKind": "package_doc",
+      "origin": "docs/guide.md",
+      "title": "guide.md",
+      "lineCount": 18
+    },
+    {
+      "sourceId": "readme__md",
+      "sourceKind": "readme",
+      "origin": "README.md",
+      "title": "README.md",
+      "lineCount": 42
+    }
+  ],
+  "debug": {
+    "precedence": "explicit_target_only",
+    "targetMode": "local",
+    "freshness": "mutable_local_filesystem",
+    "cacheEnabled": false,
+    "cacheReason": "Local filesystem targets are mutable, so corpus and search caches stay disabled.",
+    "cachePaths": {},
+    "packageRoot": "/home/me/dev/acme/packages/docs-pkg",
+    "sourceOrigins": ["API.md", "docs/guide.md", "README.md"]
+  }
+}
+```
+
 ### `get_toc`
 
 > **Discover what's in the documentation.**
@@ -335,6 +461,74 @@ optional `origin`.
 }
 ```
 
+### `get_examples`
+
+> **Extract fenced code examples from a whole doc or one section.**
+
+Returns the fenced code blocks found in a markdown document or a selected
+section. Use `topic_id`, or `path` plus optional `origin`, to narrow the
+extraction scope.
+
+**Parameters:**
+
+| Name      | Type     | Required | Description                                                             |
+| :-------- | :------- | :------- | :---------------------------------------------------------------------- |
+| `package` | `string` | No       | NPM package name, or workspace package name when using `workspace_path` |
+| `version` | `string` | No       | NPM version string for remote usage, or optional exact local-version check |
+| `local_path` | `string` | No    | Local package directory or local `package.json` path |
+| `workspace_path` | `string` | No | Local monorepo / workspace root; requires `package` |
+| `path`    | `string` | No       | Optional section path from `get_toc` |
+| `origin`  | `string` | No       | Optional markdown source path such as `"docs/faq.md"` or `"CHANGELOG.md"` |
+| `topic_id`| `string` | No       | Stable topic identifier from `search_docs` or aggregated `get_toc` |
+
+**Example call:**
+
+```json
+{
+  "name": "get_examples",
+  "arguments": {
+    "package": "zod",
+    "version": "3.23.8",
+    "topic_id": "README.md#Coercion for primitives"
+  }
+}
+```
+
+### `find_symbol_in_docs`
+
+> **Find documentation that mentions a known identifier.**
+
+Searches the indexed markdown corpus for an exact exported identifier or literal
+symbol name such as `createClient`, `z.object`, or `parseAsync`.
+
+This is especially useful after `get_api_ref` when you know the symbol and want
+the documentation sections that mention it.
+
+**Parameters:**
+
+| Name      | Type     | Required | Description                                                             |
+| :-------- | :------- | :------- | :---------------------------------------------------------------------- |
+| `package` | `string` | No       | NPM package name, or workspace package name when using `workspace_path` |
+| `version` | `string` | No       | NPM version string for remote usage, or optional exact local-version check |
+| `local_path` | `string` | No    | Local package directory or local `package.json` path |
+| `workspace_path` | `string` | No | Local monorepo / workspace root; requires `package` |
+| `name`    | `string` | Yes      | Identifier or literal symbol to locate |
+| `limit`   | `number` | No       | Maximum ranked results to return, from `1` to `20`, default `10` |
+
+**Example call:**
+
+```json
+{
+  "name": "find_symbol_in_docs",
+  "arguments": {
+    "package": "zod",
+    "version": "3.23.8",
+    "name": "z.object",
+    "limit": 5
+  }
+}
+```
+
 ### `search_docs`
 
 > **Search package docs when you do not know the exact section yet.**
@@ -344,8 +538,9 @@ small allowlist of top-level markdown docs such as `API.md`, `FAQ.md`,
 `MIGRATING.md`, `UPGRADING.md`, `CHANGELOG.md`, and `CONTRIBUTING.md`.
 
 Results are ranked lexically and return the source origin, section path, line
-ranges, a stable `topicId`, and a short preview so the caller can follow up
-with `get_toc` or `get_topic`.
+ranges, a stable `topicId`, a short preview, and lightweight example metadata
+such as `hasExamples`, `exampleCount`, and `exampleLanguages` so the caller can
+pick sections that are more likely to contain runnable snippets.
 
 **Current language support:** search is currently optimized for **English**
 tokenization and ranking.
@@ -396,6 +591,48 @@ tokenization and ranking.
 2. If needed, call `get_toc` with the returned `origin` to inspect that doc's structure.
 3. Call `get_topic` with the returned `topicId`, or with the returned `path` and `origin`, to fetch the exact section.
 
+### `search_examples`
+
+> **Search for explanation plus nearby examples in one response.**
+
+Searches the same markdown corpus as `search_docs`, but returns section-centered
+results that keep the prose preview and attach the nearest fenced examples from
+that matching section.
+
+Use this when the user intent is closer to "keywords -> paragraph + example"
+than to raw document navigation.
+
+**Parameters:**
+
+| Name      | Type     | Required | Description                                                             |
+| :-------- | :------- | :------- | :---------------------------------------------------------------------- |
+| `package` | `string` | No       | NPM package name, or workspace package name when using `workspace_path` |
+| `version` | `string` | No       | NPM version string for remote usage, or optional exact local-version check |
+| `local_path` | `string` | No    | Local package directory or local `package.json` path |
+| `workspace_path` | `string` | No | Local monorepo / workspace root; requires `package` |
+| `query`   | `string` | Yes      | Keyword query or natural-language question                              |
+| `limit`   | `number` | No       | Maximum number of ranked results to return, from `1` to `20`, default `5` |
+
+**Example call:**
+
+```json
+{
+  "name": "search_examples",
+  "arguments": {
+    "package": "zod",
+    "version": "3.23.8",
+    "query": "coercion example",
+    "limit": 3
+  }
+}
+```
+
+**Example usage pattern:**
+
+1. Call `search_examples` when the user asks for a concrete usage example.
+2. If the attached examples are enough, answer directly from that response.
+3. If more context is needed, pivot to `get_topic` with the returned `topicId`.
+
 ### `get_traps`
 
 > **Surface warnings, caveats, and operational gotchas.**
@@ -680,6 +917,39 @@ operational caveats.
 }
 ```
 
+### `get_security_notes`
+
+> **Surface authentication, authorization, token, and attack-surface guidance.**
+
+Returns evidence-backed security findings extracted deterministically from the
+same markdown corpus used by `search_docs`.
+
+Use it when you want package docs filtered specifically for security-relevant
+guidance rather than general caveats or performance notes.
+
+**Parameters:**
+
+| Name      | Type     | Required | Description                                                                    |
+| :-------- | :------- | :------- | :----------------------------------------------------------------------------- |
+| `package` | `string` | No       | NPM package name, or workspace package name when using `workspace_path` |
+| `version` | `string` | No       | NPM version string for remote usage, or optional exact local-version check |
+| `local_path` | `string` | No    | Local package directory or local `package.json` path |
+| `workspace_path` | `string` | No | Local monorepo / workspace root; requires `package` |
+| `limit`   | `number` | No       | Maximum number of ranked security findings to return, from `1` to `50`, default `10` |
+
+**Example call:**
+
+```json
+{
+  "name": "get_security_notes",
+  "arguments": {
+    "package": "demo",
+    "version": "1.0.0",
+    "limit": 2
+  }
+}
+```
+
 ### `soup-chop://capabilities`
 
 > **Quick MCP entry point for resource-oriented clients.**
@@ -743,8 +1013,8 @@ only when needed.
 
 > **See what changed between versions.**
 
-Diffs the documentation structure between two versions of a package, showing
-added, removed, and moved sections.
+Diffs the documentation structure between two **published npm versions** of a
+package, showing added, removed, and unchanged sections.
 
 **Parameters:**
 
@@ -754,6 +1024,37 @@ added, removed, and moved sections.
 | `v_old`   | `string` | Yes      | NPM version string: exact version or published dist-tag (e.g., `"3.22.0"`, `"latest"`) |
 | `v_new`   | `string` | Yes      | NPM version string: exact version or published dist-tag (e.g., `"3.23.8"`, `"latest"`) |
 
+### `get_upgrade_guide`
+
+> **Get a migration-focused upgrade bundle for two published npm versions.**
+
+Composes `compare_versions`, changelog extraction, and deprecations from the
+target version into a single response that is easier for agents to consume as
+an upgrade guide.
+
+**Parameters:**
+
+| Name      | Type     | Required | Description                                                                            |
+| :-------- | :------- | :------- | :------------------------------------------------------------------------------------- |
+| `package` | `string` | Yes      | NPM package name                                                                       |
+| `v_old`   | `string` | Yes      | Older version to compare from                                                          |
+| `v_new`   | `string` | Yes      | Newer version to compare to                                                            |
+| `limit`   | `number` | No       | Maximum number of deprecation findings to include from the target version, default `10` |
+
+**Example call:**
+
+```json
+{
+  "name": "get_upgrade_guide",
+  "arguments": {
+    "package": "express",
+    "v_old": "4.18.2",
+    "v_new": "5.0.0",
+    "limit": 5
+  }
+}
+```
+
 ---
 
 ## How It Works
@@ -837,12 +1138,101 @@ To clear the cache, simply delete the directory.
 
 ---
 
+## For MCP Providers
+
+If you are building an MCP server and want to help your users register it with their AI client, `soup-chop` exports a library API for exactly this purpose.
+
+### `setupClient(clientId, options)`
+
+Registers an MCP server with a named AI client. Handles both file-based clients (Cursor, Windsurf, VS Code Copilot, …) and CLI-based clients (Claude Code) transparently.
+
+```ts
+import { setupClient } from 'soup-chop';
+
+// stdio server — file-based client
+await setupClient('cursor', {
+  name: 'my-mcp-server',
+  server: { command: 'npx', args: ['my-mcp-server', 'serve'] },
+  scope: 'project',
+  cwd: process.cwd(),
+});
+
+// stdio server — CLI-based client (runs: claude mcp add my-mcp-server npx -- my-mcp-server serve)
+await setupClient('claude-code', {
+  name: 'my-mcp-server',
+  server: { command: 'npx', args: ['my-mcp-server', 'serve'] },
+});
+
+// URL server — VS Code Copilot project config
+await setupClient('vscode-copilot', {
+  name: 'my-mcp-server',
+  server: { type: 'http', url: 'https://my-server.example.com/mcp' },
+  scope: 'project',
+  cwd: process.cwd(),
+});
+```
+
+**Returns** a `SetupOutcome` discriminated union:
+
+```ts
+type SetupOutcome =
+  | { mode: 'auto-config'; path: string; created: boolean }  // wrote/merged a JSON config file
+  | { mode: 'cli-install'; command: string; args: string[] }; // ran an external CLI command
+```
+
+**`SetupOptions`:**
+
+| Field | Type | Required | Description |
+| :---- | :--- | :------- | :---------- |
+| `name` | `string` | Yes | Key used in the client config JSON or as the CLI registration name |
+| `server` | `McpServer` | Yes | stdio or URL transport descriptor |
+| `scope` | `'global' \| 'project'` | No | Config scope for file-based clients |
+| `cwd` | `string` | No | Base directory for project-scoped path resolution |
+| `spawnImpl` | `SpawnLike` | No | Injectable spawn function for testing |
+
+**`McpServer` union:**
+
+```ts
+// stdio transport
+type McpStdioServer = { type?: 'stdio'; command: string; args: string[]; env?: Record<string, string> };
+
+// HTTP or SSE transport
+type McpUrlServer = { type: 'http' | 'sse'; url: string; headers?: Record<string, string> };
+
+type McpServer = McpStdioServer | McpUrlServer;
+```
+
+### `installMcp(command, args, options?)`
+
+Low-level helper that spawns an external command (e.g. `claude mcp add …`) and collects its output. Rejects with an `InstallMcpError` on non-zero exit.
+
+```ts
+import { installMcp } from 'soup-chop';
+
+const result = await installMcp('claude', ['mcp', 'add', 'my-server', 'npx', '--', 'my-server', 'serve']);
+console.log(result.stdout);
+```
+
+### `getSupportedSetupClientIds()`
+
+Returns the list of client IDs that `setupClient` can handle automatically on the current platform.
+
+```ts
+import { getSupportedSetupClientIds } from 'soup-chop';
+console.log(getSupportedSetupClientIds());
+// e.g. ['cursor', 'windsurf', 'claude-code', 'vscode-copilot', 'firebase-studio']
+```
+
+---
+
 ## For Library Authors
 
 `soupChop` is designed to work with ordinary package docs. You do not need a special integration, custom metadata, or an MCP-specific format.
 
 That said, some documentation patterns make retrieval much more reliable for both humans and AI agents:
 
+For declaration inspection, `soupChop` uses the `types` entry from `package.json` when resolving a package's TypeScript declarations, so publishing an accurate `types` path helps `get_api_ref` and `get_declaration` target the right `.d.ts` surface.
+
 ### Best Practices for Library Authors
 
 #### Use Clear, Specific Headings
@@ -914,6 +1304,27 @@ A good rule of thumb is simple: write docs so that a person can jump straight to
 > **AI** *(calls `get_declaration("zod", "3.23.8", "object")`)*: "Here is the
 > explicit declaration from the published type definitions..."
 
+### Example 4 — Verifying a local workspace corpus
+
+> **You:** "Search my local package docs, but first show me exactly what files you indexed."
+>
+> **AI** *(calls `list_sources({"package":"@acme/docs-pkg","workspace_path":"/home/me/dev/acme-monorepo"})`)*:
+> "I indexed `README.md`, `API.md`, and `docs/guide.md`. This target is local,
+> so caches are intentionally disabled and the resolved package root is
+> `/home/me/dev/acme-monorepo/packages/docs-pkg`."
+>
+> **AI** *(calls `search_docs({"package":"@acme/docs-pkg","workspace_path":"/home/me/dev/acme-monorepo","query":"workspace guide"})`)*:
+> "The best match is `docs/guide.md#Workspace Guide`."
+
+### Example 5 — Building an upgrade guide
+
+> **You:** "Summarize the risky migration points between `express@4.18.2` and `express@5.0.0`."
+>
+> **AI** *(calls `get_upgrade_guide("express", "4.18.2", "5.0.0")`)*: "The
+> documentation gained several new sections, the changelog includes the relevant
+> release notes, and the target version docs contain deprecation guidance you
+> should address during the upgrade."
+
 ---
 
 ## Requirements