Updated documents for new release (#236)

* Updated documents for new release

* fixed 0.3.0's migration

---------

Co-authored-by: zhao <jornathanm910923@gmail.com>

Author: jonathanMLDev

CHANGELOG.md

@@ -8,17 +8,21 @@ Tagged releases are published to npm from GitHub Actions when a **GitHub Release
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-07-25
+
 ### Added
 
+- **`suggest_query_params` in core:** Tool registered by `setupCoreServer` / package-root import (handler lives in core; suggest-flow gate remains off by default via `resolveConfig`). (#223)
 - **Per-source and per-namespace private config:** optional `description` (source-level) and `namespaces` map (`description` + declared `metadata_schema`) in JSON config files (`PINECONE_CONFIG_FILE`), or loaded automatically from the `_mcp_config` Pinecone namespace when not declared locally. Declared schemas skip live sampling; stale declared namespaces surface as `config_warnings` in `list_namespaces`. See [CONFIGURATION.md § Multi-source mode](docs/CONFIGURATION.md#multi-source-mode).
 - **Remote `_mcp_config` schema manifest:** automatic per-source loading of description and namespace declarations from Pinecone at startup (opt out via `PINECONE_DISABLE_REMOTE_SCHEMA` / `--disable-remote-schema`); non-fatal on failure.
 - **`list_namespaces`:** optional per-namespace `schema_source` (`declared` | `sampled`), optional per-namespace `description` (from private config), and top-level `config_warnings` when private config declarations do not match live Pinecone data.
 - **Tests:** MCP verification harness ([src/__tests__/mcp-rc-readiness.test.ts](src/__tests__/mcp-rc-readiness.test.ts)) that drives the real server over an in-memory transport with the SDK client (initialize and protocol negotiation, the full registered tool surface, and a round-trip tool call), so a future SDK or MCP protocol bump is verified in one place. Protocol assertions key off the SDK's `LATEST_PROTOCOL_VERSION`, so pinning the RC SDK re-runs the check with no test edits. (#202)
 
 ### Changed
 
-- **Breaking (`list_sources`):** response shape `sources: string[]` → `sources: { name, description? }[]`. Migration: [MIGRATION.md § Unreleased list_sources](docs/MIGRATION.md#unreleased-list_sources-response-shape).
-- **Breaking (library API):** `PineconeClient.listNamespacesWithMetadata()` now returns `{ namespaces, warnings }` instead of a bare array. Migration: [MIGRATION.md § Unreleased PineconeClient.listNamespacesWithMetadata](docs/MIGRATION.md#unreleased-pineconeclientlistnamespaceswithmetadata-return-shape).
+- **Pinecone I/O resilience:** Configurable request timeout and retry with backoff on the Pinecone search/rerank hot path for retryable HTTP statuses (429, 408, 5xx). (#225)
+- **Breaking (`list_sources`):** response shape `sources: string[]` → `sources: { name, description? }[]`. Migration: [MIGRATION.md § 0.5.0 list_sources](docs/MIGRATION.md#050-list_sources-response-shape).
+- **Breaking (library API):** `PineconeClient.listNamespacesWithMetadata()` now returns `{ namespaces, warnings }` instead of a bare array. Migration: [MIGRATION.md § 0.5.0 PineconeClient.listNamespacesWithMetadata](docs/MIGRATION.md#050-pineconeclientlistnamespaceswithmetadata-return-shape).
 - **Dependencies:** Bumped the declared `@modelcontextprotocol/sdk` floor from `^1.25.3` to `^1.29.0` to match the resolved version and ready the server for the upcoming MCP RC protocol revision. `McpServer` construction and tool registration are re-verified by the harness above through `server.connect()` over the SDK in-memory transport; the production `StdioServerTransport` wiring in `src/index.ts` is unchanged and was reviewed, not exercised, by the harness. (#202)
 - **Instructions:** Trimmed operator/install/deploy content (env-var setup, misconfiguration note, Alliance CLI index/rerank defaults, stderr logging config) from `CORE_SERVER_INSTRUCTIONS` and `ALLIANCE_INSTRUCTIONS_APPENDIX` — reduces per-session token cost; no behavior change. Replaced colliding Alliance appendix steps 4–5 with unnumbered "Manual Alliance flow" bullets (includes `PINECONE_DISABLE_SUGGEST_FLOW=true` escape clause). Full detail remains in [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
 
@@ -28,6 +32,8 @@ Tagged releases are published to npm from GitHub Actions when a **GitHub Release
 
 ### Fixed
 
+- **Credential redaction:** Tool error messages and `source_errors` no longer echo Pinecone API keys or other secrets from upstream error text. (#234)
+- **Retry and timeout classification:** `defaultShouldRetry` and app-timeout handling prefer structured HTTP status, Pinecone SDK error names, and branded `AppTimeoutError` over message-regex heuristics. (#235)
 - **Hybrid query degradation:** When exactly one search leg fails and the surviving leg returns zero hits, `query` / `query_documents` / `guided_query` now set `experimental.hybrid_leg_failed` and `experimental.degraded: true` with `degradation_reason` `dense_leg_failed` or `sparse_leg_failed`, so empty results from a leg failure are distinguishable from a legitimately empty namespace. (#228)
 
 ## [0.4.0] - 2026-06-24
@@ -60,15 +66,15 @@ Tagged releases are published to npm from GitHub Actions when a **GitHub Release
 - **Breaking (core):** `resolveConfig` requires a Pinecone index name and no longer applies Alliance index/rerank defaults. Removed exported `DEFAULT_INDEX_NAME` and `DEFAULT_RERANK_MODEL` from the package root. Rerank is opt-in when `PINECONE_RERANK_MODEL` / `rerankModel` is unset.
 - **Breaking (core):** `setupCoreServer` MCP `instructions` use `CORE_SERVER_INSTRUCTIONS` (includes `guided_query`; no `suggest_query_params`). `resolveConfig` defaults `disableSuggestFlow` to `true` so `query` / `count` / `query_documents` work without Alliance tools. Alliance CLI / `resolveAllianceConfig` unchanged: gate on by default, `ALLIANCE_SERVER_INSTRUCTIONS`.
 - **Alliance CLI / `resolveAllianceConfig`:** When index or rerank env/CLI values are omitted, defaults remain `rag-hybrid` and `bge-reranker-v2-m3` (API-key-only MCP configs unchanged). See [examples/alliance/.env.example](examples/alliance/.env.example).
-- **Breaking (library):** Trimmed public re-exports — `buildQueryExperimental` and `buildGuidedQueryExperimental` removed from package root and `/alliance` entry. See [MIGRATION.md](docs/MIGRATION.md#unreleased-trimmed-library-exports).
+- **Breaking (library):** Trimmed public re-exports — `buildQueryExperimental` and `buildGuidedQueryExperimental` removed from package root and `/alliance` entry. See [MIGRATION.md § 0.3.0 trimmed library exports](docs/MIGRATION.md#030-trimmed-library-exports).
 
 ### Deprecated
 
 - Module-level singleton facades — use `ServerContext` instance methods via `createServer(config)` and `{ context: ctx }` at setup instead. Deprecated in **0.3.0**; earliest removal **0.5.0** per [deprecation-policy.md](docs/deprecation-policy.md#deprecation-window). Affected symbols: `getPineconeClient`, `setPineconeClient`, `clearPineconeClient`, `getServerConfig`, `setServerConfig`, `resetServerConfig`, `registerUrlGenerator`, `unregisterUrlGenerator`, `generateUrlForNamespace`, `hasUrlGenerator`, `resetUrlGenerationRegistry`, `markSuggested`, `requireSuggested`, `resetSuggestionFlow`, `getNamespacesWithCache`, `invalidateNamespacesCache`, `getDefaultServerContext`. Opt-in runtime warnings when `PINECONE_DEPRECATION_WARNINGS=1` or log level is `DEBUG`. See [MIGRATION.md § Legacy module-facade deprecations](docs/MIGRATION.md#030-legacy-module-facade-deprecations) and [deprecation-policy.md](docs/deprecation-policy.md#active-deprecations-legacy-module-facades).
 
 ### Removed
 
-- **Breaking (library):** `buildQueryExperimental` and `buildGuidedQueryExperimental` are no longer re-exported from `@will-cppa/pinecone-read-only-mcp` or `@will-cppa/pinecone-read-only-mcp/alliance`. They were internal helpers used to assemble the `experimental` block on `query` / `query_documents` / `guided_query` success payloads. The assembled fields and Zod schemas (`queryResponseSchema`, `QueryExperimental`, etc.) are unchanged — see [Unreleased stable vs experimental](docs/MIGRATION.md#unreleased-stable-vs-experimental-response-fields).
+- **Breaking (library):** `buildQueryExperimental` and `buildGuidedQueryExperimental` are no longer re-exported from `@will-cppa/pinecone-read-only-mcp` or `@will-cppa/pinecone-read-only-mcp/alliance`. They were internal helpers used to assemble the `experimental` block on `query` / `query_documents` / `guided_query` success payloads. The assembled fields and Zod schemas (`queryResponseSchema`, `QueryExperimental`, etc.) are unchanged — see [MIGRATION.md § 0.3.0 trimmed library exports](docs/MIGRATION.md#030-trimmed-library-exports) and [stable vs experimental response fields](docs/MIGRATION.md#unreleased-stable-vs-experimental-response-fields).
 - **No change:** `HybridQueryResult`, `HybridLegFailed`, and `KeywordIndexNamespacesResult` remain exported as the declared return types of public `PineconeClient` methods.
 
 ### Fixed
@@ -166,7 +172,8 @@ details. Newer shipped changes are recorded in this changelog by version.
 - Environment variable support
 - Full documentation and examples
 
-[Unreleased]: https://github.com/cppalliance/pinecone-read-only-mcp-typescript/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/cppalliance/pinecone-read-only-mcp-typescript/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/cppalliance/pinecone-read-only-mcp-typescript/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/cppalliance/pinecone-read-only-mcp-typescript/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/cppalliance/pinecone-read-only-mcp-typescript/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/cppalliance/pinecone-read-only-mcp-typescript/compare/v0.1.6...v0.2.0

README.md

@@ -7,7 +7,11 @@
 
 A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that implements the MCP specification via `@modelcontextprotocol/sdk` v1.29+ and provides semantic search over Pinecone vector databases using hybrid search (dense + sparse) with reranking.
 
-Current version: 0.4.0 (npm `latest` after publish). Pin `@0.4.0` in install and MCP config for reproducible upgrades.
+Current version: 0.5.0 (npm `latest` after publish). Pin `@0.5.0` in install and MCP config for reproducible upgrades.
+
+## Upgrading to 0.5.0
+
+Version **0.5.0** includes breaking MCP and library changes: `list_sources` returns `sources: { name, description? }[]`, `PineconeClient.listNamespacesWithMetadata()` returns `{ namespaces, warnings }`, internal-only package re-exports were removed (#203), the MCP SDK floor is **^1.29.0**, and hybrid leg failure with zero surviving hits is signaled under `experimental.degraded` / `experimental.hybrid_leg_failed` (#228). Legacy module facades remain deprecated but are **not** removed in this release. See [docs/MIGRATION.md § list_sources](docs/MIGRATION.md#050-list_sources-response-shape), [§ listNamespacesWithMetadata](docs/MIGRATION.md#050-pineconeclientlistnamespaceswithmetadata-return-shape), [§ internal re-exports (#203)](docs/MIGRATION.md#internal-only-re-exports-removed-203), and the [CHANGELOG](CHANGELOG.md#050---2026-07-25).
 
 ## Upgrading to 0.4.0
 
@@ -74,25 +78,25 @@ For successful `query`, `query_documents`, and `guided_query` payloads, **rerank
 ### As a Package
 
 ```bash
-npm install @will-cppa/pinecone-read-only-mcp@0.4.0
+npm install @will-cppa/pinecone-read-only-mcp@0.5.0
 ```
 
 Or using yarn:
 
 ```bash
-yarn add @will-cppa/pinecone-read-only-mcp@0.4.0
+yarn add @will-cppa/pinecone-read-only-mcp@0.5.0
 ```
 
 Or using pnpm:
 
 ```bash
-pnpm add @will-cppa/pinecone-read-only-mcp@0.4.0
+pnpm add @will-cppa/pinecone-read-only-mcp@0.5.0
 ```
 
 ### Global Installation
 
 ```bash
-npm install -g @will-cppa/pinecone-read-only-mcp@0.4.0
+npm install -g @will-cppa/pinecone-read-only-mcp@0.5.0
 ```
 
 ### From Source
@@ -260,7 +264,7 @@ Add to your `claude_desktop_config.json`:
   "mcpServers": {
     "pinecone-search": {
       "command": "npx",
-      "args": ["-y", "@will-cppa/pinecone-read-only-mcp@0.4.0"],
+      "args": ["-y", "@will-cppa/pinecone-read-only-mcp@0.5.0"],
       "env": {
         "PINECONE_API_KEY": "your-api-key-here",
         "PINECONE_INDEX_NAME": "your-index-name",
@@ -280,7 +284,7 @@ Or with explicit options:
       "command": "npx",
       "args": [
         "-y",
-        "@will-cppa/pinecone-read-only-mcp@0.4.0",
+        "@will-cppa/pinecone-read-only-mcp@0.5.0",
         "--api-key",
         "your-api-key-here",
         "--index-name",
@@ -313,7 +317,7 @@ For a global installation:
 Run the server using npx (no installation required):
 
 ```bash
-npx @will-cppa/pinecone-read-only-mcp@0.4.0 --api-key YOUR_API_KEY --index-name YOUR_INDEX
+npx @will-cppa/pinecone-read-only-mcp@0.5.0 --api-key YOUR_API_KEY --index-name YOUR_INDEX
 ```
 
 Or if installed globally:
@@ -353,10 +357,10 @@ Run `pinecone-read-only-mcp --help` for the full option list.
 
 ```bash
 # install
-npm i @will-cppa/pinecone-read-only-mcp@0.4.0
+npm i @will-cppa/pinecone-read-only-mcp@0.5.0
 
 # run
-npx @will-cppa/pinecone-read-only-mcp@0.4.0 --api-key YOUR_API_KEY
+npx @will-cppa/pinecone-read-only-mcp@0.5.0 --api-key YOUR_API_KEY
 ```
 
 ### Deploy with Docker

docs/MIGRATION.md

@@ -6,7 +6,7 @@ This guide is for **library and MCP client authors** upgrading from earlier **0.
 
 Under [semver 0.y.z](https://semver.org/spec/v2.0.0.html#spec-item-4), **0.1.x → 0.2.0 is a breaking minor** — pin `@0.2.0` only after reading this guide.
 
-## Unreleased: `list_sources` response shape
+## 0.5.0: `list_sources` response shape
 
 **Who is affected:** MCP clients parsing `list_sources` success JSON in multi-source mode.
 
@@ -35,7 +35,7 @@ Under [semver 0.y.z](https://semver.org/spec/v2.0.0.html#spec-item-4), **0.1.x 
 
 Read `sources[].name` instead of treating `sources` as `string[]`. `description` is omitted when not configured.
 
-## Unreleased: `PineconeClient.listNamespacesWithMetadata` return shape
+## 0.5.0: `PineconeClient.listNamespacesWithMetadata` return shape
 
 **Who is affected:** Direct library consumers of `PineconeClient` (not MCP tool clients — `list_namespaces` tool response shape is additive only).
 
@@ -235,7 +235,7 @@ Or point `PINECONE_CONFIG_FILE` at a JSON file (see [examples/multi-source/pinec
 
 Single-key configs are unchanged; no migration required when using one API key.
 
-## Unreleased: trimmed library exports
+## 0.3.0: trimmed library exports
 
 **Who is affected:** Library embedders that imported `buildQueryExperimental` or `buildGuidedQueryExperimental` from `@will-cppa/pinecone-read-only-mcp` or `/alliance`.
 
@@ -252,7 +252,7 @@ import { buildQueryExperimental } from '@will-cppa/pinecone-read-only-mcp';
 
 `PineconeClient.query()` return types (`HybridQueryResult`, etc.) and all Zod response schemas remain on the public surface.
 
-### Internal-only re-exports removed (#203)
+## 0.5.0: internal-only re-exports removed (#203)
 
 **Who is affected:** Library embedders that imported any of these internal helpers from the package root or `/alliance`:
 

docs/deprecation-policy.md

@@ -10,7 +10,7 @@ For step-by-step upgrades, see [MIGRATION.md](./MIGRATION.md). For publish mecha
 
 ## Semantic versioning while `0.y.z`
 
-This package currently ships as **`0.y.z`**. Under [Semantic Versioning §4](https://semver.org/spec/v2.0.0.html#spec-item-4), **minor releases may include breaking changes** until the first `1.0.0` release. Consumers should **pin an exact version** (for example `@will-cppa/pinecone-read-only-mcp@0.4.0`) in `package.json`, MCP server config, and Docker tags.
+This package currently ships as **`0.y.z`**. Under [Semantic Versioning §4](https://semver.org/spec/v2.0.0.html#spec-item-4), **minor releases may include breaking changes** until the first `1.0.0` release. Consumers should **pin an exact version** (for example `@will-cppa/pinecone-read-only-mcp@0.5.0`) in `package.json`, MCP server config, and Docker tags.
 
 After **`1.0.0`**, this project intends to follow standard semver: breaking changes land only in **major** releases, and the deprecation window below becomes **binding** for removals that were previously announced as deprecated.
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@will-cppa/pinecone-read-only-mcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A Model Context Protocol (MCP) server that provides semantic search over Pinecone vector databases using hybrid search (dense + sparse) with reranking.",
   "type": "module",
   "main": "dist/core/index.js",