# visaroute

Visa answers for any passport and destination pair,
backed by official government sources. visaroute
tells you whether a traveler holding a given passport
needs a visa for a destination country, what entry
and transit requirements apply along the way, and
where the official word on each requirement lives —
plus a deep link to the full analysis.

It is read-only, sends no personal data (just the two
country names or codes), and needs no API key.

> Not legal or immigration advice. Results are a
> generic analysis for any citizen of the passport
> country. Always verify with your airline and the
> destination's authorities before travel.

## How it works

- `check_visa` is a forwarding client: it calls the
  published EasyOnward remote MCP endpoint
  (`https://mcp.easyonward.com/mcp`) over streamable
  HTTP as a JSON-RPC client — `initialize`, then
  `notifications/initialized`, then `tools/call`,
  honouring the session header the remote returns —
  and passes the answer through. The remote URL can
  be overridden with `EASYONWARD_MCP_URL`. This wire
  choice is a reconstruction: the upstream project
  documents the tool's inputs, outputs and text shape
  but not its wire protocol, and the rebuild labels
  it as such.
- `country_code` is fully local: it resolves against
  an embedded ISO 3166-1 alpha-2 list and never
  touches the network.

## Tools

- `check_visa` — check whether a traveler holding a
  given passport needs a visa, and what entry &
  transit requirements apply, for a destination
  country — with official government sources. Inputs:
  `passport_country` and `destination_country`, each
  an ISO 3166-1 alpha-2 code (`US`) or a country name
  (`United States`). The answer comes back as
  human-readable text (also carried as
  `structuredContent` over MCP) with:
  - `verdict` — a one-line plain-language summary
    (restricted / conditional / straightforward).
  - `worst_severity` — `BLOCK` | `WARN` | `INFO` |
    `NONE`.
  - `requirements[]` — each flagged requirement as
    `severity`, `title`, `detail`.
  - `official_sources[]` — deduped official
    government source URLs.
  - `deep_link` — `https://easyonward.com/visa/{ORIGIN}-{DEST}`
    for the full analysis.
  - `prepare_link` — the same page tagged
    `?ref=mcp`.
  - `disclaimer`.
- `country_code` — resolve a country name (or an
  existing ISO-2 code) to its uppercase ISO 3166-1
  alpha-2 code — e.g. `Kenya` → `KE`. Handy before
  calling `check_visa`. An unknown name fails with
  `visaroute error: unknown country: <input>` rather
  than guessing.

Calling `check_visa` with
`{ "passport_country": "US", "destination_country": "KE" }`
produces text of this shape:

```
Travel from United States to Kenya is conditional — see requirements.

Requirements:
  [INFO] US travel advisory: Kenya — Level 2 (Exercise Increased Caution) — …
  [INFO] Be ready to show proof of funds for Kenya (KE) — …
  [WARN] An electronic travel authorization (eta) for Kenya on your United States (US) passport — …

Official government sources:
  - https://www.etakenya.go.ke
  - https://immigration.go.ke
  - https://travel.state.gov/…/kenya-travel-advisory.html
  …

Full details: https://easyonward.com/visa/US-KE

Generic analysis for any United States citizen. Not legal or immigration advice — verify with
your airline and the destination's authorities before travel.
```

Failures use this rebuild's own error strings, all in
the `visaroute error:` family: `visaroute error:
HTTP <status>` for a non-2xx remote reply,
`visaroute error: upstream unreachable` when the
remote cannot be reached, and
`visaroute error: <message>` for a remote JSON-RPC or
tool error.

## Configuration

- `EASYONWARD_MCP_URL` (optional) — remote MCP
  endpoint for `check_visa`. Defaults to
  `https://mcp.easyonward.com/mcp`.

No API key or other configuration is required.

## CLI

Each tool is a subcommand taking one JSON argument
string:

```bash
npx @reneturcios/visaroute check_visa '{"passport_country":"US","destination_country":"KE"}'
npx @reneturcios/visaroute country_code '{"country":"Kenya"}'
npx @reneturcios/visaroute --version
```

`check_visa` prints the human-readable text;
`country_code` prints the resolved code. Exit codes:
`0` on success, `1` on a runtime error, `2` on a
usage error.

## MCP server

```bash
npx -y @reneturcios/visaroute mcp
```

MCP client config:

```json
{
  "mcpServers": {
    "visaroute": {
      "command": "npx",
      "args": ["-y", "@reneturcios/visaroute", "mcp"]
    }
  }
}
```

## Docker

```bash
docker run -i ghcr.io/cloudcorprecords/visaroute
docker run --rm ghcr.io/cloudcorprecords/visaroute country_code '{"country":"Kenya"}'
```

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source
```

## License

MIT — Copyright (c) 2026 Rene Turcios