codecompass-mcp 2.0.0__py3-none-any.whl

graph/mcp_server.py

@@ -0,0 +1,280 @@
+"""CodeCompass MCP Server — exposes code graph queries as native opencode tools.
+
+Registered in ~/.config/opencode/opencode.json as a local MCP server.
+Available from any working directory — no need to cd to the codecompass project.
+
+Tools exposed:
+    list_projects  — list all ingested projects
+    blast_radius   — all files reachable from a symbol/file (forward)
+    impact         — what calls/uses a symbol (reverse)
+    deps           — what a file imports (direct + transitive)
+    trace          — forward call chain from a function
+    tree           — folder/file hierarchy for a project
+    styles         — CSS selectors that target an element
+    batch_impact   — union blast radius for N targets (plan a PR)
+
+Usage:
+    python -m graph.mcp_server
+"""
+
+from __future__ import annotations
+
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+_project_root = Path(__file__).resolve().parent.parent
+if str(_project_root) not in sys.path:
+    sys.path.insert(0, str(_project_root))
+
+from mcp.server.fastmcp import FastMCP
+
+from graph.code_graph_client import get_client
+
+mcp = FastMCP("codecompass")
+DEFAULT_HOPS = 3
+STALE_WARN_HOURS = 24
+
+
+def _stale_warning(project: str) -> str:
+    client = get_client(project)
+    try:
+        ts = client.get_project_last_ingested(project)
+    finally:
+        client.close()
+    if not ts:
+        return ""
+    try:
+        dt = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+        age_hours = (datetime.now(timezone.utc) - dt).total_seconds() / 3600
+        if age_hours > STALE_WARN_HOURS:
+            return f"\nWARNING: index for '{project}' is {age_hours:.0f}h old — re-run ingest-code to refresh"
+    except (ValueError, TypeError):
+        pass
+    return ""
+
+
+# ── list_projects ────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def list_projects() -> str:
+    """List all projects currently ingested in the code graph."""
+    client = get_client("default")
+    try:
+        projects = client.get_all_projects()
+    finally:
+        client.close()
+
+    if not projects:
+        return "No projects ingested yet.\n  Run: codecompass ingest-code <repo_path> --project <name>"
+
+    return "Ingested projects:\n" + "\n".join(f"  {p}" for p in projects)
+
+
+# ── impact ───────────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def impact(symbol: str, project: str, hops: int = DEFAULT_HOPS) -> str:
+    """What calls or uses a symbol? Reverse traversal — find everything that
+    references a function, class, CSS variable, or HTML element."""
+    client = get_client(project)
+    try:
+        rows = client.find_callers(symbol, project, max_hops=hops)
+    finally:
+        client.close()
+
+    if not rows:
+        return f"Nothing calls '{symbol}' within {hops} hops."
+
+    lines = [f"Callers of '{symbol}':"]
+    for r in rows:
+        tag = f"({r.get('caller_type', '')})" if r.get("caller_type") else ""
+        lines.append(f"  {r['caller_name']} {tag}in {r['caller_file']} [depth {r['depth']}]")
+
+    lines.append(_stale_warning(project))
+    return "\n".join(lines)
+
+
+# ── deps ─────────────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def deps(file_path: str, project: str, hops: int = DEFAULT_HOPS) -> str:
+    """What does a file import? Returns direct and transitive dependencies."""
+    client = get_client(project)
+    try:
+        rows = client.find_dependencies(file_path, project, max_hops=hops)
+    finally:
+        client.close()
+
+    if not rows:
+        return f"No dependencies found for '{file_path}'."
+
+    lines = [f"Dependencies of '{file_path}':"]
+    for r in rows:
+        tag = f"({r.get('dep_type', '')})" if r.get("dep_type") else ""
+        lines.append(f"  {r['dependency']} {tag}[depth {r['depth']}]")
+
+    lines.append(_stale_warning(project))
+    return "\n".join(lines)
+
+
+# ── styles ───────────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def styles(element_name: str, project: str) -> str:
+    """CSS selectors that style an HTML element or web component."""
+    client = get_client(project)
+    try:
+        rows = client.find_styles(element_name, project)
+    finally:
+        client.close()
+
+    if not rows:
+        return f"No CSS selectors found for '{element_name}'."
+
+    lines = [f"CSS selectors for '{element_name}':"]
+    for r in rows:
+        line_info = f" line {r['line']}" if r.get("line") else ""
+        lines.append(f"  {r['selector']} in {r['source_file']}{line_info}")
+
+    lines.append(_stale_warning(project))
+    return "\n".join(lines)
+
+
+# ── trace ────────────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def trace(start_name: str, project: str, hops: int = 4) -> str:
+    """Forward call chain — what functions does this entry point call?"""
+    client = get_client(project)
+    try:
+        rows = client.trace_calls(start_name, project, max_hops=hops)
+    finally:
+        client.close()
+
+    if not rows:
+        return f"No call chain found from '{start_name}' within {hops} hops."
+
+    lines = [f"Call chain from '{start_name}':"]
+    for r in rows:
+        tag = f"({r.get('callee_type', '')})" if r.get("callee_type") else ""
+        lines.append(f"  {r['callee_name']} {tag}in {r['callee_file']} [depth {r['depth']}]")
+
+    lines.append(_stale_warning(project))
+    return "\n".join(lines)
+
+
+# ── blast_radius ─────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def blast_radius(target: str, project: str, hops: int = DEFAULT_HOPS) -> str:
+    """All files reachable from a symbol or file via CALLS/IMPORTS/INHERITS.
+    Use before editing — shows everything a change will touch."""
+    client = get_client(project)
+    try:
+        rows, target_file = client.get_blast_radius(target, project, max_hops=hops)
+    finally:
+        client.close()
+
+    if target_file is None and not rows:
+        return f"'{target}' not found in project '{project}'."
+
+    lines = [f"Blast radius for '{target}' (via {target_file or 'unknown file'}):"]
+    if not rows:
+        lines.append("  (nothing reachable within hops)")
+
+    seen = set()
+    for r in rows:
+        f = r["file"]
+        if f not in seen:
+            seen.add(f)
+            lines.append(f"  {f}  [via: {r.get('edge_type', '?')}]")
+
+    lines.append(f"\n# blast radius: {len(seen)} files across {hops} hops")
+    lines.append(_stale_warning(project))
+    return "\n".join(lines)
+
+
+# ── batch_impact ─────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def batch_impact(targets: str, project: str, hops: int = DEFAULT_HOPS) -> str:
+    """Union blast radius across multiple targets (comma-separated).
+    Use when planning a PR — see the full set of files touched."""
+    target_list = [t.strip() for t in targets.split(",") if t.strip()]
+
+    client = get_client(project)
+    try:
+        all_files: set[str] = set()
+        lines = [f"Batch impact for {len(target_list)} targets in '{project}':"]
+        found_any = False
+
+        for target in target_list:
+            rows, target_file = client.get_blast_radius(target, project, max_hops=hops)
+            if target_file is None and not rows:
+                lines.append(f"  WARNING: '{target}' not found")
+                continue
+            found_any = True
+            for r in rows:
+                if r["file"] not in all_files:
+                    all_files.add(r["file"])
+                    lines.append(f"  {r['file']}  [via: {target}]")
+
+        if not found_any:
+            return f"None of the targets found in project '{project}'."
+
+        lines.append(f"\n# batch impact: {len(all_files)} files, {len(target_list)} input targets, {hops} hops")
+    finally:
+        client.close()
+
+    lines.append(_stale_warning(project))
+    return "\n".join(lines)
+
+
+# ── tree ─────────────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def tree(project: str) -> str:
+    """Folder and file hierarchy for a project."""
+    client = get_client(project)
+    try:
+        rows = client.get_project_tree(project)
+    finally:
+        client.close()
+
+    if not rows:
+        return f"No hierarchy found for project '{project}'. Run ingest-code first."
+
+    lines = [project + "/"]
+    for r in rows:
+        indent = "  " * (r.get("depth", 0) or 0)
+        name = r["name"]
+        node_type = r.get("node_type", "")
+        suffix = "/" if node_type == "Folder" else ""
+        lines.append(f"{indent}├── {name}{suffix}")
+
+    lines.append(_stale_warning(project))
+    return "\n".join(lines)
+
+
+# ── entry point ──────────────────────────────────────────────────────────────
+
+def main() -> None:
+    transport = sys.argv[1] if len(sys.argv) > 1 else "stdio"
+    if transport == "sse":
+        port = int(sys.argv[2]) if len(sys.argv) > 2 else 8000
+        mcp.run(transport="sse", host="0.0.0.0", port=port)
+    else:
+        mcp.run()
+
+
+if __name__ == "__main__":
+    main()

graph/setup.py

@@ -0,0 +1,255 @@
+"""CodeCompass setup wizard — writes all config files a pip-installed agent needs.
+
+Usage:
+    codecompass setup
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+INSTRUCTIONS_MD = """\
+# CodeCompass — opencode Instructions
+
+A Neo4j-backed code dependency graph is available via MCP tools. \
+**Always query it before editing code.** The graph knows what's connected — \
+trust it over file exploration.
+
+---
+
+## Available tools (MCP)
+
+All tools use the `codecompass` MCP server. Call them from any working directory.
+
+| Tool | Purpose |
+|---|---|
+| `list_projects` | See all ingested projects |
+| `blast_radius` | Every file a symbol/file touches (forward) |
+| `impact` | What calls/uses a symbol (reverse) |
+| `deps` | What a file imports |
+| `trace` | Forward call chain from a function |
+| `tree` | Folder/file hierarchy |
+| `styles` | CSS selectors for an element |
+| `batch_impact` | Union blast radius across N targets |
+
+---
+
+## When to use each tool
+
+| Scenario | Tool to call first |
+|---|---|
+| About to edit one file or symbol | `blast_radius(symbol, project)` |
+| Planning a PR touching N files | `batch_impact("file1, file2", project)` |
+| Renaming or removing a function | `impact(function_name, project)` |
+| Understanding what a file imports | `deps(file_path, project)` |
+| Tracing a call chain forward | `trace(entry_point, project)` |
+| Orienting in an unfamiliar project | `tree(project)` |
+| Finding which CSS targets an element | `styles(element_name, project)` |
+| Discovering ingested projects | `list_projects()` |
+
+---
+
+## Mandatory rules
+
+1. **Before editing any file in an ingested project, call the codecompass tools first.**
+2. Use `list_projects()` to discover what projects are available.
+3. Use `blast_radius` to understand impact before making changes.
+4. Use `impact` before renaming or removing anything.
+5. If a tool returns a WARNING about stale index, suggest re-running `codecompass ingest-code`.
+6. The graph provides **structural truth** (AST-parsed). Trust it. It cannot tell you what code *means* — only what's connected.
+
+---
+
+## Project memory
+
+Session learnings are stored in `memory/learnings.md`. Design decisions are in \
+`memory/decisions.md`. These accumulate across sessions — read them at session \
+start if relevant to your task.
+"""
+
+DOT_ENV_TEMPLATE = """\
+ANTHROPIC_API_KEY=your_key_here
+NEO4J_URI=bolt://localhost:7687
+NEO4J_USER=neo4j
+NEO4J_PASSWORD=password123
+"""
+
+
+def _memory_plugin_ts(script_dir: str) -> str:
+    return f"""\
+import type {{ Plugin }} from "@opencode-ai/plugin"
+
+const SAVE_SCRIPT = "{script_dir}/save_learnings.py"
+const LOG_SCRIPT = "{script_dir}/log_session.py"
+
+export const CodeCompassMemory: Plugin = async ({{ $, directory }}) => {{
+  return {{
+    "experimental.session.compacting": async (_input, output) => {{
+      output.context.push(`## CodeCompass Session Memory
+
+Before generating the compaction summary, review this conversation and include:
+
+### Key Learnings
+- Design decisions made and why
+- Problems solved and how
+- Constraints discovered
+- Patterns established
+- Non-obvious insights
+
+### Active Context
+- Current task and its status
+- Files being modified
+- Blockers or dependencies
+
+Format the learnings section so they can be extracted later if needed.`)
+    }},
+
+    event: async ({{ event }}) => {{
+      if (event.type === "session.idle") {{
+        await $`python ${{LOG_SCRIPT}} ${{directory}}`.quiet().nothrow()
+      }}
+      if (event.type === "session.compacted") {{
+        await $`python ${{SAVE_SCRIPT}} ${{directory}}`.quiet().nothrow()
+      }}
+    }},
+  }}
+}}
+"""
+
+
+def _save_learnings_py(memory_dir: str) -> str:
+    return f"""\
+from __future__ import annotations
+
+import subprocess, sys
+from datetime import datetime
+from pathlib import Path
+
+MEMORY_DIR = Path("{memory_dir}")
+LEARNINGS_FILE = MEMORY_DIR / "learnings.md"
+
+
+def _get_changed_files(cwd: str) -> list[str]:
+    try:
+        r = subprocess.run(["git", "diff", "--name-only", "HEAD"],
+                           capture_output=True, text=True, timeout=5, cwd=cwd)
+        return [f.strip() for f in r.stdout.strip().split("\\n") if f.strip()]
+    except Exception:
+        return []
+
+
+def main() -> None:
+    cwd = sys.argv[1] if len(sys.argv) > 1 else __import__("os").getcwd()
+    changed = _get_changed_files(cwd)
+    date_key = datetime.now().strftime("%Y-%m-%d")
+    lines = [f"\\n\\n## {{date_key}} (post-compact)", f"cwd: {{cwd}}"]
+    if changed:
+        lines.append(f"Files changed: {{', '.join(changed)}}")
+        lines.append(f"- (review conversation for key learnings about: {{', '.join(changed[:3])}})")
+    else:
+        lines.append("Session compacted — no file changes detected.")
+    MEMORY_DIR.mkdir(parents=True, exist_ok=True)
+    with open(LEARNINGS_FILE, "a", encoding="utf-8") as f:
+        f.write("\\n".join(lines) + "\\n")
+
+
+if __name__ == "__main__":
+    main()
+"""
+
+
+def _log_session_py(memory_dir: str) -> str:
+    return f"""\
+from __future__ import annotations
+
+import subprocess, sys
+from datetime import datetime
+from pathlib import Path
+
+MEMORY_DIR = Path("{memory_dir}")
+SESSION_LOG = MEMORY_DIR / "session_log.md"
+
+
+def _get_changed_files(cwd: str) -> list[str]:
+    try:
+        r = subprocess.run(["git", "diff", "--name-only", "HEAD"],
+                           capture_output=True, text=True, timeout=5, cwd=cwd)
+        return [f.strip() for f in r.stdout.strip().split("\\n") if f.strip()]
+    except Exception:
+        return []
+
+
+def main() -> None:
+    cwd = sys.argv[1] if len(sys.argv) > 1 else __import__("os").getcwd()
+    changed = _get_changed_files(cwd)
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M")
+    lines = [f"\\n\\n## {{timestamp}}", f"cwd: {{cwd}}"]
+    lines.append(f"files changed: {{', '.join(changed) if changed else 'none'}}")
+    MEMORY_DIR.mkdir(parents=True, exist_ok=True)
+    with open(SESSION_LOG, "a", encoding="utf-8") as f:
+        f.write("\\n".join(lines) + "\\n")
+
+
+if __name__ == "__main__":
+    main()
+"""
+
+
+def run_setup() -> None:
+    base_dir = Path.home() / ".config" / "opencode" / "codecompass"
+    plugins_dir = base_dir / "plugins"
+    scripts_dir = base_dir / "scripts"
+    memory_dir = base_dir / "memory"
+
+    for d in (plugins_dir, scripts_dir, memory_dir):
+        d.mkdir(parents=True, exist_ok=True)
+
+    # 1. Write instructions
+    instructions_path = base_dir / "instructions.md"
+    instructions_path.write_text(INSTRUCTIONS_MD)
+    print(f"Wrote {instructions_path}")
+
+    # 2. Write memory plugin
+    plugin_path = plugins_dir / "memory.ts"
+    plugin_path.write_text(_memory_plugin_ts(str(scripts_dir)))
+    print(f"Wrote {plugin_path}")
+
+    # 3. Write helper scripts
+    (scripts_dir / "save_learnings.py").write_text(_save_learnings_py(str(memory_dir)))
+    (scripts_dir / "log_session.py").write_text(_log_session_py(str(memory_dir)))
+    print(f"Wrote scripts to {scripts_dir}/")
+
+    # 4. Write .env template
+    env_path = Path.cwd() / ".env"
+    if env_path.exists():
+        print(f".env exists at {env_path} — skipping")
+    else:
+        env_path.write_text(DOT_ENV_TEMPLATE)
+        print(f"Created {env_path}")
+
+    # 5. Print opencode config
+    config_block = {
+        "instructions": [str(instructions_path)],
+        "mcp": {
+            "codecompass": {
+                "type": "local",
+                "command": ["codecompass-mcp"]
+            }
+        },
+        "plugin": [str(plugin_path)]
+    }
+
+    opencode_config = Path.home() / ".config" / "opencode" / "opencode.json"
+    print()
+    if opencode_config.exists():
+        print(f"Merge this into {opencode_config}:")
+    else:
+        print(f"Add this to {opencode_config}:")
+    print()
+    print(json.dumps(config_block, indent=2))
+    print()
+    print("Restart opencode. Then: opencode")
+    print('Ask "what ingested projects are available?" — it should use list_projects.')

ingestion/chunker.py

@@ -0,0 +1,70 @@
+import re
+import PyPDF2
+
+# Rough approximation: 1 token ≈ 4 characters (standard for English prose/code).
+# Used when a tokeniser library is unavailable.
+_CHARS_PER_TOKEN = 4
+
+
+def _estimate_tokens(text: str) -> int:
+    return max(1, len(text) // _CHARS_PER_TOKEN)
+
+
+def chunk_pdf(filepath: str, tokens_per_chunk: int = 500, overlap_tokens: int = 50) -> list[str]:
+    """Split PDF into overlapping token-sized chunks."""
+    with open(filepath, "rb") as f:
+        reader = PyPDF2.PdfReader(f)
+        full_text = " ".join(page.extract_text() or "" for page in reader.pages)
+    return chunk_text(full_text, tokens_per_chunk=tokens_per_chunk, overlap_tokens=overlap_tokens)
+
+
+def chunk_text(text: str, tokens_per_chunk: int = 500, overlap_tokens: int = 50) -> list[str]:
+    """
+    Split text into chunks of approximately `tokens_per_chunk` tokens with
+    `overlap_tokens` of overlap between consecutive chunks.
+
+    Splitting prefers sentence boundaries so that a chunk never cuts mid-sentence.
+    Falls back to hard character splitting when no boundary is found.
+    """
+    chunk_chars = tokens_per_chunk * _CHARS_PER_TOKEN
+    overlap_chars = overlap_tokens * _CHARS_PER_TOKEN
+
+    # Normalise whitespace but preserve paragraph breaks as sentence boundaries.
+    text = re.sub(r"\r\n|\r", "\n", text)
+    text = re.sub(r"[ \t]+", " ", text).strip()
+
+    if not text:
+        return []
+
+    chunks: list[str] = []
+    start = 0
+    step = chunk_chars - overlap_chars
+
+    while start < len(text):
+        end = start + chunk_chars
+        segment = text[start:end]
+
+        # If this isn't the last chunk, trim to the last sentence boundary.
+        if end < len(text):
+            # Look for a sentence-ending punctuation followed by whitespace/newline.
+            boundary = _last_sentence_boundary(segment)
+            if boundary and boundary > chunk_chars // 2:
+                segment = segment[:boundary]
+
+        chunk = segment.strip()
+        if chunk:
+            chunks.append(chunk)
+
+        # Advance by the length of the actual segment taken (minus overlap).
+        advance = max(len(segment) - overlap_chars, step)
+        start += advance
+
+    return chunks
+
+
+def _last_sentence_boundary(text: str) -> int | None:
+    """Return the index just after the last sentence-ending boundary in `text`."""
+    # Match '. ', '! ', '? ', or end of a paragraph ('\n\n').
+    for match in reversed(list(re.finditer(r"(?<=[.!?])\s+|(?<=\n)\n", text))):
+        return match.end()
+    return None