| name | mcp-tools |
| description | MCP tool implementation patterns for HestAI including tool structure, session tools, and shared utilities |
| allowed-tools | * |
| triggers | ["MCP tool","clock_in","clock_out","bind","mcp server","tool implementation","hestai context","session management","path_resolution","fast_layer"] |
===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===
