soup-chop 1.0.2 → 1.0.4

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,122 @@ 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.
+
+Source discovery is broader than package-shipped markdown alone:
+
+- `README.md`
+- package-local markdown under `doc/` and `docs/`
+- a small allowlist of top-level markdown docs such as `API.md`, `FAQ.md`, `MIGRATING.md`, `UPGRADING.md`, `CHANGELOG.md`, and `CONTRIBUTING.md`
+- synthetic `source_jsdoc` entries generated from exported TypeScript JSDoc/TSDoc discovered from local packages, published npm tarballs, and GitHub/GitLab repositories
+- same-origin website docs crawled from an explicit `docs_url`, or auto-detected from README links when a package is website-first
+- repository-derived wiki pages indexed as `wiki_doc` when a GitHub / GitLab wiki is discoverable
+- one-hop local workspace dependency docs when resolving a package through `workspace_path`
+
+Website pages are indexed as `website_doc` sources and use `origin` values such as `website/dockview.dev/docs/core/overview`.
+Synthetic JSDoc pages use origins like `jsdoc/createstableclient`. Wiki pages use `wiki/...` origins.
+
+For website ingestion, soup-chop currently stays **Node-only**: it supports static HTML crawling plus manifest-aware discovery such as VitePress `hashmap.json` and sitemap-backed doc sites, but intentionally does **not** require Playwright or a browser runtime for JS-rendered SPA fallback.
+
+`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. For website-first packages, this can include `website_doc` entries in addition to packaged markdown.
+
+**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 |
+| `docs_url` | `string` | No      | Optional docs website entry URL; when provided, soup-chop crawls this website as an additional documentation source |
+| `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": "dockview",
+  "version": "5.1.0",
+  "sources": [
+    {
+      "sourceId": "readme__md",
+      "sourceKind": "readme",
+      "origin": "README.md",
+      "title": "README.md",
+      "lineCount": 81
+    },
+    {
+      "sourceId": "website__dockview__dev__docs__core__overview",
+      "sourceKind": "website_doc",
+      "origin": "website/dockview.dev/docs/core/overview",
+      "title": "Overview | Dockview",
+      "lineCount": 3
+    },
+    {
+      "sourceId": "website__dockview__dev__docs__core__panels__register",
+      "sourceKind": "website_doc",
+      "origin": "website/dockview.dev/docs/core/panels/register",
+      "title": "Registering Panels | Dockview",
+      "lineCount": 5
+    }
+  ],
+  "debug": {
+    "precedence": "explicit_target_only",
+    "targetMode": "npm",
+    "freshness": "immutable_published_version",
+    "cacheEnabled": true,
+    "cacheReason": "Exact published npm versions are immutable, so manifest and search caches are safe.",
+    "cachePaths": {
+      "manifest": "/home/me/.cache/soup-chop/dockview/5.1.0/sources-manifest.json",
+      "searchIndex": "/home/me/.cache/soup-chop/dockview/5.1.0/search-index.json"
+    },
+    "sourceOrigins": [
+      "README.md",
+      "website/dockview.dev/docs/core/overview",
+      "website/dockview.dev/docs/core/panels/register"
+    ]
+  }
+}
+```
+
 ### `get_toc`
 
 > **Discover what's in the documentation.**
@@ -208,20 +356,22 @@ have a useful entry point.
 Returns a structured table of contents for a package's markdown docs.
 
 Without `origin`, it returns a package-wide multi-document TOC that includes
-synthetic file-root entries such as `README.md`, `CHANGELOG.md`, or
-`docs/faq.md`.
+synthetic file-root entries such as `README.md`, `CHANGELOG.md`, `docs/faq.md`, or website origins such as `website/dockview.dev/docs/core/overview`.
 
 With `origin`, it returns the TOC for a single markdown document.
 
+For `README.md`, soup-chop also adds direct synthetic entries for common top-level sections such as `Installation`, `API`, `Usage`, and `FAQ` so callers can jump straight to those sections without the full hierarchical path.
+
 **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 |
+| `docs_url` | `string` | No      | Optional docs website entry URL; when provided, soup-chop crawls this website as an additional documentation source |
 | `local_path` | `string` | No    | Local package directory or local `package.json` path |
 | `workspace_path` | `string` | No | Local monorepo / workspace root; requires `package` |
-| `origin`  | `string` | No       | Markdown source path from `search_docs` such as `"docs/faq.md"` or `"CHANGELOG.md"` |
+| `origin`  | `string` | No       | Source path from `search_docs` such as `"docs/faq.md"`, `"CHANGELOG.md"`, or `"website/dockview.dev/docs/core/overview"` |
 
 **Example call:**
 
@@ -298,16 +448,20 @@ document.
 You can identify the target either with `topic_id`, or with `path` plus an
 optional `origin`.
 
+For website docs, `origin` and `topic_id` use the normalized website source path returned by `search_docs` and `get_toc`.
+The same applies to synthetic README section shortcuts such as `README.md#Installation`.
+
 **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 |
+| `docs_url` | `string` | No      | Optional docs website entry URL; when provided, soup-chop crawls this website as an additional documentation source |
 | `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       | Section path from `get_toc` (e.g., `"Zod/Installation"`) |
-| `origin`  | `string` | No       | Markdown source path from `search_docs` such as `"docs/faq.md"` or `"CHANGELOG.md"` |
+| `origin`  | `string` | No       | Source path from `search_docs` such as `"docs/faq.md"`, `"CHANGELOG.md"`, or `"website/dockview.dev/docs/core/panels/register"` |
 | `topic_id`| `string` | No       | Stable topic identifier from `search_docs` or aggregated `get_toc` |
 
 **Example call using `topic_id`:**
@@ -335,17 +489,88 @@ 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 |
+| `docs_url` | `string` | No      | Optional docs website entry URL; when provided, soup-chop crawls this website as an additional documentation source |
+| `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 source path such as `"docs/faq.md"`, `"CHANGELOG.md"`, or `"website/dockview.dev/docs/core/panels/add"` |
+| `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 |
+| `docs_url` | `string` | No      | Optional docs website entry URL; when provided, soup-chop crawls this website as an additional documentation source |
+| `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.**
 
 Searches `README.md`, package-local markdown under `doc/` and `docs/`, and a
 small allowlist of top-level markdown docs such as `API.md`, `FAQ.md`,
-`MIGRATING.md`, `UPGRADING.md`, `CHANGELOG.md`, and `CONTRIBUTING.md`.
+`MIGRATING.md`, `UPGRADING.md`, `CHANGELOG.md`, and `CONTRIBUTING.md`. For website-first packages, soup-chop can also crawl same-origin website docs and index them as `website_doc` sources.
 
 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.
@@ -358,6 +583,7 @@ tokenization and ranking.
 | :-------- | :------- | :------- | :---------------------------------------------------------------------- |
 | `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 |
+| `docs_url` | `string` | No      | Optional docs website entry URL; when provided, soup-chop crawls this website as an additional documentation source |
 | `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                              |
@@ -396,6 +622,49 @@ 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 |
+| `docs_url` | `string` | No      | Optional docs website entry URL; when provided, soup-chop crawls this website as an additional documentation source |
+| `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.**
@@ -424,6 +693,7 @@ range, snippet, and detector names so the caller can pivot back into
 | :-------- | :------- | :------- | :----------------------------------------------------------------------- |
 | `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 |
+| `docs_url` | `string` | No      | Optional docs website entry URL; when provided, soup-chop crawls this website as an additional documentation source |
 | `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 trap findings to return, from `1` to `50`, default `10` |
@@ -495,6 +765,7 @@ broader caveat-oriented `get_traps` view.
 | :-------- | :------- | :------- | :----------------------------------------------------------------------------- |
 | `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 |
+| `docs_url` | `string` | No      | Optional docs website entry URL; when provided, soup-chop crawls this website as an additional documentation source |
 | `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 deprecation findings to return, from `1` to `50`, default `10` |
@@ -562,6 +833,7 @@ general caveats.
 | :-------- | :------- | :------- | :--------------------------------------------------------------------------- |
 | `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 |
+| `docs_url` | `string` | No      | Optional docs website entry URL; when provided, soup-chop crawls this website as an additional documentation source |
 | `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 constraint findings to return, from `1` to `50`, default `10` |
@@ -629,6 +901,7 @@ operational caveats.
 | :-------- | :------- | :------- | :----------------------------------------------------------------------------- |
 | `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 |
+| `docs_url` | `string` | No      | Optional docs website entry URL; when provided, soup-chop crawls this website as an additional documentation source |
 | `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 performance findings to return, from `1` to `50`, default `10` |
@@ -680,6 +953,40 @@ 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 |
+| `docs_url` | `string` | No      | Optional docs website entry URL; when provided, soup-chop crawls this website as an additional documentation source |
+| `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,17 +1050,48 @@ 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:**
 
 | Name      | Type     | Required | Description                                                                            |
 | :-------- | :------- | :------- | :------------------------------------------------------------------------------------- |
 | `package` | `string` | Yes      | NPM package name                                                                       |
-| `v_old`   | `string` | Yes      | NPM version string: exact version or published dist-tag (e.g., `"3.22.0"`, `"latest"`) |
+| `v_old`   | `string` | Yes      | NPM version string: exact version or published dist-tag (e.g., `"3.22.0"`, `"oldest"`) (jk) |
 | `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
@@ -799,11 +1137,12 @@ You ask about express@4.18.2
 **Key design decisions:**
 
 - **Version-scoped caching** — Each `package@version` pair is cached independently.
-  Since published NPM versions are immutable, the cache never goes stale.
+  Since published NPM versions are immutable, packaged markdown, website-source manifests, search indexes, and findings caches can be reused safely.
 - **No API keys required** — Everything runs locally. No LLM calls, no embeddings
-  API, no external services beyond UNPKG (a public CDN).
+  API, no external services beyond UNPKG (a public CDN) and the target documentation website when `docs_url` or README-based website detection is used.
 - **Surgical delivery** — The AI gets a *table of contents*, not the full README.
   It can then request only the section it needs, keeping context windows lean.
+- **Website-first docs support** — Packages whose real docs live on a website can be indexed through bounded same-origin crawling and HTML-to-Markdown normalization.
 
 ---
 
@@ -826,10 +1165,16 @@ Cache is organized as:
 ~/.cache/soup-chop/
 ├── express/
 │   └── 4.18.2/
-│       └── README.md
+│       ├── README.md
+│       ├── sources-manifest.json
+│       ├── search-index.json
+│       └── mincer-findings.json
 ├── zod/
 │   └── 3.23.8/
-│       └── README.md
+│       ├── README.md
+│       ├── sources-manifest.json
+│       ├── search-index.json
+│       └── mincer-findings.json
 └── ...
 ```
 
@@ -837,12 +1182,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 +1348,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