kash-shell 0.3.8__py3-none-any.whl → 0.3.10__py3-none-any.whl

kash/local_server/local_server_commands.py

@@ -1,7 +1,6 @@
 from kash.config.logger import get_logger
-from kash.config.settings import global_settings, server_log_file_path
+from kash.config.settings import global_settings
 from kash.exec import kash_command
-from kash.local_server.local_server import LOCAL_SERVER_NAME
 from kash.local_server.local_url_formatters import enable_local_urls
 from kash.shell.utils.native_utils import tail_file
 from kash.utils.errors import InvalidState
@@ -10,49 +9,50 @@ log = get_logger(__name__)
 
 
 @kash_command
-def start_local_server() -> None:
+def start_ui_server() -> None:
     """
-    Start the kash local server. This exposes local info on files and commands so they can be displayed in your terminal, if it supports OSC 8 links.
+    Start the kash local ui server. This exposes local info on files and commands so
+    they can be displayed in your terminal, if it supports OSC 8 links.
     Note this is most useful for the Kerm terminal, which shows links as
     tooltips.
     """
-    from kash.local_server.local_server import start_local_server
+    from kash.local_server.local_server import start_ui_server
 
-    start_local_server()
+    start_ui_server()
     enable_local_urls(True)
 
 
 @kash_command
-def stop_local_server() -> None:
+def stop_ui_server() -> None:
     """
     Stop the kash local server.
     """
-    from kash.local_server.local_server import stop_local_server
+    from kash.local_server.local_server import stop_ui_server
 
-    stop_local_server()
+    stop_ui_server()
     enable_local_urls(False)
 
 
 @kash_command
-def restart_local_server() -> None:
+def restart_ui_server() -> None:
     """
     Restart the kash local server.
     """
-    from kash.local_server.local_server import restart_local_server
+    from kash.local_server.local_server import restart_ui_server
 
-    restart_local_server()
+    restart_ui_server()
 
 
 @kash_command
 def local_server_logs(follow: bool = False) -> None:
     """
-    Show the logs from the kash local server.
+    Show the logs from the kash local (UI and MCP) servers.
 
     :param follow: Follow the file as it grows.
     """
-    log_path = server_log_file_path(LOCAL_SERVER_NAME, global_settings().local_server_port)
+    log_path = global_settings().local_server_log_path
     if not log_path.exists():
         raise InvalidState(
-            f"Local server log not found (forgot to run `start_local_server`?): {log_path}"
+            f"Local ui server log not found (forgot to run `start_ui_server`?): {log_path}"
         )
     tail_file(log_path, follow=follow)

kash/local_server/local_server_routes.py

@@ -43,11 +43,11 @@ def format_local_url(route_path: str, **params: str | None) -> str:
     """
     URL to content on the local server.
     """
-    from kash.local_server.local_server import LOCAL_SERVER_HOST
+    from kash.local_server.local_server import UI_SERVER_HOST
 
     settings = global_settings()
     route_path = route_path.strip("/")
-    url = f"http://{LOCAL_SERVER_HOST}:{settings.local_server_port}/{route_path}"
+    url = f"http://{UI_SERVER_HOST}:{settings.local_server_port}/{route_path}"
     if params:
         query_params = {k: v for k, v in params.items() if v is not None}
         if query_params:

kash/local_server/local_url_formatters.py

@@ -4,13 +4,13 @@ from pathlib import Path
 
 from rich.style import Style
 from rich.text import Text
+from strif import AtomicVar
 from typing_extensions import override
 
 from kash.config.logger import get_logger
 from kash.config.text_styles import STYLE_HINT
 from kash.model.paths_model import StorePath
 from kash.shell.output.kerm_codes import KriLink, TextTooltip, UIAction, UIActionType
-from kash.utils.common.atomic_var import AtomicVar
 from kash.utils.common.format_utils import fmt_loc
 from kash.utils.errors import InvalidState
 from kash.workspaces import current_ws

kash/mcp/__init__.py

@@ -1,2 +1,5 @@
-# Ensure commands are registered.
-import kash.mcp.mcp_server_commands  # noqa: F401
+from pathlib import Path
+
+from kash.exec.importing import import_and_register
+
+import_and_register(__package__, Path(__file__).parent, ["."])

kash/mcp/mcp_cli.py

@@ -1,6 +1,6 @@
 """
-Command-line launcher for running an MCP server. By default runs in stdio
-standalone mode, with all kash tools exposed. But can be run in SSE standalone
+Command-line launcher for running an MCP server. With no options, by default runs in
+stdio standalone mode, with all kash tools exposed. But can be run in SSE standalone
 mode or as a stdio proxy to another SSE server.
 """
 
@@ -9,27 +9,24 @@ import logging
 import os
 from pathlib import Path
 
-from kash.config.logger_basic import basic_logging_setup
-from kash.config.settings import DEFAULT_MCP_SERVER_PORT, LogLevel, get_system_logs_dir
-from kash.config.setup import setup
-from kash.mcp.mcp_main import McpMode, run_mcp_server
-from kash.mcp.mcp_server_sse import MCP_LOG_PREFIX
+from kash.config.settings import DEFAULT_MCP_SERVER_PORT, LogLevel, global_settings
+from kash.config.setup import kash_setup
 from kash.shell.utils.argparse_utils import WrappedColorFormatter
 from kash.shell.version import get_version
-from kash.workspaces.workspaces import Workspace, get_ws, global_ws_dir
 
 __version__ = get_version()
 
 DEFAULT_PROXY_URL = f"http://localhost:{DEFAULT_MCP_SERVER_PORT}/sse"
 
-LOG_PATH = get_system_logs_dir() / f"{MCP_LOG_PREFIX}_cli.log"
+MCP_CLI_LOG_PATH = global_settings().system_logs_dir / "mcp_cli.log"
 
-basic_logging_setup(LOG_PATH, LogLevel.info)
 
 log = logging.getLogger()
 
 
 def build_parser():
+    from kash.workspaces.workspaces import global_ws_dir
+
     parser = argparse.ArgumentParser(description=__doc__, formatter_class=WrappedColorFormatter)
     parser.add_argument(
         "--version",
@@ -54,21 +51,50 @@ def build_parser():
             f"{DEFAULT_PROXY_URL}"
         ),
     )
-    parser.add_argument("--sse", action="store_true", help="Run in SSE standalone mode")
+    parser.add_argument(
+        "--sse", action="store_true", help="Run in SSE standalone mode instead of stdio"
+    )
+    parser.add_argument(
+        "--list_tools",
+        action="store_true",
+        help="List tools that will be available",
+    )
+    parser.add_argument(
+        "--tool_help",
+        action="store_true",
+        help="Show full help for each tool",
+    )
+
     return parser
 
 
-def main():
-    args = build_parser().parse_args()
+def show_tool_info(full_help: bool):
+    from kash.exec.action_registry import get_all_actions_defaults
+    from kash.help.help_printing import print_action_help
+    from kash.mcp.mcp_server_routes import get_published_mcp_tools, publish_mcp_tools
+    from kash.shell.output.shell_output import cprint
 
-    base_dir = Path(args.workspace)
+    publish_mcp_tools()
+    tools = get_published_mcp_tools()
+    cprint("Actions available as MCP tools:")
+    cprint()
+    actions = get_all_actions_defaults()
+    for tool in tools:
+        action = actions[tool]
+        print_action_help(
+            action, verbose=False, include_options=full_help, include_precondition=full_help
+        )
+        cprint()
 
-    setup(rich_logging=False)
 
-    log.warning("kash MCP CLI started, logging to: %s", LOG_PATH)
+def run_server(args: argparse.Namespace):
+    from kash.mcp.mcp_main import McpMode, run_mcp_server
+    from kash.workspaces.workspaces import Workspace, get_ws
+
+    log.warning("kash MCP CLI started, logging to: %s", MCP_CLI_LOG_PATH)
     log.warning("Current working directory: %s", Path(".").resolve())
 
-    ws: Workspace = get_ws(name_or_path=base_dir, auto_init=True)
+    ws: Workspace = get_ws(name_or_path=Path(args.workspace), auto_init=True)
     os.chdir(ws.base_dir)
     log.warning("Running in workspace: %s", ws.base_dir)
 
@@ -83,5 +109,16 @@ def main():
     run_mcp_server(mcp_mode, proxy_to=proxy_to)
 
 
+def main():
+    args = build_parser().parse_args()
+
+    if args.list_tools or args.tool_help:
+        kash_setup(rich_logging=True, level=LogLevel.warning)
+        show_tool_info(args.tool_help)
+    else:
+        kash_setup(rich_logging=False, level=LogLevel.info)
+        run_server(args)
+
+
 if __name__ == "__main__":
     main()

kash/mcp/mcp_server_commands.py

@@ -3,13 +3,11 @@ from pathlib import Path
 
 from kash.config.logger import get_logger
 from kash.config.settings import (
-    get_system_logs_dir,
     global_settings,
-    server_log_file_path,
 )
 from kash.exec import kash_command
 from kash.mcp import mcp_server_routes
-from kash.mcp.mcp_server_sse import MCP_LOG_PREFIX, MCP_SERVER_NAME
+from kash.mcp.mcp_cli import MCP_CLI_LOG_PATH
 from kash.shell.output.shell_formatting import format_name_and_value
 from kash.shell.output.shell_output import cprint, print_h2
 from kash.shell.utils.native_utils import tail_file
@@ -59,13 +57,14 @@ def mcp_logs(follow: bool = False, all: bool = False) -> None:
     :param follow: Follow the file as it grows.
     :param all: Show all logs, not just the server logs, including Claude Desktop logs if found.
     """
+    settings = global_settings()
     if all:
-        global_log_base = get_system_logs_dir()
+        global_log_base = settings.system_logs_dir
         claude_log_base = Path("~/Library/Logs/Claude").expanduser()
         log_paths = []
         did_log = False
         while len(log_paths) == 0:
-            log_paths = list(global_log_base.glob(f"{MCP_LOG_PREFIX}*.log"))
+            log_paths = [settings.local_server_log_path, MCP_CLI_LOG_PATH]
             claude_logs = list(claude_log_base.glob("mcp*.log"))
             if claude_logs:
                 log.message("Found Claude Desktop logs, will also tail them: %s", claude_logs)
@@ -82,7 +81,7 @@ def mcp_logs(follow: bool = False, all: bool = False) -> None:
                     did_log = True
                 time.sleep(1)
     else:
-        server_log_path = server_log_file_path(MCP_SERVER_NAME, global_settings().mcp_server_port)
+        server_log_path = settings.local_server_log_path  # MCP logs shared with local server logs.
         if not server_log_path.exists():
             raise InvalidState(
                 f"MCP server log not found (forgot to run `start_mcp_server`?): {server_log_path}"

kash/mcp/mcp_server_routes.py

@@ -8,16 +8,16 @@ from funlog import log_calls
 from mcp.server.lowlevel import Server
 from mcp.types import Prompt, Resource, TextContent, Tool
 from prettyfmt import fmt_path
+from strif import AtomicVar
 
 from kash.config.capture_output import CapturedOutput, captured_output
 from kash.config.logger import get_logger
-from kash.config.settings import get_mcp_ws_dir
+from kash.config.settings import global_settings
 from kash.exec.action_exec import prepare_action_input, run_action_with_caching
 from kash.exec.action_registry import get_all_actions_defaults, look_up_action_class
 from kash.model.actions_model import Action, ActionResult, ExecContext
 from kash.model.params_model import TypedParamValues
 from kash.model.paths_model import StorePath
-from kash.utils.common.atomic_var import AtomicVar
 from kash.workspaces.workspaces import current_ws, get_ws
 
 log = get_logger(__name__)
@@ -27,6 +27,13 @@ log = get_logger(__name__)
 _mcp_published_actions: AtomicVar[list[str]] = AtomicVar([])
 
 
+def get_published_mcp_tools() -> list[str]:
+    """
+    Get the list of currently published MCP tools.
+    """
+    return _mcp_published_actions.copy()
+
+
 def publish_mcp_tools(action_names: list[str] | None = None) -> None:
     """
     Add actions to the list of published MCP tools.
@@ -40,12 +47,8 @@ def publish_mcp_tools(action_names: list[str] | None = None) -> None:
     with _mcp_published_actions.updates() as published_actions:
         new_actions = set(action_names).difference(published_actions)
         published_actions.extend(new_actions)
-        log.message(
-            "Published %s MCP tools (total now %s): %s",
-            len(new_actions),
-            len(published_actions),
-            new_actions,
-        )
+        log.message("Adding %s MCP tools (total now %s)", len(new_actions), len(published_actions))
+        log.info("Current MCP tools: %s", ", ".join(published_actions))
 
 
 def unpublish_mcp_tools(action_names: list[str] | None) -> None:
@@ -210,7 +213,7 @@ def run_mcp_tool(action_name: str, arguments: dict) -> list[TextContent]:
             # XXX For now, unless the user has overridden the MCP workspace, we use the
             # current workspace, which could be changed by the user by changing working
             # directories. Maybe confusing?
-            explicit_mcp_ws = get_mcp_ws_dir()
+            explicit_mcp_ws = global_settings().mcp_ws_dir
             ws = get_ws(explicit_mcp_ws) if explicit_mcp_ws else current_ws()
 
             with ws:
@@ -228,8 +231,8 @@ def run_mcp_tool(action_name: str, arguments: dict) -> list[TextContent]:
                 context = ExecContext(
                     action=action,
                     workspace_dir=ws.base_dir,
-                    # Enabling rerun always for now, seems good for tools.
-                    rerun=True,
+                    rerun=True,  # Enabling rerun always for now, seems good for tools.
+                    refetch=False,  # Using the file caches.
                     # Keeping all transient files for now, but maybe make transient?
                     override_state=None,
                 )

kash/mcp/mcp_server_sse.py

@@ -3,9 +3,11 @@ from __future__ import annotations
 import asyncio
 import threading
 from functools import cached_property
+from pathlib import Path
 from typing import TYPE_CHECKING
 
 from mcp.server.sse import SseServerTransport
+from prettyfmt import fmt_path
 from sse_starlette.sse import AppStatus
 from starlette.applications import Starlette
 from starlette.routing import Mount, Route
@@ -16,14 +18,14 @@ if TYPE_CHECKING:
 
 from kash.config.logger import get_logger
 from kash.config.server_config import create_server_config
-from kash.config.settings import global_settings, server_log_file_path
+from kash.config.settings import global_settings
+from kash.local_server.port_tools import find_available_local_port
 from kash.mcp import mcp_server_routes
 from kash.utils.errors import InvalidState
 
 log = get_logger(__name__)
 
-MCP_LOG_PREFIX = "mcp"
-MCP_SERVER_NAME = f"{MCP_LOG_PREFIX}_server_sse"
+MCP_SERVER_NAME = "mcp_server_sse"
 MCP_SERVER_HOST = "127.0.0.1"
 """The local hostname to run the MCP SSE server on."""
 
@@ -47,64 +49,84 @@ def create_mcp_app() -> Starlette:
 
 
 class MCPServerSSE:
-    def __init__(self):
+    def __init__(self, server_name: str, host: str, log_path: Path):
+        self.server_name = server_name
+        self.host = host
+        self.log_path = log_path
         self.server_lock = threading.RLock()
         self.server_instance: uvicorn.Server | None = None
         self.did_exit = threading.Event()
+        self.port: int
 
     @cached_property
     def app(self) -> Starlette:
         return create_mcp_app()
 
-    def _run_server(self):
+    @property
+    def host_port(self) -> str | None:
+        if self.server_instance:
+            return f"{self.server_instance.config.host}:{self.server_instance.config.port}"
+        else:
+            return None
+
+    def _setup_server(self):
         import uvicorn
 
         # Reset AppStatus.should_exit_event to None to ensure it's created
-        # in the correct event loop when needed
+        # in the correct event loop when needed.
         AppStatus.should_exit_event = None
 
         port = global_settings().mcp_server_port
-        self.log_path = server_log_file_path(MCP_SERVER_NAME, port)
-        config = create_server_config(
-            self.app, MCP_SERVER_HOST, port, MCP_SERVER_NAME, self.log_path
-        )
-        with self.server_lock:
-            server = uvicorn.Server(config)
-            self.server_instance = server
-
-        async def serve():
-            try:
-                log.message(
-                    "Starting MCP server on %s:%s",
-                    MCP_SERVER_HOST,
-                    port,
-                )
-                await server.serve()
-            finally:
-                self.did_exit.set()
 
+        # Check if the port is available.
         try:
-            asyncio.run(serve())
+            find_available_local_port(self.host, [port])
+        except RuntimeError:
+            log.warning(
+                f"MCP Server port {port} ({self.server_name}) is in use. Will not start another server."
+            )
+            return False
+
+        self.port = port
+
+        config = create_server_config(self.app, self.host, port, self.server_name, self.log_path)
+
+        server = uvicorn.Server(config)
+        self.server_instance = server
+        return True
+
+    def _run_server_thread(self):
+        assert self.server_instance
+        try:
+            asyncio.run(self.server_instance.serve())
         except Exception as e:
             log.error("MCP Server failed with error: %s", e)
         finally:
-            with self.server_lock:
-                self.server_instance = None
+            self.server_instance = None
+            self.did_exit.set()
 
     def start_server(self):
         with self.server_lock:
             if self.server_instance:
                 log.warning(
-                    "MCP Server already running on %s:%s.",
-                    self.server_instance.config.host,
-                    self.server_instance.config.port,
+                    "MCP Server already running on: %s",
+                    self.host_port,
                 )
                 return
 
             self.did_exit.clear()
-            server_thread = threading.Thread(target=self._run_server, daemon=True)
+            if not self._setup_server():
+                return
+
+            server_thread = threading.Thread(target=self._run_server_thread, daemon=True)
             server_thread.start()
             log.info("Created new MCP server thread: %s", server_thread)
+            log.message(
+                "Started server %s on %s with logs to %s",
+                self.server_name,
+                self.host_port,
+                fmt_path(self.log_path),
+            )
 
     def stop_server(self):
         with self.server_lock:
@@ -113,6 +135,7 @@ class MCPServerSSE:
                 return
             self.server_instance.should_exit = True
 
+            # Wait a few seconds for the server to shut down.
             timeout = 5.0
             if not self.did_exit.wait(timeout=timeout):
                 log.warning(
@@ -123,7 +146,7 @@ class MCPServerSSE:
                     raise InvalidState(f"MCP Server did not shut down within {timeout} seconds")
 
             self.server_instance = None
-            log.warning("MCP Server stopped.")
+            log.warning("Stopped server %s", self.server_name)
 
     def restart_server(self):
         self.stop_server()
@@ -131,7 +154,9 @@ class MCPServerSSE:
 
 
 # Singleton instance
-_mcp_sse_server = MCPServerSSE()
+_mcp_sse_server = MCPServerSSE(
+    MCP_SERVER_NAME, MCP_SERVER_HOST, global_settings().local_server_log_path
+)
 
 
 def start_mcp_server_sse():
@@ -150,7 +175,9 @@ def restart_mcp_server_sse():
 
 
 def run_mcp_server_sse():
-    """Run server, blocking until shutdown. Handles graceful shutdown for both daemon and blocking usage."""
+    """
+    Run server, blocking until shutdown.
+    """
     try:
         start_mcp_server_sse()
         _mcp_sse_server.did_exit.wait()

kash/mcp/mcp_server_stdio.py

@@ -5,18 +5,10 @@ import sys
 from anyio import ClosedResourceError
 from mcp.server.stdio import stdio_server
 
-from kash.config.settings import server_log_file_path
 from kash.mcp import mcp_server_routes
-from kash.mcp.mcp_server_sse import MCP_LOG_PREFIX
 
 log = logging.getLogger(__name__)
 
-MCP_SERVER_NAME = f"{MCP_LOG_PREFIX}_server_stdio"
-
-
-def get_log_path():
-    return server_log_file_path(MCP_SERVER_NAME, "stdio")
-
 
 def run_mcp_server_stdio():
     """

kash/media_base/audio_processing.py

@@ -1,13 +1,26 @@
 import logging
+from dataclasses import dataclass
 from os.path import getsize
 from pathlib import Path
 
+from prettyfmt import fmt_path, fmt_size_human
 from strif import atomic_output_file
 
 log = logging.getLogger(__name__)
 
 
-def downsample_to_16khz(audio_file_path: Path, downsampled_out_path: Path) -> None:
+@dataclass(frozen=True)
+class AudioFileStats:
+    duration: float
+    size: int
+
+    def __str__(self) -> str:
+        return f"duration {self.duration:.2f}s, size {fmt_size_human(self.size)}"
+
+
+def downsample_to_16khz(
+    audio_file_path: Path, downsampled_out_path: Path
+) -> tuple[AudioFileStats, AudioFileStats]:
     from pydub import AudioSegment
 
     audio = AudioSegment.from_mp3(audio_file_path)
@@ -16,11 +29,72 @@ def downsample_to_16khz(audio_file_path: Path, downsampled_out_path: Path) -> No
     with atomic_output_file(downsampled_out_path) as temp_target:
         audio.export(temp_target, format="mp3")
 
+    before = AudioFileStats(
+        duration=len(audio) / 1000,
+        size=getsize(audio_file_path),
+    )
+    after = AudioFileStats(
+        duration=len(audio) / 1000,
+        size=getsize(downsampled_out_path),
+    )
     log.info(
-        "Downsampled %s -> %s: size %s to 16kHz size %s (%sX reduction)",
-        audio_file_path,
-        downsampled_out_path,
-        getsize(audio_file_path),
-        getsize(downsampled_out_path),
-        getsize(audio_file_path) / getsize(downsampled_out_path),
+        "Downsampled %s -> %s: %s to 16kHz %s (%sX reduction)",
+        fmt_path(audio_file_path),
+        fmt_path(downsampled_out_path),
+        before,
+        after,
+        before.size / after.size,
     )
+
+    return before, after
+
+
+# TODO: Test and integrate with JSON caching of transcription results.
+def slice_audio_segments(
+    audio_file_path: Path, segments: list[tuple[float, float]], output_path: Path
+) -> tuple[AudioFileStats, AudioFileStats]:
+    """
+    Takes a list of time segments in seconds and creates a new audio file
+    containing only those segments concatenated together.
+    """
+    from pydub import AudioSegment
+
+    # Load the audio file.
+    audio = AudioSegment.from_file(audio_file_path)
+    audio_duration = len(audio) / 1000
+
+    # Extract and concatenate each segment.
+    result: AudioSegment = AudioSegment.empty()
+    slices_duration = 0
+    for start_sec, end_sec in segments:
+        # Convert seconds to milliseconds for pydub.
+        start_ms = int(start_sec * 1000)
+        end_ms = int(end_sec * 1000)
+
+        # Extract the segment and add to result.
+        segment_audio = audio[start_ms:end_ms]
+        result += segment_audio
+        slices_duration += end_sec - start_sec
+
+    # Export the concatenated audio.
+    with atomic_output_file(output_path) as temp_target:
+        result.export(temp_target, format="mp3")
+
+    before = AudioFileStats(
+        duration=audio_duration,
+        size=getsize(audio_file_path),
+    )
+    after = AudioFileStats(
+        duration=slices_duration,
+        size=getsize(output_path),
+    )
+    log.info(
+        "Sliced audio: %s -> %s: extracted %d segments, %s to %s",
+        fmt_path(audio_file_path),
+        fmt_path(output_path),
+        len(segments),
+        before,
+        after,
+    )
+
+    return before, after