feat(plugin-mcp): add localization support to MCP resource operations #14334

stevenceuppens · 2025-10-24T11:06:31Z

What?

Adds full localization support to the MCP plugin's resource operations (create, update, find, delete).

Why?

The MCP plugin did not expose Payload's localization capabilities. Users with multilingual content could not create or manage translations through MCP, limiting the plugin's usefulness for international projects. This brings MCP feature parity with Payload's REST API.

How?

Add locale and fallbackLocale parameters to all resource tools (create, update, find, delete)
Pass locale parameters through to underlying Payload operations
Add comprehensive integration tests for localization features (6 new tests, all passing)
Update documentation with localization usage examples and MCP client configuration
Follow Payload REST API localization pattern for consistency

Testing:

pnpm test:int plugin-mcp
# All 15 tests passing (9 existing + 6 new localization tests)

Example Usage:

// Create content in English
{ "name": "createPosts", "arguments": { "title": "Hello", "locale": "en" }}

// Add Spanish translation
{ "name": "updatePosts", "arguments": { "id": "123", "title": "Hola", "locale": "es" }}

// Retrieve all translations
{ "name": "findPosts", "arguments": { "id": "123", "locale": "all" }}

Fixes #

Copilot

Pull Request Overview

This PR adds comprehensive localization support to the MCP plugin, enabling multilingual content management through MCP that matches Payload's REST API capabilities.

Key Changes:

Added locale and fallbackLocale parameters to all resource operations (create, update, find, delete)
Implemented 6 new integration tests covering localization scenarios (all passing)
Updated documentation with localization usage examples and MCP client setup guide

Reviewed Changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
test/plugin-mcp/int.spec.ts	Added 6 comprehensive localization tests and updated `getApiKey` helper to support update/delete permissions
test/plugin-mcp/config.ts	Configured localization with en/es/fr locales and enabled update/delete operations for Posts collection
test/plugin-mcp/collections/Posts.ts	Marked title and content fields as localized
packages/plugin-mcp/src/mcp/tools/schemas.ts	Added locale and fallbackLocale parameters to find, create, update, and delete tool schemas
packages/plugin-mcp/src/mcp/tools/resource/update.ts	Implemented locale parameter handling in update operation and added to schema
packages/plugin-mcp/src/mcp/tools/resource/find.ts	Implemented locale parameter handling in find operation
packages/plugin-mcp/src/mcp/tools/resource/delete.ts	Implemented locale parameter handling in delete operation
packages/plugin-mcp/src/mcp/tools/resource/create.ts	Implemented locale parameter handling in create operation with schema restructuring
docs/plugins/mcp.mdx	Added comprehensive documentation for MCP client setup and localization features with examples

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

kendelljoseph · 2025-10-27T15:11:23Z

This is a great start @stevenceuppens!

I'll dig into more detail today.

docs/plugins/mcp.mdx

DanRibbens

Looks like there are test failures need to be addressed https://github.com/payloadcms/payload/actions/runs/18868951904/job/53872817402?pr=14334#step:12:13889

The MCP plugin's resource tools (find, update, delete) were only accepting string IDs, which caused validation errors when using PostgreSQL. PostgreSQL uses numeric IDs by default, while MongoDB uses string-based ObjectIDs. Changes: - Updated ID parameter schemas to accept both string and number types - Added ID-to-string conversion in find, update, and delete tools - Ensured backward compatibility with MongoDB's string IDs This fixes test failures in PR payloadcms#14334 where all 4 localization tests were failing with "Expected string, received number" validation errors in the PostgreSQL integration test suite. All 15 tests now pass in both PostgreSQL and MongoDB. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

stevenceuppens · 2025-11-04T13:39:14Z

PR Update: PostgreSQL & Partial Update Fixes

Two commits added to resolve testing issues:

PostgreSQL ID Compatibility (`e004c551d`)

Issue: 4 localization tests failing in PostgreSQL due to numeric vs string ID mismatch
Fix: Updated MCP tool schemas to accept both string | number for IDs, with conversion to string for Payload operations
Files: Updated schemas and resource handlers (find/update/delete)

Partial Update Support (`1696f9ecc`)

Issue: Update tool required ALL fields, making single-field updates impossible
Fix: Applied .partial() to update schema, making all fields optional

- ...convertedFields.shape,
+ ...convertedFields.partial().shape,

Result: Both fixes maintain backward compatibility. All 15 tests pass in MongoDB and PostgreSQL.

The MCP plugin's resource tools (find, update, delete) were only accepting string IDs, which caused validation errors when using PostgreSQL. PostgreSQL uses numeric IDs by default, while MongoDB uses string-based ObjectIDs. Changes: - Updated ID parameter schemas to accept both string and number types - Added ID-to-string conversion in find, update, and delete tools - Ensured backward compatibility with MongoDB's string IDs This fixes test failures in PR payloadcms#14334 where all 4 localization tests were failing with "Expected string, received number" validation errors in the PostgreSQL integration test suite. All 15 tests now pass in both PostgreSQL and MongoDB. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

stevenceuppens · 2025-11-05T08:26:42Z

I've rebased this PR to resolve the merge conflicts.

stevenceuppens · 2025-11-06T09:46:53Z

@kendelljoseph @DanRibbens - can you give my PR another review :)

jonathanelmgren · 2025-11-07T13:26:19Z

Bumping this. Would be really nice to have and seems like an easy merge :)

stevenceuppens · 2025-11-13T10:07:44Z

@kendelljoseph @DanRibbens Can you give my PR another review please? 🙂

kendelljoseph · 2025-11-14T14:59:57Z

@stevenceuppens Hey! I'll look at this right now. Lets get this done today :)

kendelljoseph

This is looking and working great! A much needed improvement! There are also improvements in this PR for Postgres users too, so this is all around a great addition!

We just need to have code conflicts resolved.

The comments about docs you can do as a part of resolving as well -- if not, I will make those improvements with a docs only PR.

docs/plugins/mcp.mdx

packages/plugin-mcp/src/mcp/tools/resource/create.ts

docs/plugins/mcp.mdx

packages/plugin-mcp/src/mcp/tools/resource/delete.ts

- Add locale and fallbackLocale parameters to all resource tools (create, update, find, delete) - Add comprehensive integration tests for localization features - Update documentation with localization usage examples and MCP client configuration - Follow Payload REST API localization pattern for consistency

Updated documentation to accurately reflect that HTTP is the currently supported connection method, with REDIS and STDIO under consideration for future releases. Added a dedicated "Connection Methods" section with HTTP configuration example to provide clearer guidance for users. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

The MCP plugin's resource tools (find, update, delete) were only accepting string IDs, which caused validation errors when using PostgreSQL. PostgreSQL uses numeric IDs by default, while MongoDB uses string-based ObjectIDs. Changes: - Updated ID parameter schemas to accept both string and number types - Added ID-to-string conversion in find, update, and delete tools - Ensured backward compatibility with MongoDB's string IDs This fixes test failures in PR payloadcms#14334 where all 4 localization tests were failing with "Expected string, received number" validation errors in the PostgreSQL integration test suite. All 15 tests now pass in both PostgreSQL and MongoDB. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Previously, the MCP update tool required all collection fields to be provided when updating a document, even for partial updates. This was because the schema converter preserved the 'required' status of fields from the collection schema. Changes: - Use Zod's `.partial()` method on converted fields to make all fields optional - This allows updating a single field without providing all required fields - Maintains backward compatibility with full updates Fixes issue where users couldn't update a single field (like a title) without passing in all the document data. This was particularly problematic with complex nested fields like layout blocks. Example: Before: updatePosts({ id: 1, title: "New Title", content: "...", ... }) ❌ After: updatePosts({ id: 1, title: "New Title" }) ✅ All 15 tests pass in both PostgreSQL and MongoDB. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

@JarrodMFlesch

- Remove unnecessary String() conversions for IDs in delete, find, and update tools - Payload operations accept both string and number IDs natively - Conversion was confusing and didn't provide PostgreSQL compatibility benefits - Update MCP documentation: - Clarify HTTP-only transport support (remove REDIS/STDIO mentions) - Add detailed VSCode and Cursor MCP client configuration examples - Update localization examples to use proper JSON-RPC 2.0 format - Recommend npx mcp-remote approach for better compatibility Addresses review comments from @JarrodMFlesch and @kendelljoseph 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

…lity - Fix beforeRead hook in Posts collection to handle localized fields - Handle both object (localized) and string (non-localized) field values - Apply MCP hook override to all locale values when field is localized - Update test expectations to match new MCP hook behavior - Replace "Title Override: " prefix with " (MCP Hook Override)" suffix - Hook adds suffix to all localized values when locale="all" - Add products collection to API key in test helper - Fixes "should list tools" test expecting 4 tools 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

kendelljoseph

fix: id number | string for postgres
feat: CRUD resource tools support locale and fallbackLocale

Looks great, 👍🏿

DanRibbens

Thanks for the contribution!

Stale review

github-actions · 2025-11-25T18:47:26Z

🚀 This is included in version v3.65.0

stevenceuppens changed the title ~~feat(plugin-mcp): add localization support to resource operations~~ feat(mcp): add localization support to resource operations Oct 24, 2025

stevenceuppens changed the title ~~feat(mcp): add localization support to resource operations~~ feat: add localization support to MCP resource operations Oct 24, 2025

stevenceuppens mentioned this pull request Oct 24, 2025

feat: plugin mcp #13674

Merged

DanRibbens requested a review from kendelljoseph October 24, 2025 19:17

stevenceuppens mentioned this pull request Oct 24, 2025

feat: add globals support to MCP resource operations #14343

Draft

DanRibbens requested a review from Copilot October 27, 2025 14:52

Copilot AI reviewed Oct 27, 2025

View reviewed changes

kendelljoseph reviewed Oct 27, 2025

View reviewed changes

docs/plugins/mcp.mdx Outdated Show resolved Hide resolved

kendelljoseph reviewed Oct 27, 2025

View reviewed changes

docs/plugins/mcp.mdx Outdated Show resolved Hide resolved

stevenceuppens requested a review from kendelljoseph October 30, 2025 09:52

DanRibbens requested changes Oct 30, 2025

View reviewed changes

stevenceuppens requested a review from DanRibbens November 4, 2025 13:35

stevenceuppens force-pushed the mcp-localization branch from 1696f9e to ee08dd4 Compare November 5, 2025 08:24

kendelljoseph requested changes Nov 14, 2025

View reviewed changes

docs/plugins/mcp.mdx Outdated Show resolved Hide resolved

packages/plugin-mcp/src/mcp/tools/resource/create.ts Show resolved Hide resolved

docs/plugins/mcp.mdx Outdated Show resolved Hide resolved

docs/plugins/mcp.mdx Show resolved Hide resolved

JarrodMFlesch previously requested changes Nov 14, 2025

View reviewed changes

packages/plugin-mcp/src/mcp/tools/resource/delete.ts Outdated Show resolved Hide resolved

stevenceuppens and others added 6 commits November 15, 2025 14:53

stevenceuppens force-pushed the mcp-localization branch from ee08dd4 to d4ad382 Compare November 15, 2025 14:24

stevenceuppens requested review from JarrodMFlesch and kendelljoseph November 15, 2025 14:28

kendelljoseph added 5 commits November 20, 2025 10:55

Merge branch 'main' into mcp-localization

8700a5c

docs: updates docs

cee087e

chore: adds drafts arg

e639c78

chore: adds check for input schemas

89dcde8

chore: adds check for input schemas

e9f3927

kendelljoseph changed the title ~~feat: add localization support to MCP resource operations~~ feat(plugin-mcp): add localization support to MCP resource operations Nov 20, 2025

kendelljoseph assigned kendelljoseph and unassigned kendelljoseph Nov 20, 2025

kendelljoseph approved these changes Nov 20, 2025

View reviewed changes

DanRibbens approved these changes Nov 20, 2025

View reviewed changes

DanRibbens merged commit a3f490b into payloadcms:main Nov 20, 2025
186 of 188 checks passed

feat(plugin-mcp): add localization support to MCP resource operations #14334

feat(plugin-mcp): add localization support to MCP resource operations #14334

Uh oh!

Conversation

stevenceuppens commented Oct 24, 2025

What?

Why?

How?

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

kendelljoseph commented Oct 27, 2025

Uh oh!

Uh oh!

Uh oh!

DanRibbens left a comment

Choose a reason for hiding this comment

Uh oh!

stevenceuppens commented Nov 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Update: PostgreSQL & Partial Update Fixes

PostgreSQL ID Compatibility (e004c551d)

Partial Update Support (1696f9ecc)

Uh oh!

stevenceuppens commented Nov 5, 2025

Uh oh!

stevenceuppens commented Nov 6, 2025

Uh oh!

jonathanelmgren commented Nov 7, 2025

Uh oh!

stevenceuppens commented Nov 13, 2025

Uh oh!

kendelljoseph commented Nov 14, 2025

Uh oh!

kendelljoseph left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kendelljoseph left a comment

Choose a reason for hiding this comment

Uh oh!

DanRibbens left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Nov 25, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

stevenceuppens commented Nov 4, 2025 •

edited

Loading

PostgreSQL ID Compatibility (`e004c551d`)

Partial Update Support (`1696f9ecc`)