feat: post-rebase hardening, query tool presets, and CI coverage scope

- Unify MCP query surface behind one tool with fast/detailed/full presets; update guided flow and docs.
- Abort-aware withTimeout (reject-before-abort race, swallow stray fn rejections); add retry tests.
- Pinecone client: shared hit mapping, keyword index namespace discriminated result, metadata filter and logger fixes; builtin URL generators register in setupServer.
- README/CHANGELOG/.npmignore align with packaging and deployment model; vitest excludes glue layers from coverage gates.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: zho

.npmignore

@@ -31,7 +31,6 @@ PUBLISHING.md
 node_modules/
 .vscode/
 .idea/
-dist/
 docs/
 
 # Testing

CHANGELOG.md

@@ -10,6 +10,9 @@ Future releases are managed automatically by [release-please](https://github.com
 
 ### Added
 
+- `registerBuiltinUrlGenerators()` for built-in URL generators; `setupServer()` invokes it so CLI/library parity stays default.
+- Discriminated result type for `listNamespacesFromKeywordIndex()` (`KeywordIndexNamespacesResult`).
+- Unit tests for `withRetry` / `withTimeout` in `src/server/retry.test.ts`.
 - `SERVER_VERSION` is now read from `package.json` at runtime so MCP `serverInfo` always matches the published package version.
 - `--version` CLI flag prints the package version and exits.
 - `list_namespaces` response now includes `expires_at_iso` so clients see the cache expiry as an ISO-8601 timestamp without converting `cache_ttl_seconds`.
@@ -22,6 +25,13 @@ Future releases are managed automatically by [release-please](https://github.com
 
 ### Changed
 
+- **Breaking (MCP):** Single hybrid `query` tool with `preset` (`fast` | `detailed` | `full`); removed separate `query_fast` / `query_detailed` tool registrations.
+- **Breaking (library):** Stopped re-exporting `withRetry` / `withTimeout` from the package entry (`server.ts`).
+- `withTimeout` aborts an internal `AbortSignal` on deadline (cooperative cancellation).
+- `PineconeClient`: shared hit-field extraction, safer merge dedup without empty `_id` collisions, metadata sampling skips zero-vector probe when dimension is unknown, `listNamespacesFromKeywordIndex` surfaces errors via `{ ok: false }`.
+- Metadata filter manual validation accepts primitive arrays for `$in`/`$nin` including numbers (matches Zod).
+- README: deployment model for process-global gate/cache/registry; adjusted feature wording vs pre-1.0 semver.
+- `.npmignore` no longer excludes `dist/` (still shipped via `package.json` `files`).
 - `.env.example` log-level options corrected to the four levels actually supported (`DEBUG`, `INFO`, `WARN`, `ERROR`); the stale `WARNING`/`CRITICAL` values are gone.
 - README Slack URL example now matches the generator output (`https://app.slack.com/client/{team_id}/{channel_id}/p{messageId}`).
 - README "Comparison with Python Version" no longer claims an identical API interface; the new TypeScript-only tools (`guided_query`, `query_documents`, `keyword_search`, `namespace_router`, `suggest_query_params`, `count`, `generate_urls`) are listed explicitly.

README.md

@@ -27,8 +27,8 @@ A Model Context Protocol (MCP) server that provides semantic search over Pinecon
 - **Semantic Reranking**: Uses BGE reranker model for improved precision
 - **Dynamic Namespace Discovery**: Automatically discovers available namespaces in your Pinecone index
 - **Metadata Filtering**: Supports optional metadata filters for refined searches
-- **Fast & Optimized**: Lazy initialization, connection pooling, and efficient result merging
-- **Production Ready**: Input validation, error handling, and configurable logging
+- **Fast presets**: Lazy initialization, connection pooling, and efficient result merging; use the `query` tool `preset=fast` / `detailed` to trade latency vs quality (no published benchmarks yet — treat descriptions as qualitative).
+- **Production-oriented defaults**: Input validation, error handling, and configurable logging (semantic versioning is pre-1.0 — review CHANGELOG before upgrading).
 - **TypeScript Support**: Full TypeScript support with type definitions
 
 ## Installation
@@ -82,6 +82,10 @@ Quick reference:
 
 Run `pinecone-read-only-mcp --help` for CLI equivalents (`--cache-ttl-seconds`, `--request-timeout-ms`, `--disable-suggest-flow`, etc.).
 
+### Deployment model
+
+The server uses **process-global** memory for the suggest-flow gate (`suggest_query_params` context), namespaces cache, URL generator registry, and active configuration. **Stdio MCP (one client per Node process)** matches this model. If you embed `setupServer` behind a multi-tenant HTTP transport, isolate those structures per session yourself or treat the suggest-flow guard as best-effort only.
+
 ### Claude Desktop Configuration
 
 Add to your `claude_desktop_config.json`:
@@ -254,7 +258,7 @@ Discovers and lists all available namespaces in the configured Pinecone index, i
 
 ### `suggest_query_params`
 
-Suggests which **fields** to request and which tool to use (`count`, `query_fast`, or `query_detailed`), based on the namespace’s schema (from `list_namespaces`) and the user’s natural language query. This is a mandatory flow step before `count`/`query` tools.
+Suggests which **fields** to request and which path to use (`count`, or hybrid query as **fast** vs **detailed** — implemented via the `query` tool `preset` argument), based on the namespace’s schema (from `list_namespaces`) and the user’s natural language query. This is a mandatory flow step before `count` / `query` tools.
 
 **Parameters:**
 
@@ -286,7 +290,7 @@ Single orchestrator tool that runs the full flow in one call:
 
 1. namespace routing (if namespace is omitted),
 2. query param suggestion,
-3. execution via `count`, `query_fast`, or `query_detailed`.
+3. execution via `count` or hybrid `query` (fast vs detailed behavior).
 
 It returns both the final result and a `decision_trace` for transparency.
 
@@ -298,7 +302,7 @@ It returns both the final result and a `decision_trace` for transparency.
 | `namespace`       | string  | No       | -       | Optional explicit namespace                                                         |
 | `metadata_filter` | object  | No       | -       | Optional metadata filter                                                            |
 | `top_k`           | integer | No       | `10`    | Query result size for query paths (1-100)                                           |
-| `preferred_tool`  | enum    | No       | `auto`  | One of `auto`, `count`, `query_fast`, `query_detailed`                              |
+| `preferred_tool`  | enum    | No       | `auto`  | One of `auto`, `count`, `fast`, `detailed`                                          |
 | `enrich_urls`     | boolean | No       | `true`  | Auto-generate URLs for `mailing` and `slack-Cpplang` when `metadata.url` is missing |
 
 **Returns:** JSON containing `decision_trace` and `result`.

scripts/test-search.ts

@@ -155,7 +155,11 @@ async function test() {
     // Test 5: Keyword (sparse-only) search — use namespace from sparse index, not dense
     let duration5: number | undefined;
     let test5Skipped = false;
-    const sparseNamespaces = await client.listNamespacesFromKeywordIndex();
+    const sparseResult = await client.listNamespacesFromKeywordIndex();
+    const sparseNamespaces = sparseResult.ok ? sparseResult.namespaces : [];
+    if (!sparseResult.ok) {
+      console.warn(`⚠️ listNamespacesFromKeywordIndex failed: ${sparseResult.error}`);
+    }
     if (sparseNamespaces.length === 0) {
       test5Skipped = true;
       console.log(`\n🔤 Test 5: Keyword search (sparse-only index)`);

src/cli.ts

@@ -3,11 +3,7 @@
  * for {@link resolveConfig}; environment variables remain the fallback there.
  */
 
-import {
-  DEFAULT_INDEX_NAME,
-  DEFAULT_RERANK_MODEL,
-  SERVER_VERSION,
-} from './constants.js';
+import { DEFAULT_INDEX_NAME, DEFAULT_RERANK_MODEL, SERVER_VERSION } from './constants.js';
 import type { ConfigOverrides } from './config.js';
 
 export type ParseCliResult =

src/constants.ts

@@ -34,7 +34,7 @@ export const QUERY_DOCUMENTS_MAX_CHUNKS = 500;
 export const SERVER_NAME = 'Pinecone Read-Only MCP';
 export { SERVER_VERSION } from './server-version.js';
 
-export const SERVER_INSTRUCTIONS = `Quickstart for AI clients: for most user questions, call \`guided_query\` with the user's question — it does namespace routing, suggestion, and execution in one shot and returns a decision_trace you can show the user. For manual flows, call \`list_namespaces\` -> \`suggest_query_params\` -> \`query_fast\` / \`query_detailed\` / \`count\` (the suggest step is a mandatory gate). Use \`query_documents\` for full-document reading, \`keyword_search\` for exact-keyword retrieval against the sparse index, and \`generate_urls\` when records need URLs synthesized from metadata.
+export const SERVER_INSTRUCTIONS = `Quickstart for AI clients: for most user questions, call \`guided_query\` with the user's question — it does namespace routing, suggestion, and execution in one shot and returns a decision_trace you can show the user. For manual flows, call \`list_namespaces\` -> \`suggest_query_params\` -> \`query\` (use preset fast/detailed/full per suggestion) or \`count\` (the suggest step is a mandatory gate). Use \`query_documents\` for full-document reading, \`keyword_search\` for exact-keyword retrieval against the sparse index, and \`generate_urls\` when records need URLs synthesized from metadata.
 
 A semantic search server that provides hybrid search capabilities over Pinecone vector indexes with automatic namespace discovery.
 
@@ -53,7 +53,7 @@ Usage:
 1. Use list_namespaces (cached) to discover available namespaces in the index. The response includes \`expires_at_iso\` so you know when to refresh.
 2. Optionally use namespace_router to choose candidate namespace(s) from user intent.
 3. Call suggest_query_params before query/count/query_documents tools (mandatory flow gate) to get suggested_fields and recommended_tool.
-4. Use count for count questions, query_fast/query_detailed for chunk-level retrieval, or query_documents for full-document content.
+4. Use count for count questions, \`query\` with the appropriate preset for chunk-level retrieval, or query_documents for full-document content.
 
 Notes:
 - Result rows include both \`document_id\` (canonical) and \`paper_number\` (deprecated alias kept for one minor cycle; will be removed in the next major release). Prefer \`document_id\` in new code.

src/logger.ts

@@ -51,21 +51,16 @@ function shouldLog(level: LogLevel): boolean {
 /**
  * Pinecone API keys are typically UUID-like strings. We mask anything that
  * looks like a key (`xxxxxxxx-xxxx-...`) plus tokens marked with `apiKey`,
- * `api_key`, or `Authorization: Bearer ...`. The intent is defence in
- * depth: callers should already be careful, this is the last guard.
+ * `api_key`, or `Authorization: Bearer ...`.
  */
-const API_KEY_PATTERNS: RegExp[] = [
-  /[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/g,
-  /(api[_-]?key["':\s=]+)([^\s"',}]+)/gi,
-  /(Authorization:\s*Bearer\s+)([^\s"',}]+)/gi,
-];
-
 /** Replace API-key-shaped substrings in `s` with `***`. Idempotent and safe to call on any string. */
 export function redactApiKey(s: string): string {
-  let out = s;
-  for (const re of API_KEY_PATTERNS) {
-    out = out.replace(re, (_match, prefix?: string) => (prefix ? `${prefix}***` : '***'));
-  }
+  let out = s.replace(
+    /[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/g,
+    '***'
+  );
+  out = out.replace(/(api[_-]?key["':\s=]+)([^\s"',}]+)/gi, '$1***');
+  out = out.replace(/(Authorization:\s*Bearer\s+)([^\s"',}]+)/gi, '$1***');
   return out;
 }