# 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**:
```bash
git clone https://github.com/<YOUR_USERNAME>/mcp-beckn-mobility.git
cd mcp-beckn-mobility
```
2. **Install dependencies**:
```bash
npm install
```
## Configuration
1. **Generate Keys**:
Run the helper script to generate your Ed25519 signing keys.
```bash
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:
```env
# 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](https://mobility.becknprotocol.io/sandbox).
## Usage
1. **Start the Server**:
```bash
npm run dev
```
2. **Connect via Ngrok** (if running locally):
```bash
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.
```bash
npx tsx src/verify_crypto.ts
```
* **Verify Full Flow (Local)**: Runs a local Mock BPP and tests the full HTTP request/response loop.
```bash
npx tsx src/verify_full_flow.ts
```
* **Black Box Test**: Simulates an MCP Client connecting via SSE and calling tools.
```bash
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
