tcl-mcp-server 0.1.2

# TCL MCP Server CLI Usage

The TCL MCP Server now includes a command-line interface for directly executing tools without starting the MCP server.

## Commands

### `run` - Execute a Tool

Run a specific tool by name with arguments.

```bash
# Run with key=value format (recommended for simple arguments)
tcl-mcp-server run bin__tcl_execute 'script=puts "Hello World!"'
tcl-mcp-server run user__test__working__simple_calc 'operation=add,a=5,b=3'

# Run with JSON format
tcl-mcp-server run bin__tcl_execute '{"script": "puts \"Hello World!\""}'

# Tool names can be partial (will search common namespaces)
tcl-mcp-server run tcl_execute 'script=puts "Hello"'
```

### `list` - List Available Tools

List all available tools, optionally filtered by namespace or pattern.

```bash
# List all tools
tcl-mcp-server list

# Filter by namespace
tcl-mcp-server list -n bin
tcl-mcp-server list --namespace test

# Filter by pattern
tcl-mcp-server list -f calc
tcl-mcp-server list --filter execute
```

### `info` - Get Tool Information

Display detailed information about a specific tool including its parameters.

```bash
# Get info by tool name
tcl-mcp-server info tcl_execute
tcl-mcp-server info simple_calc

# Use full tool name
tcl-mcp-server info bin___tcl_execute
```

### `server` - Start MCP Server (Default)

Start the MCP server for JSON-RPC communication over stdio. This is the default behavior when no command is specified.

```bash
# Start server (these are equivalent)
tcl-mcp-server
tcl-mcp-server server

# Start in privileged mode
tcl-mcp-server --privileged
```

## Global Options

- `--privileged` - Enable privileged mode with full TCL access and tool management capabilities
- `--runtime <RUNTIME>` - Select TCL runtime (molt|tcl)

## Examples

### Execute TCL Scripts
```bash
# Simple script
tcl-mcp-server run tcl_execute 'script=puts "Hello from TCL!"'

# Complex script with variables
tcl-mcp-server run tcl_execute 'script=set x 10; set y 20; expr {$x * $y}'

# Multi-line script (use semicolons)
tcl-mcp-server run tcl_execute 'script=set list {a b c}; foreach item $list { puts $item }'
```

### Use Built-in Tools
```bash
# Simple calculator
tcl-mcp-server run simple_calc 'operation=mul,a=7,b=8'

# List directory contents
tcl-mcp-server run list_dir 'path=/tmp'

# Access Molt documentation
tcl-mcp-server run molt_book 'topic=commands'
```

### Tool Discovery
```bash
# Find all test tools
tcl-mcp-server list -n test

# Find tools with "calc" in the name
tcl-mcp-server list -f calc

# Get detailed info about a tool
tcl-mcp-server info simple_calc
```

## Argument Formats

The `run` command supports two argument formats:

1. **Key=Value Format** (Recommended for CLI usage)
   - Simple: `'key=value'`
   - Multiple: `'key1=value1,key2=value2'`
   - Supports automatic type inference (numbers, booleans, strings)

2. **JSON Format**
   - Full JSON: `'{"key": "value", "number": 123}'`
   - Requires proper escaping for quotes

## Tool Naming Convention

Tools use a consistent naming pattern:
- **Namespace separator**: Double underscore (`__`)
- **Name parts**: Single underscore (`_`) within names
- **Examples**: 
  - `bin__tcl_execute` (bin namespace, tcl_execute tool)
  - `sbin__mcp_add` (sbin namespace, mcp_add tool)
  - `user__test__working__simple_calc` (user namespace, test package, working subpackage, simple_calc tool)

## Tips

1. Use the key=value format for easier command-line usage
2. Tool names can be partial - the CLI will search common namespaces
3. Use `--privileged` mode to access administrative tools in the `sbin` namespace
4. The `info` command shows all required and optional parameters for a tool