shabaaspay-mcp-server 1.0.1

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "shabaaspay-mcp-server",
+  "version": "1.0.1",
+  "description": "ShaBaas Pay MCP Server - Australian real time payment API for AI applications",
+  "keywords": [
+    "mcp-server",
+    "mcp",
+    "shabaaspay",
+    "australian-payments",
+    "real-time-payments",
+    "claude",
+    "chatgpt",
+    "vscode-copilot",
+    "payment-api"
+  ],
+  "author": "ShaBaas",
+  "license": "MIT",
+  "homepage": "https://shabaas.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shabaaspay/shabaaspay-mcp-server"
+  },
+  "bugs": {
+    "url": "https://github.com/shabaaspay/shabaaspay-mcp-server/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "mcpName": "io.github.shabaaspay/shabaaspay-payto",
+  "main": "dist/index.js",
+  "bin": {
+    "shabaaspay-mcp": "dist/index.js",
+    "shabaaspay-mcp-http": "dist/server-http.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "server.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev:stdio": "tsx watch src/index.ts",
+    "dev:http": "tsx watch src/server-http.ts",
+    "start:stdio": "node dist/index.js",
+    "start:http": "node dist/server-http.js",
+    "deploy:cloudflare": "wrangler deploy",
+    "inspect": "dotenv -e .env -- npx @modelcontextprotocol/inspector node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "axios": "^1.6.0",
+    "dotenv": "^16.3.0",
+    "zod": "^3.22.0",
+    "zod-to-json-schema": "^3.23.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "dotenv-cli": "^11.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0",
+    "wrangler": "^4.54.0"
+  }
+}

package/readme.md

@@ -0,0 +1,113 @@
+# ShaBaas Pay MCP Server
+
+Australian real time payment processing for AI applications.
+
+Connect AI assistants to ShaBaas Pay to create and retrieve PayTo payment agreements with optional enrichment.
+
+## Quick start
+
+### Install
+npm install -g shabaaspay-mcp-server
+
+### Run locally
+shabaaspay-mcp
+
+### Run HTTP (for VS Code / HTTP MCP clients)
+shabaaspay-mcp-http
+
+The HTTP server exposes:
+- `GET /health` for health checks
+- `POST /tools/execute` for simple REST execution
+- `POST/GET /mcp` for MCP Streamable HTTP (use this endpoint in VS Code / HTTP clients)
+
+Environment (defaults shown):
+- `HTTP_PORT=3000`
+- `HTTP_HOST=0.0.0.0`
+- `MCP_HTTP_API_KEY=` (if empty, HTTP guard is disabled; set a value to lock down access)
+- `API_RATE_LIMIT_PER_MINUTE=60`, `API_RATE_LIMIT_PER_HOUR=1000`
+- `Authorization` header for tool calls: **plain ShaBaas-issued client UUID** (no Bearer prefix). Hosted Worker validates UUID against policy/secrets and fetches/caches the bearer internally.
+
+## Claude Desktop configuration
+
+Edit this file:
+%APPDATA%\Claude\claude_desktop_config.json
+
+Example:
+
+{
+  "mcpServers": {
+    "shabaaspay": {
+      "command": "shabaaspay-mcp",
+      "env": {
+        "SHABAAS_ENVIRONMENT": "sandbox",
+        "SHABAAS_SANDBOX_URL": "<sandbox_api_base_url>",
+        "SHABAAS_AUTH_UUID": "your_uuid_here"
+      }
+    }
+  }
+}
+
+## VS Code / MCP HTTP configuration
+
+Hosted (staging/prod): point to `https://mcp-staging.shabaas.com/mcp` or `https://mcp.shabaas.com/mcp` and send `Authorization: <client_uuid_issued_by_shabaas>` (plain, no Bearer).  
+Local dev: `http://localhost:3000/mcp` with `Authorization: <uuid>` (from your local env).
+
+## LLM integration quickstart
+- **Auth header**: use your ShaBaas-issued client UUID as `Authorization: <uuid>` (plain, no Bearer). Hosted Worker validates it; server manages the bearer internally.
+- **Endpoints**: STDIO (`shabaaspay-mcp`) or HTTP MCP (`http://localhost:3000/mcp`), staging (`https://mcp-staging.shabaas.com/mcp`), production (`https://mcp.shabaas.com/mcp`).
+- **Common calls (curl)**:
+  - Get agreement:
+    ```bash
+    curl -X POST http://localhost:3000/mcp \
+      -H "Authorization: <uuid>" \
+      -H "Content-Type: application/json" \
+      -d '{"tool":"get_payment_agreement","arguments":{"payment_agreement_id":"2882PA20251227045450257","enrich":true}}'
+    ```
+  - Create agreement:
+    ```bash
+    curl -X POST http://localhost:3000/mcp \
+      -H "Authorization: <uuid>" \
+      -H "Content-Type: application/json" \
+      -d '{"tool":"create_payment_agreement","arguments":{"name":"Test","type":"email","maximum_amount":"10.00","frequency":"WEEK","number_of_transactions_permitted":1,"pay_id":"sample@shabaas.com"}}'
+    ```
+- **Inspector/VS Code**: set MCP URL to `/mcp` and header `Authorization: <uuid>`; list tools then call by name. Enrichment toggles (`enrich`, `include_raw`) are available on payment tools.
+
+## Tool manifest (LLM-friendly)
+- Catalog JSON: `docs/tool-catalog.json` (publishable at a stable URL for ingestion).
+- Tools:
+  - `get_auth_token` – fetch bearer (debug; server auto-manages tokens)
+  - `create_payment_agreement` – create PayTo agreement
+  - `get_payment_agreement` – retrieve agreement with enrichment toggle
+  - `initiate_payment` – initiate payment against agreement
+  - `get_payment_initiation` – retrieve payment initiation
+- Auth: `Authorization: <uuid>` (plain). Server fetches/caches ShaBaas bearer.
+
+## Auth & rate limits
+- Provide your ShaBaas UUID in the `Authorization` header (plain value, no `Bearer`). The MCP server fetches and caches the ShaBaas bearer internally.
+- HTTP guard is optional via `MCP_HTTP_API_KEY`; leave empty to avoid 403s in local testing.
+- Rate limits: defaults 60/min and 1000/hour; configure with `API_RATE_LIMIT_PER_MINUTE` / `API_RATE_LIMIT_PER_HOUR`.
+- CORS: configure `ALLOWED_ORIGINS` (comma separated) for HTTP clients (e.g., Inspector UI).
+
+## Enrichment toggle
+Tools support `enrich` (default true) and `include_raw` (default false) to control business context and raw payloads. Set `enrich: false` for lean responses.
+
+## Available tools
+
+Payment agreements
+1. create_payment_agreement
+2. get_payment_agreement
+
+Authentication helper
+1. get_auth_token
+
+## Examples
+
+See examples/basic.md
+
+## Documentation
+1. docs/installation.md
+2. docs/authentication.md
+3. docs/api-reference.md
+
+## License
+MIT, see LICENSE