@codespar/mcp-nequi 0.1.0 → 0.2.0-alpha.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +18 -5
  2. package/dist/index.d.ts +12 -2
  3. package/dist/index.js +302 -4
  4. package/package.json +13 -4
package/README.md CHANGED
@@ -1,5 +1,8 @@
1
1
  # MCP Nequi
2
2
 
3
+
4
+ > **Alpha release** — published under the `alpha` npm dist-tag. Endpoint paths follow public docs and BACEN/provider conventions but have not been fully live-validated. Pin exact versions during `0.x.x-alpha`. Install with `npm install <pkg>@alpha`.
5
+
3
6
  MCP server for **Nequi** — Colombia's leading digital wallet with 50M+ users, powered by Bancolombia. Supports push payments, QR payments, and subscriptions.
4
7
 
5
8
  ## Quick Start
@@ -28,16 +31,26 @@ npx tsx packages/colombia/nequi/src/index.ts --http
28
31
  | `MCP_HTTP` | No | Set to `"true"` to enable HTTP transport |
29
32
  | `MCP_PORT` | No | HTTP port (default: 3000) |
30
33
 
31
- ## Tools
34
+ ## Tools (16)
32
35
 
33
- | Tool | Description |
34
- |------|-------------|
36
+ | Tool | Purpose |
37
+ |---|---|
35
38
  | `create_push_payment` | Send a push payment notification to a Nequi user |
36
- | `get_payment_status` | Check payment status |
39
+ | `get_payment_status` | Check the status of a payment |
37
40
  | `create_qr_payment` | Generate a QR code for payment |
38
41
  | `reverse_payment` | Reverse a completed payment |
39
- | `get_subscription` | Get subscription details |
42
+ | `get_subscription` | Get subscription details for a phone number |
40
43
  | `unsubscribe` | Cancel a subscription |
44
+ | `create_static_qr` | Generate a static (reusable) Nequi QR code for a merchant |
45
+ | `reverse_transaction` | Reverse any Nequi transaction by transaction ID (refund flow) |
46
+ | `validate_phone` | Check whether a phone number is enrolled in Nequi |
47
+ | `notify_unregistered_payment` | Notify a non-Nequi recipient with instructions to claim a payment |
48
+ | `list_transactions` | List transactions for a merchant within a date range |
49
+ | `get_balance` | Get the merchant's own Nequi account balance |
50
+ | `schedule_payment` | Schedule a Nequi push payment for a future date |
51
+ | `authorize_recurring_charge` | Authorize a recurring charge agreement against a Nequi user |
52
+ | `get_merchant_info` | Retrieve registered merchant business profile |
53
+ | `get_settlement` | Query settlement (liquidation) for a given date |
41
54
 
42
55
  ## Auth
43
56
 
package/dist/index.d.ts CHANGED
@@ -2,13 +2,23 @@
2
2
  /**
3
3
  * MCP Server for Nequi — Colombian digital wallet (50M+ users, by Bancolombia).
4
4
  *
5
- * Tools:
5
+ * Tools (16):
6
6
  * - create_push_payment: Send a push payment notification to a Nequi user
7
7
  * - get_payment_status: Check payment status
8
- * - create_qr_payment: Generate a QR code payment
8
+ * - create_qr_payment: Generate a QR code payment (dynamic)
9
+ * - create_static_qr: Generate a static (reusable) QR code
9
10
  * - reverse_payment: Reverse a payment
11
+ * - reverse_transaction: Reverse any transaction by ID
10
12
  * - get_subscription: Get subscription details
11
13
  * - unsubscribe: Cancel a subscription
14
+ * - validate_phone: Check if a phone number is enrolled in Nequi
15
+ * - notify_unregistered_payment: Notify a non-Nequi user with payment instructions
16
+ * - list_transactions: List transactions for a merchant in a date range
17
+ * - get_balance: Get merchant account balance
18
+ * - schedule_payment: Schedule a payment for a future date
19
+ * - authorize_recurring_charge: Authorize a recurring charge agreement
20
+ * - get_merchant_info: Retrieve merchant business profile
21
+ * - get_settlement: Query settlement for a given date
12
22
  *
13
23
  * Environment:
14
24
  * NEQUI_API_KEY — API key
package/dist/index.js CHANGED
@@ -2,13 +2,23 @@
2
2
  /**
3
3
  * MCP Server for Nequi — Colombian digital wallet (50M+ users, by Bancolombia).
4
4
  *
5
- * Tools:
5
+ * Tools (16):
6
6
  * - create_push_payment: Send a push payment notification to a Nequi user
7
7
  * - get_payment_status: Check payment status
8
- * - create_qr_payment: Generate a QR code payment
8
+ * - create_qr_payment: Generate a QR code payment (dynamic)
9
+ * - create_static_qr: Generate a static (reusable) QR code
9
10
  * - reverse_payment: Reverse a payment
11
+ * - reverse_transaction: Reverse any transaction by ID
10
12
  * - get_subscription: Get subscription details
11
13
  * - unsubscribe: Cancel a subscription
14
+ * - validate_phone: Check if a phone number is enrolled in Nequi
15
+ * - notify_unregistered_payment: Notify a non-Nequi user with payment instructions
16
+ * - list_transactions: List transactions for a merchant in a date range
17
+ * - get_balance: Get merchant account balance
18
+ * - schedule_payment: Schedule a payment for a future date
19
+ * - authorize_recurring_charge: Authorize a recurring charge agreement
20
+ * - get_merchant_info: Retrieve merchant business profile
21
+ * - get_settlement: Query settlement for a given date
12
22
  *
13
23
  * Environment:
14
24
  * NEQUI_API_KEY — API key
@@ -67,7 +77,7 @@ async function nequiRequest(method, path, body) {
67
77
  }
68
78
  return res.json();
69
79
  }
70
- const server = new Server({ name: "mcp-nequi", version: "0.1.0" }, { capabilities: { tools: {} } });
80
+ const server = new Server({ name: "mcp-nequi", version: "0.2.0-alpha.2" }, { capabilities: { tools: {} } });
71
81
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
72
82
  tools: [
73
83
  {
@@ -153,6 +163,140 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
153
163
  required: ["phone_number", "code", "token"],
154
164
  },
155
165
  },
166
+ {
167
+ name: "create_static_qr",
168
+ description: "Generate a static (reusable) Nequi QR code for a merchant",
169
+ inputSchema: {
170
+ type: "object",
171
+ properties: {
172
+ code: { type: "string", description: "Merchant QR code identifier" },
173
+ merchant_id: { type: "string", description: "Merchant ID" },
174
+ message: { type: "string", description: "QR description" },
175
+ },
176
+ required: ["code"],
177
+ },
178
+ },
179
+ {
180
+ name: "reverse_transaction",
181
+ description: "Reverse any Nequi transaction by transaction ID (refund flow)",
182
+ inputSchema: {
183
+ type: "object",
184
+ properties: {
185
+ transaction_id: { type: "string", description: "Original transaction ID" },
186
+ merchant_id: { type: "string", description: "Merchant ID" },
187
+ value: { type: "string", description: "Amount to reverse in COP" },
188
+ reason: { type: "string", description: "Reversal reason" },
189
+ },
190
+ required: ["transaction_id", "value"],
191
+ },
192
+ },
193
+ {
194
+ name: "validate_phone",
195
+ description: "Check whether a phone number is enrolled in Nequi",
196
+ inputSchema: {
197
+ type: "object",
198
+ properties: {
199
+ phone_number: { type: "string", description: "Phone number (10 digits, CO)" },
200
+ merchant_id: { type: "string", description: "Merchant ID" },
201
+ },
202
+ required: ["phone_number"],
203
+ },
204
+ },
205
+ {
206
+ name: "notify_unregistered_payment",
207
+ description: "Notify a non-Nequi recipient with instructions to claim a payment",
208
+ inputSchema: {
209
+ type: "object",
210
+ properties: {
211
+ phone_number: { type: "string", description: "Recipient phone number" },
212
+ code: { type: "string", description: "Payment code" },
213
+ value: { type: "string", description: "Amount in COP" },
214
+ merchant_id: { type: "string", description: "Merchant ID" },
215
+ message: { type: "string", description: "Notification message" },
216
+ },
217
+ required: ["phone_number", "code", "value"],
218
+ },
219
+ },
220
+ {
221
+ name: "list_transactions",
222
+ description: "List transactions for a merchant within a date range",
223
+ inputSchema: {
224
+ type: "object",
225
+ properties: {
226
+ merchant_id: { type: "string", description: "Merchant ID" },
227
+ date_from: { type: "string", description: "Start date (ISO 8601)" },
228
+ date_to: { type: "string", description: "End date (ISO 8601)" },
229
+ status: { type: "string", description: "Optional status filter" },
230
+ },
231
+ required: ["date_from", "date_to"],
232
+ },
233
+ },
234
+ {
235
+ name: "get_balance",
236
+ description: "Get the merchant's own Nequi account balance",
237
+ inputSchema: {
238
+ type: "object",
239
+ properties: {
240
+ merchant_id: { type: "string", description: "Merchant ID" },
241
+ },
242
+ required: [],
243
+ },
244
+ },
245
+ {
246
+ name: "schedule_payment",
247
+ description: "Schedule a Nequi push payment for a future date",
248
+ inputSchema: {
249
+ type: "object",
250
+ properties: {
251
+ phone_number: { type: "string", description: "Nequi phone number" },
252
+ code: { type: "string", description: "Payment code" },
253
+ value: { type: "string", description: "Amount in COP" },
254
+ merchant_id: { type: "string", description: "Merchant ID" },
255
+ scheduled_date: { type: "string", description: "ISO 8601 date to execute" },
256
+ message: { type: "string", description: "Description" },
257
+ },
258
+ required: ["phone_number", "code", "value", "scheduled_date"],
259
+ },
260
+ },
261
+ {
262
+ name: "authorize_recurring_charge",
263
+ description: "Authorize a recurring charge agreement against a Nequi user",
264
+ inputSchema: {
265
+ type: "object",
266
+ properties: {
267
+ phone_number: { type: "string", description: "Nequi phone number" },
268
+ code: { type: "string", description: "Subscription/agreement code" },
269
+ merchant_id: { type: "string", description: "Merchant ID" },
270
+ max_value: { type: "string", description: "Max charge amount in COP" },
271
+ frequency: { type: "string", description: "Frequency: monthly|weekly|daily" },
272
+ message: { type: "string", description: "Description" },
273
+ },
274
+ required: ["phone_number", "code", "max_value", "frequency"],
275
+ },
276
+ },
277
+ {
278
+ name: "get_merchant_info",
279
+ description: "Retrieve registered merchant business profile",
280
+ inputSchema: {
281
+ type: "object",
282
+ properties: {
283
+ merchant_id: { type: "string", description: "Merchant ID" },
284
+ },
285
+ required: [],
286
+ },
287
+ },
288
+ {
289
+ name: "get_settlement",
290
+ description: "Query settlement (liquidation) for a given date",
291
+ inputSchema: {
292
+ type: "object",
293
+ properties: {
294
+ merchant_id: { type: "string", description: "Merchant ID" },
295
+ settlement_date: { type: "string", description: "Settlement date (YYYY-MM-DD)" },
296
+ },
297
+ required: ["settlement_date"],
298
+ },
299
+ },
156
300
  ],
157
301
  }));
158
302
  server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -254,6 +398,160 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
254
398
  },
255
399
  },
256
400
  }), null, 2) }] };
401
+ case "create_static_qr":
402
+ return { content: [{ type: "text", text: JSON.stringify(await nequiRequest("POST", "/payments/v2/-services-paymentservice-generatestaticcodeqr", {
403
+ RequestMessage: {
404
+ RequestHeader: { Channel: "PNP04-C001", RequestDate: new Date().toISOString(), MessageID: `MCP-${Date.now()}`, ClientID: CLIENT_ID },
405
+ RequestBody: {
406
+ any: {
407
+ generateStaticCodeQRRQ: {
408
+ code: args?.code,
409
+ merchantId: args?.merchant_id,
410
+ message: args?.message,
411
+ },
412
+ },
413
+ },
414
+ },
415
+ }), null, 2) }] };
416
+ case "reverse_transaction":
417
+ return { content: [{ type: "text", text: JSON.stringify(await nequiRequest("POST", "/payments/v2/-services-reverseservices-reversetransactionbyid", {
418
+ RequestMessage: {
419
+ RequestHeader: { Channel: "PNP04-C001", RequestDate: new Date().toISOString(), MessageID: `MCP-${Date.now()}`, ClientID: CLIENT_ID },
420
+ RequestBody: {
421
+ any: {
422
+ reverseTransactionByIdRQ: {
423
+ transactionId: args?.transaction_id,
424
+ merchantId: args?.merchant_id,
425
+ value: args?.value,
426
+ reason: args?.reason,
427
+ },
428
+ },
429
+ },
430
+ },
431
+ }), null, 2) }] };
432
+ case "validate_phone":
433
+ return { content: [{ type: "text", text: JSON.stringify(await nequiRequest("POST", "/payments/v2/-services-clientservice-validateclient", {
434
+ RequestMessage: {
435
+ RequestHeader: { Channel: "PNP04-C001", RequestDate: new Date().toISOString(), MessageID: `MCP-${Date.now()}`, ClientID: CLIENT_ID },
436
+ RequestBody: {
437
+ any: {
438
+ validateClientRQ: {
439
+ phoneNumber: args?.phone_number,
440
+ merchantId: args?.merchant_id,
441
+ },
442
+ },
443
+ },
444
+ },
445
+ }), null, 2) }] };
446
+ case "notify_unregistered_payment":
447
+ return { content: [{ type: "text", text: JSON.stringify(await nequiRequest("POST", "/payments/v2/-services-paymentservice-notifyunregistered", {
448
+ RequestMessage: {
449
+ RequestHeader: { Channel: "PNP04-C001", RequestDate: new Date().toISOString(), MessageID: `MCP-${Date.now()}`, ClientID: CLIENT_ID },
450
+ RequestBody: {
451
+ any: {
452
+ notifyUnregisteredRQ: {
453
+ phoneNumber: args?.phone_number,
454
+ code: args?.code,
455
+ value: args?.value,
456
+ merchantId: args?.merchant_id,
457
+ message: args?.message,
458
+ },
459
+ },
460
+ },
461
+ },
462
+ }), null, 2) }] };
463
+ case "list_transactions":
464
+ return { content: [{ type: "text", text: JSON.stringify(await nequiRequest("POST", "/payments/v2/-services-reportservice-listtransactions", {
465
+ RequestMessage: {
466
+ RequestHeader: { Channel: "PNP04-C001", RequestDate: new Date().toISOString(), MessageID: `MCP-${Date.now()}`, ClientID: CLIENT_ID },
467
+ RequestBody: {
468
+ any: {
469
+ listTransactionsRQ: {
470
+ merchantId: args?.merchant_id,
471
+ dateFrom: args?.date_from,
472
+ dateTo: args?.date_to,
473
+ status: args?.status,
474
+ },
475
+ },
476
+ },
477
+ },
478
+ }), null, 2) }] };
479
+ case "get_balance":
480
+ return { content: [{ type: "text", text: JSON.stringify(await nequiRequest("POST", "/payments/v2/-services-merchantservice-getbalance", {
481
+ RequestMessage: {
482
+ RequestHeader: { Channel: "PNP04-C001", RequestDate: new Date().toISOString(), MessageID: `MCP-${Date.now()}`, ClientID: CLIENT_ID },
483
+ RequestBody: {
484
+ any: {
485
+ getBalanceRQ: {
486
+ merchantId: args?.merchant_id,
487
+ },
488
+ },
489
+ },
490
+ },
491
+ }), null, 2) }] };
492
+ case "schedule_payment":
493
+ return { content: [{ type: "text", text: JSON.stringify(await nequiRequest("POST", "/payments/v2/-services-paymentservice-schedulepayment", {
494
+ RequestMessage: {
495
+ RequestHeader: { Channel: "PNP04-C001", RequestDate: new Date().toISOString(), MessageID: `MCP-${Date.now()}`, ClientID: CLIENT_ID },
496
+ RequestBody: {
497
+ any: {
498
+ schedulePaymentRQ: {
499
+ phoneNumber: args?.phone_number,
500
+ code: args?.code,
501
+ value: args?.value,
502
+ merchantId: args?.merchant_id,
503
+ scheduledDate: args?.scheduled_date,
504
+ message: args?.message,
505
+ },
506
+ },
507
+ },
508
+ },
509
+ }), null, 2) }] };
510
+ case "authorize_recurring_charge":
511
+ return { content: [{ type: "text", text: JSON.stringify(await nequiRequest("POST", "/payments/v2/-services-subscriptionpaymentservice-authorizerecurring", {
512
+ RequestMessage: {
513
+ RequestHeader: { Channel: "PNP04-C001", RequestDate: new Date().toISOString(), MessageID: `MCP-${Date.now()}`, ClientID: CLIENT_ID },
514
+ RequestBody: {
515
+ any: {
516
+ authorizeRecurringRQ: {
517
+ phoneNumber: args?.phone_number,
518
+ code: args?.code,
519
+ merchantId: args?.merchant_id,
520
+ maxValue: args?.max_value,
521
+ frequency: args?.frequency,
522
+ message: args?.message,
523
+ },
524
+ },
525
+ },
526
+ },
527
+ }), null, 2) }] };
528
+ case "get_merchant_info":
529
+ return { content: [{ type: "text", text: JSON.stringify(await nequiRequest("POST", "/payments/v2/-services-merchantservice-getmerchantinfo", {
530
+ RequestMessage: {
531
+ RequestHeader: { Channel: "PNP04-C001", RequestDate: new Date().toISOString(), MessageID: `MCP-${Date.now()}`, ClientID: CLIENT_ID },
532
+ RequestBody: {
533
+ any: {
534
+ getMerchantInfoRQ: {
535
+ merchantId: args?.merchant_id,
536
+ },
537
+ },
538
+ },
539
+ },
540
+ }), null, 2) }] };
541
+ case "get_settlement":
542
+ return { content: [{ type: "text", text: JSON.stringify(await nequiRequest("POST", "/payments/v2/-services-reportservice-getsettlement", {
543
+ RequestMessage: {
544
+ RequestHeader: { Channel: "PNP04-C001", RequestDate: new Date().toISOString(), MessageID: `MCP-${Date.now()}`, ClientID: CLIENT_ID },
545
+ RequestBody: {
546
+ any: {
547
+ getSettlementRQ: {
548
+ merchantId: args?.merchant_id,
549
+ settlementDate: args?.settlement_date,
550
+ },
551
+ },
552
+ },
553
+ },
554
+ }), null, 2) }] };
257
555
  default:
258
556
  return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
259
557
  }
@@ -280,7 +578,7 @@ async function main() {
280
578
  const t = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID(), onsessioninitialized: (id) => { transports.set(id, t); } });
281
579
  t.onclose = () => { if (t.sessionId)
282
580
  transports.delete(t.sessionId); };
283
- const s = new Server({ name: "mcp-nequi", version: "0.1.0" }, { capabilities: { tools: {} } });
581
+ const s = new Server({ name: "mcp-nequi", version: "0.2.0-alpha.2" }, { capabilities: { tools: {} } });
284
582
  server._requestHandlers.forEach((v, k) => s._requestHandlers.set(k, v));
285
583
  server._notificationHandlers?.forEach((v, k) => s._notificationHandlers.set(k, v));
286
584
  await s.connect(t);
package/package.json CHANGED
@@ -1,13 +1,15 @@
1
1
  {
2
2
  "name": "@codespar/mcp-nequi",
3
- "version": "0.1.0",
4
- "description": "MCP server for Nequi — Colombian digital wallet (by Bancolombia)",
3
+ "version": "0.2.0-alpha.2",
4
+ "description": "MCP server for Nequi \u2014 Colombian digital wallet (by Bancolombia)",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
7
7
  "bin": {
8
8
  "mcp-nequi": "dist/index.js"
9
9
  },
10
- "files": ["dist"],
10
+ "files": [
11
+ "dist"
12
+ ],
11
13
  "scripts": {
12
14
  "build": "tsc",
13
15
  "start": "node dist/index.js"
@@ -20,6 +22,13 @@
20
22
  "typescript": "^5.8.0"
21
23
  },
22
24
  "license": "MIT",
23
- "keywords": ["nequi", "wallet", "colombia", "bancolombia", "payments", "mcp"],
25
+ "keywords": [
26
+ "nequi",
27
+ "wallet",
28
+ "colombia",
29
+ "bancolombia",
30
+ "payments",
31
+ "mcp"
32
+ ],
24
33
  "mcpName": "io.github.codespar/mcp-nequi"
25
34
  }