feat: add referenceURL lookup and Vitest integration test suite

[darylrobbins]

Summary

• referenceURL lookup: Adds referenceURL parameter to get_record_by_identifier for x-devonthink-item:// URL lookup, supporting both UUID and non-UUID formats (e.g. imported emails with message-ID-based reference URLs). Uses two-tier lookup: UUID fast path → lookupRecordsWithURL scan across databases.
• Integration test refactor: Replaces monolithic regression-test.ts with a proper Vitest integration test suite split by domain (connectivity, CRUD, identification, organization, transformation, network, AI). Tests use globalSetup/globalTeardown with an isolated temp database, ensuring no impact on production data. Covers 28 tests across all 27 MCP tools.

Test plan

• Run npm test — unit tests pass
• Run npm run test:integration — 28 integration tests pass (1 skipped: selected_records requires UI)
• Verify temp database is created and cleaned up automatically
• Verify no records leak into global inbox or production databases
• Test get_record_by_identifier with referenceURL for UUID-format URLs
• Test get_record_by_identifier with referenceURL for email message-ID URLs

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello, 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 significantly improves the DEVONthink integration by enabling more flexible record identification through referenceURL lookups and by modernizing the testing infrastructure. The new referenceURL capability allows for more reliable retrieval of records, especially for items like imported emails that don't use standard UUIDs. Concurrently, the introduction of a Vitest-based integration test suite enhances the reliability and maintainability of the codebase by providing isolated, domain-specific tests that ensure the stability of all 27 MCP tools without affecting production data.

Highlights

• Enhanced Record Identification: Implemented a new referenceURL parameter in get_record_by_identifier to support x-devonthink-item:// URLs, including non-UUID formats like message-IDs for imported emails, using a robust three-tier lookup mechanism.
• Refactored Integration Test Suite: Replaced the previous monolithic regression-test.ts with a comprehensive, modular Vitest integration test suite, organized by domain (connectivity, CRUD, identification, organization, transformation, network, AI) and utilizing an isolated temporary database for clean, non-destructive testing.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• .gitignore
  • Added .worktrees to ignored files.
• package.json
  • Added a new test:integration script to run the Vitest integration tests.
• src/tools/getRecordByIdentifier.ts
  • Added referenceURL as an optional string parameter to the GetRecordByIdentifierSchema.
  • Updated the schema's refinement logic to allow referenceURL as a valid identifier.
  • Included referenceURL in the RecordResult interface.
  • Modified the getRecordByIdentifier function to implement a three-tier lookup for referenceURL (UUID fast path, lookupRecordsWithURL, brute-force referenceURL() comparison).
  • Updated the tool's description to include examples for referenceURL usage.
• tests/integration/ai.test.ts
  • Added new integration tests for AI-related functionalities, including checking AI health and asking questions about documents.
• tests/integration/connectivity.test.ts
  • Added new integration tests to verify DEVONthink's running status, database listing, and API compatibility.
• tests/integration/crud.test.ts
  • Added new integration tests for create, read, update, and delete operations on DEVONthink records.
• tests/integration/helpers.ts
  • Added utility functions for integration tests, such as JXA execution, test context management, record creation, group creation, and record deletion.
• tests/integration/identification.test.ts
  • Added new integration tests for various record identification methods, including UUID, referenceURL, filename, comment, and tags.
• tests/integration/network.test.ts
  • Added new integration tests for network-related operations, specifically creating records from URLs.
• tests/integration/organization.test.ts
  • Added new integration tests for organizing records, including listing group content, adding/removing tags, moving, replicating, and duplicating records.
• tests/integration/regression-test.ts
  • Removed the old, monolithic regression-test.ts file.
• tests/integration/setup.ts
  • Added a global setup script for integration tests to create a temporary DEVONthink database and an .eml file, and a teardown script to clean them up.
• tests/integration/transformation.test.ts
  • Added new integration tests for record transformation functionalities like converting and classifying records.
• tests/integration/vitest.integration.config.ts
  • Added a dedicated Vitest configuration file for integration tests, specifying inclusion patterns and global setup.
• vitest.config.ts
  • Updated the main Vitest configuration to exclude integration test files from standard unit test runs.

Activity

• The pull request description was generated using Claude Code.

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 introduces a valuable new lookup method using referenceURL and significantly improves the project's quality by adding a comprehensive Vitest integration test suite. While the new referenceURL feature is well-implemented with proper escaping for string inputs, a critical JXA injection vulnerability was identified in the existing id lookup logic. The id parameter, expected to be a number, is interpolated directly into the JXA script without validation, allowing for arbitrary code execution if a malicious string is provided. This requires immediate remediation by ensuring runtime validation of the id parameter. Furthermore, I've identified two potential issues in the getRecordByIdentifier implementation: a possible bug related to UUID case-sensitivity and a significant performance concern with the fallback lookup mechanism.

[darylrobbins]

@gemini-code-assist review

[gemini-code-assist]

Code Review

This pull request introduces referenceURL lookup capabilities and refactors the testing approach into a robust Vitest integration suite. While the new test suite is well-structured and get_record_by_identifier follows JXA best practices, a critical security vulnerability exists: the existing id lookup logic remains vulnerable to JXA injection. The id parameter is directly interpolated without validation, potentially leading to Remote Code Execution (RCE) via prompt injection. It is strongly recommended to use the formatValueForJXA helper for all interpolated values. Furthermore, the referenceURL lookup implementation may not work as intended for non-UUID URLs and lacks sufficient test coverage.

[darylrobbins]

@gemini-code-assist review

All feedback addressed:

• id injection (critical): Added runtime type check + formatValueForJXA(id) for safe interpolation
• UUID case sensitivity: Added .toUpperCase() to UUID fast path
• Brute-force fallback: Removed entirely, replaced with URL-decode + getRecordWithUuid() tier
• Non-UUID referenceURL lookup: New tier 2 decodes percent-encoded identifiers (handles email message-IDs)
• Test coverage: referenceURL_email test now exercises the actual lookup path end-to-end

[gemini-code-assist]

Code Review

This pull request introduces two major improvements: a new Vitest integration test suite and the implementation of referenceURL lookup in get_record_by_identifier. A security audit focused on the new referenceURL lookup logic, specifically addressing potential JXA (JavaScript for Automation) Injection due to user-supplied inputs being injected into scripts executed via osascript. However, the implementation uses robust escaping and validation, including isJXASafeString, escapeStringForJXA, formatValueForJXA, and secure execution with execFile. No vulnerabilities meeting the criteria for reporting (medium severity or higher) were identified. There is one minor suggestion to improve the efficiency of the fallback lookup logic.

[dvcrn]

Thanks for the PR! Why did you close and delete this @darylrobbins ?

[darylrobbins]

Thanks for the PR! Why did you close and delete this @darylrobbins ?

Claude got a bit overzealous when I asked it to merge the changes into my fork.

[darylrobbins]

@gemini-code-assist review

[gemini-code-assist]

Code Review

This pull request introduces two major improvements: it adds support for referenceURL lookup in the get_record_by_identifier tool and completely refactors the testing infrastructure to a modern Vitest-based integration suite. The implementation for referenceURL lookup is robust, handling both standard UUID-based and non-UUID (e.g., email message-ID) x-devonthink-item:// URLs. The accompanying fix in lookup_record to correctly handle these URLs is also a valuable addition. The new integration test suite is a significant enhancement, providing isolated, comprehensive, and reliable testing for all tools against a live DEVONthink instance. The code quality is high, adhering to the project's JXA scripting best practices, and the documentation has been updated accordingly. Overall, this is an excellent contribution that improves both functionality and maintainability. I have not found any issues that meet the required severity threshold for comments.

[darylrobbins]

@dvcrn This one should be ready to go.

[dvcrn]

Thanks, looks good to me! Could you run the formatter, then I'll merge this

[darylrobbins]

@dvcrn Formatted

[dvcrn]

Released in https://github.com/dvcrn/mcp-server-devonthink/releases/tag/1.8.0