From 0c0b0c89399bc6cd37f04d7a54217c9da386ae14 Mon Sep 17 00:00:00 2001 From: zhao Date: Sat, 25 Jul 2026 02:16:04 +0800 Subject: [PATCH 1/2] Updated documents for new release --- CHANGELOG.md | 15 +++++++++++---- README.md | 24 ++++++++++++++---------- docs/MIGRATION.md | 6 +++--- docs/deprecation-policy.md | 2 +- package-lock.json | 4 ++-- package.json | 2 +- 6 files changed, 32 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a78fa9..32a769a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,8 +8,11 @@ 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. @@ -17,8 +20,9 @@ Tagged releases are published to npm from GitHub Actions when a **GitHub Release ### 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,7 +66,7 @@ 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](docs/MIGRATION.md#050-trimmed-library-exports). ### Deprecated @@ -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 diff --git a/README.md b/README.md index 85c8138..ac1c5ea 100644 --- a/README.md +++ b/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), [§ trimmed exports](docs/MIGRATION.md#050-trimmed-library-exports), [§ 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 diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md index 6794334..563a95a 100644 --- a/docs/MIGRATION.md +++ b/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.5.0: trimmed library exports **Who is affected:** Library embedders that imported `buildQueryExperimental` or `buildGuidedQueryExperimental` from `@will-cppa/pinecone-read-only-mcp` or `/alliance`. diff --git a/docs/deprecation-policy.md b/docs/deprecation-policy.md index 2d6a09b..3a39155 100644 --- a/docs/deprecation-policy.md +++ b/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. diff --git a/package-lock.json b/package-lock.json index 68f5e42..6efb0ad 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@will-cppa/pinecone-read-only-mcp", - "version": "0.4.0", + "version": "0.5.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@will-cppa/pinecone-read-only-mcp", - "version": "0.4.0", + "version": "0.5.0", "license": "BSL-1.0", "dependencies": { "@modelcontextprotocol/sdk": "^1.29.0", diff --git a/package.json b/package.json index 109f4ca..dbf4fb0 100644 --- a/package.json +++ b/package.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", From b7a693a5a876fbc73df5270151fd74c76d5e6a5f Mon Sep 17 00:00:00 2001 From: zhao Date: Sat, 25 Jul 2026 02:28:13 +0800 Subject: [PATCH 2/2] fixed 0.3.0's migration --- CHANGELOG.md | 4 ++-- README.md | 2 +- docs/MIGRATION.md | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 32a769a..ed787dc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -66,7 +66,7 @@ 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#050-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 @@ -74,7 +74,7 @@ Tagged releases are published to npm from GitHub Actions when a **GitHub Release ### 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 diff --git a/README.md b/README.md index ac1c5ea..5184070 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ Current version: 0.5.0 (npm `latest` after publish). Pin `@0.5.0` in install and ## 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), [§ trimmed exports](docs/MIGRATION.md#050-trimmed-library-exports), [§ internal re-exports (#203)](docs/MIGRATION.md#internal-only-re-exports-removed-203), and the [CHANGELOG](CHANGELOG.md#050---2026-07-25). +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 diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md index 563a95a..1607677 100644 --- a/docs/MIGRATION.md +++ b/docs/MIGRATION.md @@ -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. -## 0.5.0: 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`: