loki-mode 6.75.3 → 6.76.1

package/autonomy/run.sh

@@ -5784,6 +5784,53 @@ run_doc_quality_gate() {
     [ "$score" -ge 70 ]
 }
 
+# ============================================================================
+# Magic Modules Debate Gate - Gate 12 (v6.77.0)
+# Runs when any .loki/magic/specs/*.md changed since last iteration.
+# Blocks iteration completion if debate flags any block severity.
+# ============================================================================
+
+run_magic_debate_gate() {
+    local specs_dir="$TARGET_DIR/.loki/magic/specs"
+    if [ ! -d "$specs_dir" ]; then
+        return 0
+    fi
+
+    local has_specs
+    has_specs=$(find "$specs_dir" -maxdepth 1 -name "*.md" 2>/dev/null | head -1)
+    if [ -z "$has_specs" ]; then
+        return 0
+    fi
+
+    # Auto-run update to catch stale generated files
+    log_info "Magic Modules: running incremental update"
+    (cd "$TARGET_DIR" && PYTHONPATH="$PROJECT_DIR" LOKI_PROVIDER="${PROVIDER_NAME:-claude}" \
+        "$PROJECT_DIR/autonomy/loki" magic update 2>&1 | tail -10) || true
+
+    # Run debate on most recently modified component
+    local latest_spec
+    latest_spec=$(find "$specs_dir" -maxdepth 1 -name "*.md" -type f -print0 2>/dev/null | xargs -0 ls -t 2>/dev/null | head -1)
+    if [ -z "$latest_spec" ]; then
+        return 0
+    fi
+    local latest_name
+    latest_name=$(basename "$latest_spec" .md)
+
+    log_info "Magic Modules: running debate on '$latest_name'"
+    local debate_out
+    debate_out=$(cd "$TARGET_DIR" && PYTHONPATH="$PROJECT_DIR" LOKI_PROVIDER="${PROVIDER_NAME:-claude}" \
+        timeout 300 "$PROJECT_DIR/autonomy/loki" magic debate "$latest_name" --rounds 2 2>&1 || true)
+
+    # Parse debate outcome; block if any persona set severity=block
+    if echo "$debate_out" | grep -qi '"severity"[[:space:]]*:[[:space:]]*"block"'; then
+        log_warn "Magic Modules Gate 12: debate returned BLOCK severity for '$latest_name'"
+        return 1
+    fi
+
+    log_info "Magic Modules Gate 12: PASS"
+    return 0
+}
+
 # ============================================================================
 # 3-Reviewer Parallel Code Review (v5.35.0)
 # Specialist pool from skills/quality-gates.md with blind review
@@ -7905,6 +7952,24 @@ except Exception as e:
 PYEOF
 }
 
+# Magic Modules COMPOUND: record successful component patterns (v6.77.0)
+# Called at end of each iteration to capture generated/updated components
+# as semantic memory patterns via magic.core.memory_bridge.
+_magic_compound_capture() {
+    local registry="$TARGET_DIR/.loki/magic/registry.json"
+    if [ ! -f "$registry" ]; then
+        return 0
+    fi
+    # Delegate to memory_bridge (built by agent 3)
+    PYTHONPATH="$PROJECT_DIR" python3 -c "
+try:
+    from magic.core.memory_bridge import capture_iteration_compound
+    capture_iteration_compound('${TARGET_DIR}', iteration=${ITERATION_COUNT:-0})
+except Exception as exc:
+    pass
+" 2>/dev/null || true
+}
+
 # Automatic episode capture with enriched context (v6.15.0)
 # Captures git changes, files modified, and RARV phase automatically
 # after every iteration -- no manual invocation needed.
@@ -8583,6 +8648,21 @@ except Exception:
 " 2>/dev/null || true)
     fi
 
+    # Magic Modules context injection
+    local magic_context=""
+    local magic_specs_dir="$TARGET_DIR/.loki/magic/specs"
+    if [ -d "$magic_specs_dir" ]; then
+        local spec_count
+        spec_count=$(find "$magic_specs_dir" -maxdepth 1 -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+        if [ "$spec_count" -gt 0 ]; then
+            local spec_list
+            spec_list=$(find "$magic_specs_dir" -maxdepth 1 -name "*.md" -exec basename {} .md \; 2>/dev/null | tr '\n' ',' | sed 's/,$//')
+            magic_context="MAGIC_MODULES: ${spec_count} component specs exist: ${spec_list}. To add or update a component: write markdown to ${magic_specs_dir}/<Name>.md and run 'loki magic update'. The spec becomes source of truth; implementation regenerates automatically. Debate runs in VERIFY phase -- if accessibility or performance blocks, refine the spec and re-run."
+        else
+            magic_context="MAGIC_MODULES: available. To create UI components, write spec at ${magic_specs_dir}/<Name>.md and run 'loki magic update'. Spec-driven generation produces React + Web Component variants with auto-generated tests. Debate gate runs in VERIFY."
+        fi
+    fi
+
     # Degraded providers with small models need simplified prompts
     # Full RARV/SDLC instructions overwhelm models < 30B parameters
     if [ "${PROVIDER_DEGRADED:-false}" = "true" ]; then
@@ -8607,15 +8687,15 @@ except Exception:
     else
         if [ $retry -eq 0 ]; then
             if [ -n "$prd" ]; then
-                echo "Loki Mode with PRD at $prd. $human_directive $gate_failure_context $queue_tasks $bmad_context $openspec_context $mirofish_context $checklist_status $app_runner_info $playwright_info $memory_context_section $rarv_instruction $memory_instruction $compaction_reminder $completion_instruction $sdlc_instruction $autonomous_suffix"
+                echo "Loki Mode with PRD at $prd. $human_directive $gate_failure_context $queue_tasks $bmad_context $openspec_context $mirofish_context $magic_context $checklist_status $app_runner_info $playwright_info $memory_context_section $rarv_instruction $memory_instruction $compaction_reminder $completion_instruction $sdlc_instruction $autonomous_suffix"
             else
-                echo "Loki Mode. $human_directive $gate_failure_context $queue_tasks $bmad_context $openspec_context $mirofish_context $checklist_status $app_runner_info $playwright_info $memory_context_section $analysis_instruction $rarv_instruction $memory_instruction $compaction_reminder $completion_instruction $sdlc_instruction $autonomous_suffix"
+                echo "Loki Mode. $human_directive $gate_failure_context $queue_tasks $bmad_context $openspec_context $mirofish_context $magic_context $checklist_status $app_runner_info $playwright_info $memory_context_section $analysis_instruction $rarv_instruction $memory_instruction $compaction_reminder $completion_instruction $sdlc_instruction $autonomous_suffix"
             fi
         else
             if [ -n "$prd" ]; then
-                echo "Loki Mode - Resume iteration #$iteration (retry #$retry). PRD: $prd. $human_directive $gate_failure_context $queue_tasks $bmad_context $openspec_context $mirofish_context $checklist_status $app_runner_info $playwright_info $memory_context_section $rarv_instruction $memory_instruction $compaction_reminder $completion_instruction $sdlc_instruction $autonomous_suffix"
+                echo "Loki Mode - Resume iteration #$iteration (retry #$retry). PRD: $prd. $human_directive $gate_failure_context $queue_tasks $bmad_context $openspec_context $mirofish_context $magic_context $checklist_status $app_runner_info $playwright_info $memory_context_section $rarv_instruction $memory_instruction $compaction_reminder $completion_instruction $sdlc_instruction $autonomous_suffix"
             else
-                echo "Loki Mode - Resume iteration #$iteration (retry #$retry). $human_directive $gate_failure_context $queue_tasks $bmad_context $openspec_context $mirofish_context $checklist_status $app_runner_info $playwright_info $memory_context_section Use .loki/generated-prd.md if exists. $rarv_instruction $memory_instruction $compaction_reminder $completion_instruction $sdlc_instruction $autonomous_suffix"
+                echo "Loki Mode - Resume iteration #$iteration (retry #$retry). $human_directive $gate_failure_context $queue_tasks $bmad_context $openspec_context $mirofish_context $magic_context $checklist_status $app_runner_info $playwright_info $memory_context_section Use .loki/generated-prd.md if exists. $rarv_instruction $memory_instruction $compaction_reminder $completion_instruction $sdlc_instruction $autonomous_suffix"
             fi
         fi
     fi
@@ -9475,6 +9555,22 @@ run_autonomous() {
     # Populate task queue from PRD (if no adapters already populated, runs once)
     populate_prd_queue "$prd_path"
 
+    # Magic Modules BOOTSTRAP: extract design tokens from project so component
+    # generation matches the codebase design language from iteration 1.
+    if [ -x "${PROJECT_DIR}/autonomy/loki" ]; then
+        PYTHONPATH="${PROJECT_DIR}" python3 -c "
+try:
+    from magic.core.design_tokens import DesignTokens
+    dt = DesignTokens('${TARGET_DIR}')
+    observed = dt.extract_from_codebase(save=True)
+    print(f'[magic] Extracted design tokens: '
+          f'{len(observed.get(\"colors\",{}))} colors, '
+          f'{len(observed.get(\"spacing\",{}))} spacing')
+except Exception as exc:
+    print(f'[magic] Token extraction skipped: {exc}')
+" 2>&1 | grep -E '\[magic\]' || true
+    fi
+
     # Check max iterations before starting
     if check_max_iterations; then
         log_error "Max iterations already reached. Reset with: rm .loki/autonomy-state.json"
@@ -10087,6 +10183,18 @@ if __name__ == "__main__":
                     log_warn "Documentation coverage gate: Score below threshold ($dc_count consecutive)"
                 fi
             fi
+            # Magic Modules debate gate - Gate 12 (v6.77.0)
+            if [ "${LOKI_GATE_MAGIC_DEBATE:-true}" = "true" ] && [ "$ITERATION_COUNT" -gt 0 ]; then
+                log_info "Quality gate: magic modules debate..."
+                if run_magic_debate_gate; then
+                    clear_gate_failure "magic_debate"
+                else
+                    local md_count
+                    md_count=$(track_gate_failure "magic_debate")
+                    gate_failures="${gate_failures}magic_debate,"
+                    log_warn "Magic Modules debate gate: BLOCK severity detected ($md_count consecutive)"
+                fi
+            fi
             # Store gate failures for prompt injection
             if [ -n "$gate_failures" ]; then
                 echo "$gate_failures" > "${TARGET_DIR:-.}/.loki/quality/gate-failures.txt"
@@ -10106,6 +10214,9 @@ if __name__ == "__main__":
         auto_capture_episode "$ITERATION_COUNT" "$exit_code" "${rarv_phase:-iteration}" \
             "${prd_path:-codebase-analysis}" "$duration" "$log_file"
 
+        # Magic Modules COMPOUND capture (v6.77.0): record component patterns
+        _magic_compound_capture
+
         # BUG-QG-008: Track iteration for convergence regardless of exit code
         if type council_track_iteration &>/dev/null; then
             council_track_iteration "$log_file"

package/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "6.75.3"
+__version__ = "6.76.1"
 
 # Expose the control app for easy import
 try:

package/docs/INSTALLATION.md

@@ -2,7 +2,7 @@
 
 The flagship product of [Autonomi](https://www.autonomi.dev/). Complete installation instructions for all platforms and use cases.
 
-**Version:** v6.75.3
+**Version:** v6.76.1
 
 ---
 

package/mcp/__init__.py

@@ -57,4 +57,4 @@ try:
 except ImportError:
     __all__ = ['mcp']
 
-__version__ = '6.75.3'
+__version__ = '6.76.1'

package/mcp/magic_tools.py

@@ -0,0 +1,471 @@
+"""MCP tools for Magic Modules.
+
+Exposes loki magic functionality to AI coding assistants via the MCP
+protocol. Tools delegate to the magic/ package where possible and fall
+back to the `loki magic` CLI when direct imports are unavailable.
+
+Registration pattern:
+    from mcp.magic_tools import register_magic_tools
+    register_magic_tools(mcp_server)   # Called from mcp/server.py
+
+All tools are resilient: they catch exceptions and return structured
+error dicts rather than raising, so an MCP client always receives a
+well-formed JSON response.
+"""
+
+import json
+import re
+import subprocess
+from typing import Any, Dict, List, Optional
+
+
+# Regex used to validate component names. Mirrors the rule stated in the
+# tool docstrings so callers get a consistent, early error.
+_NAME_RE = re.compile(r"^[a-zA-Z][a-zA-Z0-9_-]*$")
+
+# Default timeout (seconds) for CLI subprocess calls. Generation involves
+# an LLM round-trip so it can legitimately take a while; we still cap it
+# to avoid hanging the MCP server indefinitely.
+_CLI_TIMEOUT = 600
+
+
+def _error(message: str, **extra: Any) -> Dict[str, Any]:
+    """Return a structured error dict."""
+    result: Dict[str, Any] = {"ok": False, "error": message}
+    result.update(extra)
+    return result
+
+
+def _ok(**fields: Any) -> Dict[str, Any]:
+    """Return a structured success dict."""
+    result: Dict[str, Any] = {"ok": True}
+    result.update(fields)
+    return result
+
+
+def _validate_name(name: str) -> Optional[str]:
+    """Return an error message if name is invalid, else None."""
+    if not isinstance(name, str) or not name:
+        return "name must be a non-empty string"
+    if not _NAME_RE.match(name):
+        return (
+            "name must match ^[a-zA-Z][a-zA-Z0-9_-]*$ "
+            "(letters, digits, underscore, hyphen; must start with a letter)"
+        )
+    return None
+
+
+def _run_loki(args: List[str], timeout: int = _CLI_TIMEOUT) -> Dict[str, Any]:
+    """Invoke the `loki` CLI and return a structured result.
+
+    The CLI is expected to emit JSON on stdout for machine consumers. If
+    stdout is not valid JSON we surface both stdout and stderr in the
+    error response so callers can diagnose.
+    """
+    cmd = ["loki", *args]
+    try:
+        proc = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+    except FileNotFoundError:
+        return _error("loki CLI not found on PATH", command=cmd)
+    except subprocess.TimeoutExpired:
+        return _error(
+            "loki CLI timed out", command=cmd, timeout_seconds=timeout
+        )
+    except Exception as exc:  # pragma: no cover - defensive
+        return _error(f"failed to invoke loki CLI: {exc}", command=cmd)
+
+    stdout = (proc.stdout or "").strip()
+    stderr = (proc.stderr or "").strip()
+
+    if proc.returncode != 0:
+        return _error(
+            f"loki CLI exited with code {proc.returncode}",
+            command=cmd,
+            stdout=stdout,
+            stderr=stderr,
+            returncode=proc.returncode,
+        )
+
+    # Try to decode JSON first; fall back to raw stdout if not JSON.
+    if stdout:
+        try:
+            parsed = json.loads(stdout)
+            if isinstance(parsed, dict):
+                parsed.setdefault("ok", True)
+                return parsed
+            return _ok(result=parsed)
+        except json.JSONDecodeError:
+            return _ok(stdout=stdout, stderr=stderr)
+
+    return _ok(stdout=stdout, stderr=stderr)
+
+
+# ---------------------------------------------------------------------------
+# Tool implementations
+# ---------------------------------------------------------------------------
+
+
+def loki_magic_generate(
+    name: str,
+    description: str = "",
+    target: str = "react",
+    placement: str = "",
+    tags: Optional[List[str]] = None,
+) -> Dict[str, Any]:
+    """Generate a new component from a description.
+
+    Args:
+        name: Component name (must match ^[a-zA-Z][a-zA-Z0-9_-]*$).
+        description: Natural-language description of what the component does.
+        target: 'react' | 'webcomponent' | 'both'.
+        placement: Optional file path where the component should be placed.
+        tags: List of tags for registry search.
+
+    Returns:
+        A dict with keys:
+          ok (bool), name (str), spec_path (str),
+          react_path (str, if target includes react),
+          webcomponent_path (str, if target includes webcomponent),
+          version (str), debate_passed (bool)
+        On failure: {"ok": False, "error": "..."}.
+    """
+    err = _validate_name(name)
+    if err:
+        return _error(err, name=name)
+
+    allowed_targets = {"react", "webcomponent", "both"}
+    if target not in allowed_targets:
+        return _error(
+            f"target must be one of {sorted(allowed_targets)}",
+            target=target,
+        )
+
+    if tags is not None and not isinstance(tags, list):
+        return _error("tags must be a list of strings", tags=tags)
+
+    args: List[str] = ["magic", "generate", name, "--target", target]
+    if description:
+        args.extend(["--description", description])
+    if placement:
+        args.extend(["--placement", placement])
+    if tags:
+        args.extend(["--tags", ",".join(str(t) for t in tags)])
+
+    return _run_loki(args)
+
+
+def loki_magic_list(
+    query: str = "",
+    tags: Optional[List[str]] = None,
+    target: Optional[str] = None,
+) -> Dict[str, Any]:
+    """List / search registered components.
+
+    Args:
+        query: Substring match against component names.
+        tags: Filter by tags (AND logic).
+        target: Filter by target framework.
+
+    Returns:
+        {"ok": True, "count": int, "components": [...]} on success,
+        or a structured error dict on failure.
+    """
+    if tags is not None and not isinstance(tags, list):
+        return _error("tags must be a list of strings", tags=tags)
+
+    try:
+        # Prefer direct Python API when available.
+        from magic.core.registry import ComponentRegistry  # type: ignore
+    except ImportError:
+        # Fall back to CLI if the magic package is not importable.
+        args: List[str] = ["magic", "list", "--json"]
+        if query:
+            args.extend(["--query", query])
+        if tags:
+            args.extend(["--tags", ",".join(str(t) for t in tags)])
+        if target:
+            args.extend(["--target", target])
+        return _run_loki(args)
+    except Exception as exc:
+        return _error(f"failed to import magic registry: {exc}")
+
+    try:
+        reg = ComponentRegistry(".")
+        results = reg.search(query=query, tags=tags, target=target)
+    except Exception as exc:
+        return _error(f"registry search failed: {exc}")
+
+    components = list(results) if results is not None else []
+    return _ok(count=len(components), components=components)
+
+
+def loki_magic_get(name: str) -> Dict[str, Any]:
+    """Fetch details for a specific component.
+
+    Args:
+        name: Component name (must match ^[a-zA-Z][a-zA-Z0-9_-]*$).
+
+    Returns:
+        {"ok": True, "component": {...}} on success,
+        or a structured error dict on failure.
+    """
+    err = _validate_name(name)
+    if err:
+        return _error(err, name=name)
+
+    try:
+        from magic.core.registry import ComponentRegistry  # type: ignore
+    except ImportError:
+        return _run_loki(["magic", "get", name, "--json"])
+    except Exception as exc:
+        return _error(f"failed to import magic registry: {exc}")
+
+    try:
+        reg = ComponentRegistry(".")
+        # Prefer a .get() method if the registry exposes one; otherwise
+        # fall back to searching by exact name.
+        component: Any = None
+        if hasattr(reg, "get"):
+            component = reg.get(name)
+        elif hasattr(reg, "find"):
+            component = reg.find(name)
+        else:
+            results = reg.search(query=name)
+            for item in (results or []):
+                if isinstance(item, dict) and item.get("name") == name:
+                    component = item
+                    break
+    except Exception as exc:
+        return _error(f"registry lookup failed: {exc}", name=name)
+
+    if component is None:
+        return _error(f"component not found: {name}", name=name)
+    return _ok(component=component)
+
+
+def loki_magic_update(
+    name: str,
+    spec_update: str = "",
+    force: bool = False,
+) -> Dict[str, Any]:
+    """Update a component when its spec has changed.
+
+    Args:
+        name: Component name.
+        spec_update: Optional updated description / spec text to apply
+            before regeneration.
+        force: If False (default), only regenerates when the spec hash
+            has diverged. If True, always regenerates.
+
+    Returns:
+        A dict describing the update result on success, or a structured
+        error dict on failure.
+    """
+    err = _validate_name(name)
+    if err:
+        return _error(err, name=name)
+
+    args: List[str] = ["magic", "update", name]
+    if spec_update:
+        args.extend(["--spec-update", spec_update])
+    if force:
+        args.append("--force")
+    args.append("--json")
+
+    return _run_loki(args)
+
+
+def loki_magic_debate(
+    name: str,
+    rounds: int = 3,
+    personas: Optional[List[str]] = None,
+) -> Dict[str, Any]:
+    """Run multi-persona debate on an existing component.
+
+    Args:
+        name: Component name.
+        rounds: Number of debate rounds (default 3).
+        personas: Optional list of persona identifiers. When omitted,
+            the debate runner uses its default persona set.
+
+    Returns:
+        Debate result including critiques and (if applicable) refined
+        code, or a structured error dict on failure.
+    """
+    err = _validate_name(name)
+    if err:
+        return _error(err, name=name)
+
+    if not isinstance(rounds, int) or rounds < 1:
+        return _error("rounds must be a positive integer", rounds=rounds)
+
+    if personas is not None and not isinstance(personas, list):
+        return _error("personas must be a list of strings", personas=personas)
+
+    try:
+        from magic.core.debate import DebateRunner  # type: ignore
+    except ImportError:
+        args: List[str] = ["magic", "debate", name, "--rounds", str(rounds)]
+        if personas:
+            args.extend(["--personas", ",".join(str(p) for p in personas)])
+        args.append("--json")
+        return _run_loki(args)
+    except Exception as exc:
+        return _error(f"failed to import debate runner: {exc}")
+
+    try:
+        runner_kwargs: Dict[str, Any] = {"rounds": rounds}
+        if personas:
+            runner_kwargs["personas"] = personas
+        # DebateRunner's exact constructor signature is defined by the
+        # magic package. We pass the workspace root positionally and
+        # forward debate params as kwargs, staying tolerant of minor
+        # signature differences.
+        try:
+            runner = DebateRunner(".", **runner_kwargs)
+        except TypeError:
+            runner = DebateRunner(".")
+            for attr, value in runner_kwargs.items():
+                try:
+                    setattr(runner, attr, value)
+                except Exception:
+                    pass
+
+        if hasattr(runner, "run"):
+            result = runner.run(name)
+        elif hasattr(runner, "debate"):
+            result = runner.debate(name)
+        else:
+            return _error(
+                "DebateRunner exposes neither run() nor debate()",
+                name=name,
+            )
+    except Exception as exc:
+        return _error(f"debate failed: {exc}", name=name)
+
+    if isinstance(result, dict):
+        result.setdefault("ok", True)
+        return result
+    return _ok(result=result)
+
+
+def loki_magic_tokens_extract() -> Dict[str, Any]:
+    """Extract design tokens from the current codebase.
+
+    Returns observed colors, spacing, typography, etc. Observation is
+    non-destructive: the registry is not modified (save=False).
+    """
+    try:
+        from magic.core.design_tokens import DesignTokens  # type: ignore
+    except ImportError:
+        return _run_loki(["magic", "tokens", "extract", "--json"])
+    except Exception as exc:
+        return _error(f"failed to import design tokens module: {exc}")
+
+    try:
+        dt = DesignTokens(".")
+        observed = dt.extract_from_codebase(save=False)
+    except Exception as exc:
+        return _error(f"token extraction failed: {exc}")
+
+    if isinstance(observed, dict):
+        observed.setdefault("ok", True)
+        return observed
+    return _ok(tokens=observed)
+
+
+def loki_magic_stats() -> Dict[str, Any]:
+    """Registry stats: total components, per-target counts, debate pass rate.
+
+    Returns:
+        A dict of statistics on success, or a structured error dict on
+        failure.
+    """
+    try:
+        from magic.core.registry import ComponentRegistry  # type: ignore
+    except ImportError:
+        return _run_loki(["magic", "stats", "--json"])
+    except Exception as exc:
+        return _error(f"failed to import magic registry: {exc}")
+
+    try:
+        stats = ComponentRegistry(".").stats()
+    except Exception as exc:
+        return _error(f"failed to compute stats: {exc}")
+
+    if isinstance(stats, dict):
+        stats.setdefault("ok", True)
+        return stats
+    return _ok(stats=stats)
+
+
+# ---------------------------------------------------------------------------
+# Public registration entry point
+# ---------------------------------------------------------------------------
+
+
+# Tuple of (callable, public-tool-name). Tool names are stable and match
+# the CLI verbs so MCP clients can predict them.
+_TOOLS = (
+    (loki_magic_generate, "loki_magic_generate"),
+    (loki_magic_list, "loki_magic_list"),
+    (loki_magic_get, "loki_magic_get"),
+    (loki_magic_update, "loki_magic_update"),
+    (loki_magic_debate, "loki_magic_debate"),
+    (loki_magic_tokens_extract, "loki_magic_tokens_extract"),
+    (loki_magic_stats, "loki_magic_stats"),
+)
+
+
+def register_magic_tools(mcp_server: Any) -> List[str]:
+    """Wire the module's functions into a FastMCP server instance.
+
+    Usage from mcp/server.py:
+        from mcp.magic_tools import register_magic_tools
+        register_magic_tools(mcp)
+
+    Args:
+        mcp_server: A FastMCP-compatible server instance exposing a
+            `.tool()` decorator factory.
+
+    Returns:
+        The list of tool names that were successfully registered.
+    """
+    if mcp_server is None:
+        raise ValueError("mcp_server must not be None")
+
+    if not hasattr(mcp_server, "tool"):
+        raise TypeError(
+            "mcp_server does not expose a .tool() method; "
+            "expected a FastMCP-compatible instance"
+        )
+
+    registered: List[str] = []
+    for func, tool_name in _TOOLS:
+        try:
+            mcp_server.tool()(func)
+            registered.append(tool_name)
+        except Exception:
+            # Don't let a single bad registration break the rest. The
+            # integration pass can inspect the returned list to confirm
+            # which tools made it through.
+            continue
+    return registered
+
+
+__all__ = [
+    "loki_magic_generate",
+    "loki_magic_list",
+    "loki_magic_get",
+    "loki_magic_update",
+    "loki_magic_debate",
+    "loki_magic_tokens_extract",
+    "loki_magic_stats",
+    "register_magic_tools",
+]

package/mcp/server.py

@@ -1954,6 +1954,19 @@ async def loki_phase_report() -> str:
 Use loki_state_get and loki_task_queue_list to gather data."""
 
 
+# ============================================================
+# MAGIC MODULES TOOLS (spec-driven component generation)
+# ============================================================
+
+try:
+    from mcp.magic_tools import register_magic_tools
+    register_magic_tools(mcp)
+except Exception as _magic_err:
+    # Magic Modules is optional; log and continue if unavailable
+    import sys as _sys
+    print(f"[warn] magic_tools registration skipped: {_magic_err}", file=_sys.stderr)
+
+
 # ============================================================
 # MAIN
 # ============================================================