Skip to content

tools-reference.md

Latest commit

 

History

History
283 lines (190 loc) · 10.2 KB

tools-reference.md

File metadata and controls

283 lines (190 loc) · 10.2 KB

PAI-Codomyrmex Tools Reference

Version: v1.2.3 | Last Updated: March 2026

Overview

Codomyrmex exposes tools to PAI via two mechanisms:

  1. Static tools (22): Defined in mcp_bridge.py, always available (17 core + 3 universal proxy + 2 maintenance)
  2. Dynamic tools (variable): Auto-discovered from module public functions at runtime

The PAI Skill (SKILL.md) curates a subset for MCP consumption.

Static Tools (22)

File Operations

Tool Trust Description
codomyrmex.read_file Safe Read file contents with metadata
codomyrmex.write_file Destructive Write content to a file
codomyrmex.list_directory Safe List directory contents with filtering

codomyrmex.read_file

  • Parameters: path (required), encoding (default: "utf-8"), max_size (default: 1000000)
  • Returns: File contents with metadata

codomyrmex.write_file

  • Parameters: path (required), content (required), create_dirs (default: true)
  • Returns: Write confirmation
  • Trust: Requires TRUSTED level

codomyrmex.list_directory

  • Parameters: path (default: "."), pattern (default: "*"), recursive (default: false), max_items (default: 200)
  • Returns: Directory listing

Code Analysis

Tool Trust Description
codomyrmex.analyze_python Safe Analyze Python file structure and metrics
codomyrmex.search_codebase Safe Search for patterns (regex supported)

codomyrmex.analyze_python

  • Parameters: path (required)
  • Returns: Structure analysis (classes, functions, imports, metrics)

codomyrmex.search_codebase

  • Parameters: pattern (required), path (default: "."), file_types (array), case_sensitive (default: false), max_results (default: 100)
  • Returns: Matching files and lines

Git Operations

The PAI Dashboard provides a visual interface for git repository management, wrapping these MCP tools with Push/Pull/Sync controls per-project:

PAI Git — Repository sync manager showing 18 linked repos with per-project Push, Pull, Sync, and Unlink controls

Tool Trust Description
codomyrmex.git_status Safe Get git repository status
codomyrmex.git_diff Safe Get git diff for changes

codomyrmex.git_status

  • Parameters: path (default: ".")
  • Returns: Repository status (branch, staged, modified, untracked)

codomyrmex.git_diff

  • Parameters: path (default: "."), staged (default: false)
  • Returns: Diff output

Shell

Tool Trust Description
codomyrmex.run_command Destructive Execute shell commands safely

codomyrmex.run_command

  • Parameters: command (required), cwd (default: "."), timeout (default: 30)
  • Returns: stdout, stderr, return code
  • Trust: Requires TRUSTED level

Data Utilities

Tool Trust Description
codomyrmex.json_query Safe Read/query JSON files via dot-notation
codomyrmex.checksum_file Safe Calculate file checksum (md5, sha1, sha256)

codomyrmex.json_query

  • Parameters: path (required), query (optional dot-notation path)
  • Returns: JSON data or queried subset

codomyrmex.checksum_file

  • Parameters: path (required), algorithm (default: "sha256")
  • Returns: Hex digest string

Discovery

Tool Trust Description
codomyrmex.list_modules Safe List all available Codomyrmex modules
codomyrmex.module_info Safe Get module docstring, exports, path

codomyrmex.list_modules

  • Parameters: none
  • Returns: {modules: [...], count: N}

codomyrmex.module_info

  • Parameters: module_name (required)
  • Returns: {module, docstring, exports, export_count, path}

PAI

Tool Trust Description
codomyrmex.pai_status Safe Get PAI installation status and components
codomyrmex.pai_awareness Safe Get full PAI awareness data

codomyrmex.pai_status

  • Parameters: none
  • Returns: Installation status with component counts (skills, tools, hooks, agents, memory)

codomyrmex.pai_awareness

  • Parameters: none
  • Returns: Missions, projects, tasks, TELOS, memory data

Testing

Tool Trust Description
codomyrmex.run_tests Destructive Run pytest for a module or project

codomyrmex.run_tests

  • Parameters: module (optional), verbose (default: false)
  • Returns: {returncode, passed, stdout, stderr}
  • Trust: Requires TRUSTED level (test execution may have side effects)

Universal Module Proxy (3 tools)

These tools provide generic access to any Codomyrmex module's public API:

Tool Trust Description
codomyrmex.list_module_functions Safe List all public callables in a module
codomyrmex.call_module_function Destructive Call any public function by path
codomyrmex.get_module_readme Safe Read module README/SPEC docs

codomyrmex.list_module_functions

  • Parameters: module (required, e.g. "encryption", "cache")
  • Returns: {module, functions: [{name, signature, docstring}], classes: [{name, docstring, public_methods}], total_callables}

codomyrmex.call_module_function

  • Parameters: function (required, e.g. "encryption.encrypt"), kwargs (optional dict)
  • Returns: {result: ...} or {error: ...}
  • Trust: Requires TRUSTED level (arbitrary code execution)
  • Safety: Private functions (underscore-prefixed) are blocked

codomyrmex.get_module_readme

  • Parameters: module (required)
  • Returns: {module, path, content} (truncated at 5000 chars)

Maintenance (2 tools)

Tool Trust Description
codomyrmex.list_workflows Safe List all registered workflow prompts
codomyrmex.invalidate_cache Safe Clear cached module/tool discovery data

codomyrmex.list_workflows

  • Parameters: none
  • Returns: {workflows: [{name, description}], count: N}

codomyrmex.invalidate_cache

  • Parameters: none
  • Returns: {status: "cleared", caches: [...]}

Dynamic Tool Discovery

Beyond the 9 static proxy tools, the MCP bridge auto-discovers additional tools at runtime:

  1. Decorated tools: Functions with @mcp_tool decorator in any mcp_tools.py submodule — 141 modules auto-discovered
  2. pkgutil scan: All mcp_tools.py files are scanned at startup (5-minute TTL cache)

Trust Classification for Dynamic Tools

Dynamic tools are classified using pattern matching on function names:

  • Names containing write, delete, execute, run, create, modify, etc. → Destructive
  • All others → Safe

See _DESTRUCTIVE_PATTERNS in trust_gateway.py for the full list.

Email / AgentMail + Gmail (12 tools)

The Email tab in the PAI Dashboard provides a browser-accessible interface for all email MCP tools:

PAI Email — AgentMail and Gmail dual-provider with inbox view, compose form, and AI-assisted drafting

Module: codomyrmex.email.mcp_tools Auth: AgentMail tools require AGENTMAIL_API_KEY. Gmail tools require GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and GOOGLE_REFRESH_TOKEN. Category: email

Tool Trust Description
agentmail_list_inboxes Safe List AgentMail inboxes
agentmail_create_inbox Destructive Create a new AgentMail inbox
agentmail_send_message Destructive Send an email from an AgentMail inbox
agentmail_list_messages Safe List messages in an AgentMail inbox
agentmail_get_message Safe Fetch a specific message by ID
agentmail_reply_to_message Destructive Reply to an existing message
agentmail_list_threads Safe List conversation threads in an inbox
agentmail_create_webhook Destructive Register a webhook for inbox events
gmail_send_message Destructive Send an email via Gmail API
gmail_list_messages Safe List messages in the Gmail inbox
gmail_get_message Safe Fetch a specific Gmail message by ID
gmail_create_draft Destructive Create a Gmail draft without sending

Notes:

  • AgentMail tools require agentmail>=0.2.17 (uv sync --extra email)
  • Gmail tools require Google OAuth2 credentials in environment variables
  • Inbox defaults to AGENTMAIL_DEFAULT_INBOX env var when inbox_id is omitted
  • Full provider API: src/codomyrmex/email/agentmail/API_SPECIFICATION.md

Calendar / Google Calendar (5 tools)

Module: codomyrmex.calendar_integration.mcp_tools Auth: Requires GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and GOOGLE_REFRESH_TOKEN. Category: calendar

Tool Trust Description
gcal_list_calendars Safe List all accessible Google Calendars
gcal_list_events Safe List events from a calendar with date range filters
gcal_create_event Destructive Create a new calendar event with attendees
gcal_update_event Destructive Update an existing calendar event
gcal_delete_event Destructive Delete a calendar event by ID

Notes:

  • Calendar tools require Google OAuth2 credentials in environment variables
  • Default calendar is primary when calendar_id is omitted
  • Full provider API: src/codomyrmex/calendar_integration/gcal/

Tool Count Summary

Category Count Trust
Static proxy 9 Auto-VERIFIED
Static destructive 4 Requires TRUSTED
Dynamic safe ~299 Pattern-classified, auto-VERIFIED
Dynamic destructive 4 Requires TRUSTED
Total ~303 —

Run /codomyrmexVerify to get the current exact count. Total reflects 141 auto-discovered modules (Sprint 22).

Navigation