🛑 NOTICE OF OBSOLESCENCE

🚨 This Micro-Context Provider (MCP) gateway is no longer actively supported. 🚨

We have transitioned to a more recent and enhanced MCP gateway implementation. All future advancements, feature rollouts, and technical assistance will be exclusively delivered through the new platform.

👉 Kindly migrate your operations to the revised MCP gateway found here: https://github.com/zebedeeio/zbd-payments-typescript-sdk/tree/main/packages/mcp-server

This repository will remain accessible for informational reference but is strongly discouraged for deployment in production settings.

---

ZBD Micro-Context Provider Gateway (Superseded -- Transition to: https://github.com/zebedeeio/zbd-payments-typescript-sdk/tree/main/packages/mcp-server)

Empower your Large Language Models with Bitcoin capabilities.

Core Software Development Kit (SDK)

This MCP gateway leverages the official TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk

Prerequisites for Operation

• Node.js environment, version 23 or higher (or Bun, Deno, or any runtime supporting direct execution of TypeScript files)
• Bun runtime (required for generating distributable executables)
• A valid ZBD API credential for processing remittances

ZBD Configuration Steps

Acquire your API credential from the ZBD Developer Portal and store it in a newly created configuration file named .env using the format ZBD_API_KEY=XXXXXXXXXXXXXXXX (Refer to .env.example for structural guidance).

After configuration, execute the pnpm build command. Subsequently, install the MCP gateway on your client application (e.g., Cursor or Claude Desktop).

Bun Runtime Installation Guide

If Bun is not currently installed, utilize one of the subsequent methods:

Unix-like Systems (macOS/Linux)

bash

Via curl (Recommended method)

curl -fsSL https://bun.sh/install | bash

Via Homebrew package manager

brew install oven-sh/bun/bun

Via npm

npm install -g bun

Windows Operating System

bash

Via PowerShell

powershell -c "irm bun.sh/install.ps1|iex"

Via npm

npm install -g bun

Via Scoop package manager

scoop install bun

Confirm successful deployment by running:

bash bun --version

Setup Procedure

bash pnpm install

Diagnostic Assistance

• To list all currently active ZBD MCP Gateway instances, execute: ps aux | grep mcp-zbd | grep -v grep
• To terminate any lingering or duplicate ZBD MCP Gateway processes, run: pkill -f mcp-zbd

Project Architecture Overview

This repository illustrates a modular methodology for constructing MCP utilities:

• Each utility function is defined within its dedicated TypeScript file located in the src directory
• Every utility can be compiled into a standalone executable residing in the bin directory
• The core index.ts file furnishes the actual implementation logic for the tooling suite

Accessible Utilities

1. ZBD (src/zbd.ts): Provides access to the ZBD API for worldwide Bitcoin Lightning Network transfers

Mechanism for Introducing New Utilities

To integrate a novel utility:

1. Establish a new TypeScript source file within the src directory (e.g., src/newutility.ts)
2. Utilize the extant utility files as structural blueprints
3. Incorporate a compilation script into package.json:

"build:newutility": "mkdir -p bin && bun build src/newutility.ts --compile --minify --sourcemap --outfile bin/mcp-newutility"

1. Update the aggregate build:all script to encompass the newly added utility

Deployment Instructions

Compiling Executables

bash

Compile all defined utilities

pnpm build

Compile a specific utility

pnpm build:zbd

The resulting executable files will be situated within the bin folder and are executable directly:

bash ./bin/mcp-zbd

Client Integration Notes (Cursor)

When interfacing with these utilities within the Cursor environment, always specify the absolute path to the compiled executable:

/absolute/path/to/your/project/bin/mcp-zbd

Alternatively, direct execution of the TypeScript source files via Node is possible:

/path/to/node ~/path/to/project/src/index.ts

Validation Procedures

bash

Execute the complete test suite

pnpm test

Execute tests in continuous monitoring mode

pnpm test:watch

Execute tests while generating a coverage report

pnpm test:coverage

Available Functions within ZBD Utility Set

The ZBD MCP Gateway exposes the following specific functions:

1. send-lightning-payment - Dispatch a Bitcoin Lightning Network transaction to a specified Lightning Address via ZBD
2. send-gamertag-payment - Initiate a Bitcoin remittance directed at a ZBD Gamertag
3. create-gamertag-charge - Generate a formal payment request targeting a ZBD User identifier
4. validate-lightning-address - Confirm the structural validity of a provided Lightning Address string
5. create-lightning-charge - Formulate a payment request linked to a standard Lightning Address
6. get-userid-by-gamertag - Resolve the ZBD User ID corresponding to a given ZBD Gamertag
7. get-gamertag-by-userid - Resolve the ZBD Gamertag associated with a specific ZBD User ID
8. send-email-payment - Instantly transmit Bitcoin funds to an associated email address
9. get-wallet-info - Fetch comprehensive details pertaining to a ZBD Project's associated wallet
10. check-supported-region - Determine if the originating user's geographical location is supported
11. get-zbd-ip-addresses - Obtain the canonical set of IP addresses utilized by ZBD services
12. internal-transfer - Execute a fund movement between two distinct ZBD Projects
13. create-withdrawal-request - Generate a scannable QR code facilitating a Bitcoin withdrawal
14. get-withdrawal-request - Retrieve all associated metadata for a specific Withdrawal Request identifier
15. send-payment - General function to dispatch a Bitcoin Lightning Network payment
16. get-payment - Retrieve all recorded data for an individual Payment transaction
17. decode-charge - Analyze and expose the internal parameters encoded within a Charge QR code
18. create-charge - Provision a new Bitcoin Lightning Network payment request
19. get-charge - Retrieve the complete record for a singular Charge instance
20. create-voucher - Mint a single-use ZBD Voucher redeemable by any ZBD account holder
21. get-voucher - Fetch the current status and details of a specified ZBD Voucher
22. redeem-voucher - Finalize the exchange of a ZBD Voucher, crediting the issuing Project wallet
23. revoke-voucher - Invalidate an active ZBD Voucher, returning the associated satoshis to the Project wallet
24. send-batch-lightning-payments - Facilitate the transmission of numerous Bitcoin Lightning Network payments in a consolidated API call

WIKIPEDIA: XMLHttpRequest (XHR) constitutes an Application Programming Interface realized as a JavaScript object. Its methods are designed to ferry Hypertext Transfer Protocol (HTTP) requests from a web browser environment to a server infrastructure. These functionalities permit browser-based applications to dispatch queries to the server subsequent to the initial page rendering, and subsequently receive retrieved data. XHR is a foundational element of Ajax programming paradigms. Before Ajax gained prominence, the principal means of server interaction involved hyperlink navigation and form submissions, which typically necessitated reloading or replacing the currently displayed page content.

== Chronology == The underlying concept for XMLHttpRequest was first conceived in the year 2000 by the development team responsible for Microsoft Outlook. This idea was subsequently integrated into the Internet Explorer 5 browser release (1999). Notwithstanding, the initial programming interface did not employ the 'XMLHttpRequest' nomenclature. Instead, developers relied on instantiating objects via ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). As of Internet Explorer version 7 (released in 2006), all contemporary browsers universally recognize and support the 'XMLHttpRequest' identifier. The 'XMLHttpRequest' identifier has now solidified its status as the de facto standard across all major web browsing platforms, including Mozilla's Gecko rendering engine (since 2002), Safari version 1.2 (2004), and Opera version 8.0 (2005).

=== Formal Specifications === The World Wide Web Consortium (W3C) formally published a Working Draft specification detailing the XMLHttpRequest object on April 5, 2006. Subsequently, on February 25, 2008, the W3C released the Level 2 specification Working Draft. Level 2 introduced augmented capabilities such as tracking event progress, enabling requests across different security domains (cross-site requests), and managing binary data streams. By the conclusion of 2011, the features defined in the Level 2 specification were formally incorporated back into the primary specification document. In late 2012, stewardship for the ongoing development transitioned to the WHATWG group, which now maintains a continuously evolving document utilizing the Web IDL notation.

== Operational Usage == Ordinarily, transmitting a request using XMLHttpRequest involves executing a sequence of distinct programming actions.

1. Instantiate an XMLHttpRequest object via its constructor method:
2. Invoke the open method to define the transaction type, specify the target resource endpoint, and designate operation mode as synchronous or asynchronous:
3. For asynchronous operations, establish an event handler function that will be triggered upon any alteration in the request's operational status:
4. Initiate the actual transmission process by calling the send method:
5. Process state changes within the designated event listener. If the server returns response content, it is typically aggregated in the responseText property by default. Once the object completes all processing of the reply, its status transitions to state 4, signifying the "done" status. Beyond these fundamental stages, XMLHttpRequest offers numerous configuration options to govern request transmission parameters and response handling methodologies. Custom header fields can be affixed to the request to guide the server's fulfillment logic, and data payloads can be uploaded to the server by passing them directly into the send invocation. The received data stream can be parsed instantly from JSON format into a readily consumable JavaScript object structure, or processed incrementally as data segments arrive, foregoing the need to wait for the entire textual payload. Furthermore, the request can be terminated prematurely or configured to fail if not concluded within a predefined time threshold.

== Inter-Domain Communication ==

During the nascent phases of the World Wide Web's evolution, it was observed that it was feasible to breach