Payram Helper MCP Server

🚀 Payram Helper MCP Server

The MCP (Model Context Protocol) server teaches GitHub Copilot (and any MCP-aware client) how to integrate with a self-hosted Payram stack. It offers one-click tools for evaluating an existing codebase, setting up new starter apps, generating multi-language code snippets, reading inline documentation, and verifying connectivity to your Payram deployment.

📋 Table of Contents

• 🚀 Project Goals
• 🏎️ Quick Start
• 🛠️ Tool Catalog
• 🧭 Guided Workflows
• 📖 Docs & Specs
• 💻 Development
• 🐞 Troubleshooting

🚀 Project Goals

• Accelerate onboarding: Provide environment templates, readiness checklists, and per-framework guides.
• Retrofit existing repos: Use the project assessment tool to scan package manifests and .env files, then suggest appropriate integration snippets.
• Offer copy/paste snippets: Cover Payments, Payouts, Referrals, Webhooks, and multi-language backends (Express, Next.js, FastAPI, Laravel, Gin, Spring Boot, etc.).
• Keep docs local: Enable Copilot to explain Payram concepts, workflows, and referral dashboards without leaving the editor.
• Validate connectivity: Use the built-in /api/v1/payment probe to enforce the API-Key header expected by Payram.

🏎️ Quick Start

1. Install dependencies

yarn install

2. Configure environment

• Copy .env.example to .env and fill in PAYRAM_BASE_URL and PAYRAM_API_KEY. Alternatively, run the MCP tool generate_env_template from Copilot to automatically append the template.

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

• Point the client to http://localhost:3333/mcp (or /mcp/sse if it supports streaming).

5. Health check

curl http://localhost:3333/healthz

💡 Usage Tip

When you tell Copilot "test payram", it will automatically run the readiness checklist, ensure .env exists, and 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 are in src/tools/index.ts; individual implementations are in src/tools/** with language-specific templates in 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. Say "Create a Payram Express demo". scaffold_payram_app builds an Express project with payments, payouts, webhooks, and a UI console.
2. Place the generated files in an empty repo or compare them with 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: Use generate_payment_sdk_snippet (JS SDK) or generate_payment_http_snippet (Python/Go/PHP/Java).
• Multi-language routes: Use snippet_nextjs_payment_route, snippet_fastapi_payment_route, etc.
• Payouts: Use generate_payout_sdk_snippet for creation and generate_payout_status_snippet for polling.
• Referrals: Use generate_referral_route_snippet, generate_referral_validation_snippet.
• Webhooks: Use generate_webhook_handler and generate_webhook_event_router for fan-out, and generate_mock_webhook_event to test each status.

📖 Docs & Specs

• Local references are in docs/:
  • docs/js-sdk.md: An in-depth guide for the TypeScript SDK.
  • docs/payram-external.yaml, docs/payram-webhook.yaml: OpenAPI specifications.
  • docs/referrals.md: Referral FAQs and workflows.
• MCP doc tools (get_payram_doc_by_id, list_payram_docs) read files from docs/payram-docs/** via src/utils/markdownLoader.ts.
• For future updates, mirror the upstream docs tree in docs/payram-docs to keep the server's responses in sync.

💻 Development

The project uses TypeScript (ESM). The Prettier configuration is in .prettierrc.json, and ESLint is configured via eslint.config.mjs. For 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 has loaded the server. Re-run "test payram" or "assess my project" to trigger the expected automation.
• test_payram_connection fails with 401: Confirm that .env uses the API-Key header, not Authorization. The tool will show the missing fields if placeholders are detected.
• Docs tool says a file is missing: Verify that your local docs/payram-docs/ directory contains the requested markdown file (get_payram_doc_by_id rejects paths with ..).
• Server won’t start: Check .env for PAYRAM_BASE_URL and PAYRAM_API_KEY, ensure Node 18+ is installed, and run yarn install to get the MCP SDK.

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