terminal_interface - MCP Tool Specification

Overview

This document specifies the Model Context Protocol (MCP) tools provided by the terminal_interface module.

Available Tools

tool_name

Description: [Tool description]

Parameters:

{
  "param1": {
    "type": "string",
    "description": "Parameter description",
    "required": true
  },
  "param2": {
    "type": "integer",
    "description": "Parameter description",
    "required": false,
    "default": 0
  }
}

Returns: Return value description

Example:

{
  "tool": "tool_name",
  "parameters": {
    "param1": "value",
    "param2": 42
  }
}

Tool Registration

Tools are defined with the @mcp_tool decorator in mcp_tools.py and are auto-discovered by the PAI MCP bridge; no manual registration call is needed. The decorated functions can also be called directly:

from codomyrmex.terminal_interface.mcp_tools import terminal_info, terminal_list_themes

info = terminal_info()
themes = terminal_list_themes()

Related Documentation

• Module README
• API Specification
• Usage Examples (See README for examples)

---

Tool: run_terminal_command

1. Tool Purpose and Description

Execute terminal commands and capture output for system administration and development tasks.

2. Invocation Name

run_terminal_command

3. Input Schema (Parameters)

Parameter Name	Type	Required	Description	Example Value
command	string	Yes	Terminal command to execute	"ls -la"
working_directory	string	No	Directory to execute command in	"/path/to/project"
timeout_seconds	integer	No	Command execution timeout	30
capture_output	boolean	No	Whether to capture and return command output	true

4. Output Schema (Return Value)

{
  "command": "ls -la",
  "return_code": 0,
  "stdout": "total 48
drwxr-xr-x  12 user  staff   384 Jan 18 13:46 .
drwxr-xr-x   3 user  staff    96 Jan 18 13:46 ..
-rw-r--r--   1 user  staff  1073 Jan 18 13:46 README.md
",
  "stderr": "",
  "execution_time": 0.023,
  "working_directory": "/path/to/project"
}

Tool: format_terminal_output

1. Tool Purpose and Description

Format and enhance terminal output with colors, tables, and structured display for better readability.

2. Invocation Name

format_terminal_output

3. Input Schema (Parameters)

Parameter Name	Type	Required	Description	Example Value
content	string	Yes	Content to format	"Error: Connection failed"
format_type	string	No	Type of formatting (success, error, warning, info, table, json)	"error"
table_headers	array[string]	No	Headers for table formatting	["Name", "Status", "Size"]
table_rows	array[array[string]]	No	Data rows for table formatting	[["file1.txt", "active", "1.2MB"]]

4. Output Schema (Return Value)

{
  "formatted_content": "\u001b[31m❌ Error: Connection failed\u001b[0m",
  "format_type": "error",
  "original_content": "Error: Connection failed",
  "terminal_codes": ["31m", "0m"]
}

Tool: start_interactive_shell

1. Tool Purpose and Description

Launch an interactive terminal shell session for complex multi-step operations and exploration.

2. Invocation Name

start_interactive_shell

3. Input Schema (Parameters)

Parameter Name	Type	Required	Description	Example Value
shell_type	string	No	Type of shell to launch (bash, zsh, python, codomyrmex)	"codomyrmex"
working_directory	string	No	Initial working directory	"/path/to/project"
prompt	string	No	Custom shell prompt	"codomyrmex> "
startup_commands	array[string]	No	Commands to execute on shell startup	["cd /project", "git status"]

4. Output Schema (Return Value)

{
  "shell_id": "shell_12345",
  "shell_type": "codomyrmex",
  "status": "started",
  "working_directory": "/path/to/project",
  "startup_commands_executed": 2,
  "available_commands": ["analyze", "build", "deploy", "help"]
}

Navigation Links

• Parent: Project Overview
• Module Index: All Agents
• Documentation: Reference Guides
• Home: Root README