ephemeral-buffer-mcp 0.1.1__py3-none-any.whl

capture_utils.py

@@ -0,0 +1,152 @@
+"""Utilities for bounded command and stream output capture."""
+
+import os
+import selectors
+import signal
+import subprocess
+import time
+from pathlib import Path
+from typing import Iterable, Optional, Tuple
+from config import DEFAULT_MAX_OUTPUT_BYTES
+
+
+class _BoundedCapture:
+    """Incrementally retain bounded head/tail bytes from a binary stream."""
+
+    def __init__(self, max_output_bytes: int):
+        if max_output_bytes < 512:
+            raise ValueError("max_output_bytes must be at least 512")
+        payload_limit = max_output_bytes - 256
+        self.max_output_bytes = max_output_bytes
+        self.head_limit = payload_limit // 2
+        self.tail_limit = payload_limit - self.head_limit
+        self.captured = bytearray()
+        self.head = bytearray()
+        self.tail = bytearray()
+        self.total_bytes = 0
+        self.truncated = False
+
+    def add(self, chunk: bytes) -> None:
+        if not chunk:
+            return
+        self.total_bytes += len(chunk)
+        if not self.truncated and len(self.captured) + len(chunk) <= self.head_limit + self.tail_limit:
+            self.captured.extend(chunk)
+            return
+        if not self.truncated:
+            combined = bytes(self.captured) + chunk
+            self.head.extend(combined[:self.head_limit])
+            self.tail.extend(combined[-self.tail_limit:])
+            self.truncated = True
+            return
+        self.tail.extend(chunk)
+        if len(self.tail) > self.tail_limit:
+            del self.tail[:-self.tail_limit]
+
+    def finish(self) -> Tuple[str, bool, int]:
+        if not self.truncated:
+            return self.captured.decode("utf-8", errors="replace"), False, self.total_bytes
+        marker = (
+            f"\n\n[output truncated: retained first {len(self.head):,} and last {len(self.tail):,} bytes "
+            f"of {self.total_bytes:,}]\n\n"
+        ).encode("utf-8")
+        output = bytes(self.head) + marker + bytes(self.tail)
+        if len(output) > self.max_output_bytes:
+            output = output[:self.max_output_bytes]
+        return output.decode("utf-8", errors="replace"), True, self.total_bytes
+
+
+def bound_chunks(chunks: Iterable[bytes], max_output_bytes: int) -> Tuple[str, bool, int]:
+    """Retain bounded head/tail bytes from an arbitrary binary stream."""
+    capture = _BoundedCapture(max_output_bytes)
+    for chunk in chunks:
+        capture.add(chunk)
+    return capture.finish()
+
+
+def run_command_bounded(
+    command: str,
+    cwd: Optional[str],
+    max_output_bytes: int,
+    timeout_seconds: Optional[float] = None,
+) -> Tuple[str, int, bool, int, bool]:
+    """Run a command while retaining bounded output and enforcing an optional timeout."""
+    return _run_command_bounded(command, cwd, max_output_bytes, timeout_seconds)
+
+
+def _run_command_bounded(
+    command: str,
+    cwd: Optional[str],
+    max_output_bytes: int,
+    timeout_seconds: Optional[float],
+) -> Tuple[str, int, bool, int, bool]:
+    if timeout_seconds is not None and timeout_seconds <= 0:
+        raise ValueError("timeout_seconds must be greater than 0")
+    capture = _BoundedCapture(max_output_bytes)
+    proc = subprocess.Popen(
+        command,
+        shell=True,
+        cwd=cwd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        start_new_session=True,
+    )
+    selector = selectors.DefaultSelector()
+    selector.register(proc.stdout, selectors.EVENT_READ)
+    deadline = None if timeout_seconds is None else time.monotonic() + timeout_seconds
+    timed_out = False
+    try:
+        while selector.get_map():
+            remaining = None if deadline is None else deadline - time.monotonic()
+            if remaining is not None and remaining <= 0:
+                timed_out = True
+                break
+            events = selector.select(remaining)
+            if not events:
+                timed_out = True
+                break
+            for key, _ in events:
+                chunk = key.fileobj.read1(65536)
+                if chunk:
+                    capture.add(chunk)
+                else:
+                    selector.unregister(key.fileobj)
+    finally:
+        if timed_out:
+            _terminate_process_group(proc)
+        try:
+            proc.wait(timeout=1)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait()
+        selector.close()
+        if proc.stdout is not None:
+            proc.stdout.close()
+    output, truncated, total_bytes = capture.finish()
+    return output, (124 if timed_out else proc.returncode), truncated, total_bytes, timed_out
+
+
+def _terminate_process_group(proc: subprocess.Popen) -> None:
+    """Terminate a shell command and all children started in its process group."""
+    try:
+        os.killpg(proc.pid, signal.SIGTERM)
+    except (ProcessLookupError, OSError):
+        proc.terminate()
+    try:
+        proc.wait(timeout=1)
+    except subprocess.TimeoutExpired:
+        try:
+            os.killpg(proc.pid, signal.SIGKILL)
+        except (ProcessLookupError, OSError):
+            proc.kill()
+
+
+def read_file_bounded(file_path: str, max_bytes: int) -> str:
+    """Read a UTF-8 file only when it fits within the configured byte limit."""
+    if max_bytes < 1:
+        raise ValueError("max_bytes must be at least 1")
+    with Path(file_path).open("rb") as stream:
+        content = stream.read(max_bytes + 1)
+    if len(content) > max_bytes:
+        raise ValueError(f"File exceeds the {max_bytes:,}-byte capture limit")
+    return content.decode("utf-8", errors="replace")

cli.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""
+CLI Helper tool for piping command output into Ephemeral Buffer MCP Server.
+Usage:
+  # Pipe stdout/stderr directly:
+  pytest -v 2>&1 | ephbuf --label "pytest run"
+
+  # Force unified-diff parsing when automatic detection is ambiguous:
+  git diff HEAD~3 | ephbuf --label "feature diff" --type diff
+  
+  # Or wrap a command execution:
+  ephbuf --label "build" -- make all
+
+  --type accepts: auto (default), diff, log, or text.
+"""
+
+import sys
+import os
+import socket
+import json
+import argparse
+from capture_utils import DEFAULT_MAX_OUTPUT_BYTES, bound_chunks, run_command_bounded
+from config import positive_int_env, socket_path
+
+SOCKET_PATH = socket_path()
+
+
+def send_to_mcp(
+    text: str,
+    label: str = "",
+    content_type: str = "auto",
+    truncated: bool = False,
+    original_byte_size: int = 0,
+    command_exit_code: int | None = None,
+    timed_out: bool = False,
+) -> dict:
+    if not os.path.exists(SOCKET_PATH):
+        return {
+            "status": "error",
+            "message": f"MCP server socket not found at {SOCKET_PATH}. Is the ephemeral-buffer MCP server running?"
+        }
+
+    try:
+        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        sock.connect(SOCKET_PATH)
+        
+        payload = json.dumps({
+            "label": label,
+            "text": text,
+            "content_type": content_type,
+            "truncated": truncated,
+            "original_byte_size": original_byte_size if truncated else None,
+            "command_exit_code": command_exit_code,
+            "timed_out": timed_out,
+        }).encode("utf-8")
+        sock.sendall(payload)
+        sock.shutdown(socket.SHUT_WR)
+        
+        resp_data = b""
+        while True:
+            chunk = sock.recv(4096)
+            if not chunk:
+                break
+            resp_data += chunk
+            
+        sock.close()
+        return json.loads(resp_data.decode("utf-8"))
+    except Exception as e:
+        return {"status": "error", "message": f"Failed to communicate with MCP server: {e}"}
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Pipe output into Ephemeral Buffer MCP server for hybrid search and agent analysis."
+    )
+    parser.add_argument("--label", "-l", default="", help="Optional descriptive label for this capture")
+    parser.add_argument("--type", "-t", choices=["auto", "diff", "log", "text"], default="auto", help="Optional content type hint (default: auto)")
+    parser.add_argument(
+        "--max-output-bytes",
+        type=int,
+        default=positive_int_env("EPHEMERAL_MAX_BUFFER_BYTES", DEFAULT_MAX_OUTPUT_BYTES),
+        help="Maximum output retained (default: EPHEMERAL_MAX_BUFFER_BYTES or 50 MiB)",
+    )
+    parser.add_argument(
+        "--timeout-seconds",
+        type=float,
+        default=None,
+        help="Maximum runtime for a wrapped command; timed-out commands exit with status 124",
+    )
+    parser.add_argument("command", nargs=argparse.REMAINDER, help="Optional command to execute and capture")
+
+    args = parser.parse_args()
+
+    # If a command was passed after '--'
+    if args.command:
+        cmd_list = args.command
+        if cmd_list and cmd_list[0] == "--":
+            cmd_list = cmd_list[1:]
+            
+        cmd_str = " ".join(cmd_list)
+        label = args.label or cmd_str
+        print(f"[ephbuf] Executing: {cmd_str}")
+        
+        try:
+            output, exit_code, truncated, original_byte_size, timed_out = run_command_bounded(
+                cmd_str, None, args.max_output_bytes, args.timeout_seconds
+            )
+        except ValueError as e:
+            parser.error(str(e))
+        # Also print output locally so user can see it if desired
+        sys.stdout.write(output)
+        sys.stdout.flush()
+        
+        res = send_to_mcp(
+            output,
+            label=label,
+            content_type=args.type,
+            truncated=truncated,
+            original_byte_size=original_byte_size,
+            command_exit_code=exit_code,
+            timed_out=timed_out,
+        )
+        if res.get("status") == "ok":
+            print(f"\n[ephbuf] Successfully captured {res['line_count']:,} lines into buffer `{res['capture_id']}` ({res['label']})", file=sys.stderr)
+        else:
+            print(f"\n[ephbuf] Warning: {res.get('message')}", file=sys.stderr)
+        if timed_out:
+            print(f"\n[ephbuf] Command timed out after {args.timeout_seconds:g}s", file=sys.stderr)
+        sys.exit(exit_code)
+
+    # Otherwise read from stdin (piped input)
+    if not sys.stdin.isatty():
+        input_stream = getattr(sys.stdin, "buffer", sys.stdin)
+        if input_stream is sys.stdin:
+            input_chunks = (chunk.encode("utf-8") for chunk in iter(lambda: sys.stdin.read(65536), ""))
+        else:
+            input_chunks = iter(lambda: input_stream.read(65536), b"")
+        input_text, truncated, original_byte_size = bound_chunks(input_chunks, args.max_output_bytes)
+        label = args.label or "Piped STDIN"
+        res = send_to_mcp(
+            input_text,
+            label=label,
+            content_type=args.type,
+            truncated=truncated,
+            original_byte_size=original_byte_size,
+        )
+        if res.get("status") == "ok":
+            print(f"[ephbuf] Successfully captured {res['line_count']:,} lines into buffer `{res['capture_id']}` ({res['label']})", file=sys.stderr)
+        else:
+            print(f"[ephbuf] Warning: {res.get('message')}", file=sys.stderr)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

config.py

@@ -0,0 +1,53 @@
+"""Environment-backed server configuration helpers."""
+
+import os
+import sys
+import tempfile
+import hashlib
+
+
+DEFAULT_MAX_CAPTURES = 25
+DEFAULT_MAX_BUFFER_BYTES = 50 * 1024 * 1024
+DEFAULT_MAX_OUTPUT_BYTES = DEFAULT_MAX_BUFFER_BYTES
+DEFAULT_EMBEDDING_MODEL = "BAAI/bge-small-en-v1.5"
+DEFAULT_SOCKET_PATH = os.path.join(tempfile.gettempdir(), "ephemeral_buffer.sock")
+SESSION_SOCKET_PREFIX = "ephemeral_buffer-"
+
+
+def socket_path() -> str:
+    """Return the shared server/CLI socket path for the current session."""
+    configured_path = os.environ.get("EPHEMERAL_SOCKET_PATH")
+    if configured_path:
+        return configured_path
+
+    session_id = os.environ.get("EPHEMERAL_SESSION_ID")
+    if session_id:
+        digest = hashlib.sha256(session_id.encode("utf-8")).hexdigest()[:16]
+        return os.path.join(tempfile.gettempdir(), f"{SESSION_SOCKET_PREFIX}{digest}.sock")
+
+    return DEFAULT_SOCKET_PATH
+
+
+def embedding_model_name() -> str:
+    """Return the configured FastEmbed model name."""
+    return os.environ.get("EPHEMERAL_EMBEDDING_MODEL", DEFAULT_EMBEDDING_MODEL)
+
+
+def embedding_cache_dir() -> str | None:
+    """Return the optional FastEmbed model cache directory."""
+    return os.environ.get("EPHEMERAL_FASTEMBED_CACHE_DIR") or None
+
+
+def positive_int_env(name: str, default: int) -> int:
+    """Return a positive integer environment setting or its safe default."""
+    value = os.environ.get(name)
+    if value is None:
+        return default
+    try:
+        parsed = int(value)
+        if parsed < 1:
+            raise ValueError
+        return parsed
+    except ValueError:
+        print(f"Ignoring invalid {name}={value!r}; using {default}", file=sys.stderr)
+        return default