# MCP Tools

> MCP tool implementation patterns for HestAI including tool structure, session tools, and shared utilities

- Skill: `elevanaltd-hestai-mcp/mcp-tools` (Agent Skill)
- Install (CLI): `npx skillmds@latest add elevanaltd-hestai-mcp/mcp-tools`
- Raw SKILL.md: https://api.skillmd.com/api/skills/elevanaltd-hestai-mcp/mcp-tools/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: elevanaltd (https://skillmd.com/u/elevanaltd-hestai-mcp)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/elevanaltd-hestai-mcp/mcp-tools

---


===MCP_TOOLS===
META:
  TYPE::SKILL
  VERSION::"1.0"
  STATUS::ACTIVE
  PURPOSE::"MCP tool implementation patterns for HestAI"
  DOMAIN::HEPHAESTUS[tool_crafting]⊕HERMES[communication]

§1::TOOL_STRUCTURE
  LOCATION::src/hestai_mcp/mcp/tools/
  RETURN_TYPE::dict[str,Any]
  PATTERN::[
    "async def my_tool_async(",
    "    required_param: str,",
    "    optional_param: str | None = None,",
    ") -> dict[str, Any]:",
    "    \"\"\"Tool description.\"\"\"",
    "    # Validate inputs first",
    "    validated = validate_param(required_param)",
    "    # Implementation",
    "    return {\"status\": \"success\", \"data\": result}"
  ]

§2::SESSION_TOOLS
  CLOCK_IN::[
    PURPOSE::"Start session, returns context paths + AI synthesis",
    PARAMS::[role,working_dir,focus?,model?],
    RETURNS::[session_id,context_paths,ai_synthesis]
  ]
  CLOCK_OUT::[
    PURPOSE::"Archive session transcript to OCTAVE",
    PARAMS::[session_id,description?],
    RETURNS::[archive_path,learnings]
  ]
  BIND::[
    PURPOSE::"Bootstrap agent binding with low token usage",
    PARAMS::[role,topic?,tier?,working_dir?],
    RETURNS::[agent_file,skills,context_paths]
  ]

§3::KEY_DIRECTORIES
  CONTEXT::.hestai/state/context/["Living context files (PROJECT-CONTEXT, etc.)"]
  ACTIVE::.hestai/state/sessions/active/["Current session data (gitignored)"]
  ARCHIVE::.hestai/state/sessions/archive/["Compressed session archives"]
  NORTH_STAR::.hestai/north-star/["North Star and specs (committed, PR-controlled)"]

§4::SHARED_UTILITIES
  LOCATION::src/hestai_mcp/mcp/tools/shared/
  MODULES::[
    path_resolution.py::"Path validation and traversal prevention",
    security.py::"Input sanitization",
    fast_layer.py::"Git state and branch detection",
    compression.py::"OCTAVE compression helpers"
  ]

§5::SECURITY
  PATH_VALIDATION::prevent_traversal[../,symlinks]
  INPUT_SANITIZATION::validate_before_use
  ROLE_VALIDATION::allowlist_pattern["^[a-z][a-z0-9-]*$"]

§6::ASYNC_PATTERNS
  REQUIREMENT::all_MCP_tools_must_be_async
  AI_INTEGRATION::AIClient.complete_text()[optional_synthesis]
  ERROR_HANDLING::graceful_fallback_on_failure

===END===