docs(examples): generic quickstart + alliance examples layout#115
Merged
wpak-ai merged 5 commits intoMay 28, 2026
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughAdds a generic quickstart: reorganized examples/docs, a quickstart ChangesQuickstart Example and Documentation
Sequence Diagram(s)sequenceDiagram
participant Client as Quickstart Client
participant Core as MCP Core Server
participant Pinecone as Pinecone Service
Client->>Core: connect via linked transport
Client->>Core: list_namespaces()
Core->>Pinecone: list namespaces request
Pinecone-->>Core: namespaces list
Core-->>Client: namespaces result
Client->>Core: count(query_text: "document")
Core->>Pinecone: count request
Pinecone-->>Core: count result
Core-->>Client: count result
Client->>Core: query(preset: fast, top_k:3)
Core->>Pinecone: query vectors
Pinecone-->>Core: query results
Core-->>Client: tool result (JSON/text)
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3 | ❌ 2❌ Failed checks (2 warnings)
✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #115 +/- ##
=======================================
Coverage ? 81.21%
=======================================
Files ? 38
Lines ? 1299
Branches ? 437
=======================================
Hits ? 1055
Misses ? 242
Partials ? 2 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
examples/quickstart/mcp-demo.ts (1)
26-32: 💤 Low valueConsider more specific error messages in
parseToolJson.The function throws a generic error if no text content is found, and
JSON.parsecan throw without indicating malformed JSON. For better debuggability, consider catching parse errors separately or including the raw text in error messages.♻️ Proposed enhancement
function parseToolJson(result: { content?: Array<{ type: string; text?: string }>; isError?: boolean }): unknown { const text = result.content?.find((c) => c.type === 'text')?.text; if (!text) { throw new Error('Tool result had no text content'); } - return JSON.parse(text) as unknown; + try { + return JSON.parse(text) as unknown; + } catch (err) { + throw new Error(`Failed to parse tool result JSON: ${err instanceof Error ? err.message : String(err)}`); + } }🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@examples/quickstart/mcp-demo.ts` around lines 26 - 32, The parseToolJson function currently throws a generic error when no text is found and lets JSON.parse errors bubble up without context; update parseToolJson to (1) include the raw result.content (or the extracted text) in the thrown error when text is missing so callers see what was returned, and (2) wrap JSON.parse in a try/catch and rethrow a new Error that includes the offending text and the original parsing error message (or attach the original error) to make malformed-JSON failures clearly debuggable; reference the parseToolJson function and the local variable text when implementing these changes.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@examples/quickstart/mcp-demo.ts`:
- Around line 70-77: The list_namespaces result handling doesn't check for a
tool error before calling parseToolJson; update the block that calls
client.callTool({ name: 'list_namespaces', ... }) to first check listRaw.isError
(same pattern used in the count and query calls) and handle/log/return the error
instead of parsing it, and only call parseToolJson(listRaw) when
!listRaw.isError so parseToolJson isn't invoked on error payloads.
---
Nitpick comments:
In `@examples/quickstart/mcp-demo.ts`:
- Around line 26-32: The parseToolJson function currently throws a generic error
when no text is found and lets JSON.parse errors bubble up without context;
update parseToolJson to (1) include the raw result.content (or the extracted
text) in the thrown error when text is missing so callers see what was returned,
and (2) wrap JSON.parse in a try/catch and rethrow a new Error that includes the
offending text and the original parsing error message (or attach the original
error) to make malformed-JSON failures clearly debuggable; reference the
parseToolJson function and the local variable text when implementing these
changes.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 2adc3735-fe49-4baa-b94f-70d26eb42ee7
📒 Files selected for processing (11)
examples/README.mdexamples/alliance/README.mdexamples/alliance/custom-url-generator.tsexamples/alliance/demo-mock-pinecone-client.tsexamples/alliance/guided-query-demo.tsexamples/alliance/library-embedding-demo.tsexamples/alliance/suggest-flow-demo.tsexamples/quickstart/.env.exampleexamples/quickstart/README.mdexamples/quickstart/mcp-demo.tsexamples/quickstart/seed-data.ts
Collaborator
Author
|
@coderabbitai full review again |
🧩 Analysis chain🏁 Script executed: #!/bin/bash
echo "=== examples/quickstart/seed-data.ts ==="
cat examples/quickstart/seed-data.ts
echo ""
echo "=== examples/quickstart/mcp-demo.ts ==="
cat examples/quickstart/mcp-demo.ts
echo ""
echo "=== examples/quickstart/README.md ==="
cat examples/quickstart/README.md
echo ""
echo "=== examples/quickstart/.env.example ==="
cat examples/quickstart/.env.example
echo ""
echo "=== examples/alliance/README.md ==="
cat examples/alliance/README.md
echo ""
echo "=== examples/README.md ==="
cat examples/README.md
echo ""
echo "=== Root README.md (first 200 lines) ==="
head -200 README.md
echo ""
echo "=== Root .env.example ==="
cat .env.example
echo ""
echo "=== docs/CONFIGURATION.md (grep alliance) ==="
grep -n "alliance\|quickstart\|library-embedding" docs/CONFIGURATION.md | head -40
echo ""
echo "=== examples/alliance/ directory listing ==="
ls -la examples/alliance/
echo ""
echo "=== examples/quickstart/ directory listing ==="
ls -la examples/quickstart/
echo ""
echo "=== package.json (scripts, dependencies) ==="
cat package.json
echo ""
echo "=== Check for tsconfig or similar ==="
cat tsconfig.json 2>/dev/null || echo "tsconfig.json not found"Length of output: 38214 🏁 Script executed: #!/bin/bash
echo "=== .gitignore (check for .env patterns) ==="
cat .gitignore
echo ""
echo "=== Pinecone SDK index() signature (look in node_modules) ==="
find node_modules/@pinecone-database/pinecone/dist -name "*.d.ts" 2>/dev/null | head -5 | xargs grep -l "upsertRecords" 2>/dev/null | head -3
echo ""
echo "=== upsertRecords signature ==="
find node_modules/@pinecone-database/pinecone/dist -name "*.d.ts" 2>/dev/null | xargs grep -A3 "upsertRecords" 2>/dev/null | head -30
echo ""
echo "=== pc.index() signature ==="
find node_modules/@pinecone-database/pinecone/dist -name "*.d.ts" 2>/dev/null | xargs grep -A3 "index(" 2>/dev/null | grep -E "index\(|IndexName|PineconeIndex" | head -20
echo ""
echo "=== Check for examples/tsconfig.json ==="
ls examples/ 2>/dev/null
echo ""
echo "=== Check if examples/quickstart/.env is gitignored ==="
git check-ignore -v examples/quickstart/.env 2>/dev/null || echo "NOT gitignored"
echo ""
echo "=== existing alliance demo files check ==="
cat examples/alliance/suggest-flow-demo.tsLength of output: 4122
PR Review —
|
| Severity | File | Issue |
|---|---|---|
| 🔴 Critical | seed-data.ts |
pc.index({ name }) → pc.index(name) |
| 🔴 Critical | seed-data.ts |
upsertRecords({ records }) → upsertRecords(records) |
| 🟡 Medium | mcp-demo.ts |
Missing isError check on list_namespaces |
| 🟡 Medium | mcp-demo.ts |
No process.exit(0) — process may hang on success |
| 🟡 Medium | root .env.example |
PINECONE_RERANK_MODEL uncommented may surprise free-tier users |
| 🟢 Low | seed-data.ts |
Unreachable return after process.exit() |
| 🟢 Low | mcp-demo.ts |
teardownServer() called before confirming server was ready |
✅ Actions performed
Full review triggered.
added 2 commits
May 28, 2026 04:23
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@examples/quickstart/mcp-demo.ts`:
- Line 69: The local variable "connected" in examples/quickstart/mcp-demo.ts is
redundant (set to true and never changed); remove its declaration and the
conditional check in the finally block, and always run the cleanup logic there
(e.g., call the same disconnect/cleanup functions directly). Update any
references to "connected" (if present) and ensure the finally block performs the
intended cleanup without the dead "if (connected)" branch.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 60dddd8b-4159-4ced-97b5-3071e9433eb5
📒 Files selected for processing (5)
.env.exampleREADME.mddocs/CONFIGURATION.mdexamples/quickstart/mcp-demo.tsexamples/quickstart/seed-data.ts
✅ Files skipped from review due to trivial changes (3)
- .env.example
- docs/CONFIGURATION.md
- README.md
🚧 Files skipped from review as they are similar to previous changes (1)
- examples/quickstart/seed-data.ts
|
Actionable comments posted: 0 |
wpak-ai
approved these changes
May 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a generic quickstart under
examples/quickstart/so any user with a free-tier Pinecone account can try the server without the C++ Alliancerag-hybridindex. Relocates all Alliance-specific demos toexamples/alliance/and updates the rootREADME.mdwith a Quick start section and a restructured Examples table.Closes w4_issue_05.
Merge order: after PR A (#109, already merged), before PR B (
week4/release).Changes
examples/quickstart/(new)README.md— End-to-end setup guide: Pinecone account, two integrated-embedding indexes (my-mcp-demodense +my-mcp-demo-sparsesparse), env copy, seed step, MCP demo run, optional CLI, troubleshooting table..env.example— Placeholder values only (your-pinecone-api-key-here,my-mcp-demo);PINECONE_DISABLE_SUGGEST_FLOW=truepre-set and explained; no Alliance defaults.seed-data.ts— Inserts 15 domain-neutral programming snippets (namespacequickstart) into both dense and sparse indexes using@pinecone-database/pineconeupsertRecords. Supports--dry-run. Guards against runningmain()when imported as a module.mcp-demo.ts— In-process MCP demo usingsetupCoreServer(package root only, no Alliance import) + linked transport + SDKClient. Callslist_namespaces,count, andquery(presetfast) in sequence.examples/alliance/(new directory, files moved)Moved via
git mv:suggest-flow-demo.ts,guided-query-demo.ts,library-embedding-demo.ts,custom-url-generator.ts,demo-mock-pinecone-client.ts.Added
examples/alliance/README.md— short banner noting Alliance surface (setupAllianceServer,suggest_query_params,guided_query, built-in URL generators), required env table, file table with run commands, and link back to quickstart for bootstrapping.examples/README.md(rewritten)Hub layout: "Generic quickstart (start here)" section first, "Alliance / advanced" section second, shared utilities (transport helper) at the bottom.
Root
README.mdexamples/quickstart/README.md.setupCoreServer, Alliance path forsetupAllianceServer, with corrected file links.PINECONE_INDEX_NAME).docs/CONFIGURATION.mdUpdated
examples/library-embedding-demo.tsreference toexamples/alliance/library-embedding-demo.ts..env.exampleAdded one-line comment pointing to
examples/quickstart/.env.examplefor onboarding.Acceptance criteria checklist
examples/alliance/npm run ci— 157 tests, 26 files, all green)Test plan
npm run ci(typecheck, lint, format, build, test:coverage) — passesnpx tsx examples/quickstart/seed-data.ts --dry-run— exits 0 with doc-only message (no env set)npx tsx examples/quickstart/mcp-demo.ts— exits 0 with doc-only message (no env set)npx tsx examples/alliance/suggest-flow-demo.ts— exits 0 with doc-only message (no env set)Related issues
close #108
Summary by CodeRabbit
Documentation
New Features