cts

中文文档

cts turns heterogeneous capabilities into stable commands.

You can compile local CLIs, shell scripts, HTTP APIs, OpenAPI specs, GraphQL services, and MCP servers into one consistent command surface, then expose them through CLI, invoke, HTTP, and UI.

Recommended Path

If you're new to cts, this order works best:

1. Import one local shell command and see it run immediately
2. Import one local CLI command
3. Try MCP / HTTP / OpenAPI / GraphQL
4. Move on to mounts, execution, plugins, and hooks

Useful entry points:

• Usage Guide
• Quickstart
• Local CLI
• Shell
• HTTP
• OpenAPI
• GraphQL
• MCP
• Mounts
• Execution
• Plugins
• Hooks

Install

pip install cts

From a wheel file:

python3 -m pip install ./dist/cts-0.1.0-py3-none-any.whl

From source:

git clone https://github.com/xlb1130/cli-tools.git
cd cli-tools
pip install -e .

MCP Dependencies

To use MCP (Model Context Protocol) features, you need additional dependencies:

1. Node.js and npm (required for MCP bridge):

# macOS (using Homebrew)
brew install node

# Or using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts

The MCP bridge will automatically install @modelcontextprotocol/sdk on first use.

2. mcp-cli (optional, provides better performance for stdio/SSE MCP servers):

npm install -g mcp-cli

mcp-cli is an optional adapter that provides native CLI access to MCP servers. CTS currently targets the modern CLI syntax, for example mcp-cli call <server> <tool> '{...}'. If mcp-cli is not installed, CTS will fall back to the Node.js bridge automatically.

Provider-Driven Import

cts import is now provider-driven:

cts import <provider-type> ...
cts import wizard
cts import wizard <provider-type>

Built-in provider types include:

• shell
• cli
• http
• openapi
• graphql
• mcp

Plugin-provided provider types can also expose their own import command and wizard automatically.

Start With A One-Line Shell Import

This is the fastest starting point because it does not depend on external services or a config file you write by hand.

cts import shell hello --exec 'echo Hello cts!' --apply
cts hello

Then inspect the generated dynamic command:

cts hello --help
cts manage explain hello

This gives you a concrete model of:

• source: hello
• operation: run
• mount: hello
• command path: hello

Import A Local CLI

The most common entry point is:

cts import cli <source-name> <command> [subcommand...] --apply

Example:

cts import cli git-status git status --apply
cts git-status --help
cts git-status

To import a full command tree:

cts import cli git git --all --apply --under git

Continue with Local CLI.

Import An MCP Server

The shortest path is:

cts import mcp my-mcp \
  --server-config '{"type":"sse","url":"https://mcp.api-inference.modelscope.net/6d85ac1213db43/sse"}' \
  --apply

Then check what was discovered:

cts manage source show my-mcp --format json
cts manage source test my-mcp --discover --format json
cts my-mcp --help

Use --include / --exclude / --tag to filter which operations to mount (works for all providers):

cts import mcp my-mcp \
  --server-config '{"type":"sse","url":"..."}' \
  --include 'search_*' \
  --exclude 'delete_*' \
  --apply

Continue with MCP.

Start the Web UI

Launch the built-in web interface to interact with your CTS instance:

cts manage ui

This starts the HTTP API together with the bundled frontend UI. By default it runs on http://127.0.0.1:8787.

Additional options:

# Open browser automatically
cts manage ui --open

# Use custom host/port
cts manage ui --host 0.0.0.0 --port 9000

# Use a custom UI directory
cts manage ui --ui-dir /path/to/ui/dist

If the UI assets are not found, build them first:

cd frontend/app
npm install
npm run build

For more control, you can also use the HTTP server command:

# Start HTTP API only
cts manage serve http

# Start HTTP API with UI
cts manage serve http --ui

# Start HTTP API with UI and open browser
cts manage serve http --ui --open

Typical Scenarios

Why Unified CLI Matters:

• Stable interface: Mount bindings create predictable command paths—AI and scripts don't need to guess tool names or parameters
• Multi-surface access: One import exposes capabilities through CLI, HTTP, UI, and MCP simultaneously
• Cross-provider consistency: MCP tools, OpenAPI endpoints, local CLIs, and shell scripts all become first-class commands
• Governance built-in: Hooks for logging, auth, rate limiting, approval workflows—applied uniformly across all sources

CTS vs Traditional Multi-MCP Configuration:

High-Level Scenarios:

• Travel Planning: Combine Gaode, 12306, and Bing MCPs with unified command access
• Automated Issue Analysis & Deployment: Chain logs, DB, deploy, and notification tools with governance hooks

Core Model

source -> operation -> mount -> surface

• source: where the capability comes from
• operation: one concrete action in that source
• mount: stable id and command path bound to the operation
• surface: how the mount is exposed

Common Commands

# View source details
cts manage source show <source> --format json

# Test and discover operations
cts manage source test <source> --discover --format json

# List mounts
cts manage mount list --format json

# Remove a source
cts manage source remove <source_name> --force --format json

# Invoke a mount
cts manage invoke <mount-id> --input-json '{"key":"value"}' --format json

# Explain a mount
cts manage explain <mount-id> --input-json '{"key":"value"}'

Command Index Warmup

If your config is large or your mounted command tree is wide, you can precompile the command index:

cts manage config warm-index --format json

To inspect whether the current index is still valid, and which dependency files caused it to become stale:

cts manage config index-status --format json

When config is updated through source, mount, alias, or import commands, the command index is refreshed automatically.

Development

git clone https://github.com/xlb1130/cli-tools.git
cd cli-tools
python3 -m pip install -e ".[dev]"

Recommended day-to-day workflow:

# Run the local source tree directly
PYTHONPATH=src python3 -m cts.main --help

# Try the shell quickstart against local code
PYTHONPATH=src python3 -m cts.main import shell hello --exec 'echo Hello cts!' --apply
PYTHONPATH=src python3 -m cts.main hello

Useful validation commands:

# Compile and lint config/runtime
PYTHONPATH=src python3 -m cts.main manage config lint --compile --format json

# Run tests
python3 -m pytest

# Run one focused test file
python3 -m pytest tests/test_cli_management.py -q

Frontend development:

cd frontend/app
npm install
npm run build

If you want the installed cts command to use your local changes immediately:

python3 -m pip install -e .

This matters when you add CLI commands such as cts import shell, because your terminal may still be using an older installed package.

More

• Usage Guide
• Architecture
• Install And Usage

License

MIT