m5-engine 1.0.0__py3-none-any.whl

m5_engine-1.0.0.dist-info/METADATA

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: m5-engine
+Version: 1.0.0
+Summary: Intelligent, zero-overhead AST code context and dependency graph engine for AI coding agents,saving LLM token costs.
+Author-email: Aman <lazyserp@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/m5-context-engine/m5
+Project-URL: Documentation, https://github.com/m5-context-engine/m5#readme
+Project-URL: Repository, https://github.com/m5-context-engine/m5.git
+Project-URL: Issues, https://github.com/m5-context-engine/m5/issues
+Keywords: mcp,model-context-protocol,ast,code-graph,developer-tools,ai-agents,cursor,claude-code,copilot
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: tree-sitter>=0.20.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: enterprise
+Requires-Dist: fastapi>=0.100.0; extra == "enterprise"
+Requires-Dist: uvicorn>=0.22.0; extra == "enterprise"
+Requires-Dist: qdrant-client>=1.6.0; extra == "enterprise"
+Requires-Dist: fastembed>=0.2.0; extra == "enterprise"
+
+# M5 — AST Code Knowledge Graph for AI Coding Agents
+
+When AI agents work on your codebase, they spend most of their time (and your tokens) doing clumsy discovery: grepping files one by one, wandering through directory listings, and trying to reconstruct call hierarchies in their head.
+
+**M5 fixes that.** It parses your codebase with Tree-sitter into an embedded, zero-overhead SQLite knowledge graph (`.m5/local_graph.db`). When your agent asks a question, M5 returns the exact code, upstream callers, downstream dependencies, and blast radius in **one single call**.
+
+- **100% Local**: No Docker, no heavy background daemons, no cloud dependency.
+- **Sub-50ms Incremental Sync**: Watches your files and updates only what changed when you save.
+- **Zero-Friction MCP Integration**: Works with Claude Code, Cursor, VS Code / Copilot, Gemini CLI, Antigravity, and Codex.
+- **Interactive Browser UI**: Visualize your architecture and dependency chains at `http://127.0.0.1:5555`.
+
+---
+
+## 🚀 Quickstart
+
+### 1. Install M5
+Install globally using `pip` or `pipx`:
+
+```bash
+pip install m5-context
+# or with pipx:
+pipx install m5-context
+```
+
+### 2. Connect Your AI Agent
+Run the interactive setup wizard to get clean, copy-pasteable MCP config snippets for your editor:
+
+```bash
+m5 setup
+```
+*(Or specify your tool directly: `m5 setup claude`, `m5 setup cursor`, `m5 setup vscode`)*
+
+Paste the provided JSON block into your editor's MCP configuration. We don't silently rewrite your system files behind your back — you stay in full control.
+
+### 3. Build Your Project Index
+Navigate to any project repository and build the graph:
+
+```bash
+cd your-project
+m5 build
+```
+
+This scans your workspace and indexes all AST symbols and call edges into `.m5/local_graph.db` in under a second.
+
+### 4. Keep It Fresh While You Code
+Start the background watcher:
+
+```bash
+m5 live
+```
+
+Whenever you or your AI agent edits a file, M5 catches the change and updates the graph in $<50\text{ms}$.
+
+---
+
+## 🔍 CLI Commands
+
+| Command | What it does | Example |
+|---|---|---|
+| `m5 setup` | Interactive manual setup wizard with exact MCP configs for your IDE | `m5 setup` or `m5 setup cursor` |
+| `m5 build` | Scans workspace and builds AST knowledge graph into `.m5/` | `m5 build` |
+| `m5 live` | Starts real-time file watcher (<50ms incremental sync on save) | `m5 live` |
+| `m5 stats` | Shows index summary (files, AST symbols, call edges, DB size) | `m5 stats` |
+| `m5 trace` | 1-shot surgical context: verbatim code + call flow + blast radius | `m5 trace "auth middleware token validation"` |
+| `m5 peek` | View symbol definition & callers, or view line-numbered file | `m5 peek UserService` or `m5 peek src/auth.py` |
+| `m5 find` | Search AST symbols by name, type, or pattern (FTS5 + B-tree) | `m5 find parse_jwt` |
+| `m5 callers` | Find all functions and files calling a symbol | `m5 callers handle_request` |
+| `m5 callees` | Find all functions called by a symbol | `m5 callees handle_request` |
+| `m5 blast` | Multi-hop blast radius & affected files analysis before refactoring | `m5 blast DatabasePool --depth 2` |
+| `m5 diff-tests` | Find test suites affected by modified files | `git diff --name-only \| m5 diff-tests --stdin` |
+| `m5 view` | Open local browser visualizer at `http://127.0.0.1:5555` | `m5 view` |
+| `m5 serve` | Start the MCP server over stdio (invoked by IDEs) | `m5 serve` |
+| `m5 purge` | Cleanly remove `.m5/` index from project | `m5 purge` |
+| `m5 scan` | Force full re-index of the repository | `m5 scan` |
+| `m5 dump` | Export index bundle for CI / team sharing | `m5 dump` |
+| `m5 pull` | Pull pre-computed team index from CI cache | `m5 pull https://ci.company.com/index.tar.gz` |
+
+---
+
+## 🖥️ Visual Graph Browser (`m5 view`)
+
+Want to see what your AI agent sees? Run:
+
+```bash
+m5 view
+```
+
+Opens a fast, dark-mode browser interface at `http://127.0.0.1:5555`:
+- **Search & Filter**: Find any function, method, or class across your repo with instant fuzzy search.
+- **Live Code Inspection**: Read exact symbol bodies with line numbers and AST metadata.
+- **Dependency Panels**: See direct callers, outgoing calls, and affected files on the side.
+- **Zero External Server**: Powered by Python's built-in HTTP server, so it starts instantly without npm or heavy node packages.
+
+---
+
+## 🤖 Agent Instructions (CLAUDE.md / AGENTS.md / GEMINI.md)
+
+To help subagents and command-line agents make the most of M5, paste this snippet into your project's `CLAUDE.md`, `AGENTS.md`, or `GEMINI.md`:
+
+```markdown
+<!-- M5 CONTEXT ENGINE START -->
+## M5 Code Context & AST Knowledge Graph
+This project uses M5 for instant AST code intelligence and dependency navigation.
+Instead of repeatedly reading entire files or running multiple grep commands:
+- Run `m5 trace "<query>"` to retrieve relevant symbol definitions, call hierarchies, and blast radius in 1 step.
+- Run `m5 peek <symbol>` to view the exact implementation and callers of any function or class.
+- Run `m5 callers <symbol>` or `m5 callees <symbol>` to navigate the call graph.
+- Run `m5 diff-tests` to see tests affected by modified files.
+<!-- M5 CONTEXT ENGINE END -->
+```
+
+---
+
+## 🌐 Supported Languages
+
+M5 extracts full AST symbol trees and resolves cross-file call edges across:
+
+- **Web & Backend**: Python, TypeScript, JavaScript, Go, Rust, Java, C++, C, C#, Ruby, PHP
+- **Mobile & Modern**: Swift, Kotlin, Dart, Scala
+
+---
+
+## 📄 License
+
+MIT License. Free and open source for developers and teams.

m5_engine-1.0.0.dist-info/RECORD

@@ -0,0 +1,36 @@
+src/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/auth.py,sha256=59katXRH3FsQjAoJj1QGPGCWbhClORjAXkwah1NL1hU,7391
+src/config.py,sha256=pkNCk9yGk42B87Sl0VivLjHJYYNuCkzWfM8FYuMFTV0,844
+src/logger.py,sha256=ewwBOhp3qhM6Y150-DA49iJXri4wPJxixYs9jdTv_WA,2268
+src/main.py,sha256=-R8KagNARKMhcMDRv8UVJQhVibZwob3ip5UdEmHLbJk,2751
+src/mcp_server.py,sha256=2dfPEBUjXOmbCZ08jJWsJcNhjB2zgF_q7PJtGrpHOOI,25322
+src/server.py,sha256=Wjfyfd55mIYvU7BiVmz0VHWu7rSwDaJEg4lhO4-ywgg,18985
+src/api/webhooks.py,sha256=gHAs80QE_l15Wr59lVa9lo4hIbzg4k-_HkBGtYcq7v0,4744
+src/audit/__init__.py,sha256=_1QPreoiNS9ujffQPZ9ULeWWODiDWRADIagdnCnKsfY,124
+src/audit/telemetry.py,sha256=isMuDqhtaRl-KsSwNpVk5lNkQSNDbP3p9VB_Hpfs0ZM,11848
+src/cli/__init__.py,sha256=qAnfxWT0K1-tfjTLbW30yg-gDQsScywzJrqpmg1ku7M,17
+src/cli/installer.py,sha256=laP3lwCRhoaQzr8yDJlWWPon3jgAAIZSiR76-XjA3w0,214
+src/cli/main.py,sha256=EmYKGOVdpidoFP-eBrJ9RZ7zSv6X4l0mkM-b79T40N0,18181
+src/cli/setup_guide.py,sha256=qDjSNMULtAUO-rrtb7n9ufMix92w6y0IF8qA57DvHUk,10090
+src/cli/sync.py,sha256=AVKzguzkD2prC5nSuZgDOCjt76Qed3WKgGnqkcAVSow,2970
+src/cli/visual_server.py,sha256=D2eY8tkfRZOs_MGn-iFr68rfkpZHCt1NXO4cSEJ0QBE,22076
+src/context/__init__.py,sha256=tOA1t3gOpel__Zzx172B3T92oByUceCQo-lo7M-lylA,18
+src/context/context_engine.py,sha256=-KHCkRHjumC8sEZ2AhAA7N9knrdWT53v9zxrYT9z_ns,16314
+src/indexer/file_watcher.py,sha256=jk9RDTwI47rAq_b6oXUV7s2ailuS9MM5HB2O4rXet1w,4179
+src/indexer/git_manager.py,sha256=C3R3zjK782dFobDUVEd07po6zZBxhbagtuq41Mj7lcQ,4065
+src/indexer/progressive_indexer.py,sha256=x647jHKrkQ-2SZanliBAnafZb6LPgFcX-dwq7xOYqIY,12670
+src/parser/ast_parser.py,sha256=nbIlHjHotuM0AmKDZbh7FNfX16Ptw5jSCkeYA8ks8a0,9957
+src/parser/customizations.py,sha256=wtiiMvljfszz93iVHW-XivANYc2fpv4qrGnct1mnt5k,5119
+src/storage/local_db.py,sha256=03shCoXKJ15Cxy7Q8tpT-ROSZ4rlkuHvLBH_5nJo72w,14725
+src/tools/__init__.py,sha256=81Vc7PrVgekkmz_HoxztxSQ09CG4lf-MSkyQW31twOM,293
+src/tools/dependency_graph.py,sha256=g1yqtt3wNvE0t7Qzjaw955OdZ4iuB6dPHfNWgRa3_BU,16081
+src/tools/hybrid_search.py,sha256=xo0nfvS8kFOq9SWnZdVITYTl-_5G7biFZPTzs84Y9-A,13526
+src/tools/line_reader.py,sha256=_57gVr9plXXMQKAUD6s_kVoR5okF4huynNzivBp_WU4,2903
+src/tools/multi_repo_graph.py,sha256=IiH24FN3k04uZPrWz7dtDbcZuCi6QuMvl-rY-0hhwzA,3127
+src/tools/test_impact.py,sha256=d2867fnJKPMGorXXrB1LSJQtGOLkwWYXA1IQhSgvBEo,3447
+src/tools/vector_search.py,sha256=u9W0n3q4py4FyIdizxXoazor7SvAIEgmCFfmJDRGYS8,11544
+m5_engine-1.0.0.dist-info/METADATA,sha256=oEIn4QbR_414_KXx1UANTEFORzXrvETSkW1mL5nfMyg,7182
+m5_engine-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+m5_engine-1.0.0.dist-info/entry_points.txt,sha256=bvv5MNM9dt6GoNZmdXXc5Di10f821Lm6Kz2fg4q6sls,51
+m5_engine-1.0.0.dist-info/top_level.txt,sha256=74rtVfumQlgAPzR5_2CgYN24MB0XARCg0t-gzk6gTrM,4
+m5_engine-1.0.0.dist-info/RECORD,,

m5_engine-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

m5_engine-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+m5 = src.cli.main:cli_entrypoint

m5_engine-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+src

src/api/webhooks.py

@@ -0,0 +1,124 @@
+import os
+import hmac
+import hashlib
+from typing import Dict, Any, List
+from fastapi import APIRouter, Request, Header, HTTPException, BackgroundTasks, status
+from pydantic import BaseModel, Field
+from src.logger import setup_m5_logger
+from src.indexer.progressive_indexer import progressive_indexer
+
+logger = setup_m5_logger("m5.webhook")
+webhook_router = APIRouter(prefix="/api/webhooks", tags=["Webhooks"])
+WEBHOOK_SECRET = os.getenv("GITHUB_WEBHOOK_SECRET", "")
+
+class WebhookSyncResponse(BaseModel):
+    status: str
+    event: str
+    repository: str
+    commits_processed: int
+    message: str
+
+def verify_github_signature(payload_bytes: bytes, signature_header: str | None) -> bool:
+    """
+    Verifies HMAC SHA-256 signature from GitHub.
+
+    Fail-closed design:
+    - If GITHUB_WEBHOOK_SECRET is set (production):  signature MUST be valid.
+    - If GITHUB_WEBHOOK_SECRET is NOT set:
+        - Dev override M5_ALLOW_UNSIGNED_WEBHOOKS=true → allow (development only).
+        - Otherwise → REJECT. Prevents silent security hole on misconfigured deployments.
+    """
+    import os as _os
+    if not WEBHOOK_SECRET:
+        allow_unsigned = _os.getenv("M5_ALLOW_UNSIGNED_WEBHOOKS", "false").lower() == "true"
+        if allow_unsigned:
+            logger.warning(
+                "Accepting unsigned webhook (M5_ALLOW_UNSIGNED_WEBHOOKS=true). "
+                "Never use this in production."
+            )
+            return True
+        logger.error(
+            "Webhook rejected: GITHUB_WEBHOOK_SECRET is not configured. "
+            "Set it in .env or use M5_ALLOW_UNSIGNED_WEBHOOKS=true for local dev only."
+        )
+        return False
+    if not signature_header or not signature_header.startswith("sha256="):
+        return False
+    
+    expected_sig = signature_header.split("sha256=")[1]
+    computed_sig = hmac.new(
+        WEBHOOK_SECRET.encode("utf-8"),
+        payload_bytes,
+        hashlib.sha256
+    ).hexdigest()
+    return hmac.compare_digest(expected_sig, computed_sig)
+
+@webhook_router.post("/github", status_code=status.HTTP_202_ACCEPTED, response_model=WebhookSyncResponse)
+async def github_webhook_endpoint(
+    request: Request,
+    background_tasks: BackgroundTasks,
+    x_github_event: str = Header(default="push"),
+    x_hub_signature_256: str | None = Header(default=None)
+):
+    payload_bytes = await request.body()
+
+    # 1. Verify Webhook Signature
+    if not verify_github_signature(payload_bytes, x_hub_signature_256):
+        logger.error("GitHub Webhook rejected: Invalid HMAC SHA-256 signature")
+        raise HTTPException(status_code=403, detail="Invalid HMAC webhook signature.")
+
+    # 2. Ignore non-push events (e.g. ping, star)
+    if x_github_event != "push":
+        logger.info(f"Received GitHub webhook event '{x_github_event}' (ignored)")
+        return WebhookSyncResponse(
+            status="ignored",
+            event=x_github_event,
+            repository="unknown",
+            commits_processed=0,
+            message=f"Event '{x_github_event}' does not require codebase delta re-indexing."
+        )
+
+    payload = await request.json()
+    repo_data = payload.get("repository", {})
+    repo_name = repo_data.get("name", "default_repo")
+    org_name = repo_data.get("owner", {}).get("name") or repo_data.get("owner", {}).get("login") or "default_org"
+
+    # 3. Extract Added, Modified, and Removed Files from commits
+    added_files: List[str] = []
+    modified_files: List[str] = []
+    removed_files: List[str] = []
+
+    for commit in payload.get("commits", []):
+        added_files.extend(commit.get("added", []))
+        modified_files.extend(commit.get("modified", []))
+        removed_files.extend(commit.get("removed", []))
+
+    added_clean = list(set(added_files))
+    modified_clean = list(set(modified_files))
+    removed_clean = list(set(removed_files))
+
+    logger.info(
+        f"GitHub Push Webhook received for '{org_name}/{repo_name}': "
+        f"{len(added_clean)} added, {len(modified_clean)} modified, {len(removed_clean)} removed files. Queueing delta sync..."
+    )
+
+    # 4. Offload Delta Synchronization to Background Task
+    background_tasks.add_task(
+        progressive_indexer.process_git_delta,
+        added=added_clean,
+        modified=modified_clean,
+        removed=removed_clean,
+        workspace_root=".",
+        org_id=org_name,
+        dept_id="engineering",
+        repo_id=repo_name
+    )
+
+    return WebhookSyncResponse(
+        status="accepted",
+        event=x_github_event,
+        repository=f"{org_name}/{repo_name}",
+        commits_processed=len(payload.get("commits", [])),
+        message=f"Queued delta sync for {len(added_clean)} added, {len(modified_clean)} modified, and {len(removed_clean)} removed files."
+    )
+

src/audit/__init__.py

@@ -0,0 +1,3 @@
+from .telemetry import log_retrieval_trace, get_telemetry_client
+
+__all__ = ["log_retrieval_trace", "get_telemetry_client"]

src/audit/telemetry.py

@@ -0,0 +1,338 @@
+"""
+telemetry.py — Langfuse AI Observability & Tracing for M5 v2
+
+Provides fail-safe, non-blocking telemetry for M5 context requests and MCP tool executions.
+Adheres to Langfuse best practices:
+- Observation Types (retriever, tool, generation, span)
+- User Attribution (identifies developer/client name)
+- Usage & Token Details (input, output, total tokens tracked via generation observations)
+- Attribute Propagation (user_id, session_id, tags, metadata)
+- Automated Flushing
+- Fail-Safe: Graceful no-op when credentials are absent or network is unreachable.
+"""
+
+import os
+import time
+import logging
+from typing import Optional, Dict, Any, List
+
+logger = logging.getLogger("m5.telemetry")
+
+_LANGFUSE_CLIENT = None
+_INITIALIZED = False
+
+
+def _clean_env_val(val: Optional[str]) -> str:
+    if not val:
+        return ""
+    return val.strip().strip("\"'")
+
+
+def get_telemetry_client():
+    """Initializes and returns the singleton Langfuse client if configured."""
+    global _LANGFUSE_CLIENT, _INITIALIZED
+
+    if _INITIALIZED:
+        return _LANGFUSE_CLIENT
+
+    _INITIALIZED = True
+
+    try:
+        from dotenv import load_dotenv
+        load_dotenv(override=False)
+    except Exception:
+        pass
+
+    public_key = _clean_env_val(os.getenv("LANGFUSE_PUBLIC_KEY"))
+    secret_key = _clean_env_val(os.getenv("LANGFUSE_SECRET_KEY"))
+    host = _clean_env_val(os.getenv("LANGFUSE_BASE_URL") or os.getenv("LANGFUSE_HOST") or "https://cloud.langfuse.com")
+
+    if not public_key or not secret_key:
+        logger.debug("Langfuse telemetry credentials not set. Tracing is disabled.")
+        return None
+
+    # Set host environment variable for consistency
+    os.environ["LANGFUSE_HOST"] = host
+    os.environ["LANGFUSE_BASE_URL"] = host
+
+    try:
+        from langfuse import Langfuse
+        _LANGFUSE_CLIENT = Langfuse(
+            public_key=public_key,
+            secret_key=secret_key,
+            host=host
+        )
+        logger.info(f"Langfuse telemetry connected (Host: {host})")
+    except Exception as e:
+        logger.warning(f"Langfuse telemetry disabled: {e}")
+        _LANGFUSE_CLIENT = None
+
+    return _LANGFUSE_CLIENT
+
+
+def flush_telemetry() -> None:
+    """Flushes any buffered events to Langfuse."""
+    client = get_telemetry_client()
+    if client is not None:
+        try:
+            client.flush()
+        except Exception as e:
+            logger.debug(f"Telemetry flush error: {e}")
+
+
+def _resolve_user_id(requesting_user: Optional[str], caller_identity: Optional[str]) -> str:
+    """Resolves human/system user identifier for Langfuse attribution."""
+    if requesting_user and requesting_user.strip() and requesting_user.strip() not in ("unknown", "mcp/client"):
+        return requesting_user.strip()
+    if caller_identity and caller_identity.strip() and caller_identity.strip() not in ("unknown", "mcp/client"):
+        return caller_identity.strip()
+    system_user = os.getenv("USERNAME") or os.getenv("USER") or "developer"
+    return system_user
+
+
+def log_retrieval_trace(
+    query: str,
+    org_id: str,
+    dept_id: str,
+    repo_id: str,
+    requesting_user: Optional[str],
+    caller_identity: Optional[str],
+    top_k: int,
+    expand_dependencies: bool,
+    duration_ms: float,
+    result_bundle: Optional[Dict[str, Any]] = None,
+    error: Optional[str] = None,
+    transport: str = "mcp"
+) -> None:
+    """
+    Logs a flagship context retrieval event to Langfuse with user attribution and token usage.
+    Fail-safe: never raises exceptions or blocks execution.
+    """
+    client = get_telemetry_client()
+    if client is None:
+        return
+
+    try:
+        from langfuse import propagate_attributes
+
+        user_identifier = _resolve_user_id(requesting_user, caller_identity)
+        session_identifier = f"{org_id}:{dept_id}:{repo_id}"
+        chunks: List[Dict[str, Any]] = (result_bundle or {}).get("chunks", [])
+        dep_edges: List[Dict[str, Any]] = (result_bundle or {}).get("dependency_edges", [])
+        related_tests: List[str] = (result_bundle or {}).get("related_tests", [])
+        citations = [
+            f"{c.get('file_path')}:{c.get('start_line')}-{c.get('end_line')} ({c.get('symbol_name')})"
+            for c in chunks
+        ]
+        estimated_tokens = (result_bundle or {}).get("estimated_tokens", 0)
+        request_id = (result_bundle or {}).get("request_id")
+
+        # Estimate input, output, and total token usage for dashboard analytics
+        input_tokens = max(1, len(str(query)) // 4)
+        output_tokens = max(1, estimated_tokens or (sum(len(c.get("content", "")) for c in chunks) // 4))
+        total_tokens = input_tokens + output_tokens
+        usage_details = {
+            "input": input_tokens,
+            "output": output_tokens,
+            "total": total_tokens
+        }
+
+        tags = [
+            f"org:{org_id}",
+            f"repo:{repo_id}",
+            f"transport:{transport}",
+            f"user:{user_identifier}",
+            "tool:m5_get_context"
+        ]
+
+        metadata = {
+            "org_id": org_id,
+            "dept_id": dept_id,
+            "repo_id": repo_id,
+            "user_id": user_identifier,
+            "caller_identity": caller_identity or "unknown",
+            "duration_ms": duration_ms,
+            "chunks_count": len(chunks),
+            "dependency_edges_count": len(dep_edges),
+            "related_tests_count": len(related_tests),
+            "total_tokens": total_tokens,
+            "truncated": (result_bundle or {}).get("truncated", False),
+        }
+        if request_id:
+            metadata["request_id"] = request_id
+
+        input_payload = {
+            "query": query,
+            "top_k": top_k,
+            "expand_dependencies": expand_dependencies
+        }
+
+        output_payload = {
+            "total_chunks": len(chunks),
+            "estimated_tokens": total_tokens,
+            "citations": citations[:15],
+            "related_tests": related_tests,
+            "omissions": (result_bundle or {}).get("omissions", []),
+            "warnings": (result_bundle or {}).get("warnings", []),
+            "error": error
+        }
+
+        with propagate_attributes(
+            user_id=user_identifier,
+            session_id=session_identifier,
+            tags=tags,
+            metadata=metadata
+        ):
+            with client.start_as_current_observation(
+                name="m5_get_context",
+                as_type="retriever",
+                input=input_payload,
+                output=output_payload
+            ) as root_obs:
+                # Generation observation to populate token counts and cost dashboards in Langfuse
+                with client.start_as_current_observation(
+                    name="context_retrieval_usage",
+                    as_type="generation",
+                    model="m5-context-engine",
+                    input={"query": query},
+                    output={"chunks_retrieved": len(chunks), "citations": citations[:5]},
+                    usage_details=usage_details
+                ):
+                    pass
+
+                # Sub-observation: Hybrid Search
+                if chunks:
+                    top_chunk = chunks[0]
+                    with client.start_as_current_observation(
+                        name="hybrid_search",
+                        as_type="retriever",
+                        input={"query": query, "top_k": top_k},
+                        output={
+                            "top_symbol": top_chunk.get("symbol_name"),
+                            "top_file": top_chunk.get("file_path"),
+                            "top_score": top_chunk.get("relevance_score"),
+                            "match_type": top_chunk.get("match_type"),
+                            "confidence": top_chunk.get("confidence")
+                        }
+                    ):
+                        pass
+
+                # Sub-observation: Dependency Expansion
+                if dep_edges:
+                    with client.start_as_current_observation(
+                        name="expand_dependencies",
+                        as_type="tool",
+                        input={"expand_dependencies": expand_dependencies},
+                        output={"edges_count": len(dep_edges), "edges": dep_edges[:10]}
+                    ):
+                        pass
+
+                # Sub-observation: Companion Test Discovery
+                if related_tests:
+                    with client.start_as_current_observation(
+                        name="companion_test_discovery",
+                        as_type="tool",
+                        input={"targets": [c.get("file_path") for c in chunks[:5]]},
+                        output={"companion_tests": related_tests}
+                    ):
+                        pass
+
+        flush_telemetry()
+
+    except Exception as ex:
+        logger.debug(f"Non-critical telemetry retrieval logging error: {ex}")
+
+
+def log_mcp_tool_trace(
+    tool_name: str,
+    args: Dict[str, Any],
+    output: Any,
+    duration_ms: float,
+    caller_identity: Optional[str] = None,
+    org_id: str = "default_org",
+    dept_id: str = "default_dept",
+    repo_id: str = "default_repo",
+    transport: str = "mcp_stdio",
+    error: Optional[str] = None
+) -> None:
+    """
+    Logs any MCP tool call to Langfuse with user attribution and token usage.
+    """
+    client = get_telemetry_client()
+    if client is None:
+        return
+
+    # m5_get_context is already traced in detail by log_retrieval_trace
+    if tool_name == "m5_get_context":
+        return
+
+    try:
+        from langfuse import propagate_attributes
+
+        user_identifier = _resolve_user_id(None, caller_identity)
+        session_identifier = f"{org_id}:{dept_id}:{repo_id}"
+
+        as_type = "tool"
+        if tool_name in ("m5_search_code", "m5_find_symbol_references"):
+            as_type = "retriever"
+
+        # Estimate tokens for the tool call
+        input_tokens = max(1, len(str(args)) // 4)
+        output_tokens = max(1, len(str(output)) // 4)
+        total_tokens = input_tokens + output_tokens
+        usage_details = {
+            "input": input_tokens,
+            "output": output_tokens,
+            "total": total_tokens
+        }
+
+        tags = [
+            f"org:{org_id}",
+            f"repo:{repo_id}",
+            f"transport:{transport}",
+            f"user:{user_identifier}",
+            f"tool:{tool_name}"
+        ]
+
+        metadata = {
+            "org_id": org_id,
+            "dept_id": dept_id,
+            "repo_id": repo_id,
+            "user_id": user_identifier,
+            "caller_identity": caller_identity or "unknown",
+            "duration_ms": duration_ms,
+            "total_tokens": total_tokens,
+            "error": error
+        }
+
+        # Sanitize output representation for readable trace view
+        out_summary = output
+        if isinstance(output, str) and len(output) > 2000:
+            out_summary = output[:2000] + "\n... [truncated for display]"
+
+        with propagate_attributes(
+            user_id=user_identifier,
+            session_id=session_identifier,
+            tags=tags,
+            metadata=metadata
+        ):
+            with client.start_as_current_observation(
+                name=tool_name,
+                as_type=as_type,
+                input=args,
+                output={"result": out_summary, "error": error}
+            ):
+                with client.start_as_current_observation(
+                    name=f"{tool_name}_usage",
+                    as_type="generation",
+                    model="m5-context-engine",
+                    input=args,
+                    output={"result": "completed"},
+                    usage_details=usage_details
+                ):
+                    pass
+
+        flush_telemetry()
+
+    except Exception as ex:
+        logger.debug(f"Non-critical MCP tool telemetry error: {ex}")