@smilintux/skcapstone 0.1.0 → 0.2.4

package/scripts/install-bundle.sh

@@ -0,0 +1,171 @@
+#!/bin/bash
+# SKCapstone Complete Bundle Installer
+# Installs skcapstone + skmemory + sksecurity + cloud9-protocol as a unified package
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(dirname "$SCRIPT_DIR")"
+
+echo "🚀 SKCapstone Complete Bundle Installer"
+echo "========================================"
+echo ""
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Function to print colored output
+print_status() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+print_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+# Check Python version
+print_status "Checking Python version..."
+PYTHON_VERSION=$(python3 --version 2>&1 | awk '{print $2}')
+REQUIRED_VERSION="3.10"
+
+if [ "$(printf '%s\n' "$REQUIRED_VERSION" "$PYTHON_VERSION" | sort -V | head -n1)" != "$REQUIRED_VERSION" ]; then 
+    print_error "Python 3.10+ required. Found: $PYTHON_VERSION"
+    exit 1
+fi
+print_status "✓ Python $PYTHON_VERSION detected"
+
+# Check pip
+print_status "Checking pip..."
+if ! command -v pip3 &> /dev/null; then
+    print_error "pip3 not found. Please install pip."
+    exit 1
+fi
+print_status "✓ pip3 available"
+
+# Define package paths
+SKMEMORY_PATH="${REPO_ROOT}/../skcapstone-repos/skmemory"
+SKSECURITY_PATH="${REPO_ROOT}/../skcapstone-repos/sksecurity"
+CLOUD9_PATH="${REPO_ROOT}/../skcapstone-repos/cloud9-python"
+SKCAPSTONE_PATH="${REPO_ROOT}"
+
+# Check if repos exist
+print_status "Checking SK repositories..."
+for repo_path in "$SKMEMORY_PATH" "$SKSECURITY_PATH" "$CLOUD9_PATH"; do
+    if [ ! -d "$repo_path" ]; then
+        print_error "Repository not found: $repo_path"
+        print_error "Please clone all SK repositories first:"
+        print_error "  git clone https://github.com/smilinTux/skmemory.git"
+        print_error "  git clone https://github.com/smilinTux/sksecurity.git"
+        print_error "  git clone https://github.com/smilinTux/cloud9-python.git"
+        exit 1
+    fi
+done
+print_status "✓ All repositories found"
+
+# Install in dependency order
+print_status "Installing packages in dependency order..."
+print_status "Order: cloud9 → skmemory → sksecurity → skcapstone"
+
+cd "$CLOUD9_PATH"
+print_status "Installing cloud9-protocol..."
+pip3 install -e .
+
+cd "$SKMEMORY_PATH"
+print_status "Installing skmemory..."
+pip3 install -e ".[skvector]"
+
+cd "$SKSECURITY_PATH"
+print_status "Installing sksecurity..."
+pip3 install -e .
+
+cd "$SKCAPSTONE_PATH"
+print_status "Installing skcapstone (with all dependencies)..."
+pip3 install -e .
+
+# Verify installation
+print_status "Verifying installation..."
+python3 << 'EOF'
+import sys
+try:
+    import skmemory
+    print("  ✓ skmemory:", skmemory.__version__ if hasattr(skmemory, '__version__') else "installed")
+except ImportError as e:
+    print("  ✗ skmemory: FAILED -", e)
+    sys.exit(1)
+
+try:
+    import sksecurity
+    print("  ✓ sksecurity:", sksecurity.__version__ if hasattr(sksecurity, '__version__') else "installed")
+except ImportError as e:
+    print("  ✗ sksecurity: FAILED -", e)
+    sys.exit(1)
+
+try:
+    import cloud9_protocol
+    print("  ✓ cloud9-protocol:", cloud9_protocol.__version__ if hasattr(cloud9_protocol, '__version__') else "installed")
+except ImportError as e:
+    print("  ✗ cloud9-protocol: FAILED -", e)
+    sys.exit(1)
+
+try:
+    import skcapstone
+    print("  ✓ skcapstone:", skcapstone.__version__ if hasattr(skcapstone, '__version__') else "installed")
+except ImportError as e:
+    print("  ✗ skcapstone: FAILED -", e)
+    sys.exit(1)
+
+print("\n✓ All packages installed successfully!")
+EOF
+
+# Setup agent memory
+print_status "Setting up agent memory structure..."
+mkdir -p ~/.skcapstone/agent/lumina/memory/{short,medium,long}
+mkdir -p ~/.skcapstone/agent/lumina/coordination/{inbox,plebeian,archive}
+mkdir -p ~/.skcapstone/agent/lumina/config
+mkdir -p ~/.skcapstone/agent/lumina/cron
+mkdir -p ~/.skcapstone/agent/lumina/logs
+
+print_status "✓ Memory directories created"
+
+# Check for SQLite
+print_status "Checking SQLite configuration..."
+python3 -c "
+import sqlite3
+print(f'  ✓ SQLite version: {sqlite3.sqlite_version}')
+print(f'  ✓ SQLite module: {sqlite3.version}')
+
+# Test database creation
+test_db = '~/.skcapstone/agent/lumina/test.db'
+import os
+os.makedirs(os.path.dirname(os.path.expanduser(test_db)), exist_ok=True)
+conn = sqlite3.connect(os.path.expanduser(test_db))
+conn.execute('CREATE TABLE IF NOT EXISTS test (id INTEGER PRIMARY KEY)')
+conn.close()
+os.remove(os.path.expanduser(test_db))
+print('  ✓ SQLite database operations working')
+"
+
+echo ""
+echo "========================================"
+echo "✅ Installation Complete!"
+echo "========================================"
+echo ""
+echo "Installed packages:"
+echo "  • skcapstone (sovereign agent framework)"
+echo "  • skmemory (universal AI memory)"
+echo "  • sksecurity (enterprise security)"
+echo "  • cloud9-protocol (emotional continuity)"
+echo ""
+echo "Next steps:"
+echo "  1. Run: skcapstone doctor"
+echo "  2. Run: skcapstone init"
+echo "  3. Check for updates: ~/.skcapstone/scripts/check-updates.py"
+echo ""
+echo "For help: skcapstone --help"

package/scripts/install.bat

@@ -0,0 +1,2 @@
+@echo off
+powershell -ExecutionPolicy Bypass -File "%~dp0install.ps1" %*

package/scripts/install.ps1

@@ -0,0 +1,253 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+    Sovereign Agent Suite Installer for Windows.
+
+.DESCRIPTION
+    Installs all SK* packages into a dedicated virtualenv at
+    $env:LOCALAPPDATA\skenv.  This keeps the system Python clean.
+
+.PARAMETER Dev
+    Include dev/test tools (pytest, ruff, black, pytest-cov).
+
+.PARAMETER Force
+    Remove and recreate the virtualenv from scratch.
+
+.EXAMPLE
+    .\install.ps1
+    .\install.ps1 -Dev
+    .\install.ps1 -Force -Dev
+#>
+
+[CmdletBinding()]
+param(
+    [switch]$Dev,
+    [switch]$Force
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$SKENV = Join-Path $env:LOCALAPPDATA 'skenv'
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Definition
+$RepoRoot = Split-Path -Parent $ScriptDir
+
+Write-Host '=== Sovereign Agent Suite Installer (Windows) ===' -ForegroundColor Cyan
+Write-Host ''
+
+# ---------------------------------------------------------------------------
+# Step 1: Check prerequisites — Python 3.10+
+# ---------------------------------------------------------------------------
+$Python = $null
+foreach ($candidate in @('python3', 'python')) {
+    try {
+        $verOutput = & $candidate -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')" 2>$null
+        if ($LASTEXITCODE -eq 0 -and $verOutput) {
+            $parts = $verOutput.Split('.')
+            $major = [int]$parts[0]
+            $minor = [int]$parts[1]
+            if ($major -ge 3 -and $minor -ge 10) {
+                $Python = $candidate
+                break
+            }
+        }
+    } catch {
+        # candidate not found, try next
+    }
+}
+
+if (-not $Python) {
+    Write-Host 'ERROR: Python 3.10+ required. Found none on PATH.' -ForegroundColor Red
+    Write-Host 'Download from https://www.python.org/downloads/' -ForegroundColor Red
+    exit 1
+}
+
+$pyVersion = & $Python --version 2>&1
+Write-Host "[1/6] Using $Python ($pyVersion)" -ForegroundColor Green
+
+# ---------------------------------------------------------------------------
+# Step 2: Create virtualenv
+# ---------------------------------------------------------------------------
+if ($Force -and (Test-Path $SKENV)) {
+    Write-Host '[2/6] Removing existing venv (-Force)...' -ForegroundColor Yellow
+    Remove-Item -Recurse -Force $SKENV
+}
+
+if (-not (Test-Path $SKENV)) {
+    Write-Host "[2/6] Creating virtualenv at $SKENV..."
+    & $Python -m venv $SKENV
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host 'ERROR: Failed to create virtualenv.' -ForegroundColor Red
+        exit 1
+    }
+} else {
+    Write-Host "[2/6] Virtualenv exists at $SKENV"
+}
+
+$Pip = Join-Path $SKENV 'Scripts\pip.exe'
+& $Pip install --upgrade pip -q 2>$null | Out-Null
+
+# ---------------------------------------------------------------------------
+# Step 3: Install SK* packages
+# ---------------------------------------------------------------------------
+Write-Host '[3/6] Installing SK* packages...'
+
+$ParentDir = Split-Path -Parent $RepoRoot
+$PillarDir = Join-Path $ParentDir 'pillar-repos'
+
+function Install-Pkg {
+    <#
+    .SYNOPSIS
+        Install a package editable from local paths, falling back to PyPI.
+    #>
+    param(
+        [string]$Name,
+        [string]$Extras,
+        [string[]]$Paths
+    )
+
+    foreach ($path in $Paths) {
+        if (Test-Path $path) {
+            if ($Extras) {
+                & $Pip install -e "${path}[$Extras]" -q 2>$null | Out-Null
+                if ($LASTEXITCODE -eq 0) {
+                    Write-Host "  $Name (editable: $path)"
+                    return
+                }
+                # Retry without extras
+                & $Pip install -e $path -q 2>$null | Out-Null
+                if ($LASTEXITCODE -eq 0) {
+                    Write-Host "  $Name (editable, no extras: $path)"
+                    return
+                }
+            } else {
+                & $Pip install -e $path -q 2>$null | Out-Null
+                if ($LASTEXITCODE -eq 0) {
+                    Write-Host "  $Name (editable: $path)"
+                    return
+                }
+            }
+        }
+    }
+
+    # Fall back to PyPI
+    if ($Extras) {
+        & $Pip install "${Name}[$Extras]" -q 2>$null | Out-Null
+        if ($LASTEXITCODE -eq 0) {
+            Write-Host "  $Name (PyPI)"
+            return
+        }
+        & $Pip install $Name -q 2>$null | Out-Null
+        if ($LASTEXITCODE -eq 0) {
+            Write-Host "  $Name (PyPI, no extras)"
+            return
+        }
+    } else {
+        & $Pip install $Name -q 2>$null | Out-Null
+        if ($LASTEXITCODE -eq 0) {
+            Write-Host "  $Name (PyPI)"
+            return
+        }
+    }
+
+    Write-Host "  $Name (FAILED -- skipping)" -ForegroundColor Red
+}
+
+# Core packages (in dependency order)
+Install-Pkg -Name 'capauth'    -Extras 'all'                      -Paths @((Join-Path $PillarDir 'capauth'), (Join-Path $ParentDir 'capauth'))
+Install-Pkg -Name 'skmemory'   -Extras ''                         -Paths @((Join-Path $PillarDir 'skmemory'), (Join-Path $ParentDir 'skmemory'))
+Install-Pkg -Name 'skcomm'     -Extras 'cli,crypto,discovery,api' -Paths @((Join-Path $PillarDir 'skcomm'), (Join-Path $ParentDir 'skcomm'))
+Install-Pkg -Name 'skcapstone' -Extras ''                         -Paths @($RepoRoot)
+Install-Pkg -Name 'skchat-sovereign' -Extras 'all'                -Paths @((Join-Path $ParentDir 'skchat'))
+Install-Pkg -Name 'skseal'     -Extras ''                         -Paths @((Join-Path $ParentDir 'skseal'))
+Install-Pkg -Name 'skskills'   -Extras ''                         -Paths @((Join-Path $ParentDir 'skskills'))
+Install-Pkg -Name 'sksecurity' -Extras ''                         -Paths @((Join-Path $ParentDir 'sksecurity'))
+
+# ---------------------------------------------------------------------------
+# Step 4: Dev tools (optional)
+# ---------------------------------------------------------------------------
+if ($Dev) {
+    Write-Host '[4/6] Installing dev tools...'
+    & $Pip install pytest pytest-cov ruff black -q 2>$null | Out-Null
+    Write-Host '  pytest, pytest-cov, ruff, black'
+} else {
+    Write-Host '[4/6] Skipping dev tools (use -Dev to include)'
+}
+
+# ---------------------------------------------------------------------------
+# Step 5: Register skills & MCP servers
+# ---------------------------------------------------------------------------
+Write-Host '[5/6] Registering skills and MCP servers...'
+$skcapstoneExe = Join-Path $SKENV 'Scripts\skcapstone.exe'
+if (Test-Path $skcapstoneExe) {
+    try {
+        & $skcapstoneExe register 2>$null | Out-Null
+        if ($LASTEXITCODE -eq 0) {
+            Write-Host '  Registration complete'
+        } else {
+            Write-Host '  (registration skipped -- run "skcapstone register" manually)'
+        }
+    } catch {
+        Write-Host '  (registration skipped -- run "skcapstone register" manually)'
+    }
+} else {
+    Write-Host '  (skcapstone not found -- registration skipped)'
+}
+
+# ---------------------------------------------------------------------------
+# Step 6: Verify installation & PATH setup
+# ---------------------------------------------------------------------------
+Write-Host '[6/6] Verifying installation...'
+
+$ScriptsDir = Join-Path $SKENV 'Scripts'
+$failures = 0
+foreach ($cmd in @('skcomm', 'skcapstone', 'capauth', 'skmemory')) {
+    $exe = Join-Path $ScriptsDir "$cmd.exe"
+    if (Test-Path $exe) {
+        try {
+            & $exe --version 2>$null | Out-Null
+            if ($LASTEXITCODE -eq 0) {
+                Write-Host "  $cmd OK" -ForegroundColor Green
+            } else {
+                Write-Host "  $cmd FAILED" -ForegroundColor Yellow
+                $failures++
+            }
+        } catch {
+            Write-Host "  $cmd FAILED" -ForegroundColor Yellow
+            $failures++
+        }
+    } else {
+        Write-Host "  $cmd not found" -ForegroundColor Yellow
+        $failures++
+    }
+}
+
+Write-Host ''
+
+# Add Scripts dir to user PATH if not present
+$userPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
+if ($userPath -and $userPath.Split(';') -contains $ScriptsDir) {
+    Write-Host "PATH already includes $ScriptsDir"
+} else {
+    Write-Host "Adding $ScriptsDir to user PATH..." -ForegroundColor Yellow
+    if ($userPath) {
+        $newPath = "$ScriptsDir;$userPath"
+    } else {
+        $newPath = $ScriptsDir
+    }
+    [Environment]::SetEnvironmentVariable('PATH', $newPath, 'User')
+    # Also update current session
+    $env:PATH = "$ScriptsDir;$env:PATH"
+    Write-Host "  Added to user PATH. Restart your terminal for it to take effect."
+}
+
+Write-Host ''
+if ($failures -eq 0) {
+    Write-Host '=== Installation complete ===' -ForegroundColor Green
+} else {
+    Write-Host "=== Installation complete with $failures warning(s) ===" -ForegroundColor Yellow
+}
+Write-Host ''
+Write-Host "Commands available: skcomm, skcapstone, capauth, skchat, skseal, skmemory, skskills, sksecurity"
+Write-Host "Venv location:     $SKENV"
+Write-Host "To activate:       & $SKENV\Scripts\Activate.ps1"

package/scripts/install.sh

@@ -0,0 +1,185 @@
+#!/bin/bash
+# install.sh — Sovereign Agent Suite Installer
+#
+# Installs all SK* packages into a dedicated virtualenv at ~/.skenv.
+# This keeps the system Python clean and avoids --break-system-packages.
+#
+# Usage:
+#   bash scripts/install.sh           # Standard install
+#   bash scripts/install.sh --dev     # Include dev/test tools
+#   bash scripts/install.sh --force   # Recreate venv from scratch
+#
+# After install, add to your shell profile:
+#   export PATH="$HOME/.skenv/bin:$PATH"
+
+set -euo pipefail
+
+SKENV="$HOME/.skenv"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(dirname "$SCRIPT_DIR")"
+DEV_MODE=false
+FORCE=false
+
+for arg in "$@"; do
+    case "$arg" in
+        --dev)  DEV_MODE=true ;;
+        --force) FORCE=true ;;
+    esac
+done
+
+echo "=== Sovereign Agent Suite Installer ==="
+echo ""
+
+# ---------------------------------------------------------------------------
+# Step 1: Check prerequisites
+# ---------------------------------------------------------------------------
+PYTHON=""
+for candidate in python3.12 python3.11 python3; do
+    if command -v "$candidate" &>/dev/null; then
+        ver=$("$candidate" -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
+        major="${ver%%.*}"
+        minor="${ver##*.}"
+        if [[ "$major" -ge 3 ]] && [[ "$minor" -ge 10 ]]; then
+            PYTHON="$candidate"
+            break
+        fi
+    fi
+done
+
+if [[ -z "$PYTHON" ]]; then
+    echo "ERROR: Python 3.10+ required. Found none."
+    exit 1
+fi
+
+echo "[1/6] Using $PYTHON ($($PYTHON --version 2>&1))"
+
+# ---------------------------------------------------------------------------
+# Step 2: Create virtualenv
+# ---------------------------------------------------------------------------
+if [[ "$FORCE" == "true" ]] && [[ -d "$SKENV" ]]; then
+    echo "[2/6] Removing existing venv (--force)..."
+    rm -rf "$SKENV"
+fi
+
+if [[ ! -d "$SKENV" ]]; then
+    echo "[2/6] Creating virtualenv at $SKENV..."
+    "$PYTHON" -m venv "$SKENV"
+else
+    echo "[2/6] Virtualenv exists at $SKENV"
+fi
+
+PIP="$SKENV/bin/pip"
+$PIP install --upgrade pip -q 2>/dev/null
+
+# ---------------------------------------------------------------------------
+# Step 3: Install SK* packages
+# ---------------------------------------------------------------------------
+echo "[3/6] Installing SK* packages..."
+
+# Helper: install editable if local dir exists, else from PyPI
+install_pkg() {
+    local name="$1"
+    local extras="${2:-}"
+    local paths="${3:-}"
+
+    for path in $paths; do
+        if [[ -d "$path" ]]; then
+            if [[ -n "$extras" ]]; then
+                $PIP install -e "${path}[${extras}]" -q 2>/dev/null && echo "  $name (editable: $path)" && return 0
+                # Retry without extras if they fail
+                $PIP install -e "$path" -q 2>/dev/null && echo "  $name (editable, no extras: $path)" && return 0
+            else
+                $PIP install -e "$path" -q 2>/dev/null && echo "  $name (editable: $path)" && return 0
+            fi
+        fi
+    done
+
+    # Fall back to PyPI
+    if [[ -n "$extras" ]]; then
+        $PIP install "${name}[${extras}]" -q 2>/dev/null && echo "  $name (PyPI)" && return 0
+        $PIP install "$name" -q 2>/dev/null && echo "  $name (PyPI, no extras)" && return 0
+    else
+        $PIP install "$name" -q 2>/dev/null && echo "  $name (PyPI)" && return 0
+    fi
+
+    echo "  $name (FAILED — skipping)" && return 1
+}
+
+# Parent dir of skcapstone (where sibling repos might live)
+PARENT="$(dirname "$REPO_ROOT")"
+PILLAR="$PARENT/pillar-repos"
+
+# Core packages (in dependency order)
+install_pkg "capauth"    "all"                   "$PILLAR/capauth $PARENT/capauth"
+install_pkg "skmemory"   ""                      "$PILLAR/skmemory $PARENT/skmemory"
+install_pkg "skcomm"     "cli,crypto,discovery,api" "$PILLAR/skcomm $PARENT/skcomm"
+install_pkg "skcapstone" ""                      "$REPO_ROOT"
+install_pkg "skchat-sovereign" "all"             "$PARENT/skchat"
+install_pkg "skseal"     ""                      "$PARENT/skseal"
+install_pkg "skskills"   ""                      "$PARENT/skskills"
+install_pkg "sksecurity" ""                      "$PARENT/sksecurity"
+
+# ---------------------------------------------------------------------------
+# Step 4: Dev tools (optional)
+# ---------------------------------------------------------------------------
+if [[ "$DEV_MODE" == "true" ]]; then
+    echo "[4/6] Installing dev tools..."
+    $PIP install pytest pytest-cov ruff black -q 2>/dev/null
+    echo "  pytest, pytest-cov, ruff, black"
+else
+    echo "[4/6] Skipping dev tools (use --dev to include)"
+fi
+
+# ---------------------------------------------------------------------------
+# Step 5: Register skills & MCP servers
+# ---------------------------------------------------------------------------
+echo "[5/6] Registering skills and MCP servers..."
+"$SKENV/bin/skcapstone" register 2>/dev/null && echo "  Registration complete" || echo "  (registration skipped — run 'skcapstone register' manually)"
+
+# ---------------------------------------------------------------------------
+# Step 6: PATH setup
+# ---------------------------------------------------------------------------
+echo "[6/6] Verifying installation..."
+
+failures=0
+for cmd in skcomm skcapstone capauth skmemory; do
+    if "$SKENV/bin/$cmd" --version &>/dev/null; then
+        echo "  $cmd OK"
+    else
+        echo "  $cmd FAILED"
+        failures=$((failures + 1))
+    fi
+done
+
+echo ""
+
+# Check if PATH is configured
+if echo "$PATH" | grep -q "$SKENV/bin"; then
+    echo "PATH already includes $SKENV/bin"
+else
+    echo "Add this to your ~/.bashrc (or ~/.zshrc):"
+    echo ""
+    echo "  export PATH=\"\$HOME/.skenv/bin:\$PATH\""
+    echo ""
+
+    # Auto-add if not present
+    for rcfile in "$HOME/.bashrc" "$HOME/.zshrc"; do
+        if [[ -f "$rcfile" ]] && ! grep -q ".skenv/bin" "$rcfile"; then
+            echo "" >> "$rcfile"
+            echo '# SK* sovereign suite — installed in dedicated venv' >> "$rcfile"
+            echo 'export PATH="$HOME/.skenv/bin:$PATH"' >> "$rcfile"
+            echo "  (Added to $rcfile)"
+        fi
+    done
+fi
+
+echo ""
+if [[ "$failures" -eq 0 ]]; then
+    echo "=== Installation complete ==="
+else
+    echo "=== Installation complete with $failures warning(s) ==="
+fi
+echo ""
+echo "Commands available: skcomm, skcapstone, capauth, skchat, skseal, skmemory, skskills, sksecurity"
+echo "Venv location:     $SKENV"
+echo "To activate:       source $SKENV/bin/activate"

package/scripts/mcp-serve.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# -------------------------------------------------------------------
+# skcapstone MCP server launcher (tool-agnostic)
+#
+# Works with: Cursor, Claude Desktop, Claude Code CLI, Windsurf,
+#             Aider, Cline, or any MCP client that speaks stdio.
+#
+# The script auto-detects the Python virtualenv and launches the
+# MCP server on stdio. No hardcoded paths required in client configs.
+#
+# Usage:
+#   ./skcapstone/scripts/mcp-serve.sh          (from repo root)
+#   bash skcapstone/scripts/mcp-serve.sh       (explicit bash)
+# -------------------------------------------------------------------
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKCAPSTONE_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# --- Locate the virtualenv ---
+# Priority: SKCAPSTONE_VENV env var > first venv with mcp installed
+# Candidates: skmemory/.venv (shared project venv) > skcapstone/.venv > repo .venv
+find_venv() {
+    if [[ -n "${SKCAPSTONE_VENV:-}" ]] && [[ -f "$SKCAPSTONE_VENV/bin/python" ]]; then
+        echo "$SKCAPSTONE_VENV"
+        return
+    fi
+
+    local candidates=(
+        "$REPO_ROOT/skmemory/.venv"
+        "$SKCAPSTONE_DIR/.venv"
+        "$REPO_ROOT/.venv"
+    )
+
+    for venv in "${candidates[@]}"; do
+        if [[ -f "$venv/bin/python" ]]; then
+            if "$venv/bin/python" -c "import mcp" 2>/dev/null; then
+                echo "$venv"
+                return
+            fi
+        fi
+    done
+
+    # Fallback: return first venv that exists (may need pip install mcp)
+    for venv in "${candidates[@]}"; do
+        if [[ -f "$venv/bin/python" ]]; then
+            echo "$venv"
+            return
+        fi
+    done
+
+    return 1
+}
+
+VENV_DIR="$(find_venv)" || {
+    echo "ERROR: No Python virtualenv found." >&2
+    echo "Create one with: python -m venv skcapstone/.venv && skcapstone/.venv/bin/pip install -e skcapstone/" >&2
+    exit 1
+}
+
+PYTHON="$VENV_DIR/bin/python"
+
+# --- Ensure skcapstone is importable ---
+export PYTHONPATH="${SKCAPSTONE_DIR}/src${PYTHONPATH:+:$PYTHONPATH}"
+
+# --- Launch MCP server on stdio ---
+exec "$PYTHON" -m skcapstone.mcp_server "$@"