OSS product hardening: configuration, resilience, unified query surface, and packaging

[jonathanMLDev]

Problem

The TypeScript MCP server worked for ad hoc use but was not yet shaped like a maintainable OSS product: configuration was scattered, there was no first-class CLI (--help / --version), logging was not consistently safe for production (API keys in logs), Pinecone calls lacked shared retry and timeout behavior, the MCP surface exposed multiple overlapping query tools instead of one clear contract, and CI/docs/packaging did not yet reflect a deployment-ready posture (matrix testing, coverage gates, SBOM, Dependabot grouping, npm package contents).

Downstream integrators and host operators need predictable configuration precedence (CLI over environment over defaults), tunable cache TTL and request timeouts, optional disabling of the suggest flow for constrained environments, sparse index naming separate from the dense index, and documentation that explains how this server differs from the Python variant and how to run it in production.

Goals

• Centralize runtime configuration and expose it through environment variables and CLI overrides, with validation and a single server-wide config context.
• Improve operability: structured or text logs with API key redaction; JSON log lines suitable for aggregators.
• Harden network behavior: exponential backoff retries and abort-aware timeouts around Pinecone SDK usage.
• Simplify the MCP tool contract: one query tool driven by presets (fast, detailed, full) and aligned guided-query behavior (preferred_tool: auto, count, fast, detailed).
• Polish packaging and engineering hygiene: LF line endings, examples, .gitignore for local data, README and CHANGELOG updates, .npmignore so published tarballs exclude bulky docs, expanded .env.example.
• Strengthen CI: OS × Node matrix, coverage on Ubuntu + Codecov upload, CycloneDX SBOM artifact, Vitest coverage thresholds and sensible excludes, Dependabot npm groups.

Acceptance Criteria

• resolveConfig() (or equivalent) builds a ServerConfig from CLI args, environment variables, and documented defaults; invalid values fail fast with clear messages.
• CLI supports --help, --version, and documented override flags; npm package main/exports point at built dist/ entrypoints.
• Logger supports text and JSON formats; API keys and sensitive values are redacted in both paths.
• All Pinecone-facing operations run through shared retry + timeout helpers with tests covering retry predicates and timeout / abort races.
• MCP exposes a unified query tool with preset (and internal mapping from legacy split tools is removed or fully bridged); guided_query documents and honors the expanded preferred_tool enum including auto.
• New or renamed settings are documented in .env.example and README: sparse index name, cache TTL, suggest-flow disable flag, request timeout, log format.
• list_namespaces responses include a machine-readable cache expiry timestamp where applicable; keyword search results include document_id (with any legacy alias documented as deprecated).
• Metadata filter validation accepts the intended scalar types in $in / $nin arrays; errors name supported operators clearly.
• Builtin URL generators register idempotently on server setup; URL generation tests initialize generators in beforeAll as needed.
• CI runs tests across ubuntu / windows / macos with Node LTS matrix; coverage + Codecov + SBOM steps run on the canonical Linux + Node 20 job; npm run typecheck, lint, format:check, and tests pass.
• CHANGELOG “Unreleased” records breaking MCP/library notes where tool names or schemas changed; README includes deployment model and comparison with the Python server.

Implementation Notes

Prefer lazy getServerConfig() for modules that previously imported constants for TTLs. Keep suggestion-flow caching sweepable (sweepExpired) when TTL is config-driven. When consolidating query tools, preserve semantic behavior of old query_fast / query_detailed paths via preset mapping and update CodeRabbit- or user-facing tool descriptions in lockstep. For withTimeout, handle the reject-before-abort race and swallow stray rejections from the wrapped function after abort, as called out in PR review themes.

References

• Pull request: Feat/oss product hardening #67
• Related prior work: #15-update mcp with several tools #21 (config, logger, URL generation, namespaces cache), feat: add keyword_search tool for pinecone-rag-sparse index (#29) #31 (sparse / keyword index plumbing)