Menu
MCP tool implementation patterns for HestAI including tool structure, session tools, and shared utilities
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| 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===
Supabase test harness patterns including local Supabase setup, test user creation via Auth Admin API, RLS testing, migration testing (db_reset), seed sequences, rate limiting, and environment detection. Use when setting up Supabase testing infrastructure, creating test users, troubleshooting Supabase test failures, or implementing RLS validation. Triggers on: supabase test setup, test user creation, supabase local testing, RLS testing, migration testing, supabase test harness, auth test helpers.
Supabase operational knowledge for migrations, RLS optimization, MCP tool benchmarks, and ADR-003 compliance. Use when validating database migrations, optimizing Row-Level Security policies, checking MCP tool performance, or ensuring Supabase operational standards. Triggers on: migration validation, RLS patterns, Supabase benchmarks, ADR-003, database state tracking, schema governance.
LLM-native structured communication format. Teaches OCTAVE syntax rules, canonical forms, and warning prevention for zero-error .oct.md authoring.
Advanced semantic vocabulary, holographic contracts, and structural patterns for OCTAVE. REQUIRES octave-literacy. Extends literacy with mythology, archetype annotation, v6 contracts, and anti-pattern rules.
Workflow for transforming prose into semantic OCTAVE structures. Covers tier selection, transformation phases, loss accounting, and decision rules. REQUIRES octave-literacy.
Strategic oversight mode for the Holistic Orchestrator. Episodic State Machine pattern with ho-liaison advisory (via pal_clink), run_debate escalation, and oa-router delegation. REPLACES holistic-orchestration when loaded.
