Metadata-Version: 2.4
Name: klo-mobility-quote-mcp
Version: 1.0.0
Summary: MCP server wrapper for the KLO Mobility Quote A2A agent.
Author: KLO
License-Expression: MIT-0
Keywords: mcp,a2a,mobility,trip-planning,route,quote
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Mobility Quote Agent

<!-- mcp-name: io.github.ubunyod574-max/mobility-quote -->

Provider-agnostic A2A agent for mobility quote/discovery. It exposes one skill,
`get_quote`, over JSON-RPC and returns route options sorted by estimated cost.

The first real provider path is SkedGo / TripGo. It is self-serve and useful for
multimodal route discovery; booking/payment remains a future provider-specific
integration.

The no-key production fallback is `Estimated Taxi`: it estimates distance, ETA,
and fare from a transparent local formula. This is not a live provider price and
must be labelled as an estimate.

Human-readable address input is resolved to coordinates with OpenStreetMap
Nominatim before providers run. Coordinate input still works directly. The agent
also returns a no-price Yandex Go route launcher when coordinates are available.
This is a deeplink, not a Yandex price quote or comparison result.

Payment metadata is advertised through the Agent Card and `/payment-info`.
The current default price is `0.001 USDC` per quote on Base, paid to
`0x55CFe1Dd5d341e5f9D57ADf26f98c8E8727bb3C2`. Facilitator-backed verify/settle
is wired through OpenX402. Full x402 enforcement is off by default until a live
paid request is tested.

## Files

```text
a2a-quote-agent/
  server.py                 A2A server: Agent Card + JSON-RPC message/send
  agent_card.py             Builds /.well-known/agent-card.json
  payments.py               x402/Base USDC payment metadata helpers
  client_test.py            Discovery + JSON-RPC smoke test
  MARKETPLACE-LISTING.md    Draft listing for A2A/OpenClaw marketplaces
  providers/
    __init__.py             Provider registry
    base.py                 Provider/Quote contract
    estimate.py             No-key coordinate fare estimator
    mock.py                 Demo providers
    geocode.py              No-key address-to-coordinate resolver
    tripgo.py               Live SkedGo/TripGo adapter
    yandex.py               No-price Yandex Go deeplink builder
```

## Run locally

```powershell
cd C:\agent\a2a-quote-agent
python server.py 8080
python client_test.py
```

Agent Card:

```text
http://localhost:8080/.well-known/agent-card.json
```

## Enable TripGo

Get a self-serve key from SkedGo / TripGo, then run:

```powershell
$env:TRIPGO_API_KEY="YOUR_KEY"
$env:PUBLIC_BASE_URL="http://localhost:8080"
python server.py 8080
```

TripGo v1 in this agent expects coordinate input:

```text
quote from 25.1972,55.2744 to 25.2532,55.3657
```

The server can also resolve normal addresses before calling providers:

```text
quote from Dubai Mall to DXB Airport
```

Resolved coordinates are returned in `resolved_route`. Address geocoding uses
OpenStreetMap Nominatim as a no-key MVP layer; for heavier production traffic,
configure Google, TomTom, HERE, or a self-hosted geocoder later.

Coordinate routes and successfully resolved address routes enable
`route_launchers[]` with an "Open in Yandex Go" deeplink.

Mock providers stay enabled by default for demos and health checks. To run only
live providers:

```powershell
$env:INCLUDE_MOCK_PROVIDERS="0"
```

## Payment metadata

The server advertises x402-compatible payment terms without requiring a private
key:

```powershell
$env:PAYMENT_RECEIVE_ADDRESS="0x55CFe1Dd5d341e5f9D57ADf26f98c8E8727bb3C2"
$env:X402_PRICE_USDC="0.001"
$env:X402_ADVERTISE="1"
$env:X402_ENFORCE="0"
$env:X402_FACILITATOR_URL="https://facilitator.openx402.ai"
python server.py 8080
```

Discovery endpoints:

```text
/.well-known/agent-card.json
/payment-info
/.well-known/payment-info.json
/x402/payment-required
```

`/x402/payment-required` returns HTTP 402 with a `PAYMENT-REQUIRED` header that
contains Base64-encoded JSON payment terms. When a paid client retries the JSON
RPC endpoint with a `PAYMENT-SIGNATURE` header, the server posts the payment
payload and selected requirements to the facilitator `/verify`, performs the
quote, then posts to `/settle` and returns `PAYMENT-RESPONSE` on success.

Keep `X402_ENFORCE=0` until a live paid request is tested. With enforcement off,
free quote smoke tests continue to work, while paid clients can still submit
`PAYMENT-SIGNATURE` and settle.

With mocks disabled and no live provider configured, coordinate routes still
return an estimated fare plus route launchers:

```powershell
$env:INCLUDE_MOCK_PROVIDERS="0"
python server.py 8080
python test_yandex_launcher.py
```

That mode is the clean no-approval MVP: transparent estimated fare, no displayed
Yandex price, no competitor price comparison, and an "Open in Yandex Go" route
deeplink where supported.

## Publish checklist

- Put the server behind public HTTPS.
- Set `PUBLIC_BASE_URL=https://212-47-77-33.sslip.io`.
- Verify `https://212-47-77-33.sslip.io/.well-known/agent-card.json`.
- Run `python client_test.py https://212-47-77-33.sslip.io`.
- Use `MARKETPLACE-LISTING.md` for A2A/OpenClaw marketplace submission.
