Skip to content

holon-run/uxc

BranchesTags

Repository files navigation

UXC

Universal X-Protocol CLI

A stable execution surface for agents.

English | 简体中文

CI Coverage License: MIT Rust

UXC gives agents one stable way to discover, authenticate, and call remote tools across OpenAPI, gRPC, GraphQL, MCP, and JSON-RPC.

Instead of writing separate glue for each protocol, SDK, or local MCP setup, UXC turns remote interfaces into one predictable command contract with help-first discovery, structured execution, and deterministic JSON output.

Why UXC Exists

Agent tool use usually breaks down in the same places:

  • auth scattered across prompts, scripts, and local setup
  • different invocation models for each protocol
  • local MCP server names and config that are not portable across machines
  • large tool manifests or schemas pushed into prompt context
  • one-off wrappers that drift from upstream interfaces

UXC exists to make remote capabilities feel like one stable execution surface for agents and automation.

What UXC Does

  • Discover operations from an endpoint on demand
  • Inspect input and output shape before execution
  • Execute operations with structured arguments
  • Return deterministic JSON envelopes by default
  • Reuse auth bindings, signer profiles, and linked shortcuts

If a target can describe itself, UXC can usually call it.

Why It Works Well With Agents and Skills

  • Progressive discovery keeps context small: <host> -h, <host> <operation_id> -h, then execute
  • URL-first usage avoids dependency on machine-specific MCP aliases or local wrapper names
  • Auth bindings externalize credential matching instead of burying it in prompts
  • Linked shortcuts (uxc link) turn remote endpoints into stable local commands
  • The same command contract can be reused across many skills and workflows

Core Capabilities

  • URL-first usage: call endpoints directly, no server alias required
  • Multi-protocol detection and adapter routing
  • Schema-driven operation discovery (<host> -h, <host> <operation_id> -h)
  • Structured invocation (positional JSON, key-value args)
  • Deterministic JSON envelopes for automation and agents
  • Auth model with reusable credentials, bindings, and signer profiles
  • App-credential bootstrap for short-lived bearer tokens (for example, Feishu/Lark and DingTalk)
  • Host shortcut commands via uxc link
  • Link-level default OpenAPI schema persistence via uxc link --schema-url
  • Daemon-backed background subscriptions via uxc subscribe
  • Provider-aware event transports for Slack Socket Mode, Discord Gateway, and Feishu long connection
  • Stdio child-process auth injection via --inject-env NAME={{secret}}

Supported protocols:

  • OpenAPI / Swagger
  • gRPC (server reflection)
  • GraphQL (introspection)
  • MCP (HTTP and stdio)
  • JSON-RPC (OpenRPC-based discovery)

Architecture Snapshot

UXC keeps protocol diversity behind one execution contract:

UXC architecture snapshot

This design keeps discovery, auth, and execution stable while allowing protocol-specific internals.

Target Use Cases

  • AI agents and skills that need deterministic remote tool execution
  • CI/CD and automation jobs that need schema-driven calls without SDK setup
  • Cross-protocol integration testing with one command contract
  • Controlled runtime environments where JSON envelopes and predictable errors matter

Non-Goals

UXC is not:

  • a code generator
  • an SDK framework
  • an API gateway or reverse proxy

UXC is a stable execution surface for remote capabilities that can describe themselves.

Install

Homebrew (macOS/Linux)

brew tap holon-run/homebrew-tap
brew install uxc

Install Script (macOS/Linux)

curl -fsSL https://raw.githubusercontent.com/holon-run/uxc/main/scripts/install.sh | bash

Review before running:

curl -fsSL https://raw.githubusercontent.com/holon-run/uxc/main/scripts/install.sh -o install-uxc.sh
less install-uxc.sh
bash install-uxc.sh

Install a specific version:

curl -fsSL https://raw.githubusercontent.com/holon-run/uxc/main/scripts/install.sh | bash -s -- -v v0.12.3

Windows note: native Windows is no longer supported; run UXC through WSL.

Cargo

cargo install uxc

From Source

git clone https://github.com/holon-run/uxc.git
cd uxc
cargo install --path .

Quickstart (3 Minutes)

Most HTTP examples omit the scheme for brevity. For public hosts, UXC infers https:// when omitted.

  1. Discover operations:
uxc petstore3.swagger.io/api/v3 -h
  1. Inspect operation schema:
uxc petstore3.swagger.io/api/v3 get:/pet/{petId} -h
  1. Execute with structured input:
uxc petstore3.swagger.io/api/v3 get:/pet/{petId} petId=1

Use only these endpoint forms:

  • uxc <host> -h
  • uxc <host> <operation_id> -h
  • uxc <host> <operation_id> key=value or uxc <host> <operation_id> '{...}'

For nested object or array inputs, key-value mode also supports dotted and indexed paths:

uxc <host> <operation_id> \
  prompt="summarize this file" \
  attachmentPaths[0]=/tmp/spec.pdf

Protocol Examples (One Each)

Operation ID conventions:

  • OpenAPI: method:/path (example: get:/users/{id})
  • gRPC: Service/Method
  • GraphQL: query/viewer, mutation/createUser
  • MCP: tool name (example: ask_question)
  • JSON-RPC: method name (example: eth_getBalance)

OpenAPI

uxc petstore3.swagger.io/api/v3 -h
uxc petstore3.swagger.io/api/v3 get:/pet/{petId} petId=1

For schema-separated services, you can override schema source:

uxc api.github.com -h \
  --schema-url https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json

gRPC

uxc grpcb.in:9000 -h
uxc grpcb.in:9000 addsvc.Add/Sum a=1 b=2

Note: gRPC unary runtime invocation requires grpcurl on PATH.

GraphQL

uxc countries.trevorblades.com -h
uxc countries.trevorblades.com query/country code=US
# Prefer positional JSON for non-string object arguments
uxc api.linear.app/graphql mutation/issueCreate '{"input":{"teamId":"TEAM_ID","title":"Test"}}'
# Optional: control GraphQL return fields via reserved _select argument
uxc api.linear.app/graphql query/issues '{"first":5,"_select":"nodes { identifier title url state { name } }"}'

MCP

uxc mcp.deepwiki.com/mcp -h
uxc mcp.deepwiki.com/mcp ask_question repoName=holon-run/uxc question='What does this project do?'

MCP (stdio)

UXC can also invoke MCP servers started as local processes over stdio. For stdio endpoints, the "URL" is a quoted command line.

Playwright MCP (stdio) example:

# One-off discovery
uxc "npx -y @playwright/mcp@latest --headless --isolated" -h

# Create a stable command name for repeated use (recommended)
uxc link playwright-mcp-cli "npx -y @playwright/mcp@latest --headless --isolated"
playwright-mcp-cli -h

# Inspect an operation before calling it
playwright-mcp-cli browser_navigate -h

# Call operations with key=value args
playwright-mcp-cli browser_navigate url=https://example.com
playwright-mcp-cli browser_snapshot

JSON-RPC

uxc fullnode.mainnet.sui.io -h
uxc fullnode.mainnet.sui.io sui_getLatestCheckpointSequenceNumber

Skills

UXC provides one canonical skill plus scenario-specific official wrappers. Use uxc skill as the shared execution layer, and add wrappers when they fit your workflow.

Start Here

  • uxc: canonical schema discovery and multi-protocol execution layer
  • playwright-mcp-skill: browser automation over MCP stdio through uxc
  • context7-mcp-skill: current library documentation and examples over MCP

See docs/skills.md for publish history, validation notes, and ClawHub maintenance details.

Core and Skill Authoring
  • uxc: canonical schema discovery and multi-protocol execution layer
  • uxc-skill-creator: templates and workflow guidance for building new UXC-based skills
Browser Automation and Documentation
Workspace and Messaging
Crypto and Web3

Install Skills

Use the skill folder name as the skill id for both npx skills and ClawHub.

Install from this repository using npx skills:

# Install the shared execution layer only
npx -y skills@latest add holon-run/uxc --skill uxc --agent codex -y

# Install any selected bundle of skills from this repo
npx -y skills@latest add holon-run/uxc \
  --skill uxc \
  --skill slack-openapi-skill \
  --skill discord-openapi-skill \
  --skill bitquery-graphql-skill \
  --agent codex -y

Install published skills from ClawHub:

# Install the shared execution layer only
clawhub --workdir ~/.openclaw --dir skills install uxc

# Install any selected published skill by its folder/slug name
clawhub --workdir ~/.openclaw --dir skills install slack-openapi-skill
clawhub --workdir ~/.openclaw --dir skills install chrome-devtools-mcp-skill
clawhub --workdir ~/.openclaw --dir skills install defillama-openapi-skill

See docs/skills.md for the complete publish log and maintenance rules.

Output and Help Conventions

UXC is JSON-first by default. Use --text (or --format text) when you want human-readable CLI output.

Examples:

uxc
uxc help
uxc <host> -h
uxc <host> <operation_id> -h
uxc --text help

Note: In endpoint routing, help is treated as a literal operation name, not a help alias.

Success envelope shape:

{
  "ok": true,
  "kind": "call_result",
  "protocol": "openapi",
  "endpoint": "https://petstore3.swagger.io/api/v3",
  "operation": "get:/pet/{petId}",
  "data": {},
  "meta": {
    "version": "v1",
    "duration_ms": 128
  }
}

For MCP tools/call, data may include content, optional structuredContent, and optional isError.

Failure envelope shape:

{
  "ok": false,
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "Field 'id' must be an integer"
  },
  "meta": {
    "version": "v1"
  }
}

Auth (Credentials + Bindings)

UXC authentication has two resources:

  • Credentials: secret material and auth type
  • Bindings: endpoint matching rules that select a credential

For non-OAuth credentials, use two auth tracks:

  • simple auth: keep using --secret, --secret-env, or --secret-op
  • complex auth: use repeatable --field <name>=<source> plus optional binding-level --signer-json

Example:

uxc auth credential set deepwiki --auth-type bearer --secret-env DEEPWIKI_TOKEN
uxc auth credential set deepwiki --secret-op op://Engineering/deepwiki/token
uxc auth binding add --id deepwiki-mcp --host mcp.deepwiki.com --path-prefix /mcp --scheme https --credential deepwiki --priority 100

# api_key supports configurable header names and templates
uxc auth credential set okx --auth-type api_key --secret-env OKX_ACCESS_KEY --api-key-header OK-ACCESS-KEY
uxc auth credential set okx-advanced --auth-type api_key --header "OK-ACCESS-KEY={{secret}}" --header "OK-ACCESS-PASSPHRASE={{env:OKX_PASSPHRASE}}"

# multi-field auth for signed APIs
uxc auth credential set binance --auth-type api_key --field api_key=env:BINANCE_API_KEY --field secret_key=env:BINANCE_SECRET_KEY
uxc auth binding add --id binance-account --host api.binance.com --path-prefix /api/v3 --scheme https --credential binance --signer-json '{"kind":"hmac_query_v1","algorithm":"hmac_sha256","signing_field":"secret_key","key_field":"api_key","key_placement":"header","key_name":"X-MBX-APIKEY","signature_param":"signature","signature_encoding":"hex","timestamp_param":"timestamp","timestamp_unit":"milliseconds","canonicalization":{"mode":"preserve_order"}}' --priority 100

For --secret-op, secret resolution happens at request runtime through daemon execution. Ensure daemon has usable 1Password auth context (for example OP_SERVICE_ACCOUNT_TOKEN), and restart daemon after env changes.

OAuth for MCP HTTP is supported (device code, client credentials, authorization code + PKCE). See docs/oauth-mcp-http.md for full workflows.

Docs Map

Contributing

Contributions are welcome.

License

MIT License - see LICENSE.

About

Universal API calling CLI for URL-first discovery and invocation across OpenAPI, gRPC, GraphQL, MCP, and JSON-RPC.

github.com/holon-run/uxc#readme

Topics

api graphql cli mcp grpc openapi json-rpc developer-tools ai-agents schema-driven agent-tools model-context-protocol

Resources

Readme

License

MIT license

Contributing

Contributing
Activity
Custom properties

Stars

96 stars

Watchers

0 watching

Forks

3 forks
Report repository

Releases 18

v0.12.3 Latest
Mar 19, 2026
+ 17 releases

Packages

 
 
 

Contributors

Languages