code-context-mcp 1.0.0__py3-none-any.whl

code_context/adapters/driving/mcp_server.py

@@ -0,0 +1,365 @@
+"""MCP driving adapter: registers the 7 contract tools on an mcp Server."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from mcp.server import Server
+from mcp.types import TextContent, Tool
+
+from code_context.domain.use_cases.explain_diff import ExplainDiffUseCase
+from code_context.domain.use_cases.find_definition import FindDefinitionUseCase
+from code_context.domain.use_cases.find_references import FindReferencesUseCase
+from code_context.domain.use_cases.get_file_tree import GetFileTreeUseCase
+from code_context.domain.use_cases.get_summary import GetSummaryUseCase
+from code_context.domain.use_cases.recent_changes import RecentChangesUseCase
+from code_context.domain.use_cases.search_repo import SearchRepoUseCase
+
+log = logging.getLogger(__name__)
+
+
+def register(
+    server: Server,
+    *,
+    search_repo: SearchRepoUseCase,
+    recent_changes: RecentChangesUseCase,
+    get_summary: GetSummaryUseCase,
+    find_definition: FindDefinitionUseCase,
+    find_references: FindReferencesUseCase,
+    get_file_tree: GetFileTreeUseCase,
+    explain_diff: ExplainDiffUseCase,
+) -> None:
+    """Register the 7 contract tools on the given mcp Server instance."""
+
+    @server.list_tools()
+    async def list_tools() -> list[Tool]:
+        return [
+            Tool(
+                name="search_repo",
+                description=(
+                    "Semantic search over the indexed codebase. Use this INSTEAD of Grep "
+                    "when the query is conceptual (e.g. 'where do we validate input', "
+                    "'how is caching implemented', 'authentication flow'). Returns ranked "
+                    "code fragments with file path, line range, snippet, score and a "
+                    "one-line `why` excerpt. For exact-string lookup, Grep is still better."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "query": {"type": "string"},
+                        "top_k": {"type": "integer", "default": 5},
+                        "scope": {
+                            "type": "string",
+                            "description": (
+                                "Optional repo-relative path prefix to constrain results."
+                            ),
+                        },
+                    },
+                    "required": ["query"],
+                },
+            ),
+            Tool(
+                name="recent_changes",
+                description=(
+                    "Recent git commits with structured fields (sha, ISO date, author, "
+                    "paths, summary). Use INSTEAD of `git log` shell calls — the output "
+                    "is already parsed and filterable by `since` and `paths`. Defaults "
+                    "to the last 7 days when `since` is omitted."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "since": {
+                            "type": "string",
+                            "description": "ISO 8601 cutoff; defaults to 7 days ago.",
+                        },
+                        "paths": {"type": "array", "items": {"type": "string"}},
+                        "max": {"type": "integer", "default": 20},
+                    },
+                },
+            ),
+            Tool(
+                name="get_summary",
+                description=(
+                    "Structured snapshot of the project or a module: name, purpose "
+                    "(README first paragraph), stack (Python/Node/Rust/Go/Java), "
+                    "entry_points, key_modules, stats (files, loc, languages). Useful "
+                    "at session start for orientation; prefer it over reading "
+                    "README/CLAUDE.md when you need machine-readable fields."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "scope": {"type": "string", "enum": ["project", "module"]},
+                        "path": {
+                            "type": "string",
+                            "description": "Required when scope='module'; repo-relative path.",
+                        },
+                    },
+                },
+            ),
+            Tool(
+                name="find_definition",
+                description=(
+                    "Locate the definition site of a named symbol (function, class, "
+                    "method, type, struct, enum, interface, record). Use this INSTEAD of "
+                    'shelling out to grep when the user asks "where is X defined?" — '
+                    "returns SymbolDef[] with path, line range, kind, and language. "
+                    "Faster and more accurate than grepping for `def X` / `class X` / "
+                    "`function X` / etc., because it consults a tree-sitter-indexed "
+                    "symbol table built at reindex time, not the raw text."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "name": {
+                            "type": "string",
+                            "description": "Exact identifier to locate.",
+                        },
+                        "language": {
+                            "type": "string",
+                            "enum": [
+                                "python",
+                                "javascript",
+                                "typescript",
+                                "go",
+                                "rust",
+                                "csharp",
+                            ],
+                            "description": ("Optional language hint for same-name disambiguation."),
+                        },
+                        "max": {"type": "integer", "default": 5},
+                    },
+                    "required": ["name"],
+                },
+            ),
+            Tool(
+                name="find_references",
+                description=(
+                    "List every textual occurrence of a named symbol in the indexed "
+                    'corpus. Use INSTEAD of `grep -n "X"` when the user asks "who '
+                    'calls X?" or "where is X used?". Returns SymbolRef[] with path, '
+                    "line, snippet. Word-boundary matched, so 'log' won't return "
+                    "'logger' or 'log_format'."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "name": {
+                            "type": "string",
+                            "description": "Exact identifier to find references for.",
+                        },
+                        "max": {"type": "integer", "default": 50},
+                    },
+                    "required": ["name"],
+                },
+            ),
+            Tool(
+                name="get_file_tree",
+                description=(
+                    "Repo-relative directory tree, gitignore-aware. Use INSTEAD of "
+                    "shelling out to `Bash: ls -R` or `Bash: tree` when the user "
+                    "asks for the project structure or for orientation in an "
+                    "unfamiliar module. Returns a hierarchical FileTreeNode with "
+                    "files (with byte sizes) and directories (with recursive "
+                    "children, capped at max_depth). Honors .gitignore; skips "
+                    "hidden files unless include_hidden=true."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "path": {
+                            "type": "string",
+                            "description": (
+                                "Optional repo-relative subdirectory; defaults to root."
+                            ),
+                        },
+                        "max_depth": {
+                            "type": "integer",
+                            "default": 4,
+                            "description": "Cap on tree depth.",
+                        },
+                        "include_hidden": {
+                            "type": "boolean",
+                            "default": False,
+                            "description": "Include dot-files / dot-directories.",
+                        },
+                    },
+                },
+            ),
+            Tool(
+                name="explain_diff",
+                description=(
+                    "AST-aligned chunks affected by the diff at `ref`. Use INSTEAD "
+                    'of `Bash: git show <sha>` when the user asks "what does this '
+                    'commit do?" or "what changed in HEAD~3?". The chunker resolves '
+                    "which whole functions / classes were touched, not just raw line "
+                    "additions — much easier for an LLM to reason about. Returns "
+                    "DiffChunk[] with path, lines, snippet, kind, and change "
+                    '("added"|"modified"|"deleted").'
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "ref": {
+                            "type": "string",
+                            "description": (
+                                "Git ref: full SHA, short SHA, HEAD, HEAD~N, branch name."
+                            ),
+                        },
+                        "max_chunks": {"type": "integer", "default": 50},
+                    },
+                    "required": ["ref"],
+                },
+            ),
+        ]
+
+    @server.call_tool()
+    async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
+        if name == "search_repo":
+            return await asyncio.to_thread(_handle_search, search_repo, arguments)
+        if name == "recent_changes":
+            return await asyncio.to_thread(_handle_recent, recent_changes, arguments)
+        if name == "get_summary":
+            return await asyncio.to_thread(_handle_summary, get_summary, arguments)
+        if name == "find_definition":
+            return await asyncio.to_thread(_handle_find_definition, find_definition, arguments)
+        if name == "find_references":
+            return await asyncio.to_thread(_handle_find_references, find_references, arguments)
+        if name == "get_file_tree":
+            return await asyncio.to_thread(_handle_file_tree, get_file_tree, arguments)
+        if name == "explain_diff":
+            return await asyncio.to_thread(_handle_explain_diff, explain_diff, arguments)
+        raise ValueError(f"unknown tool: {name}")
+
+
+def _handle_search(uc: SearchRepoUseCase, args: dict[str, Any]) -> list[TextContent]:
+    results = uc.run(
+        query=args["query"],
+        top_k=int(args.get("top_k", 5)),
+        scope=args.get("scope"),
+    )
+    payload = [
+        {
+            "path": r.path,
+            "lines": list(r.lines),
+            "snippet": r.snippet,
+            "score": r.score,
+            "why": r.why,
+        }
+        for r in results
+    ]
+    return [TextContent(type="text", text=_to_json(payload))]
+
+
+def _handle_recent(uc: RecentChangesUseCase, args: dict[str, Any]) -> list[TextContent]:
+    since = None
+    if args.get("since"):
+        since = datetime.fromisoformat(args["since"])
+    commits = uc.run(
+        since=since,
+        paths=args.get("paths"),
+        max_count=int(args.get("max", 20)),
+    )
+    payload = [
+        {
+            "sha": c.sha,
+            "date": c.date.isoformat(),
+            "author": c.author,
+            "paths": c.paths,
+            "summary": c.summary,
+        }
+        for c in commits
+    ]
+    return [TextContent(type="text", text=_to_json(payload))]
+
+
+def _handle_summary(uc: GetSummaryUseCase, args: dict[str, Any]) -> list[TextContent]:
+    scope = args.get("scope", "project")
+    path = Path(args["path"]) if args.get("path") else None
+    summary = uc.run(scope=scope, path=path)
+    payload = {
+        "name": summary.name,
+        "purpose": summary.purpose,
+        "stack": summary.stack,
+        "entry_points": summary.entry_points,
+        "key_modules": summary.key_modules,
+        "stats": summary.stats,
+    }
+    return [TextContent(type="text", text=_to_json(payload))]
+
+
+def _handle_find_definition(uc: FindDefinitionUseCase, args: dict[str, Any]) -> list[TextContent]:
+    defs = uc.run(
+        name=args["name"],
+        language=args.get("language"),
+        max_count=int(args.get("max", 5)),
+    )
+    payload = [
+        {
+            "name": d.name,
+            "path": d.path,
+            "lines": list(d.lines),
+            "kind": d.kind,
+            "language": d.language,
+        }
+        for d in defs
+    ]
+    return [TextContent(type="text", text=_to_json(payload))]
+
+
+def _handle_find_references(uc: FindReferencesUseCase, args: dict[str, Any]) -> list[TextContent]:
+    refs = uc.run(
+        name=args["name"],
+        max_count=int(args.get("max", 50)),
+    )
+    payload = [{"path": r.path, "line": r.line, "snippet": r.snippet} for r in refs]
+    return [TextContent(type="text", text=_to_json(payload))]
+
+
+def _handle_file_tree(uc: GetFileTreeUseCase, args: dict[str, Any]) -> list[TextContent]:
+    tree = uc.run(
+        path=args.get("path"),
+        max_depth=int(args.get("max_depth", 4)),
+        include_hidden=bool(args.get("include_hidden", False)),
+    )
+    payload = _serialize_tree_node(tree)
+    return [TextContent(type="text", text=_to_json(payload))]
+
+
+def _serialize_tree_node(node) -> dict[str, Any]:
+    """Recursively flatten a FileTreeNode tuple to plain JSON dicts."""
+    out: dict[str, Any] = {
+        "path": node.path,
+        "kind": node.kind,
+        "size": node.size,
+        "children": [_serialize_tree_node(c) for c in node.children],
+    }
+    return out
+
+
+def _handle_explain_diff(uc: ExplainDiffUseCase, args: dict[str, Any]) -> list[TextContent]:
+    chunks = uc.run(
+        ref=args["ref"],
+        max_chunks=int(args.get("max_chunks", 50)),
+    )
+    payload = [
+        {
+            "path": c.path,
+            "lines": list(c.lines),
+            "snippet": c.snippet,
+            "kind": c.kind,
+            "change": c.change,
+        }
+        for c in chunks
+    ]
+    return [TextContent(type="text", text=_to_json(payload))]
+
+
+def _to_json(obj: Any) -> str:
+    return json.dumps(obj, ensure_ascii=False, indent=2)

code_context/cli.py

@@ -0,0 +1,161 @@
+"""code-context CLI: reindex, status, query, clear."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import shutil
+import sys
+
+from code_context._composition import (
+    build_indexer_and_store,
+    build_use_cases,
+    safe_reindex,
+    setup_logging,
+)
+from code_context.config import load_config
+
+log = logging.getLogger("code_context")
+
+
+def _cmd_reindex(args: argparse.Namespace) -> int:
+    cfg = load_config()
+    setup_logging(cfg)
+    indexer, _, _, _, _ = build_indexer_and_store(cfg)
+    if args.force:
+        log.info("reindexing %s (forced full)", cfg.repo_root)
+        new_dir = safe_reindex(cfg, indexer)
+        print(f"reindexed (full, forced) -> {new_dir}")
+        return 0
+    stale = indexer.dirty_set()
+    log.info("reindexing %s (%s)", cfg.repo_root, stale.reason)
+    new_dir = safe_reindex(cfg, indexer, stale=stale)
+    mode = "full" if stale.full_reindex_required else "incremental"
+    print(f"reindexed ({mode}: {stale.reason}) -> {new_dir}")
+    return 0
+
+
+def _cmd_status(args: argparse.Namespace) -> int:
+    cfg = load_config()
+    setup_logging(cfg)
+    indexer, _, _, _, _ = build_indexer_and_store(cfg)
+    current = indexer.current_index_dir()
+    print(f"repo_root:  {cfg.repo_root}")
+    print(f"cache_dir:  {cfg.repo_cache_subdir()}")
+    if current is None:
+        print("status:     no index yet")
+        return 0
+    meta_path = current / "metadata.json"
+    if not meta_path.exists():
+        print("status:     index dir present but metadata missing")
+        return 1
+    meta = json.loads(meta_path.read_text())
+    print(f"index_dir:  {current}")
+    print(f"head_sha:   {meta.get('head_sha')}")
+    print(f"indexed_at: {meta.get('indexed_at')}")
+    print(f"n_chunks:   {meta.get('n_chunks')}")
+    print(f"n_files:    {meta.get('n_files')}")
+    print(f"model:      {meta.get('embeddings_model')}")
+    print(f"chunker:    {meta.get('chunker_version')}")
+    print(f"keyword:    {meta.get('keyword_version', '<not indexed — pre-v0.4.0>')}")
+    print(f"symbol:     {meta.get('symbol_version', '<not indexed — pre-v0.5.0>')}")
+    stale = indexer.dirty_set()
+    print(f"dirty:      {len(stale.dirty_files)}")
+    print(f"deleted:    {len(stale.deleted_files)}")
+    print(f"full_reindex_required: {stale.full_reindex_required}")
+    print(f"reason:     {stale.reason}")
+    return 0
+
+
+def _cmd_query(args: argparse.Namespace) -> int:
+    cfg = load_config()
+    setup_logging(cfg)
+    indexer, store, embeddings, keyword_index, symbol_index = build_indexer_and_store(cfg)
+    current = indexer.current_index_dir()
+    if current is None:
+        print("error: no index. run `code-context reindex` first.", file=sys.stderr)
+        return 1
+    if indexer.is_stale():
+        print(
+            "warning: index is stale (HEAD/files/model/chunker changed since last reindex). "
+            "Results may be out of date. Run `code-context reindex` to refresh.",
+            file=sys.stderr,
+        )
+    store.load(current)
+    try:
+        keyword_index.load(current)
+    except FileNotFoundError:
+        log.warning(
+            "keyword index missing in %s — search will fall back to vector-only. "
+            "Run `code-context reindex` to backfill the keyword leg.",
+            current,
+        )
+    try:
+        symbol_index.load(current)
+    except FileNotFoundError:
+        log.warning(
+            "symbol index missing in %s — find_definition/find_references unavailable. "
+            "Run `code-context reindex` to backfill the symbol leg.",
+            current,
+        )
+    search, _, _, _, _, _, _ = build_use_cases(
+        cfg,
+        indexer,
+        store,
+        embeddings,
+        keyword_index,
+        symbol_index,
+    )
+    results = search.run(query=args.text, top_k=args.k or cfg.top_k_default)
+    for r in results:
+        print(f"{r.score:.3f} {r.path}:{r.lines[0]}-{r.lines[1]}  ({r.why})")
+    return 0
+
+
+def _cmd_clear(args: argparse.Namespace) -> int:
+    cfg = load_config()
+    setup_logging(cfg)
+    target = cfg.repo_cache_subdir()
+    if not target.exists():
+        print("nothing to clear")
+        return 0
+    if not args.yes:
+        print(f"this will delete {target}. pass --yes to confirm.", file=sys.stderr)
+        return 1
+    shutil.rmtree(target)
+    print(f"cleared {target}")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="code-context", description="code-context CLI")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    r = sub.add_parser(
+        "reindex",
+        help="Reindex now (incremental by default; --force for full)",
+    )
+    r.add_argument(
+        "--force",
+        action="store_true",
+        help="Force a full reindex regardless of dirty_set verdict.",
+    )
+    r.set_defaults(func=_cmd_reindex)
+    sub.add_parser("status", help="Show index health").set_defaults(func=_cmd_status)
+
+    q = sub.add_parser("query", help="Run a search query without MCP")
+    q.add_argument("text")
+    q.add_argument("-k", type=int, default=None, help="Override top_k")
+    q.set_defaults(func=_cmd_query)
+
+    c = sub.add_parser("clear", help="Delete the cache for this repo")
+    c.add_argument("--yes", action="store_true", help="Confirm deletion")
+    c.set_defaults(func=_cmd_clear)
+
+    args = parser.parse_args()
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

code_context/config.py

@@ -0,0 +1,114 @@
+"""Configuration: env vars + defaults, frozen dataclass."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+import platformdirs
+
+_DEFAULT_EXTENSIONS = [
+    ".py",
+    ".js",
+    ".ts",
+    ".jsx",
+    ".tsx",
+    ".go",
+    ".rs",
+    ".cs",
+    ".java",
+    ".c",
+    ".cpp",
+    ".h",
+    ".hpp",
+    ".md",
+    ".yaml",
+    ".yml",
+    ".json",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class Config:
+    repo_root: Path
+    embeddings_provider: str  # "local" or "openai"
+    embeddings_model: str | None
+    openai_api_key: str | None
+    include_extensions: list[str]
+    max_file_bytes: int
+    cache_dir: Path
+    log_level: str
+    top_k_default: int
+    chunk_lines: int
+    chunk_overlap: int
+    chunker_strategy: str  # "treesitter" (default) or "line"
+    keyword_strategy: str  # "sqlite" (default) or "none"
+    rerank: bool
+    rerank_model: str | None
+    symbol_index_strategy: str  # "sqlite" (default) or "none"
+    trust_remote_code: bool  # Off by default. Required for some HF models that ship custom Python.
+    # Sprint 7 — background reindex thread (default ON). Coalesce window
+    # for trigger storms.
+    bg_reindex: bool = True
+    bg_idle_seconds: float = 1.0
+    # Sprint 7 — optional file-system watcher (off by default; needs
+    # the [watch] extra installed).
+    watch: bool = False
+    watch_debounce_ms: int = 1000
+
+    def repo_cache_subdir(self) -> Path:
+        """Cache subdir specific to this repo (hashed for collision safety)."""
+        h = hashlib.sha256(str(self.repo_root.resolve()).encode("utf-8")).hexdigest()[:16]
+        return self.cache_dir / h
+
+
+def load_config(default_repo_root: Path | None = None) -> Config:
+    repo_root = Path(os.environ.get("CC_REPO_ROOT") or default_repo_root or Path.cwd())
+    embeddings = os.environ.get("CC_EMBEDDINGS", "local")
+
+    default_model = "all-MiniLM-L6-v2" if embeddings == "local" else "text-embedding-3-small"
+    model = os.environ.get("CC_EMBEDDINGS_MODEL", default_model)
+
+    cache_override = os.environ.get("CC_CACHE_DIR")
+    cache_dir = (
+        Path(cache_override)
+        if cache_override
+        else Path(platformdirs.user_cache_dir("code-context"))
+    )
+
+    exts_raw = os.environ.get("CC_INCLUDE_EXTENSIONS")
+    if exts_raw:
+        exts = [
+            e.strip() if e.startswith(".") else f".{e.strip()}"
+            for e in exts_raw.split(",")
+            if e.strip()
+        ]
+    else:
+        exts = list(_DEFAULT_EXTENSIONS)
+
+    return Config(
+        repo_root=repo_root.resolve(),
+        embeddings_provider=embeddings,
+        embeddings_model=model,
+        openai_api_key=os.environ.get("OPENAI_API_KEY"),
+        include_extensions=exts,
+        max_file_bytes=int(os.environ.get("CC_MAX_FILE_BYTES", "1048576")),
+        cache_dir=cache_dir,
+        log_level=os.environ.get("CC_LOG_LEVEL", "INFO"),
+        top_k_default=int(os.environ.get("CC_TOP_K_DEFAULT", "5")),
+        chunk_lines=int(os.environ.get("CC_CHUNK_LINES", "50")),
+        chunk_overlap=int(os.environ.get("CC_CHUNK_OVERLAP", "10")),
+        chunker_strategy=os.environ.get("CC_CHUNKER", "treesitter"),
+        keyword_strategy=os.environ.get("CC_KEYWORD_INDEX", "sqlite"),
+        rerank=os.environ.get("CC_RERANK", "off").lower() in ("on", "true", "1"),
+        rerank_model=os.environ.get("CC_RERANK_MODEL"),
+        symbol_index_strategy=os.environ.get("CC_SYMBOL_INDEX", "sqlite"),
+        trust_remote_code=os.environ.get("CC_TRUST_REMOTE_CODE", "off").lower()
+        in ("on", "true", "1"),
+        bg_reindex=os.environ.get("CC_BG_REINDEX", "on").lower() in ("on", "true", "1"),
+        bg_idle_seconds=float(os.environ.get("CC_BG_IDLE_SECONDS", "1.0")),
+        watch=os.environ.get("CC_WATCH", "off").lower() in ("on", "true", "1"),
+        watch_debounce_ms=int(os.environ.get("CC_WATCH_DEBOUNCE_MS", "1000")),
+    )