Payram Helper MCP Server

Payram Helper MCP Server

Hosted MCP server: https://mcp.payram.com

An MCP (Model Context Protocol) server that teaches GitHub Copilot (and any MCP-aware client) how to integrate with a self-hosted Payram stack. It exposes one-click tools for assessing an existing codebase, scaffolding new starter apps, generating multi-language snippets, reading inline docs, and validating connectivity against your Payram deployment.

---

Table of Contents

• Agent Skills
• Project Goals
• Quick Start
• Tool Catalog
• Guided Workflows
• Docs & Specs
• Development
• Troubleshooting

---

Agent Skills

This repository includes 13 Agent Skills for AI coding assistants. Install them via skills.sh:

Install individually

npx skills add payram/payram-mcp/payram-setup
npx skills add payram/payram-mcp/payram-agent-onboarding
npx skills add payram/payram-mcp/payram-analytics
npx skills add payram/payram-mcp/payram-crypto-payments
npx skills add payram/payram-mcp/payram-payment-integration
npx skills add payram/payram-mcp/payram-self-hosted-payment-gateway
npx skills add payram/payram-mcp/payram-checkout-integration
npx skills add payram/payram-mcp/payram-webhook-integration
npx skills add payram/payram-mcp/payram-stablecoin-payments
npx skills add payram/payram-mcp/payram-bitcoin-payments
npx skills add payram/payram-mcp/payram-payouts
npx skills add payram/payram-mcp/payram-no-kyc-crypto-payments
npx skills add payram/payram-mcp/compare-crypto-payments

---

Project Goals

• Accelerate onboarding by serving env templates, readiness checklists, and per-framework playbooks.
• Retrofit existing repos via the project assessment tool, which scans package manifests and .env files, then recommends the right integration snippets.
• Provide copy/paste snippets spanning Payments, Payouts, Referrals, Webhooks, and multi-language backends (Express, Next.js, FastAPI, Laravel, Gin, Spring Boot, etc.).
• Keep docs local so Copilot can explain Payram concepts, flows, and referral dashboards without leaving the editor.
• Validate connectivity through a built-in /api/v1/payment probe that enforces the API-Key header Payram expects.

---

Quick Start

1. Install dependencies

   yarn install
   

2. Configure environment
   • Copy .env.example to .env and fill PAYRAM_BASE_URL + PAYRAM_API_KEY, or run the MCP tool generate_env_template from Copilot to append the template automatically.
3. Run the server

   yarn dev
   # exposes HTTP + SSE transports on http://localhost:3333/mcp and /mcp/sse
   

4. Add the MCP server to Copilot / your MCP client
   • Hosted MCP server: https://mcp.payram.com.
   • Local dev server: http://localhost:3333/mcp (or /mcp/sse if it supports streaming).
5. Health check

   curl http://localhost:3333/healthz
   

Tip: When you tell Copilot "test payram" it will automatically run the readiness checklist, ensure .env exists, and only then call test_payram_connection with your real credentials. The behavior is documented in COPILOT-USE.md—no manual prompting required.

---

Tool Catalog

Tool registrations live in src/tools/index.ts; individual implementations sit in src/tools/** with language-specific templates under templates/ folders.

---

Guided Workflows

1. Assess and Retrofit an Existing Project

1. Ask Copilot: "Can you integrate Payram into this project?"
2. The assistant runs assess_payram_project, reviewing dependency manifests and .env.
3. Follow the recommended steps (install payram, request Express/FastAPI/Spring route snippets, add webhooks, etc.).
4. Use test_payram_connection once credentials are real to ensure the backend can reach your self-hosted server.

2. Scaffold a Fresh Sample

1. "Create a Payram Express demo" → scaffold_payram_app builds an Express project with payments, payouts, webhooks, and a UI console.
2. Drop the generated files into an empty repo or compare against your existing directory for reference wiring.

3. Run the "Test Payram" Readiness Flow

1. Say "test payram". The assistant automatically:
   • Calls prepare_payram_test to share the readiness checklist.
   • Ensures .env exists (creating it if missing) using generate_env_template.
   • Waits for real credentials before invoking test_payram_connection.
2. Review the structured JSON result to confirm the Payram API is reachable.

4. Wire Payments, Payouts, Referrals, and Webhooks

• Payments: generate_payment_sdk_snippet (JS SDK) or generate_payment_http_snippet (Python/Go/PHP/Java).
• Multi-language routes: snippet_nextjs_payment_route, snippet_fastapi_payment_route, etc.
• Payouts: generate_payout_sdk_snippet for create + generate_payout_status_snippet for polling.
• Referrals: generate_referral_route_snippet, generate_referral_validation_snippet.
• Webhooks: generate_webhook_handler plus generate_webhook_event_router for fan-out + generate_mock_webhook_event to test each status.

---

Skills vs. MCP Tools

This repository provides two integration paths for AI agents:

Recommended workflow with skills:

1. Start with payram-setup to configure your server, API keys, and wallets
2. Use payram-payment-integration or payram-crypto-payments for integration overview
3. Follow payram-checkout-integration for payment flow implementation
4. Add payram-webhook-integration for real-time event handling
5. Use payram-payouts for outbound payments and affiliate tracking

---

Docs & Specs

• Local references live under docs/:
  • docs/js-sdk.md – expanded guide for the TypeScript SDK.
  • docs/payram-external.yaml, docs/payram-webhook.yaml – OpenAPI specs.
  • docs/referrals.md – referral FAQs and workflows.
• MCP doc tools (get_payram_doc_by_id, list_payram_docs) read files from docs/payram-docs-live/** via src/utils/markdownLoader.ts.
• For future updates, run make fetch-docs to sync the latest documentation from docs.payram.com into docs/payram-docs-live/.

---

Development

Project is TypeScript-first (ESM). Prettier config lives in .prettierrc.json; ESLint is configured via eslint.config.mjs. Smooth contributions follow the commit helper in Makefile → make commit.

---

Troubleshooting

• Copilot doesn’t call the right tool: Check COPILOT-USE.md and ensure your MCP client loaded the server. Re-run "test payram" or "assess my project" to trigger the expected automation.
• test_payram_connection fails with 401: Confirm .env uses the API-Key header, not Authorization. The tool echoes the missing fields when placeholders are detected.
• Docs tool says a file is missing: Verify your local docs/payram-docs-live/ tree contains the requested markdown (get_payram_doc_by_id rejects paths with ..).
• Server won’t start: Check .env for PAYRAM_BASE_URL/PAYRAM_API_KEY, ensure Node 18+, and run yarn install to grab the MCP SDK.

For anything else, inspect the structured logs emitted from src/utils/logger.ts (set LOG_LEVEL=debug) and open an issue/PR with reproduction details.