PayMCP
by SKSAMIMGOOD
README.md
# PayMCP
**PayMCP is an MCP server that audits Razorpay payment integrations in Next.js App Router + TypeScript projects.**
It helps AI coding agents and developers detect common payment-integration mistakes **before they become security or production problems**.
PayMCP is **verification-first and read-only**:
* 🔍 Inspects your project statically
* 🔐 Detects common payment-security mistakes
* 📊 Produces a deterministic engineering score
* 🧾 Returns redacted evidence
* 🧪 Provides Test Mode readiness checks
* 🛠️ Explains audit findings
* 💡 Suggests fixes without modifying your files
> **Important:** A PayMCP static PASS is not a payment, compliance, security, or production certification.
---
# What PayMCP Does
A typical Razorpay integration has several places where things can go wrong:
```text
Your Next.js App
│
┌──────────────┼──────────────┐
│ │ │
Create Order Checkout Webhook
│ │ │
▼ ▼ ▼
Razorpay API Client Your Server
│
▼
Verify Signature
│
▼
Fulfill
```
PayMCP examines your implementation and looks for problems such as:
* Razorpay secrets exposed to the client
* Hardcoded API keys
* Client-controlled payment amounts
* Missing payment signature verification
* Missing webhook verification
* Incorrect webhook-body handling
* Incorrect webhook-secret configuration
* Client-side fulfillment before verification
* Fulfillment before payment confirmation
* Missing idempotency protection
* Capture confirmation problems
* Test/Live environment mixing
* Unsafe refund authorization
---
# Supported Stack
PayMCP V0.1 currently focuses on:
| Component | Support |
| ---------------------------------- | ------------ |
| Payment provider | Razorpay |
| Framework | Next.js |
| Routing | App Router |
| Language | TypeScript |
| Static analysis | ✅ |
| Test Mode runtime validation | ✅ Controlled |
| Payment processing | ❌ |
| Live transactions | ❌ |
| Credential storage | ❌ |
| Automatic source-code modification | ❌ |
| Dashboards | ❌ |
| Other payment providers | ❌ |
---
# Quick Start
If you only want to get PayMCP running, follow these steps.
## Step 1 — Install Node.js
PayMCP is a Node.js application.
Install a current supported Node.js version from:
[Node.js](https://nodejs.org/?utm_source=chatgpt.com)
Check your installation:
```bash
node --version
npm --version
```
---
# Step 2 — Install PayMCP
## Option A — Recommended: npx
```bash
npx -y paymcp-security
```
This downloads and runs the published PayMCP package directly. No global installation is required.
## Option B — Global installation
```bash
npm install -g paymcp-security
```
Then run:
```bash
paymcp-security
```
> If `paymcp-security` has not yet been published to npm, use the GitHub installation method below.
---
# Step 3 — Install from GitHub
For development or pre-publication use:
```bash
git clone https://github.com/SKSAMIMGOOD/PayMCP.git
cd PayMCP
npm install
```
Build the project:
```bash
npm run build
```
Start the MCP server:
```bash
node dist/index.js
```
You normally do **not** need to manually start this process when your MCP client is configured to launch PayMCP for you.
---
# Step 4 — Connect PayMCP to Your MCP Client
PayMCP uses the **MCP stdio transport**.
Your MCP client needs to know:
1. What command to run
2. Which PayMCP executable to use
3. Where the project being audited is located
The exact configuration format depends on the MCP client.
---
## Option A — Using npx
After PayMCP is published to npm:
```json
{
"mcpServers": {
"paymcp": {
"command": "npx",
"args": ["-y", "paymcp-security"]
}
}
}
```
This allows the MCP client to launch PayMCP using `npx`.
---
## Option B — Using a global installation
If you installed:
```bash
npm install -g paymcp-security
```
use:
```json
{
"mcpServers": {
"paymcp": {
"command": "paymcp-security"
}
}
}
```
---
## Option C — Using the local GitHub build
If you cloned the repository and built it locally:
```bash
npm run build
```
your MCP configuration can point directly to:
```text
dist/index.js
```
Example:
```json
{
"mcpServers": {
"paymcp": {
"command": "node",
"args": [
"/absolute/path/to/PayMCP/dist/index.js"
]
}
}
}
```
### Windows example
```json
{
"mcpServers": {
"paymcp": {
"command": "node",
"args": [
"C:\\Users\\YourName\\PayMCP\\dist\\index.js"
]
}
}
}
```
### macOS/Linux example
```json
{
"mcpServers": {
"paymcp": {
"command": "node",
"args": [
"/Users/YourName/PayMCP/dist/index.js"
]
}
}
}
```
> Use an **absolute path** for the local build.
---
# Step 5 — Restart Your MCP Client
After adding PayMCP to your MCP configuration:
1. Save the configuration.
2. Completely restart your MCP client.
3. Open your Next.js project.
4. Check that PayMCP is available as an MCP server/tool.
The exact UI and configuration location varies between MCP clients.
---
# Step 6 — Give PayMCP Your Project Root
PayMCP intentionally does **not** automatically scan your computer.
Every filesystem operation requires an explicit:
```text
projectRoot
```
For example:
```text
C:\Users\YourName\Projects\my-store
```
or:
```text
/Users/YourName/projects/my-store
```
This is an important part of PayMCP's security model.
### Why?
Instead of giving the MCP server broad access like:
```text
C:\
```
you give it only:
```text
C:\Users\YourName\Projects\my-store
```
PayMCP then restricts project file access to that supplied root.
---
# Your First Audit
Once PayMCP is connected, open the Next.js project you want to inspect.
Then ask your AI coding agent something like:
> **Audit my Razorpay payment integration using PayMCP. Use my current project as the projectRoot and explain every security finding.**
Your MCP client should use:
```text
audit_payment_integration
```
with the appropriate project root.
Conceptually:
```json
{
"projectRoot": "/absolute/path/to/my-nextjs-project"
}
```
PayMCP will inspect the project without modifying it.
---
# What the Audit Returns
The audit provides structured results containing information such as:
```text
Audit
├── Findings
│ ├── severity
│ ├── confidence
│ ├── rule
│ └── redacted evidence
│
├── Engineering Score
│
├── Test Mode Readiness
│
└── Caveats
```
The evidence is deliberately redacted before it is returned over MCP.
---
# Understanding the PayMCP Tools
PayMCP provides several MCP tools.
## 1. `list_payment_providers`
Shows the payment providers and technology stacks supported by PayMCP.
Current V0.1 support includes:
```text
Razorpay
Next.js App Router
TypeScript
```
Use this when you want to check whether your project is supported.
---
## 2. `get_payment_requirements`
Returns the security and architecture requirements PayMCP expects for a Razorpay + Next.js integration.
Useful before implementing a payment system.
Example request to your AI agent:
> Show me the Razorpay payment requirements supported by PayMCP.
---
## 3. `audit_payment_integration`
This is the **main static auditing tool**.
It examines the project for known payment-integration problems.
Example:
> Audit my Razorpay integration and show me all high-confidence security findings.
It can identify issues involving:
* Client-visible secrets
* Hardcoded keys
* Client-controlled amounts
* Signature verification
* Webhooks
* Fulfillment
* Idempotency
* Capture confirmation
* Environment configuration
* Refund authorization
### Important
This tool:
```text
Reads project → Analyzes code → Returns findings
```
It does **not**:
```text
Modify files
Start your application
Contact Razorpay
Process payments
```
---
# 4. `test_payment_integration`
This checks the architecture and readiness of the payment integration.
It is a **static/readiness check**, not a real payment test.
Example:
> Check whether my Razorpay integration is ready for Test Mode.
It does not contact Razorpay or your running application.
---
# 5. `test_payment_transaction`
This is different from the static audit.
It performs a controlled Test Mode runtime validation against an **already-running application**.
Important restrictions:
* Requires an explicit base URL
* Uses secure host-environment credentials
* Never accepts secrets as tool arguments
* Never starts your project commands
* Does not perform uncontrolled live transactions
* Stops for manual checkout
For example, your application might already be running at:
```text
http://localhost:3000
```
Then the runtime test can validate the controlled payment flow.
### Static vs Runtime
```text
PayMCP
│
┌─────────┴─────────┐
│ │
STATIC AUDIT RUNTIME TEST
│ │
▼ ▼
Read source code Running app
│ │
▼ ▼
Find architecture Test controlled
problems Test Mode flow
```
A static PASS and runtime result are **separate pieces of evidence**.
---
# 6. `generate_payment_integration`
This provides a deterministic, self-audited **dry-run implementation plan**.
It does not write source files.
Think of it as:
```text
Requirements
↓
Implementation plan
↓
Self-audit
↓
File/change plan
```
It is useful when you want to plan a Razorpay integration before actually implementing it.
Example:
> Generate a Razorpay payment integration plan for this Next.js project, but do not modify any files.
---
# 7. `debug_payment`
This explains existing audit findings.
Example:
> Explain the Razorpay security findings from the PayMCP audit and tell me why each one matters.
It is:
* Read-only
* Deterministic
* Static
It does not modify your project or contact Razorpay.
---
# 8. `suggest_payment_fix`
This creates a read-only, evidence-based plan that an AI coding agent can use to manually fix an issue.
Example:
> Suggest fixes for the payment audit findings, but don't modify my files.
The important distinction is:
```text
PayMCP
│
├── Detects problem
├── Explains problem
└── Suggests fix
│
▼
AI coding agent
│
▼
Developer approves
│
▼
Code is modified
```
PayMCP itself does not modify your project.
---
# Recommended Workflow
For a real project, I recommend using the tools in this order:
```text
┌─────────────────────┐
│ Existing Next.js │
│ project │
└──────────┬──────────┘
│
▼
┌───────────────────────┐
│ list_payment_providers│
└───────────┬───────────┘
│
▼
┌───────────────────────┐
│ get_payment_requirements
└───────────┬───────────┘
│
▼
┌───────────────────────┐
│ audit_payment_ │
│ integration │
└───────────┬───────────┘
│
▼
Findings?
/ \
YES NO
│ │
▼ ▼
debug_payment Test Mode
│ readiness
▼
suggest_payment_fix
│
▼
Developer/AI agent
applies fixes
│
▼
Run audit again
│
▼
test_payment_transaction
│
▼
Manual Test Mode checkout
```
---
# Example Prompts
You don't need to manually understand MCP JSON to use PayMCP.
Your AI coding agent can invoke the appropriate tools based on your request.
### Basic audit
> Audit my Razorpay integration using PayMCP.
### Security audit
> Perform a security-focused audit of my Razorpay payment integration. Identify secrets, signature verification, webhook, amount manipulation, and fulfillment issues.
### Explain findings
> Explain every PayMCP finding in simple terms and tell me what could go wrong in production.
### Fix planning
> Create a safe implementation plan to fix all PayMCP findings. Do not modify my files.
### Test readiness
> Check whether my Razorpay integration is ready for Test Mode.
### Re-audit after changes
> Re-run the PayMCP audit and compare the current implementation against the previous findings.
---
# Security Model
PayMCP is designed to minimize filesystem and credential exposure.
## Project access
Filesystem reads are restricted to the supplied:
```text
projectRoot
```
PayMCP rejects:
* Directory traversal
* Symlink escapes
---
## Files PayMCP does not read
`.env` files are excluded.
Dependency/build directories and binaries are also skipped.
Individual file reads are capped at:
```text
1 MB
```
---
# Secrets
PayMCP does not require you to put payment secrets into MCP tool arguments.
**Never put Razorpay secrets into source code.**
Your Razorpay Key Secret should remain server-side and should be managed through environment variables or an appropriate secrets-management system.
PayMCP's audit is designed to detect unsafe secret exposure without intentionally exposing the secret itself.
---
# Important: What PayMCP Does NOT Do
PayMCP is not a payment gateway.
It does not:
* Process payments
* Hold money
* Store Razorpay credentials
* Perform live transactions
* Replace Razorpay
* Guarantee production security
* Guarantee PCI/compliance status
* Automatically modify your application
* Deploy your application
* Host your application
The relationship is:
```text
Razorpay
│
│ Payment processing
▼
Your Next.js application
│
│ Source code
▼
PayMCP
│
├── Audit
├── Verify architecture
├── Explain findings
└── Suggest fixes
```
---
# Test Mode
PayMCP supports a deliberately constrained Test Mode runtime workflow.
For development:
```text
Use Razorpay Test Mode
↓
Create Test Mode keys
↓
Configure your application
↓
Run your application
↓
Use PayMCP static audit
↓
Use PayMCP runtime validation
↓
Complete manual checkout when requested
```
**Do not use Live Mode credentials for development.**
---
# Development
Clone the repository:
```bash
git clone https://github.com/SKSAMIMGOOD/PayMCP.git
cd PayMCP
```
Install dependencies:
```bash
npm install
```
Run type checking:
```bash
npm run typecheck
```
Run tests:
```bash
npm test
```
Build:
```bash
npm run build
```
Run the built server:
```bash
node dist/index.js
```
---
# Audit Rules
The P0 static rules cover areas including:
* Client-visible secrets
* Hardcoded key literals
* Client-controlled amounts
* Missing payment verification
* Missing webhook verification
* Raw webhook-body misuse
* Webhook secret configuration
* Client-side fulfillment
* Pre-verification fulfillment
* Idempotency
* Capture confirmation
* Environment mixing
* Refund authorization
Findings include confidence levels because static source inspection cannot prove every aspect of runtime behavior.
---
# Static Analysis Limitations
Static analysis has limits.
For example, PayMCP can identify code patterns that strongly indicate missing signature verification.
However, source inspection alone cannot prove:
```text
"the production webhook always behaves correctly"
```
or:
```text
"the Razorpay dashboard is configured correctly"
```
Therefore PayMCP reports confidence levels and caveats.
Think of the result as:
```text
Engineering evidence
≠
Production certification
```
---
# Troubleshooting
## PayMCP does not appear in my MCP client
Check:
1. Node.js is installed.
2. PayMCP builds successfully.
3. The MCP configuration is valid.
4. The executable/path is correct.
5. You restarted the MCP client.
6. The path to `dist/index.js` is absolute when using a local build.
---
## `npx paymcp-security` does not work
If the npm package has not yet been published, use the GitHub installation:
```bash
git clone https://github.com/SKSAMIMGOOD/PayMCP.git
cd PayMCP
npm install
npm run build
node dist/index.js
```
Then configure your MCP client to use the local build.
---
## Audit cannot access my project
Make sure the MCP request contains an explicit:
```text
projectRoot
```
and that it points to the root directory of your project.
For example:
```text
C:\Users\YourName\Projects\my-shop
```
not:
```text
C:\
```
---
## Why doesn't PayMCP read my `.env` file?
This is intentional.
PayMCP is designed to avoid reading `.env` files and exposing credentials through the MCP interface.
You should never need to send your Razorpay Key Secret to PayMCP as a tool argument.
---
# Frequently Asked Questions
## Does PayMCP modify my code?
**No.**
The audit, testing, debugging, and suggestion workflows are designed to be read-only.
---
## Does PayMCP contact Razorpay?
Static auditing does **not** contact Razorpay.
The controlled `test_payment_transaction` workflow is specifically designed for Test Mode runtime validation and is separate from the static audit.
---
## Does PayMCP store my Razorpay credentials?
No.
PayMCP does not provide credential storage or hosted credential management.
---
## Can I use PayMCP with any payment provider?
Not currently.
V0.1 is intentionally focused on:
```text
Razorpay + Next.js App Router + TypeScript
```
---
## Does a PASS mean my payment system is secure?
No.
A PASS means PayMCP did not identify the problems covered by its current static rules/readiness checks.
It is **not** a security certification, compliance certification, or guarantee that your production payment system is safe.
---
# Documentation
Detailed documentation:
* [Agent Audit Workflow](docs/agent-workflow.md)
* [Generator](docs/generator.md)
* [Runtime Testing](docs/runtime-testing.md)
---
# Repository
GitHub:
[PayMCP on GitHub](https://github.com/SKSAMIMGOOD/PayMCP?utm_source=chatgpt.com)
---
# License
MIT License.
Runtime validation is documented in [runtime-testing.md](docs/runtime-testing.md). A static PASS and runtime result remain separate evidence.
## License
[MIT](LICENSE)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues