feat(mcp): add support to @paymesh/mcp

[almeidazs]

Summary by CodeRabbit

• New Features
  • Introduced @paymesh/mcp package enabling Paymesh clients to run as MCP servers for AI tools and editors.
  • Added paymesh mcp CLI command with support for Cursor, Claude Code, Open Code, and manual configuration.
  • Implemented customer lookup by email and external ID across all database adapters.
  • Added comprehensive MCP documentation and integration guides.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
paymesh	Ready	Preview, Comment	Jun 11, 2026 3:15pm

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR introduces a complete MCP (Model Context Protocol) server implementation for Paymesh, enabling AI clients to interact with Paymesh payment operations via standard MCP tools. The feature spans a new @paymesh/mcp package with server infrastructure, CLI configuration, database-backed customer lookups, and comprehensive tooling for introspection, customer management, and payment operations.

Changes

Complete MCP Server Implementation for Paymesh

Layer / File(s)	Summary
MCP Type System & Contracts packages/paymesh/src/types/mcp.ts, packages/mcp/src/types/index.ts	Introduces PaymeshMCPToolsOptions, PaymeshMCPOptions, PaymeshMCPMetadata type definitions; defines MCP_TOOL_AREAS constants and DEFAULT_MCP_CONFIG with tool area defaults and configuration limits.
Client-side MCP Integration packages/paymesh/src/types/client.ts, packages/paymesh/src/client/managers.ts, packages/paymesh/src/errors/index.ts	Adds $mcp property to PaymeshClient carrying merged metadata; augments client managers to construct $mcp from options and defaults; extends PaymeshErrorCode with 'mcp_error'.
Database Customer Lookup Methods packages/paymesh/src/types/database.ts, packages/drizzle/src/repositories.ts, packages/postgres/src/repositories.ts, packages/prisma/src/repositories.ts	Extends PaymeshCustomersRepository interface and all three database drivers with findByEmail and findByExternalId optional methods for direct customer lookup.
MCP Server Configuration & Validation packages/mcp/src/shared/config.ts	Merges client MCP metadata, CLI overrides, and defaults into ResolvedPaymeshMcpConfig; validates tool areas and maxListLimit with PaymeshError rejection.
MCP Server Factory & Entrypoint packages/mcp/src/server.ts, packages/mcp/src/index.ts	Creates McpServer instances with metadata and tool registration; exports public API surface (types, CLI, server, client, config helpers).
MCP Client Loading & Path Resolution packages/mcp/src/shared/client.ts	Loads Paymesh client modules dynamically (via jiti for TS or native import); resolves paths from explicit args, PAYMESH_PATH, or package.json; validates client shape.
Tool Input Schemas & Execution Helpers packages/mcp/src/shared/schema.ts, packages/mcp/src/shared/tool.ts	Defines Zod v4 schemas for tool input validation; implements assertServerCanStart, runTool (with sandbox/live-mode gating), and createToolResult for standardized MCP responses.
Introspection Tools (Capabilities & Provider Info) packages/mcp/src/tools/capabilities.ts, packages/mcp/src/tools/provider-info.ts	Implements capabilities_list (sorted enabled capability names) and provider_info (sandbox status, provider id, enabled capabilities).
Customer Operations Tools packages/mcp/src/tools/customers.ts	Implements customers_list, customers_get, customers_get_by_email, customers_get_by_external_id (with database or paginated fallback), plus conditional customers_upsert and customers_delete when not readonly.
Payment & PIX Operations Tools packages/mcp/src/tools/payments.ts, packages/mcp/src/tools/pix.ts	Implements payments_create and conditional read/write tools for PIX operations (pix_get, pix_create) with readonly gating and sandbox/includeRaw propagation.
Plugin Tools & Tool Aggregation packages/mcp/src/tools/plugins.ts, packages/mcp/src/tools/index.ts	Implements plugins_list tool; aggregates all tool definitions based on config.tools feature flags.
CLI Command & Helper Infrastructure packages/cli/src/shared/mcp.ts, packages/cli/src/commands/mcp.ts, packages/cli/src/index.ts	Registers paymesh mcp CLI subcommand; implements setup flows for Cursor (deeplink), Claude Code/Codex (spawnSync), Open Code (opencode.json merge), and manual; provides config building, deeplink generation, and JSON/TOML formatting helpers.
MCP CLI Entrypoint & Server Startup packages/mcp/src/cli.ts	Implements paymesh-mcp entrypoint with commander-based argument parsing, option coercion, client/config/server initialization, stdio transport, and graceful shutdown on process signals.
MCP Test Suite & Configuration packages/mcp/test/mcp.test.ts, packages/mcp/tsconfig.json, packages/mcp/tsdown.config.mjs	Comprehensive Bun test suite covering client loading, config merging, tool registration, limit enforcement, live-mode gating, CLI parsing, and structured results; includes TypeScript and build configs.
CLI Tests & Build Configuration Integration packages/cli/test/cli.test.ts, package.json	Updates CLI test assertions to use correct promise patterns; adds tests for MCP command output and opencode.json configuration; adds mcp and abacatepay to typecheck script filter.
MCP Package Configuration & Build Setup packages/mcp/package.json	Defines ESM package with CLI binary (paymesh-mcp), conditional ESM/CJS exports, peer dependency on paymesh, build/typecheck scripts, and runtime dependencies (@modelcontextprotocol/sdk, commander, jiti, zod).
User Documentation & Navigation apps/web/content/docs/mcp.mdx, apps/web/src/lib/docs-navigation.ts, apps/web/.source/browser.ts, apps/web/.source/server.ts, packages/mcp/README.md	Adds comprehensive MCP documentation page with installation, CLI usage, tool descriptions, config precedence, and examples; updates web docs collection and navigation to include published MCP page.
Release Notes & Repository Cleanup .changeset/complete-mcp-release.md, .gitignore	Adds changeset declaring minor bumps for @paymesh/mcp, paymesh, @paymesh/postgres, @paymesh/drizzle, @paymesh/prisma; updates .gitignore pattern for root-level client.ts.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• usepaymesh/paymesh#24: Adds support to plugins, providing the plugin infrastructure that the plugins_list MCP tool builds upon.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	No pull request description was provided; the author left it empty despite the template requiring sections like Description, Related Issues, and a Checklist.	Add a description covering what was implemented, which issues it closes, confirmation of the checklist items, and any relevant notes about the MCP feature.
Docstring Coverage	⚠️ Warning	Docstring coverage is 1.82% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat(mcp): add support to @paymesh/mcp' clearly and specifically describes the main change—introducing MCP support to the Paymesh package.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/mcp

---

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