CLI Module - MCP Tool Specification

This document defines the Model Context Protocol (MCP) tools for the cli module, which serves as the primary command-line interface entry point for the Codomyrmex platform.

General Considerations for CLI Tools

Dependencies: Requires logging_monitoring module. Many handlers depend on their respective domain modules (e.g., handle_ai_generate requires agents module).
Initialization: No module-level initialization required. Individual handlers may initialize their dependencies lazily.
Error Handling: Errors are logged via logging_monitoring. Tools return {"success": false, "error": "description"} on failure.
Security: CLI tools execute with the permissions of the calling process. File path parameters are validated against the working directory.

Tool: `cli_check_environment`

1. Tool Purpose and Description

Verifies the Codomyrmex environment setup, checking for required dependencies, configuration files, and system prerequisites. Essential for diagnosing installation issues and ensuring the platform is ready for use.

2. Invocation Name

cli_check_environment

3. Input Schema (Parameters)

Parameter Name	Type	Required	Description	Example Value
`verbose`	`boolean`	No	Enable verbose output with detailed dependency information. Default: false	`true`

Notes on Input Schema:

This tool has minimal parameters as it performs a standardized environment check.

4. Output Schema (Return Value)

Field Name	Type	Description	Example Value
`success`	`boolean`	Whether all environment checks passed	`true`
`checks`	`array[object]`	List of individual check results	See below
`checks[].name`	`string`	Name of the check	`"python_version"`
`checks[].passed`	`boolean`	Whether the check passed	`true`
`checks[].message`	`string`	Detailed status message	`"Python 3.11.4 detected"`
`missing_dependencies`	`array[string]`	List of missing required dependencies	`["docker"]`
`warnings`	`array[string]`	Non-critical issues detected	`["Optional module 'spatial' not installed"]`

5. Error Handling

EnvironmentError: Raised when critical environment checks fail
PermissionError: Raised when unable to access required paths
Return Format: {"success": false, "error": "Environment check failed: <details>"}

6. Idempotency

Idempotent: Yes
Explanation: This tool only performs read operations and checks. Repeated calls will return the same result given an unchanged environment.

7. Usage Examples (for MCP context)

{
  "tool_name": "cli_check_environment",
  "arguments": {
    "verbose": true
  }
}

8. Security Considerations

Input Validation: No user-supplied paths or code execution.
Permissions: Reads environment variables and checks file existence only.
Data Handling: No sensitive data processed.

Tool: `cli_show_modules`

1. Tool Purpose and Description

Lists all available Codomyrmex modules with their status, version, and health information. Useful for discovering platform capabilities and diagnosing module-specific issues.

2. Invocation Name

cli_show_modules

3. Input Schema (Parameters)

Parameter Name	Type	Required	Description	Example Value
`filter_status`	`enum["available", "unavailable", "all"]`	No	Filter modules by availability status. Default: "all"	`"available"`
`include_details`	`boolean`	No	Include detailed module information (version, dependencies). Default: false	`true`

4. Output Schema (Return Value)

Field Name	Type	Description	Example Value
`modules`	`array[object]`	List of module information	See below
`modules[].name`	`string`	Module name	`"coding"`
`modules[].status`	`string`	Availability status	`"available"`
`modules[].version`	`string`	Module version	`"0.1.0"`
`modules[].description`	`string`	Brief module description	`"Code execution and review"`
`total_count`	`integer`	Total number of modules	`55`
`available_count`	`integer`	Number of available modules	`52`

5. Error Handling

ModuleNotFoundError: If module discovery fails
Return Format: {"success": false, "error": "Failed to enumerate modules: <details>"}

6. Idempotency

Idempotent: Yes
Explanation: Read-only operation that queries module registry.

7. Usage Examples (for MCP context)

{
  "tool_name": "cli_show_modules",
  "arguments": {
    "filter_status": "available",
    "include_details": true
  }
}

8. Security Considerations

Input Validation: Enum validation for filter_status.
Permissions: Read-only access to module metadata.
Data Handling: No sensitive data exposed.

Tool: `cli_show_system_status`

1. Tool Purpose and Description

Displays comprehensive system status including resource utilization, active workflows, running processes, and service health. Provides a dashboard view of the Codomyrmex platform state.

2. Invocation Name

cli_show_system_status

3. Input Schema (Parameters)

Parameter Name	Type	Required	Description	Example Value
`include_resources`	`boolean`	No	Include CPU/memory/disk usage. Default: true	`true`
`include_workflows`	`boolean`	No	Include active workflow status. Default: true	`true`
`format`	`enum["text", "json"]`	No	Output format. Default: "json"	`"json"`

4. Output Schema (Return Value)

Field Name	Type	Description	Example Value
`status`	`string`	Overall system status	`"healthy"`
`resources`	`object`	Resource utilization (if requested)	See below
`resources.cpu_percent`	`float`	CPU utilization percentage	`45.2`
`resources.memory_percent`	`float`	Memory utilization percentage	`68.5`
`resources.disk_percent`	`float`	Disk utilization percentage	`32.1`
`workflows`	`object`	Workflow status (if requested)	See below
`workflows.active`	`integer`	Number of running workflows	`2`
`workflows.queued`	`integer`	Number of queued workflows	`5`
`services`	`array[object]`	Service health status	See below
`timestamp`	`string`	ISO timestamp of status check	`"2026-02-03T10:30:00Z"`

5. Error Handling

RuntimeError: If unable to collect system metrics
Return Format: {"success": false, "error": "Status collection failed: <details>"}

6. Idempotency

Idempotent: Yes
Explanation: Read-only status query with no side effects.

7. Usage Examples (for MCP context)

{
  "tool_name": "cli_show_system_status",
  "arguments": {
    "include_resources": true,
    "include_workflows": true,
    "format": "json"
  }
}

8. Security Considerations

Input Validation: Enum validation for format parameter.
Permissions: Requires read access to system metrics.
Data Handling: May expose system resource information; appropriate for trusted environments.

Tool: `cli_workflow_run`

1. Tool Purpose and Description

Executes a defined workflow by name, optionally with custom parameters. Workflows orchestrate multi-step operations across Codomyrmex modules.

2. Invocation Name

cli_workflow_run

3. Input Schema (Parameters)

Parameter Name	Type	Required	Description	Example Value
`workflow_name`	`string`	Yes	Name of the workflow to execute	`"ai-analysis"`
`params`	`object`	No	JSON parameters to pass to the workflow	`{"target_path": "./src"}`
`async_execution`	`boolean`	No	Run workflow asynchronously. Default: false	`false`
`timeout`	`integer`	No	Execution timeout in seconds. Default: 300	`600`

4. Output Schema (Return Value)

Field Name	Type	Description	Example Value
`success`	`boolean`	Whether workflow completed successfully	`true`
`workflow_id`	`string`	Unique identifier for this execution	`"wf-abc123"`
`status`	`string`	Execution status	`"completed"`
`result`	`object`	Workflow output data	`{"files_processed": 42}`
`duration_seconds`	`float`	Execution duration	`23.5`
`steps_completed`	`integer`	Number of workflow steps completed	`5`

5. Error Handling

WorkflowNotFoundError: Specified workflow does not exist
WorkflowTimeoutError: Execution exceeded timeout
WorkflowExecutionError: Step failure during execution
Return Format: {"success": false, "error": "Workflow failed: <details>", "failed_step": "<step_name>"}

6. Idempotency

Idempotent: No
Explanation: Workflow execution may modify files, create resources, or have other side effects depending on workflow definition.

7. Usage Examples (for MCP context)

{
  "tool_name": "cli_workflow_run",
  "arguments": {
    "workflow_name": "code-review",
    "params": {
      "target_path": "./src/codomyrmex/coding",
      "output_format": "json"
    },
    "timeout": 300
  }
}

8. Security Considerations

Input Validation: Workflow name validated against registered workflows. Parameters validated per workflow schema.
Permissions: Workflow execution inherits CLI process permissions.
Data Handling: Workflows may process source code; ensure appropriate access controls.
File Paths: All file paths in params are validated and sandboxed.

Tool: `cli_ai_generate`

1. Tool Purpose and Description

Generates code using AI assistance based on a natural language prompt. Leverages configured LLM providers to produce code in the specified programming language.

2. Invocation Name

cli_ai_generate

3. Input Schema (Parameters)

Parameter Name	Type	Required	Description	Example Value
`prompt`	`string`	Yes	Natural language description of code to generate	`"Create a function to validate email addresses"`
`language`	`string`	No	Target programming language. Default: "python"	`"typescript"`
`provider`	`string`	No	LLM provider to use. Default: "openai"	`"anthropic"`
`output_path`	`string`	No	File path to save generated code	`"./src/validators.py"`
`max_tokens`	`integer`	No	Maximum tokens in response. Default: 2048	`4096`

4. Output Schema (Return Value)

Field Name	Type	Description	Example Value
`success`	`boolean`	Whether generation succeeded	`true`
`code`	`string`	Generated source code	`"def validate_email..."`
`language`	`string`	Language of generated code	`"python"`
`provider`	`string`	LLM provider used	`"openai"`
`model`	`string`	Specific model used	`"gpt-4o"`
`tokens_used`	`integer`	Total tokens consumed	`856`
`output_path`	`string`	Path where code was saved (if specified)	`"./src/validators.py"`

5. Error Handling

ProviderError: LLM provider unavailable or authentication failed
RateLimitError: Provider rate limit exceeded
GenerationError: AI failed to generate valid code
Return Format: {"success": false, "error": "Generation failed: <details>"}

6. Idempotency

Idempotent: No
Explanation: Each call may produce different generated code. If output_path is specified, file will be overwritten.

7. Usage Examples (for MCP context)

{
  "tool_name": "cli_ai_generate",
  "arguments": {
    "prompt": "Create a TypeScript function that fetches data from a REST API with retry logic and exponential backoff",
    "language": "typescript",
    "provider": "anthropic",
    "output_path": "./src/api/fetcher.ts"
  }
}

8. Security Considerations

Input Validation: Prompt sanitized for injection attacks. Language validated against supported list.
Permissions: Requires API keys for LLM providers (read from environment/config).
Data Handling: Prompts sent to external LLM providers; do not include sensitive data in prompts.
File Paths: Output paths validated and restricted to project directory.
Output Sanitization: Generated code is not automatically executed.

Tool: `cli_analyze_code`

1. Tool Purpose and Description

Performs static code analysis on a file or directory, checking for code quality issues, security vulnerabilities, and style violations. Integrates with multiple analysis tools.

2. Invocation Name

cli_analyze_code

3. Input Schema (Parameters)

Parameter Name	Type	Required	Description	Example Value
`path`	`string`	Yes	Path to file or directory to analyze	`"./src/codomyrmex/"`
`output`	`string`	No	Directory for analysis reports	`"./reports/"`
`include_security`	`boolean`	No	Include security vulnerability scan. Default: true	`true`
`include_metrics`	`boolean`	No	Include code metrics (complexity, etc). Default: true	`true`
`format`	`enum["text", "json", "html"]`	No	Report output format. Default: "json"	`"json"`

4. Output Schema (Return Value)

Field Name	Type	Description	Example Value
`success`	`boolean`	Whether analysis completed	`true`
`files_analyzed`	`integer`	Number of files processed	`42`
`issues`	`array[object]`	List of detected issues	See below
`issues[].severity`	`string`	Issue severity (error, warning, info)	`"warning"`
`issues[].file`	`string`	File path containing issue	`"./src/module.py"`
`issues[].line`	`integer`	Line number	`45`
`issues[].message`	`string`	Issue description	`"Function too complex"`
`issues[].rule`	`string`	Rule/check identifier	`"C901"`
`metrics`	`object`	Code metrics summary	See below
`security_findings`	`array[object]`	Security issues found	See below
`output_path`	`string`	Path to detailed report	`"./reports/analysis.json"`

5. Error Handling

FileNotFoundError: Specified path does not exist
AnalysisError: Analysis tool failed
Return Format: {"success": false, "error": "Analysis failed: <details>"}

6. Idempotency

Idempotent: Yes
Explanation: Analysis is read-only. Repeated calls on unchanged code produce identical results.

7. Usage Examples (for MCP context)

{
  "tool_name": "cli_analyze_code",
  "arguments": {
    "path": "./src/codomyrmex/coding/",
    "output": "./reports/",
    "include_security": true,
    "include_metrics": true,
    "format": "json"
  }
}

8. Security Considerations

Input Validation: Path validated to exist within allowed directories.
Permissions: Read access to source files, write access to output directory.
Data Handling: Source code is analyzed but not transmitted externally.
File Paths: Strict path validation prevents traversal attacks.

Tool: `cli_project_create`

1. Tool Purpose and Description

Creates a new Codomyrmex project with specified template, setting up directory structure, configuration files, and initial dependencies.

2. Invocation Name

cli_project_create

3. Input Schema (Parameters)

Parameter Name	Type	Required	Description	Example Value
`name`	`string`	Yes	Project name (alphanumeric, hyphens, underscores)	`"my-analysis-project"`
`template`	`string`	No	Project template to use. Default: "ai_analysis"	`"web_application"`
`description`	`string`	No	Project description	`"Data analysis pipeline"`
`path`	`string`	No	Parent directory for project. Default: current directory	`"./projects/"`

4. Output Schema (Return Value)

Field Name	Type	Description	Example Value
`success`	`boolean`	Whether project was created	`true`
`project_path`	`string`	Full path to created project	`"./projects/my-analysis-project"`
`template_used`	`string`	Template applied	`"ai_analysis"`
`files_created`	`array[string]`	List of created files	`["pyproject.toml", "README.md"]`
`next_steps`	`array[string]`	Suggested next actions	`["cd my-project", "uv sync"]`

5. Error Handling

ProjectExistsError: Project directory already exists
TemplateNotFoundError: Specified template not available
PermissionError: Cannot create directory at specified path
Return Format: {"success": false, "error": "Project creation failed: <details>"}

6. Idempotency

Idempotent: No
Explanation: Creates new files and directories. Re-running with same name will fail if project exists.

7. Usage Examples (for MCP context)

{
  "tool_name": "cli_project_create",
  "arguments": {
    "name": "code-review-system",
    "template": "ai_analysis",
    "description": "Automated code review with LLM integration",
    "path": "./projects/"
  }
}

8. Security Considerations

Input Validation: Project name sanitized (alphanumeric, hyphens, underscores only). Path validated.
Permissions: Requires write access to parent directory.
Data Handling: No sensitive data processed.
File Paths: Path traversal prevented; projects created within allowed directories.

Tool: `cli_skills_search`

1. Tool Purpose and Description

Searches available skills by keyword or category. Skills are reusable capability definitions that can be composed into workflows.

2. Invocation Name

cli_skills_search

3. Input Schema (Parameters)

Parameter Name	Type	Required	Description	Example Value
`query`	`string`	Yes	Search query for skills	`"code analysis"`
`category`	`string`	No	Filter by skill category	`"Development"`
`limit`	`integer`	No	Maximum results to return. Default: 20	`10`

4. Output Schema (Return Value)

Field Name	Type	Description	Example Value
`success`	`boolean`	Whether search succeeded	`true`
`results`	`array[object]`	Matching skills	See below
`results[].name`	`string`	Skill name	`"code_review"`
`results[].category`	`string`	Skill category	`"Development"`
`results[].description`	`string`	Skill description	`"Automated code review"`
`results[].match_score`	`float`	Search relevance score	`0.95`
`total_results`	`integer`	Total matching skills	`5`

5. Error Handling

SearchError: Search index unavailable
Return Format: {"success": false, "error": "Search failed: <details>"}

6. Idempotency

Idempotent: Yes
Explanation: Read-only search operation.

7. Usage Examples (for MCP context)

{
  "tool_name": "cli_skills_search",
  "arguments": {
    "query": "security vulnerability scanning",
    "category": "Security",
    "limit": 10
  }
}

8. Security Considerations

Input Validation: Query sanitized, category validated against known categories.
Permissions: Read-only access to skills registry.
Data Handling: No sensitive data involved.

Tool: `cli_run_quick`

1. Tool Purpose and Description

Quick execution tool for running scripts, modules, or directories with minimal configuration. Supports parallel execution and glob patterns.

2. Invocation Name

cli_run_quick

3. Input Schema (Parameters)

Parameter Name	Type	Required	Description	Example Value
`target`	`string`	Yes	Script path, module name, directory, or glob pattern	`"./scripts/*.py"`
`args`	`array[string]`	No	Additional arguments to pass	`["--verbose", "--output", "results/"]`
`timeout`	`integer`	No	Timeout per script in seconds. Default: 60	`120`
`parallel`	`boolean`	No	Run matching targets in parallel. Default: false	`true`

4. Output Schema (Return Value)

Field Name	Type	Description	Example Value
`success`	`boolean`	Whether all executions succeeded	`true`
`targets_run`	`integer`	Number of targets executed	`5`
`results`	`array[object]`	Per-target results	See below
`results[].target`	`string`	Target that was run	`"./scripts/analyze.py"`
`results[].exit_code`	`integer`	Process exit code	`0`
`results[].stdout`	`string`	Standard output (truncated)	`"Analysis complete"`
`results[].duration_ms`	`float`	Execution duration	`2340.5`
`total_duration_ms`	`float`	Total execution time	`5420.2`

5. Error Handling

TargetNotFoundError: No matching targets found
ExecutionError: Script execution failed
TimeoutError: Execution exceeded timeout
Return Format: {"success": false, "error": "Execution failed: <details>", "failed_targets": [...]}

6. Idempotency

Idempotent: No
Explanation: Executes scripts which may have side effects.

7. Usage Examples (for MCP context)

{
  "tool_name": "cli_run_quick",
  "arguments": {
    "target": "./scripts/tests/*.py",
    "args": ["--verbose"],
    "timeout": 120,
    "parallel": true
  }
}

8. Security Considerations

Input Validation: Target paths validated and sandboxed. Glob patterns restricted.
Permissions: Executes scripts with CLI process permissions.
Data Handling: Script output captured but may contain sensitive data.
File Paths: Strict validation prevents arbitrary code execution outside allowed directories.

FilesExpand file tree

MCP_TOOL_SPECIFICATION.md

Latest commit

History

MCP_TOOL_SPECIFICATION.md

File metadata and controls

CLI Module - MCP Tool Specification

General Considerations for CLI Tools

Tool: cli_check_environment

1. Tool Purpose and Description

2. Invocation Name

3. Input Schema (Parameters)

4. Output Schema (Return Value)

5. Error Handling

6. Idempotency

7. Usage Examples (for MCP context)

8. Security Considerations

Tool: cli_show_modules

1. Tool Purpose and Description

2. Invocation Name

3. Input Schema (Parameters)

4. Output Schema (Return Value)

5. Error Handling

6. Idempotency

7. Usage Examples (for MCP context)

8. Security Considerations

Tool: cli_show_system_status

1. Tool Purpose and Description

2. Invocation Name

3. Input Schema (Parameters)

4. Output Schema (Return Value)

5. Error Handling

6. Idempotency

7. Usage Examples (for MCP context)

8. Security Considerations

Tool: cli_workflow_run

1. Tool Purpose and Description

2. Invocation Name

3. Input Schema (Parameters)

4. Output Schema (Return Value)

5. Error Handling

6. Idempotency

7. Usage Examples (for MCP context)

8. Security Considerations

Tool: cli_ai_generate

1. Tool Purpose and Description

2. Invocation Name

3. Input Schema (Parameters)

4. Output Schema (Return Value)

5. Error Handling

6. Idempotency

7. Usage Examples (for MCP context)

8. Security Considerations

Tool: cli_analyze_code

1. Tool Purpose and Description

2. Invocation Name

3. Input Schema (Parameters)

4. Output Schema (Return Value)

5. Error Handling

6. Idempotency

7. Usage Examples (for MCP context)

8. Security Considerations

Tool: cli_project_create

1. Tool Purpose and Description

2. Invocation Name

3. Input Schema (Parameters)

4. Output Schema (Return Value)

5. Error Handling

6. Idempotency

7. Usage Examples (for MCP context)

8. Security Considerations

Tool: cli_skills_search

1. Tool Purpose and Description

2. Invocation Name

3. Input Schema (Parameters)

4. Output Schema (Return Value)

5. Error Handling

6. Idempotency

7. Usage Examples (for MCP context)

8. Security Considerations

Tool: `cli_check_environment`

Tool: `cli_show_modules`

Tool: `cli_show_system_status`

Tool: `cli_workflow_run`

Tool: `cli_ai_generate`

Tool: `cli_analyze_code`

Tool: `cli_project_create`

Tool: `cli_skills_search`

Tool: `cli_run_quick`