Consolidate query and keyword_search response schemas

[jonathanMLDev]

Summary

Resolves issue #173 by eliminating duplicate loose/strict Zod response schemas for query and keyword_search. Each pair now has a single canonical handler-boundary schema; the permissive export is derived programmatically via .partial(). Also resolves issue #174

• response-schemas.ts: querySuccessResponseSchema and keywordSearchSuccessResponseSchema are the source of truth; queryResponseSchema and keywordSearchResponseSchema are derived from them
• Handlers: query-tool.ts and keyword-search-tool.ts type payloads as strict response types, matching the schemas passed to validatedJsonResponse
• Context tests: assert strict schemas (same as handler validation), closing the prior loose/strict mismatch
• types.ts: re-exports QuerySuccessResponse and KeywordSearchSuccessResponse
• Tests: derivation invariant tests confirm strict payloads are accepted by permissive schemas and permissive-only payloads are rejected by strict validation

No export names or runtime response shapes change. The other seven tool schemas were already single-source and are untouched.

Test plan

• npm test — 302 tests pass
• npm run ci — typecheck, lint, format, build, coverage all green
• Permissive query shape still accepts { status: 'success', experimental: {...} } for guided_query union reuse
• Handler output validates against strict schemas; context tests match handler validation

Related Issue

• Close Dual response schema consolidation: merge loose+strict surface (3pt) #173
• Close README: add MCP specification link to opening paragraph (1pt) #174

Summary by CodeRabbit

Summary by CodeRabbit

• New Features

  • Added clearer “strict success” response types for query and keyword search results.
  • Expanded public type exports to include the new success variants.

• Bug Fixes

  • Improved response payload validation to consistently accept fully-populated success payloads and enforce stricter success-shape requirements where appropriate.
  • Updated query and keyword-search tool outputs to match the new success validation rules.

• Tests

  • Updated tests to cover strict vs permissive success-response behavior.

• Documentation

  • Refreshed README wording and TypeScript examples/version guidance.

[coderabbitai]

Warning

Review limit reached

@wpak-ai, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 57 minutes and 49 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more credits in the billing tab to continue.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 32e8b7c7-231d-44f8-80c9-7b1bd56a3b5a

📥 Commits

Reviewing files that changed from the base of the PR and between 35d0441 and 8eb76a8.

📒 Files selected for processing (8)

• README.md
• src/core/server/response-schemas.test.ts
• src/core/server/response-schemas.ts
• src/core/server/tools/keyword-search-tool.context.test.ts
• src/core/server/tools/keyword-search-tool.ts
• src/core/server/tools/query-tool.context.test.ts
• src/core/server/tools/query-tool.ts
• src/types.ts

📝 Walkthrough

Walkthrough

The response schema layer now defines strict success schemas for query and keyword_search, derives permissive schemas from them, updates both tools and tests to use the strict variants, and refreshes README wording, snippets, and table formatting.

Changes

Response schema consolidation

Layer / File(s)	Summary
Schema contracts and exports src/core/server/response-schemas.ts, src/types.ts, src/core/server/response-schemas.test.ts	Strict success schemas are introduced for query and keyword_search, the permissive schemas are derived from them with selected fields made optional, the new strict types are re-exported, and tests cover strict-versus-permissive parsing.
Query tool uses strict success schema src/core/server/tools/query-tool.ts, src/core/server/tools/query-tool.context.test.ts	The query tool imports the strict success schema and type, annotates the response object with the strict type, and the context test now validates the handler body against the strict schema.
Keyword search tool uses strict success schema src/core/server/tools/keyword-search-tool.ts, src/core/server/tools/keyword-search-tool.context.test.ts	The keyword-search tool types its success body with the strict success response type, and the context test validates the handler output against the strict schema.

README refresh

Layer / File(s)	Summary
Overview and index updates README.md	The opening package description is expanded and the documentation index table is reformatted and updated with the same set of links.
Usage snippets and examples README.md	The embedding and legacy code snippets are reformatted, the custom URL generators import path changes to the alliance subpath, and the examples table is reformatted.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• Dual response schema consolidation: merge loose+strict surface (3pt) #173: This PR makes the same strict-canonical-response-schema split with derived permissive variants.

Possibly related PRs

• cppalliance/pinecone-read-only-mcp-typescript#31: Related keyword_search response typing and validation changes in the same tool path.
• cppalliance/pinecone-read-only-mcp-typescript#151: Directly connected follow-up work on strict success schemas and permissive derived response shapes for query and keyword_search.

Suggested labels

enhancement

Suggested reviewers

• leostar0412
• wpak-ai

Poem

A bunny hops through schemas bright,
Strict ones bloom and perms take flight.
Query, keyword_search now sing in tune,
README sparkles like a moon. 🐇

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: consolidating the query and keyword_search response schemas.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@35d0441). Learn more about missing BASE report.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #180   +/-   ##
=======================================
  Coverage        ?   87.88%           
=======================================
  Files           ?       41           
  Lines           ?     1758           
  Branches        ?      559           
=======================================
  Hits            ?     1545           
  Misses          ?      213           
  Partials        ?        0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[jonathanMLDev]

@coderabbitai full review again

[coderabbitai]

@jonathanMLDev I’ll do a full review again, with attention to the schema consolidation changes around query and keyword_search.

✅ Action performed

Full review finished.

[wpak-ai]

@coderabbitai resume

[coderabbitai]

✅ Action performed

Reviews resumed.

[wpak-ai]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.