codexlr8 0.0.1__py3-none-any.whl

codexlr8/mcp_server.py

@@ -0,0 +1,163 @@
+"""CodeXLR8 MCP server — exposes codebase search to LLM agents."""
+
+from __future__ import annotations
+
+import json
+import os
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent
+
+from .search import SearchEngine
+from .config import load_config
+
+_DEFAULT_PATH = os.getcwd()
+server = Server("codexlr8")
+
+
+def _resolve_path(arg_path: str | None) -> str:
+    """Resolve the project path from arg, config, or cwd."""
+    if arg_path and arg_path != ".":
+        return os.path.abspath(arg_path)
+    # Try reading config from cwd to get root
+    config = load_config(_DEFAULT_PATH)
+    root = config.get("root", ".")
+    return os.path.abspath(os.path.join(_DEFAULT_PATH, root))
+
+
+@server.list_tools()
+async def list_tools() -> list[Tool]:
+    return [
+        Tool(
+            name="codebase_search",
+            description=(
+                "Search the codebase using natural language. "
+                "Returns ranked results with file paths, line numbers, "
+                "relevance scores, metadata descriptions, and code previews. "
+                "Use this BEFORE reading any files to find the right code. "
+                "Describe what you're looking for — more terms increase precision. "
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query": {
+                        "type": "string",
+                        "description": "Natural language search query",
+                    },
+                    "path": {
+                        "type": "string",
+                        "description": "Path to the project root (default: current directory)",
+                        "default": ".",
+                    },
+                    "limit": {
+                        "type": "integer",
+                        "description": "Maximum results to return (default 10)",
+                        "default": 10,
+                    },
+                    "exclude": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Glob patterns for files to exclude. "
+                                       "Uses .codexlr8.yaml defaults if not set.",
+                    },
+                },
+                "required": ["query"],
+            },
+        ),
+        Tool(
+            name="codebase_index",
+            description=(
+                "Build or update the codebase search index. "
+                "Run this at the start of a session if the index is missing or stale. "
+                "Use --incremental for updates after code changes."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "Path to the project root (default: current directory)",
+                        "default": ".",
+                    },
+                    "incremental": {
+                        "type": "boolean",
+                        "description": "Only update changed files (default false)",
+                        "default": False,
+                    },
+                    "exclude": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Glob patterns for files to exclude",
+                    },
+                },
+                "required": [],
+            },
+        ),
+    ]
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+    if name == "codebase_search":
+        return await _handle_search(arguments)
+    elif name == "codebase_index":
+        return await _handle_index(arguments)
+    raise ValueError(f"Unknown tool: {name}")
+
+
+async def _handle_search(args: dict) -> list[TextContent]:
+    project_path = _resolve_path(args.get("path"))
+    query = args["query"]
+    limit = args.get("limit", 10)
+    exclude = args.get("exclude")
+
+    engine = SearchEngine(project_path)
+    results = engine.search(query, limit=limit, exclude=exclude)
+
+    if not results:
+        return [TextContent(type="text", text="No results found.")]
+
+    lines = []
+    for i, r in enumerate(results, 1):
+        lines.append(
+            f"{i}. {r['path']}:{r['line_start']}-{r['line_end']}  "
+            f"[score: {r['score']:.2f}]"
+        )
+        if r.get("summary"):
+            lines.append(f"   summary: {r['summary']}")
+        if r.get("tags"):
+            lines.append(f"   tags: {', '.join(r['tags'])}")
+        if r.get("preview"):
+            lines.append("   preview: |")
+            for pline in r["preview"].strip().splitlines()[:6]:
+                lines.append(f"     {pline}")
+        lines.append("")
+
+    return [TextContent(type="text", text="\n".join(lines))]
+
+
+async def _handle_index(args: dict) -> list[TextContent]:
+    project_path = _resolve_path(args.get("path"))
+    incremental = args.get("incremental", False)
+    exclude = args.get("exclude")
+
+    engine = SearchEngine(project_path)
+    count = engine.build_index(incremental=incremental, exclude=exclude)
+
+    msg = f"Index updated: {count} files." if incremental else f"Index built: {count} files."
+    return [TextContent(type="text", text=msg)]
+
+
+def main():
+    import asyncio
+    asyncio.run(_run())
+
+
+async def _run():
+    async with stdio_server() as (read, write):
+        await server.run(read, write, server.create_initialization_options())
+
+
+if __name__ == "__main__":
+    main()

codexlr8/meta.py

@@ -0,0 +1,110 @@
+""".meta.yaml sidecar reading, writing, and generation."""
+
+from __future__ import annotations
+
+import os
+from datetime import datetime, timezone
+
+import yaml
+
+from .scanner import scan_project
+
+META_EXTENSION = ".meta.yaml"
+
+
+def meta_path_for(filepath: str) -> str:
+    """Return the .meta.yaml sidecar path for a given source file path."""
+    return filepath + META_EXTENSION
+
+
+def source_path_for(meta_path: str) -> str:
+    """Return the source file path for a given .meta.yaml sidecar path."""
+    assert meta_path.endswith(META_EXTENSION)
+    return meta_path[: -len(META_EXTENSION)]
+
+
+def read_meta(meta_path: str) -> dict | None:
+    """Read a .meta.yaml file, returning parsed dict or None."""
+    if not os.path.exists(meta_path):
+        return None
+    with open(meta_path, "r", encoding="utf-8") as f:
+        return yaml.safe_load(f) or {}
+
+
+def write_meta(meta_path: str, data: dict) -> None:
+    """Write a .meta.yaml file."""
+    with open(meta_path, "w", encoding="utf-8") as f:
+        yaml.safe_dump(data, f, default_flow_style=False, sort_keys=False, allow_unicode=True)
+
+
+def generate_meta_skeleton(existing_meta: dict | None = None) -> dict:
+    """Generate a fresh .meta.yaml skeleton, preserving curated fields.
+
+    Auto fields are empty — they can be populated by agents over time.
+    Curated fields (summary, tags, invariants, examples) are preserved
+    from existing_meta if provided.
+    """
+    result: dict = {
+        "public_api": [],
+        "dependencies": [],
+        "used_by": [],
+        "last_modified": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+
+    if existing_meta:
+        for key in ("summary", "tags", "invariants", "examples"):
+            if key in existing_meta:
+                result[key] = existing_meta[key]
+
+    return result
+
+
+def generate_missing_sidecars(project_path: str) -> list[str]:
+    """Scan project and create .meta.yaml files for any source files that lack them.
+
+    Returns list of created meta file paths (relative to project root).
+    """
+    files_data = scan_project(project_path)
+    created = []
+
+    for entry in files_data:
+        filepath = os.path.join(project_path, entry["path"])
+        meta_path = meta_path_for(filepath)
+
+        if os.path.exists(meta_path):
+            continue
+
+        meta_data = generate_meta_skeleton()
+        write_meta(meta_path, meta_data)
+        created.append(entry["path"] + META_EXTENSION)
+
+    return created
+
+
+def validate_meta(meta_path: str) -> list[str]:
+    """Validate a .meta.yaml file structure.
+
+    Returns list of warning strings (empty if valid).
+    Checks: file exists, is valid YAML, required keys present.
+    """
+    warnings = []
+
+    if not os.path.exists(meta_path):
+        return ["No .meta.yaml found"]
+
+    try:
+        meta = read_meta(meta_path)
+    except Exception:
+        return [f"Failed to parse {meta_path}"]
+
+    if meta is None:
+        return ["Empty or invalid .meta.yaml"]
+
+    # Check auto fields exist
+    for key in ("public_api", "dependencies", "used_by"):
+        if key not in meta:
+            warnings.append(f"Missing required field: '{key}'")
+        elif not isinstance(meta[key], list):
+            warnings.append(f"Field '{key}' must be a list")
+
+    return warnings

codexlr8/scanner.py

@@ -0,0 +1,82 @@
+"""File scanner — walks project and collects source file content for indexing."""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+
+DEFAULT_EXTENSIONS = [
+    ".py", ".js", ".ts", ".jsx", ".tsx", ".go", ".rs", ".rb",
+    ".java", ".c", ".h", ".cpp", ".hpp", ".cc", ".hh",
+    ".cs", ".swift", ".kt", ".kts", ".scala", ".sh", ".bash",
+    ".sql", ".r", ".lua", ".pl", ".pm",
+]
+
+DEFAULT_IGNORE_DIRS = [
+    ".git", "__pycache__", "node_modules", ".venv", "venv",
+    ".tox", ".mypy_cache", ".pytest_cache", ".ruff_cache",
+    "dist", "build", ".eggs", "*.egg-info",
+]
+
+
+def _is_ignored_dir(dirname: str, ignore_dirs: list[str]) -> bool:
+    for pattern in ignore_dirs:
+        if fnmatch.fnmatch(dirname, pattern):
+            return True
+    if dirname.startswith("."):
+        return True
+    return False
+
+
+def _matches_glob(path: str, patterns: list[str]) -> bool:
+    if not patterns:
+        return False
+    basename = os.path.basename(path)
+    for pattern in patterns:
+        if fnmatch.fnmatch(path, pattern) or fnmatch.fnmatch(basename, pattern):
+            return True
+    return False
+
+
+def scan_project(project_path: str,
+                 extensions: list[str] | None = None,
+                 ignore_dirs: list[str] | None = None,
+                 include: list[str] | None = None,
+                 exclude: list[str] | None = None) -> list[dict]:
+    """Walk a project directory and collect file content for indexing.
+
+    extensions: file extensions to scan (default: common source code extensions).
+    ignore_dirs: directory names to skip (default: .git, node_modules, etc.).
+    include: only scan files matching these glob patterns (if set).
+    exclude: skip files matching these glob patterns.
+
+    Returns a list of dicts with 'path' (relative) and 'content' (raw text).
+    """
+    results = []
+    _extensions = extensions if extensions is not None else DEFAULT_EXTENSIONS
+    _ignore = ignore_dirs if ignore_dirs is not None else DEFAULT_IGNORE_DIRS
+
+    for root, dirs, files in os.walk(project_path):
+        dirs[:] = [d for d in dirs if not _is_ignored_dir(d, _ignore)]
+        for filename in sorted(files):
+            ext = os.path.splitext(filename)[1]
+            if ext not in _extensions:
+                continue
+            filepath = os.path.join(root, filename)
+            relpath = os.path.relpath(filepath, project_path)
+
+            if include and not _matches_glob(relpath, include):
+                continue
+            if exclude and _matches_glob(relpath, exclude):
+                continue
+
+            try:
+                with open(filepath, "r", encoding="utf-8", errors="replace") as f:
+                    content = f.read()
+            except Exception:
+                continue
+            results.append({
+                "path": relpath,
+                "content": content,
+            })
+    return results