Beckn Mobility MCP Server

A generic Model Context Protocol (MCP) server for the Beckn Mobility domain. This server acts as a Buyer Application Platform (BAP), enabling AI agents (like Claude, Gemini, etc.) to search for cabs, view prices, and book rides using the open Beckn Protocol (e.g., Namma Yatri, ONDC).

Features

• Generic BAP Implementation: Connects to any Beckn-compliant Mobility BPP.

• MCP Tools: Exposes search_cabs, select_ride, init_booking, and confirm_booking as AI tools.

• Async Webhook Handling: Robust WebhookManager handles Beckn's asynchronous callbacks with timeouts and request correlation.

• Secure Signing: Implements Ed25519 request signing required by the Beckn Registry.

• Hono Server: Built on Hono for high-performance HTTP handling and Server-Sent Events (SSE).

• Verification Scripts: Includes a suite of scripts to verify crypto signing and end-to-end flows.

Prerequisites

• Node.js v18+

• A public URL (using ngrok or a cloud deployment) for receiving webhooks.

• Registration with a Beckn Registry (e.g., Namma Yatri Sandbox).

Installation

1. Clone the repository:

   git clone https://github.com/<YOUR_USERNAME>/mcp-beckn-mobility.git
   cd mcp-beckn-mobility

2. Install dependencies:

   npm install

Configuration

1. Generate Keys: Run the helper script to generate your Ed25519 signing keys.

   npx tsx src/generate_keys.ts

   Copy the output (BAP ID, Public Key, Private Key).

2. Setup Environment: Copy .env.example to .env (or create it) and fill in your details:

   # Beckn Registry Details
   BAP_ID=mcp-mobility-bap-<TIMESTAMP>
   UNIQUE_KEY_ID=key1
   SIGNING_PRIVATE_KEY=<YOUR_PRIVATE_KEY>
   SIGNING_PUBLIC_KEY=<YOUR_PUBLIC_KEY>
   
   # URLs
   BAP_URI=https://<YOUR_NGROK_URL>  # Must be public!
   BPP_URI=https://gateway.nammayatri.in/search # Or local mock
   
   PORT=3000

3. Register: Use your BAP ID and Public Key to register on the Namma Yatri / Beckn Registry.

Usage

1. Start the Server:

   npm run dev

2. Connect via Ngrok (if running locally):

   ngrok http 3000

   Update BAP_URI in .env with the ngrok URL.

3. Connect your AI Client: Configure your MCP Client (e.g., Claude Desktop) to connect to the SSE endpoint:

   • URL: http://localhost:3000/sse

Verification

We have included scripts to verify the system before going live:

• Verify Crypto: Checks if your keys and signing logic are mathematically correct.

  npx tsx src/verify_crypto.ts

• Verify Full Flow (Local): Runs a local Mock BPP and tests the full HTTP request/response loop.

  npx tsx src/verify_full_flow.ts

• Black Box Test: Simulates an MCP Client connecting via SSE and calling tools.

  npx tsx src/verify_mcp_client.ts

Project Structure

• src/index.ts: Main server entry point (Hono app).

• src/tools/mobilityTools.ts: MCP Tool definitions (search_cabs, etc.).

• src/lib/becknClient.ts: Handles Beckn protocol communication and signing.

• src/lib/webhookManager.ts: Manages async callbacks.

• src/lib/honoTransport.ts: Custom MCP Transport for Hono.

License

MIT