apexe¶

Outside-In CLI-to-Agent Bridge — automatically wraps existing CLI tools into governed apcore modules, served via MCP.

What is apexe?¶

apexe scans any CLI tool on your system (e.g., git, curl, ls, jq), deterministically extracts its command structure, flags, and arguments — then exposes them as governed MCP tools that AI agents can invoke safely.

No LLM required for scanning. No changes to the CLI tools. Zero-config governance.

Key capabilities¶

Scan — Three-tier deterministic engine (--help → man pages → shell completions) with 4 built-in parsers (GNU, Click, Cobra, Clap)
Schema — Generates JSON Schema with type mapping, format hints (path, uri), defaults, enums, and required fields
Serve — MCP server via apcore-mcp (stdio / streamable-http / SSE) with JWT auth and Explorer UI
Govern — Behavioral annotations (readonly/destructive/idempotent), flag boosting (--force → requires_approval), default-deny ACL, audit logging
AI Guidance — Every error includes ai_guidance to help agents self-correct; non-zero exit codes return stderr context

Built on the apcore ecosystem¶

Crate	Role
apcore 0.14	Module trait, Registry, ACL, ModuleError, Context
apcore-toolkit 0.4	ScannedModule, YAMLWriter, DisplayResolver
apcore-mcp 0.11	MCP server with middleware, auth, Explorer UI
apcore-cli 0.3	AuditLogger, Sandbox

Installation¶

Requires Rust 1.75+ and Cargo.

git clone https://github.com/aiperceivable/apexe.git
cd apexe
cargo install --path .
apexe --version

Quick Start¶

# Scan git — extracts commands, flags, types, annotations
apexe scan git

# See what was generated
apexe list

# Start MCP server (Claude Desktop / Cursor)
apexe serve

# Or HTTP with browser-based tool explorer
apexe serve --transport http --port 8000 --explorer

Claude Desktop integration¶

apexe serve --show-config claude-desktop
# Copy output to ~/Library/Application Support/Claude/claude_desktop_config.json
# Restart Claude Desktop — git commands appear as MCP tools

Cursor integration¶

apexe serve --show-config cursor
# Add to Cursor's MCP settings

Commands¶

`apexe scan <TOOLS>...`¶

Scan CLI tools and generate binding files + ACL rules.

apexe scan ls jq curl                   # Scan multiple tools
apexe scan git --depth 3               # 3 levels of subcommands (default: 2, max: 5)
apexe scan git --no-cache              # Force re-scan
apexe scan git --format json           # Output as JSON (also: yaml, table)
apexe scan git --output-dir ./out      # Custom output directory

`apexe serve`¶

Start MCP server for scanned tools.

apexe serve                                         # stdio (default)
apexe serve --transport http --port 8000             # HTTP
apexe serve --transport http --port 8000 --explorer  # HTTP + browser UI
apexe serve --transport sse --port 8000              # Server-Sent Events
apexe serve --show-config claude-desktop             # Print integration config
apexe serve --name my-tools                          # Custom server name

`apexe list`¶

List registered modules.

apexe list                  # Table format
apexe list --format json    # JSON format

`apexe config`¶

Show or initialize configuration.

apexe config --show     # Print resolved config (YAML)
apexe config --init     # Create ~/.apexe/config.yaml

How It Works¶

CLI Tool Binary
      |
      v
+--------------------+
|   Scanner Engine   |  <-- Tier 1: --help (GNU/Click/Cobra/Clap)
|                    |  <-- Tier 2: man pages (DESCRIPTION + OPTIONS)
|                    |  <-- Tier 3: shell completions (subcommand discovery)
+---------+----------+
          |  ScannedCLITool
          v
+--------------------+
|   Adapter Layer    |  <-- module IDs, JSON Schema, annotations, display metadata
+---------+----------+
          |  ScannedModule (apcore-toolkit)
          |
    +-----+-----+
    |           |
    v           v
+--------+  +------------------+
| Output |  |   MCP Server     |
| .yaml  |  | apcore-mcp       |
| ACL    |  | stdio/http/sse   |
| Audit  |  | middleware+auth   |
+--------+  +------------------+

Behavioral annotations¶

Signal	Inference
Command `list`, `show`, `status`, `get`	`readonly: true`, `cacheable: true`
Command `delete`, `rm`, `kill`, `destroy`	`destructive: true`, `requires_approval: true`
Flag `--force`, `-f`, `--hard`	Escalates to `requires_approval: true`
Flag `--dry-run`, `--check`, `--simulate`	`idempotent: true`

Schema generation¶

CLI Type	JSON Schema
`--message "hello"`	`"type": "string"`
`--count 5`	`"type": "integer"`
`--config /path`	`"type": "string", "format": "path"`
`--url https://...`	`"type": "string", "format": "uri"`
`--format json\\|yaml`	`"type": "string", "enum": ["json","yaml"]`
`--include a --include b`	`"type": "array", "items": {"type":"string"}`

Configuration¶

Resolved in 4 tiers (highest wins): CLI flags > env vars > config file > defaults

apexe config --init    # Creates ~/.apexe/config.yaml

Env Variable	Default	Description
`APEXE_MODULES_DIR`	`~/.apexe/modules`	Binding file storage
`APEXE_CACHE_DIR`	`~/.apexe/cache`	Scan cache
`APEXE_LOG_LEVEL`	`info`	Log level
`APEXE_TIMEOUT`	`30`	CLI subprocess timeout (seconds)
`APEXE_SCAN_DEPTH`	`2`	Subcommand recursion depth

File Locations¶

Path	Purpose
`~/.apexe/config.yaml`	Configuration
`~/.apexe/modules/*.binding.yaml`	Generated tool bindings
`~/.apexe/cache/`	Scan result cache
`~/.apexe/acl.yaml`	Access control rules
`~/.apexe/audit.jsonl`	Audit trail

Examples¶

See examples/README.md for full details.

Example	Description	Run
basic	Shell script: scan → list → serve	`./examples/basic/run.sh`
programmatic	Rust library: scan → convert → export OpenAI tools → build MCP server	`cargo run --example programmatic`

Developer Guide¶

Build & Test¶

cargo build                                             # Build
cargo test --all-features                               # Run tests (~338)
cargo test -- --include-ignored                         # Include integration tests
cargo clippy --all-targets --all-features -- -D warnings  # Lint
cargo fmt --all -- --check                              # Format check
cargo run --example programmatic                        # Run example

Adding a Custom Parser¶

Implement the CliParser trait in src/scanner/protocol.rs:

pub trait CliParser: Send + Sync {
    fn name(&self) -> &str;
    fn can_parse(&self, help_text: &str) -> bool;
    fn parse(&self, help_text: &str, tool_name: &str) -> anyhow::Result<ParsedHelp>;
    fn priority(&self) -> u32; // lower = tried first
}

Logging¶

RUST_LOG=debug apexe scan git
apexe --log-level trace scan git

Documentation¶

Document	Description
Quick Start	Get running in 30 seconds
User Manual	Full reference — commands, config, scanning, schema generation, annotations, governance, MCP server, AI integration, error handling
Examples	Shell script walkthrough + Rust library API usage
Changelog	Release history and migration notes

Architecture & Design¶

Document	Description
Technical Design	v0.1.0 architecture with apcore ecosystem integration
Feature Manifest	Module map, crate dependencies, project status
Feature Specs	Detailed specifications for features F1-F7

Feature Specs¶

Spec	Description
F1: Scanner Adapter	ScannedCLITool → ScannedModule conversion
F2: Module Executor	apcore Module trait for CLI subprocess execution
F3: Binding Output	apcore-toolkit YAMLWriter integration
F4: MCP Server	apcore-mcp server builder
F5: Governance	ACL + AuditLogger + Sandbox wrappers
F6: Error Migration	ApexeError → ModuleError conversion
F7: Config Integration	apcore Config integration

License¶

Apache-2.0