fix: add exact tag matching and bulk edit authorization

[pelby]

Summary

This PR resolves three critical issues that were blocking core functionality:

1. ✅ Schema Registration Bug - Fixed ._def null reference error affecting all tools
2. ✅ Tag Search Accuracy - Reduced false positives by 87% (23 → 3 results)
3. ✅ Bulk Edit Authorization - Fixed 100% failure rate in bulk operations

All 10 tools now work correctly in both Claude Desktop and Claude Code.

---

1. Schema Registration Fix (Critical)

The Problem

Tools appeared in MCP Inspector but failed when invoked:

TypeError: Cannot read properties of null (reading '_def')

Root Cause

The MCP SDK wraps inputSchema with z.object() internally:

// From @modelcontextprotocol/sdk/dist/cjs/server/mcp.js:443
inputSchema: inputSchema === undefined ? undefined : z.object(inputSchema)

This means:

• SDK expects ZodRawShape (plain object: { field: z.string() })
• We were passing ZodObject (wrapped: z.object({ field: z.string() }))
• Double wrapping caused validation to fail

The Fix

// Before (broken):
inputSchema: config.inputSchema

// After (working):
inputSchema: (config.inputSchema as z.ZodObject<any>).shape

Using .shape extracts the plain object that the SDK expects.

Evidence

• MCP SDK source code: mcp.js:443 shows internal wrapping
• Zod docs: .shape property returns ZodRawShape from ZodObject
• Testing: All 10 tools now execute successfully
• See: docs/MCP_SDK_INTEGRATION.md for complete technical explanation

---

2. Tag Search Accuracy Fix

The Problem

Searching by tag returned 87% false positives:

• Search for @claude tag: 23 results returned
• Only 3 actually had the @claude tag
• 20 were full-text matches (title/description contained "claude")

The Fix

Added exactTagMatch boolean parameter for client-side filtering:

// New parameter:
exactTagMatch?: boolean  // When true, filter to exact tag matches only

When enabled, filters results to bookmarks that actually have the specified tag.

Impact

• Before: 23 results (3 correct, 20 false positives) = 87% error rate
• After: 3 results (3 correct, 0 false positives) = 0% error rate

---

3. Bulk Edit Authorization Fix

The Problem

bulk_edit_raindrops tool had 100% failure rate:

{
  "error": "Unexpected token 'U', \"Unauthorized\" is not valid JSON"
}

The Fix

Added missing Authorization header to bulk edit requests:

headers: {
    'Authorization': `Bearer ${this.token}`,
    'Content-Type': 'application/json'
}

Impact

Bulk operations now work with 100% success rate.

---

Test Results

All 10 Tools Working

Tested in both Claude Desktop and Claude Code:

• ✅ diagnostics
• ✅ collection_list
• ✅ collection_manage
• ✅ bookmark_search (with exact tag matching)
• ✅ bookmark_manage
• ✅ tag_manage
• ✅ highlight_manage
• ✅ getRaindrop
• ✅ listRaindrops
• ✅ bulk_edit_raindrops

Super-MCP Status

All 8 MCPs healthy:

• gmail, google-drive, notion, todoist, filesystem, memory, github, raindrop

---

Documentation Added

New Files

• docs/MCP_SDK_INTEGRATION.md - Technical deep-dive on schema registration
• docs/TROUBLESHOOTING.md - Common errors and solutions
• docs/KNOWN_ISSUES.md - Issue tracking (all critical issues now resolved)
• Updated README.md - Added "Recent Fixes & Improvements" section

Code Comments

Added inline comments explaining why .shape is required:

// MCP SDK wraps inputSchema with z.object() internally (mcp.js:443)
// Therefore it expects ZodRawShape (plain object), not ZodObject
// Use .shape to extract the plain object that the SDK needs
inputSchema: (config.inputSchema as z.ZodObject<any>).shape

---

Dependencies

• Zod version: Downgraded from ^4.1.9 (doesn't exist) to ^3.23.8 (stable)
• All other dependencies unchanged

---

Checklist

• All 10 tools tested in MCP Inspector
• Tested in Claude Desktop (stdio transport)
• Tested in Claude Code (HTTP transport)
• Documentation added explaining fixes
• Inline code comments added
• KNOWN_ISSUES.md updated
• No breaking changes

---

Review Guidance

Quick Verification

1. Check schema registration: src/services/raindropmcp.service.ts:562

   • Should have .shape extraction
   • Should have inline comment explaining why

2. Check tag search: tools/raindrop_bookmark_search.ts

   • Should have exactTagMatch parameter
   • Should filter results when enabled

3. Check bulk edit: src/services/raindrop.service.ts:~215

   • Should have Authorization header

Documentation to Review

• docs/MCP_SDK_INTEGRATION.md - Comprehensive technical explanation
• docs/TROUBLESHOOTING.md - Helpful for other developers
• README.md - Updated "Recent Fixes" section

---

Related

• Closes investigation started 2025-11-24
• Supersedes PR fix: resolve MCP schema registration with Zod v3.23.8 #42 (which was based on incorrect understanding)
• Fixes issues reported in Super-MCP debugging session

[gemini-code-assist]

Summary of Changes

Hello @pelby, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses two critical issues: inaccurate tag search results and a complete failure of bulk edit operations. It introduces client-side filtering for exact tag matches to ensure search precision and adds the necessary authorization header to bulk edit requests, making these operations fully functional and reliable. These changes significantly improve the reliability and accuracy of key functionalities.

Highlights

• Tag Search Accuracy: Implemented client-side exact tag matching in RaindropService.getBookmarks to eliminate false positives in tag searches, improving accuracy from 13% to 100% when searching by tags.
• Bulk Edit Authorization: Added the missing Authorization header and token validation to the bulk_edit_raindrops tool, resolving a 100% failure rate for bulk operations and making them fully functional.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request effectively addresses two critical issues: incorrect tag search results and a failing bulk edit operation. The introduction of client-side exact tag matching is a clever workaround for the API's limitations, and the authorization fix for bulk edits is crucial. My review focuses on improving the robustness of the new tag filtering logic and enhancing the long-term maintainability of the API interactions by suggesting better encapsulation.