@gnapse/jev

A TypeScript CLI and MCP server for TypeSafe’s Jev model, built for scripts, coding agents, and automation. Ask typed questions about text or JSON and receive structured answers through either interface.

Install

Requires Node.js 22.12 or later.

npm install --global @gnapse/jev
jev --help

Quick start

Get an API key from the TypeSafe console and save it once for your user account. Login prompts for the key without displaying it:

jev auth login

jev choice 'Which team should handle this request?' \
  --option support --option billing --option other \
  --state 'Please update my payment method.'

The response contains model, answers, and usage. Convenience commands put their answer under answers.result; use --id NAME to choose another key.

The CLI and MCP server use the saved key across shells and working directories. For CI or temporary overrides, set TYPESAFE_API_KEY in the process environment; it takes priority over the saved key. jev auth status reports the source without revealing the key; jev auth logout removes the saved key.

Credentials are stored in a private, unencrypted user file. See authentication for locations and noninteractive login. The CLI does not load .env automatically; see local development to run from a checkout with a .env file.

Use in a script

Read state from stdin and save the complete JSON response:

printf '%s' 'I cannot sign in and need access today.' |
  jev noul 'Does this message ask for urgent help?' > result.json

# Optional: extract a value with jq.
jq '.answers.result.noul' result.json

Or rate a text file against ordered levels:

jev score 'How much does this issue disrupt work?' \
  --level 'No functional impact' \
  --level 'Work can continue with a workaround' \
  --level 'Work cannot continue' \
  --state-file issue.txt

Stdout contains JSON, or JSONL for batches. Errors and diagnostics go to stderr. Only jev auth login prompts; use --stdin for noninteractive login. Exit 0 means the request succeeded; your script decides what the answer means and which action to take. Use set -o pipefail in Bash or Zsh pipelines to preserve upstream failures.

See TypeSafe’s question types and confidence guide for model semantics and how to interpret answers.

Commands

| Command | Purpose | | --- | --- | | jev ask | Submit a complete request or combine question and state files. | | jev choice | Select from named options. | | jev noul | Evaluate a yes/no condition. | | jev score | Rate against ordered levels. | | jev batch | Process JSONL records with bounded concurrency. | | jev models | List available model names. | | jev validate | Validate request or question files offline. | | jev schema | Print a bundled JSON Schema. | | jev describe | Print the command contract for agents and programs. | | jev mcp | Start the local MCP server over stdio. | | jev auth login/status/logout | Save, inspect the source of, or remove an API key. |

Run jev <command> --help for flags. The CLI reference covers file input, configuration, batch results, and exit codes.

Request files and batches

Save this as request.json:

{
  "state": "Please cancel my subscription before tomorrow’s renewal.",
  "questions": {
    "cancel": {
      "type": "noul",
      "instructions": "Does the message request cancellation?"
    }
  }
}

jev validate --request request.json
jev ask --request request.json

For a batch, put a complete request on each JSONL line with a caller-supplied ID:

{"id":"ticket-1","request":{"state":"Please cancel my subscription.","questions":{"cancel":{"type":"noul","instructions":"Does the message request cancellation?"}}}}

jev batch --input requests.jsonl --ordered > results.jsonl

For shared questions, use --questions FILE with { "id": "...", "state": ... } records instead. Each result includes line, id, ok, and a response or error. Check both the process exit status and record errors before consuming a batch. See batch behavior for partial failures and retries.

MCP server

Configure your MCP client to launch command jev with arguments ["mcp"], or use this common configuration to run a pinned npm version:

{
  "mcpServers": {
    "jev": {
      "command": "npx",
      "args": ["-y", "@gnapse/[email protected]", "mcp"]
    }
  }
}

Run jev auth login once on the same machine and user account, or supply TYPESAFE_API_KEY through your client's environment or secret settings. The server provides jev_ask, jev_batch, jev_models, and jev_validate. jev_ask supports all three question types, including mixed requests. Both interfaces share validation, API behavior, and complete structured results.

See the MCP reference for arguments, limits, cancellation, and errors. Use the CLI for large JSONL streams; MCP batches accept up to 100 records.

To embed these tools in a hosted MCP service, import createJevMcpServerFactory from @gnapse/jev/mcp. See hosting and embedding for the explicit configuration and lifecycle contract.

Agent skill

The npm package includes an Agent Skills skill at skills/jev/SKILL.md. It teaches agents how to prepare requests, group questions, process batches, and handle CLI or MCP results.

After installing @gnapse/jev globally, install its skill with the skills installer (Node.js 22.20+):

npx skills add "$(npm root -g)/@gnapse/jev/skills/jev" --global

The installer lets you select your agent. Omit --global to install for the current project. For a local npm dependency, use ./node_modules/@gnapse/jev/skills/jev as the source; from this checkout, use ./skills/jev. You can also copy the entire skill directory to your agent's skill directory manually.

Installing @gnapse/jev ships the skill files; it does not activate them or modify agent settings. Rerun the skill installation after updating the CLI to refresh the installed instructions.

Agents can discover the CLI and validate requests without an API key:

jev describe
jev schema request
jev ask --request request.json --dry-run

The default model is jev-latest. Use --model ID to pin a version for repeatable automation. See TypeSafe's models and API reference for current service capabilities.

Examples

The repository's examples include CI failure triage, agent claim checks, semantic search over files, diff labels, and exact email extraction. They are not included in the npm package; run them from a source checkout.

Contributing

See CONTRIBUTING.md for setup, tests, architecture, and release steps. Changes are listed in the changelog.

License

MIT.