sari 0.0.1__py3-none-any.whl

mcp/test_server.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+"""
+Unit tests for Local Search MCP Server
+
+Usage:
+  python3 -m pytest .codex/tools/sari/mcp/test_server.py -v
+  # or
+  python3 .codex/tools/sari/mcp/test_server.py
+"""
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+# Add paths for imports
+SCRIPT_DIR = Path(__file__).parent
+sys.path.insert(0, str(SCRIPT_DIR))
+sys.path.insert(0, str(SCRIPT_DIR.parent / "app"))
+
+from server import LocalSearchMCPServer
+
+
+def test_initialize():
+    """Test MCP initialize response."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        server = LocalSearchMCPServer(tmpdir)
+        
+        result = server.handle_initialize({})
+        
+        assert result["protocolVersion"] == "2025-11-25"
+        assert result["serverInfo"]["name"] == "sari"
+        assert result["serverInfo"]["version"]
+        assert "tools" in result["capabilities"]
+
+
+def test_tools_list():
+    """Test tools/list response."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        server = LocalSearchMCPServer(tmpdir)
+        
+        result = server.handle_tools_list({})
+        
+        tools = result["tools"]
+        tool_names = [t["name"] for t in tools]
+        
+        assert "search" in tool_names
+        assert "status" in tool_names
+        assert "repo_candidates" in tool_names
+        
+        # Check search tool schema
+        search_tool = next(t for t in tools if t["name"] == "search")
+        assert "query" in search_tool["inputSchema"]["properties"]
+        assert "query" in search_tool["inputSchema"]["required"]
+
+
+def test_handle_request_initialize():
+    """Test full request handling for initialize."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        server = LocalSearchMCPServer(tmpdir)
+        
+        request = {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "initialize",
+            "params": {},
+        }
+        
+        response = server.handle_request(request)
+        
+        assert response["jsonrpc"] == "2.0"
+        assert response["id"] == 1
+        assert "result" in response
+        assert response["result"]["protocolVersion"] == "2025-11-25"
+
+
+def test_handle_request_tools_list():
+    """Test full request handling for tools/list."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        server = LocalSearchMCPServer(tmpdir)
+        
+        request = {
+            "jsonrpc": "2.0",
+            "id": 2,
+            "method": "tools/list",
+            "params": {},
+        }
+        
+        response = server.handle_request(request)
+        
+        assert response["jsonrpc"] == "2.0"
+        assert response["id"] == 2
+        assert "result" in response
+        assert "tools" in response["result"]
+
+
+def test_handle_request_unknown_method():
+    """Test error handling for unknown method."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        server = LocalSearchMCPServer(tmpdir)
+        
+        request = {
+            "jsonrpc": "2.0",
+            "id": 3,
+            "method": "unknown/method",
+            "params": {},
+        }
+        
+        response = server.handle_request(request)
+        
+        assert response["jsonrpc"] == "2.0"
+        assert response["id"] == 3
+        assert "error" in response
+        assert response["error"]["code"] == -32601
+
+
+def test_handle_notification_no_response():
+    """Test that notifications (no id) don't return a response."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        server = LocalSearchMCPServer(tmpdir)
+        
+        # Notification has no "id" field
+        request = {
+            "jsonrpc": "2.0",
+            "method": "initialized",
+            "params": {},
+        }
+        
+        response = server.handle_request(request)
+        
+        assert response is None
+
+
+def test_tool_status():
+    """Test status tool execution."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        server = LocalSearchMCPServer(tmpdir)
+        server._ensure_initialized()
+        
+        result = server._tool_status({})
+        
+        assert "content" in result
+        assert len(result["content"]) > 0
+        assert result["content"][0]["type"] == "text"
+        
+        status = json.loads(result["content"][0]["text"])
+        assert "index_ready" in status
+        assert "workspace_root" in status
+
+
+def test_tool_search_empty_query():
+    """Test search tool with empty query returns error."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        server = LocalSearchMCPServer(tmpdir)
+        server._ensure_initialized()
+        
+        result = server._tool_search({"query": ""})
+        
+        assert result.get("isError") is True
+
+
+def run_tests():
+    """Run all tests without pytest."""
+    import traceback
+    
+    tests = [
+        test_initialize,
+        test_tools_list,
+        test_handle_request_initialize,
+        test_handle_request_tools_list,
+        test_handle_request_unknown_method,
+        test_handle_notification_no_response,
+        test_tool_status,
+        test_tool_search_empty_query,
+    ]
+    
+    passed = 0
+    failed = 0
+    
+    for test in tests:
+        try:
+            test()
+            print(f"✓ {test.__name__}")
+            passed += 1
+        except Exception as e:
+            print(f"✗ {test.__name__}")
+            traceback.print_exc()
+            failed += 1
+    
+    print(f"\n{passed} passed, {failed} failed")
+    return failed == 0
+
+
+if __name__ == "__main__":
+    success = run_tests()
+    sys.exit(0 if success else 1)

mcp/tools/__init__.py

@@ -0,0 +1,14 @@
+"""
+MCP Tools for Local Search.
+"""
+from .search import execute_search
+from .status import execute_status
+from .repo_candidates import execute_repo_candidates
+from .list_files import execute_list_files
+
+__all__ = [
+    "execute_search",
+    "execute_status", 
+    "execute_repo_candidates",
+    "execute_list_files",
+]

mcp/tools/_util.py

@@ -0,0 +1,244 @@
+import json
+import os
+import urllib.parse
+from enum import Enum
+from typing import Any, Dict, Optional, List, Callable
+from pathlib import Path
+
+try:
+    from app.workspace import WorkspaceManager
+except Exception:
+    WorkspaceManager = None
+
+# --- Constants & Enums ---
+
+class ErrorCode(str, Enum):
+    INVALID_ARGS = "INVALID_ARGS"
+    NOT_INDEXED = "NOT_INDEXED"
+    REPO_NOT_FOUND = "REPO_NOT_FOUND"
+    IO_ERROR = "IO_ERROR"
+    DB_ERROR = "DB_ERROR"
+    INTERNAL = "INTERNAL"
+    ERR_INDEXER_FOLLOWER = "ERR_INDEXER_FOLLOWER"
+    ERR_INDEXER_DISABLED = "ERR_INDEXER_DISABLED"
+    ERR_ROOT_OUT_OF_SCOPE = "ERR_ROOT_OUT_OF_SCOPE"
+    ERR_MCP_HTTP_UNSUPPORTED = "ERR_MCP_HTTP_UNSUPPORTED"
+    ERR_ENGINE_NOT_INSTALLED = "ERR_ENGINE_NOT_INSTALLED"
+    ERR_ENGINE_INIT = "ERR_ENGINE_INIT"
+    ERR_ENGINE_QUERY = "ERR_ENGINE_QUERY"
+    ERR_ENGINE_INDEX = "ERR_ENGINE_INDEX"
+    ERR_ENGINE_UNAVAILABLE = "ERR_ENGINE_UNAVAILABLE"
+    ERR_ENGINE_REBUILD = "ERR_ENGINE_REBUILD"
+
+# --- Format Selection ---
+
+def _get_format() -> str:
+    """
+    Returns 'pack' or 'json'.
+    Default is 'pack'.
+    'json' is used if DECKARD_FORMAT=json.
+    """
+    fmt = os.environ.get("DECKARD_FORMAT", "pack").strip().lower()
+    return "json" if fmt == "json" else "pack"
+
+def _compact_enabled() -> bool:
+    """Legacy compact check for JSON mode."""
+    val = (os.environ.get("DECKARD_RESPONSE_COMPACT") or "1").strip().lower()
+    return val not in {"0", "false", "no", "off"}
+
+# --- PACK1 Encoders ---
+
+def pack_encode_text(s: Any) -> str:
+    """
+    ENC_TEXT: safe=""
+    Used for snippet, msg, reason, detail, hint.
+    """
+    return urllib.parse.quote(str(s), safe="")
+
+def pack_encode_id(s: Any) -> str:
+    """
+    ENC_ID: safe="/._-:@"
+    Used for path, repo, name (identifiers).
+    """
+    return urllib.parse.quote(str(s), safe="/._-:@")
+
+# --- PACK1 Builders ---
+
+def pack_header(tool: str, kv: Dict[str, Any], returned: Optional[int] = None,
+                total: Optional[int] = None, total_mode: Optional[str] = None) -> str:
+    """
+    Builds the PACK1 header line.
+    PACK1 tool=<tool> ok=true k=v ... [returned=<N>] [total=<M>] [total_mode=<mode>]
+    """
+    parts = ["PACK1", f"tool={tool}", "ok=true"]
+    
+    # Add custom KV pairs
+    for k, v in kv.items():
+        parts.append(f"{k}={v}")
+
+    if returned is not None:
+        parts.append(f"returned={returned}")
+    
+    if total_mode:
+        parts.append(f"total_mode={total_mode}")
+        
+    if total is not None and total_mode != "none":
+        parts.append(f"total={total}")
+        
+    return " ".join(parts)
+
+def pack_line(kind: str, kv: Optional[Dict[str, str]] = None, single_value: Optional[str] = None) -> str:
+    """
+    Builds a PACK1 record line.
+    If single_value is provided: <kind>:<single_value>
+    If kv is provided: <kind>:k=v k2=v2 ...
+    """
+    if single_value is not None:
+        return f"{kind}:{single_value}"
+        
+    if kv:
+        field_strs = [f"{k}={v}" for k, v in kv.items()]
+        return f"{kind}:{ ' '.join(field_strs) }"
+        
+    return f"{kind}:"
+
+def pack_error(tool: str, code: Any, msg: str, hints: List[str] = None, trace: str = None, fields: Dict[str, Any] = None) -> str:
+    """
+    Generates PACK1 error response.
+    PACK1 tool=<tool> ok=false code=<CODE> msg=<ENCODED_MSG> [hint=<ENC>] [trace=<ENC>]
+    """
+    parts = [
+        "PACK1",
+        f"tool={tool}",
+        "ok=false",
+        f"code={code.value if isinstance(code, ErrorCode) else str(code)}",
+        f"msg={pack_encode_text(msg)}",
+    ]
+    if hints:
+        joined = " | ".join(hints)
+        parts.append(f"hint={pack_encode_text(joined)}")
+    if trace:
+        parts.append(f"trace={pack_encode_text(trace)}")
+    if fields:
+        for k, v in fields.items():
+            parts.append(f"{k}={pack_encode_text(v)}")
+    return " ".join(parts)
+
+def pack_truncated(next_offset: int, limit: int, truncated_state: str) -> str:
+    """
+    m:truncated=true|maybe next=use_offset offset=<nextOffset> limit=<limit>
+    """
+    return f"m:truncated={truncated_state} next=use_offset offset={next_offset} limit={limit}"
+
+# --- Main Utility ---
+
+def mcp_response(
+    tool_name: str, 
+    pack_func: Callable[[], str], 
+    json_func: Callable[[], Dict[str, Any]]
+) -> Dict[str, Any]:
+    """
+    Helper to dispatch between PACK1 and JSON based on configuration.
+    
+    pack_func: function that returns (str) - the full PACK1 text payload.
+    json_func: function that returns (dict) - the dict for JSON serialization.
+    """
+    fmt = _get_format()
+    
+    try:
+        if fmt == "pack":
+            text_output = pack_func()
+            return {
+                "content": [{"type": "text", "text": text_output}]
+            }
+        else:
+            # JSON mode (Legacy/Debug)
+            data = json_func()
+            
+            if _compact_enabled():
+                json_text = json.dumps(data, ensure_ascii=False, separators=(",", ":"))
+            else:
+                json_text = json.dumps(data, ensure_ascii=False, indent=2)
+                
+            res = {"content": [{"type": "text", "text": json_text}]}
+            if isinstance(data, dict):
+                res.update(data)
+            return res
+    except Exception as e:
+        import traceback
+        err_msg = str(e)
+        stack = traceback.format_exc()
+        
+        if fmt == "pack":
+            return {
+                "content": [{"type": "text", "text": pack_error(tool_name, ErrorCode.INTERNAL, err_msg, trace=stack)}],
+                "isError": True
+            }
+        else:
+            err_obj = {
+                "error": {"code": ErrorCode.INTERNAL.value, "message": err_msg, "trace": stack},
+                "isError": True
+            }
+            return mcp_json(err_obj)
+
+
+def mcp_json(obj):
+    """Utility to format dictionary as standard MCP response."""
+    if _compact_enabled():
+        payload = json.dumps(obj, ensure_ascii=False, separators=(",", ":"))
+    else:
+        payload = json.dumps(obj, ensure_ascii=False, indent=2)
+    res = {"content": [{"type": "text", "text": payload}]}
+    if isinstance(obj, dict):
+        res.update(obj)
+    return res
+
+
+def resolve_root_ids(roots: List[str]) -> List[str]:
+    if not roots or not WorkspaceManager:
+        return []
+    out: List[str] = []
+    for r in roots:
+        try:
+            out.append(WorkspaceManager.root_id(r))
+        except Exception:
+            continue
+    return out
+
+
+def resolve_db_path(input_path: str, roots: List[str]) -> Optional[str]:
+    """
+    Accepts either db-path (root-xxxx/rel) or filesystem path.
+    Returns normalized db-path if allowed, else None.
+    """
+    if not input_path:
+        return None
+    if "/" in input_path and input_path.startswith("root-"):
+        root_id = input_path.split("/", 1)[0]
+        if root_id in resolve_root_ids(roots):
+            return input_path
+        return None
+    if not WorkspaceManager:
+        return None
+    if input_path.startswith("root-") and "/" not in input_path:
+        return None
+    follow_symlinks = (os.environ.get("DECKARD_FOLLOW_SYMLINKS", "0").strip().lower() in ("1", "true", "yes", "on"))
+    try:
+        p = Path(os.path.expanduser(input_path))
+        if not p.is_absolute():
+            p = (Path.cwd() / p).resolve()
+        else:
+            p = p.resolve()
+    except Exception:
+        return None
+
+    for root in roots:
+        try:
+            root_norm = WorkspaceManager._normalize_path(root, follow_symlinks=follow_symlinks)  # type: ignore
+            root_path = Path(root_norm)
+            if p == root_path or root_path in p.parents:
+                rel = p.relative_to(root_path).as_posix()
+                return f"{WorkspaceManager.root_id(str(root_path))}/{rel}"
+        except Exception:
+            continue
+    return None

mcp/tools/deckard_guide.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""
+Sari guidance tool for LLMs.
+Returns a short usage guide to encourage search-first behavior.
+"""
+from typing import Any, Dict
+from mcp.tools._util import mcp_response, pack_header, pack_line, pack_encode_text
+
+
+def execute_deckard_guide(args: Dict[str, Any]) -> Dict[str, Any]:
+    text = (
+        "💡 Sari - Agentic Search Workflow Guide\n\n"
+        "이 도구는 대규모 코드베이스에서 당신의 '외부 기억' 역할을 합니다. "
+        "토큰을 낭비하며 파일을 하나씩 열어보기 전에, 아래 순서를 따르면 훨씬 정확하고 빠르게 임무를 완수할 수 있습니다.\n\n"
+        "1. [정찰] `search` 또는 `repo_candidates`를 사용해 맥락을 파악하세요.\n"
+        "2. [식별] `search_symbols`나 `search_api_endpoints`로 정확한 코드 위치를 찾으세요.\n"
+        "3. [획득] `read_symbol`을 통해 필요한 구현부만 콕 집어 읽어보세요. (전체 파일을 읽는 것보다 80% 이상의 컨텍스트를 절약합니다)\n"
+        "4. [분석] `get_callers` 또는 `get_implementations`로 코드 간의 연결 고리를 파악하세요.\n\n"
+        "핵심 원칙: 먼저 '묻고(Search)', 필요한 것만 '취하고(Select)', 그 다음에 '행동(Act)' 하세요. "
+        "이것이 당신의 추론 성능을 최상으로 유지하는 방법입니다.\n"
+        "주의: 기본 모드는 경고입니다. 필요 시 search-first 모드를 warn/enforce/off로 조정할 수 있습니다."
+    )
+    def build_pack() -> str:
+        lines = [pack_header("sari_guide", {}, returned=1)]
+        lines.append(pack_line("t", single_value=pack_encode_text(text)))
+        return "\n".join(lines)
+
+    return mcp_response(
+        "sari_guide",
+        build_pack,
+        lambda: {"content": [{"type": "text", "text": text}]},
+    )

mcp/tools/doctor.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""
+Doctor tool for Local Search MCP Server.
+Returns structured diagnostics (no ANSI/prints).
+"""
+import json
+import os
+import os
+import socket
+import shutil
+import sys
+from pathlib import Path
+from typing import Any, Dict, List
+
+try:
+    from app.db import LocalSearchDB
+    from app.config import Config
+    from app.workspace import WorkspaceManager
+    from app.registry import ServerRegistry
+    from mcp.cli import get_daemon_address, is_daemon_running, read_pid
+except ImportError:
+    import sys
+    from pathlib import Path
+    sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+    from app.db import LocalSearchDB
+    from app.config import Config
+    from app.workspace import WorkspaceManager
+    from app.registry import ServerRegistry
+    from mcp.cli import get_daemon_address, is_daemon_running, read_pid
+
+
+def _result(name: str, passed: bool, error: str = "") -> dict[str, Any]:
+    return {"name": name, "passed": passed, "error": error}
+
+
+def _check_db(ws_root: str) -> list[dict[str, Any]]:
+    results: list[dict[str, Any]] = []
+    cfg_path = WorkspaceManager.resolve_config_path(ws_root)
+    cfg = Config.load(cfg_path, workspace_root_override=ws_root)
+    db_path = Path(cfg.db_path)
+    if not db_path.exists():
+        results.append(_result("DB Existence", False, f"DB not found at {db_path}"))
+        return results
+
+    try:
+        db = LocalSearchDB(str(db_path))
+    except Exception as e:
+        results.append(_result("DB Access", False, str(e)))
+        return results
+
+    results.append(_result("DB FTS5 Support", bool(db.fts_enabled), "FTS5 module missing in SQLite" if not db.fts_enabled else ""))
+    try:
+        cursor = db._read.execute("PRAGMA table_info(symbols)")
+        cols = [r["name"] for r in cursor.fetchall()]
+        if "end_line" in cols:
+            results.append(_result("DB Schema v2.7.0", True))
+        else:
+            results.append(_result("DB Schema v2.7.0", False, "Column 'end_line' missing in 'symbols'. Run update."))
+    except Exception as e:
+        results.append(_result("DB Schema Check", False, str(e)))
+    finally:
+        try:
+            db.close()
+        except Exception:
+            pass
+
+    return results
+
+
+def _check_port(port: int, label: str) -> dict[str, Any]:
+    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        s.bind(("127.0.0.1", port))
+        return _result(f"{label} Port {port} Availability", True)
+    except OSError as e:
+        return _result(f"{label} Port {port} Availability", False, f"Address in use or missing permission: {e}")
+    finally:
+        try:
+            s.close()
+        except Exception:
+            pass
+
+
+def _check_network() -> dict[str, Any]:
+    try:
+        socket.create_connection(("8.8.8.8", 53), timeout=3)
+        return _result("Network Check", True)
+    except OSError as e:
+        return _result("Network Check", False, f"Unreachable: {e}")
+
+
+def _check_disk_space(ws_root: str, min_gb: float) -> dict[str, Any]:
+    try:
+        total, used, free = shutil.disk_usage(ws_root)
+        free_gb = free / (1024**3)
+        if free_gb < min_gb:
+            return _result("Disk Space", False, f"Low space: {free_gb:.2f} GB (Min: {min_gb} GB)")
+        return _result("Disk Space", True)
+    except Exception as e:
+        return _result("Disk Space", False, str(e))
+
+
+def _check_daemon() -> dict[str, Any]:
+    host, port = get_daemon_address()
+    running = is_daemon_running(host, port)
+    if running:
+        pid = read_pid()
+        return _result("Sari Daemon", True, f"Running on {host}:{port} (PID: {pid})")
+    return _result("Sari Daemon", False, "Not running")
+
+
+def _check_search_first_usage(usage: Dict[str, Any], mode: str) -> dict[str, Any]:
+    violations = int(usage.get("read_without_search", 0))
+    searches = int(usage.get("search", 0))
+    symbol_searches = int(usage.get("search_symbols", 0))
+    if violations == 0:
+        return _result("Search-First Usage", True, "")
+    policy = mode if mode in {"off", "warn", "enforce"} else "unknown"
+    error = (
+        f"Search-first policy {policy}: {violations} read call(s) without prior search "
+        f"(search={searches}, search_symbols={symbol_searches})."
+    )
+    return _result("Search-First Usage", False, error)
+
+
+def execute_doctor(args: Dict[str, Any]) -> Dict[str, Any]:
+    ws_root = WorkspaceManager.resolve_workspace_root()
+
+    include_network = bool(args.get("include_network", True))
+    include_port = bool(args.get("include_port", True))
+    include_db = bool(args.get("include_db", True))
+    include_disk = bool(args.get("include_disk", True))
+    include_daemon = bool(args.get("include_daemon", True))
+    include_venv = bool(args.get("include_venv", True))
+    include_marker = bool(args.get("include_marker", False))
+    port = int(args.get("port", 0))
+    min_disk_gb = float(args.get("min_disk_gb", 1.0))
+
+    results: list[dict[str, Any]] = []
+
+    if include_venv:
+        in_venv = sys.prefix != sys.base_prefix
+        results.append(_result("Virtualenv", True, "" if in_venv else "Not running in venv (ok)"))
+
+    if include_marker:
+        results.append(_result("Workspace Marker (.codex-root)", True, "Marker check deprecated"))
+
+    if include_daemon:
+        results.append(_check_daemon())
+
+    if include_port:
+        daemon_host, daemon_port = get_daemon_address()
+        results.append(_check_port(daemon_port, "Daemon"))
+        http_port = 0
+        try:
+            inst = ServerRegistry().get_instance(ws_root)
+            if inst and inst.get("port"):
+                http_port = int(inst.get("port"))
+        except Exception:
+            http_port = 0
+        if not http_port:
+            try:
+                cfg_path = WorkspaceManager.resolve_config_path(ws_root)
+                cfg = Config.load(cfg_path, workspace_root_override=ws_root)
+                http_port = int(cfg.http_api_port)
+            except Exception:
+                http_port = 0
+        if port:
+            http_port = port
+        if http_port:
+            results.append(_check_port(http_port, "HTTP"))
+
+    if include_network:
+        results.append(_check_network())
+
+    if include_db:
+        results.extend(_check_db(ws_root))
+
+    if include_disk:
+        results.append(_check_disk_space(ws_root, min_disk_gb))
+
+    usage = args.get("search_usage")
+    if isinstance(usage, dict):
+        mode = str(args.get("search_first_mode", "unknown"))
+        results.append(_check_search_first_usage(usage, mode))
+
+    output = {
+        "workspace_root": ws_root,
+        "results": results,
+    }
+
+    compact = str(os.environ.get("DECKARD_RESPONSE_COMPACT") or "1").strip().lower() not in {"0", "false", "no", "off"}
+    payload = json.dumps(output, ensure_ascii=False, separators=(",", ":")) if compact else json.dumps(output, ensure_ascii=False, indent=2)
+    try:
+        from mcp.tools._util import mcp_response, pack_header, pack_line, pack_encode_text
+    except Exception:
+        from _util import mcp_response, pack_header, pack_line, pack_encode_text
+
+    def build_pack() -> str:
+        lines = [pack_header("doctor", {}, returned=1)]
+        lines.append(pack_line("t", single_value=pack_encode_text(payload)))
+        return "\n".join(lines)
+
+    return mcp_response(
+        "doctor",
+        build_pack,
+        lambda: {"content": [{"type": "text", "text": payload}]},
+    )