Ki|4 UdZddlmZddlZddlZddlmZddlmZddl m Z m Z m Z m Z mZddlmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZm Z m!Z!m"Z"m#Z#m$Z$m%Z%m&Z&m'Z'm(Z(m)Z)m*Z*m+Z+m,Z,m-Z-da.d e/d <d4d Z0ed d Z1e1je d5 d6dZ3e1je d7 d8dZ4e1je d9 d:dZ5e1je d; ddZ7e1je d? d@dZ8e1je dA dBdZ9e1je dC dDdZ:e1je dE dFdZ;e1je dGdZe1je dL dMdZ?e1je dN dOdZ@e1je dP dQdZAe1je dL dRdZBe1je dE dFdZCe1je dS dTd ZDe1je dU dVd!ZEe1je dW dXd"ZFe1je dW dYd#ZGe1je dE dZd$ZHe1je d[ d\d%ZIe1je d[ d\d&ZJe1je dE dFd'ZKe1je d] d\d(ZLe1je dE dFd)ZMe1je d^ d_d*ZNe1jed`d+ZOe1je da dbd,ZPe1jdcddd-ZRe1jded.ZSe1jdfdgd/ZTe1jded0ZUe1jdcddd1ZVdEdhd2ZWeXd3k(reWyy)izMCP server entry point for Code Review Graph. Run as: code-review-graph serve Communicates via stdio (standard MCP transport). ) annotationsN)Optional)FastMCP)architecture_map_promptdebug_issue_promptonboard_developer_promptpre_merge_check_promptreview_changes_prompt)apply_refactor_funcbuild_or_update_graphcross_repo_search_funcdetect_changes_func embed_graphfind_large_functionsgenerate_wiki_funcget_affected_flows_funcget_architecture_overview_funcget_bridge_nodes_funcget_community_funcget_docs_sectionget_flowget_hub_nodes_funcget_impact_radiusget_knowledge_gaps_funcget_minimal_contextget_review_contextget_suggested_questions_funcget_surprising_connections_funcget_wiki_page_functraverse_graph_funclist_communities_func list_flowslist_graph_statslist_repos_func query_graph refactor_funcrun_postprocesssemantic_search_nodes str | None_default_repo_rootc|r|StS)uResolve repo_root for a tool call. Order of precedence: 1. Explicit ``repo_root`` passed by the MCP client (highest). 2. ``--repo`` CLI flag passed to ``code-review-graph serve`` (captured in ``_default_repo_root``). 3. None — the underlying impl will fall back to the server's cwd. Previously, only ``get_docs_section_tool`` consulted ``_default_repo_root``, so ``serve --repo `` had no effect for the other 21 tools. See: #222 follow-up. )r+ repo_roots b/home/jay/workspace/scripts/.codegraph-venv/lib/python3.12/site-packages/code_review_graph/main.py_resolve_repo_rootr0<s"99'99zcode-review-graphzPersistent incremental knowledge graph for token-efficient, context-aware code reviews. Parses your codebase with Tree-sitter, builds a structural graph, and provides smart impact analysis.) instructionscnKtjt|t||||d{S7w)aBuild or incrementally update the code knowledge graph. Call this first to initialize the graph, or after making changes. By default performs an incremental update (only changed files). Set full_rebuild=True to re-parse every file. Runs the blocking full_build / incremental_update work in a thread via ``asyncio.to_thread`` so the stdio event loop stays responsive. Without this wrapper, long builds deadlocked on Windows because ``ProcessPoolExecutor`` (used by parallel parsing) interacted badly with the sync handler blocking the only event-loop thread. See: #46, #136. Args: full_rebuild: If True, re-parse all files. Default: False (incremental). repo_root: Repository root path. Auto-detected from current directory if omitted. base: Git ref to diff against for incremental updates. Default: HEAD~1. postprocess: Post-processing level: "full" (default), "minimal" (signatures+FTS only), or "none" (skip all post-processing). Use "minimal" for faster builds. recurse_submodules: If True, include files from git submodules. When None (default), falls back to CRG_RECURSE_SUBMODULES env var.  full_rebuildr.base postprocessrecurse_submodulesN)asyncio to_threadr r0r4s r/build_or_update_graph_toolr;Vs<<""!$Y/ -   s ,535c lKtjt|||t|d{S7w)a[Run post-processing on existing graph (flows, communities, FTS index). Use after building with postprocess="none" or "minimal", or to re-run expensive steps independently. Signatures are always computed. Offloaded to a thread via ``asyncio.to_thread`` so community detection on large graphs doesn't block the MCP event loop. See: #46, #136. Args: flows: Run flow detection. Default: True. communities: Run community detection. Default: True. fts: Rebuild FTS index. Default: True. repo_root: Repository root path. Auto-detected if omitted. flows communitiesftsr.N)r9r:r(r0r=s r/run_postprocess_toolrA~s7,""#$Y/  s +424c2t||t||S)aJGet ultra-compact context for any task (~100 tokens). Always call this first. Returns graph stats, risk score, top communities/flows, and suggested next tools in a single compact response. Use this as the entry point before any other graph tool to minimize token usage. Args: task: What you are doing (e.g. "review PR #42", "debug login timeout"). changed_files: Explicit list of changed files. Auto-detected if omitted. repo_root: Repository root path. Auto-detected if omitted. base: Git ref for diff comparison. Default: HEAD~1. task changed_filesr.r6)rr0rCs r/get_minimal_context_toolrFs &  $Y/d r1c4t||t|||S)anAnalyze the blast radius of changed files in the codebase. Shows which functions, classes, and files are impacted by changes. Auto-detects changed files from git if not specified. Args: changed_files: List of changed file paths (relative to repo root). Auto-detected if omitted. max_depth: Number of hops to traverse in the dependency graph. Default: 2. repo_root: Repository root path. Auto-detected if omitted. base: Git ref for auto-detecting changes. Default: HEAD~1. detail_level: "standard" for full output, "minimal" for compact summary. Default: standard. rE max_depthr.r6 detail_level)rr0rHs r/get_impact_radius_toolrKs"( #y$Y/d r1c2t||t||S)aRun a predefined graph query to explore code relationships. Available patterns: - callers_of: Find functions that call the target - callees_of: Find functions called by the target - imports_of: Find what the target imports - importers_of: Find files that import the target - children_of: Find nodes contained in a file or class - tests_for: Find tests for the target - inheritors_of: Find classes inheriting from the target - file_summary: Get all nodes in a file Args: pattern: Query pattern name (see above). target: Node name, qualified name, or file path to query. repo_root: Repository root path. Auto-detected if omitted. detail_level: "standard" for full output, "minimal" for compact summary. Default: standard. patterntargetr.rJ)r&r0rMs r/query_graph_toolrPs!2 2DY2O! r1c 8t||||t|||S)aGenerate a focused, token-efficient review context for code changes. Combines impact analysis with source snippets and review guidance. Use this for comprehensive code reviews. Args: changed_files: Files to review. Auto-detected from git diff if omitted. max_depth: Impact radius depth. Default: 2. include_source: Include source code snippets. Default: True. max_lines_per_file: Max source lines per file. Default: 200. repo_root: Repository root path. Auto-detected if omitted. base: Git ref for change detection. Default: HEAD~1. detail_level: "standard" for full output, "minimal" for token-efficient summary. Default: standard. rErIinclude_sourcemax_lines_per_filer.r6rJ)rr0rRs r/get_review_context_toolrUs(2 #y%:L$Y/d r1c6t|||t|||S)aSearch for code entities by name, keyword, or semantic similarity. Uses vector embeddings for semantic search when available (run embed_graph_tool first, requires sentence-transformers). Falls back to keyword matching otherwise. Args: query: Search string to match against node names. kind: Optional filter: File, Class, Function, Type, or Test. limit: Maximum results. Default: 20. repo_root: Repository root path. Auto-detected if omitted. model: Embedding model for query vectors. Must match the model used during embed_graph. Falls back to CRG_EMBEDDING_MODEL env var, then all-MiniLM-L6-v2. detail_level: "standard" for full output, "minimal" for compact summary. Default: standard. querykindlimitr.modelrJ)r)r0rWs r/semantic_search_nodes_toolr\ s&0 !$e7I)7T\a! r1chKtjtt||d{S7w)uCompute vector embeddings for all graph nodes to enable semantic search. Requires: pip install code-review-graph[embeddings] Default model: all-MiniLM-L6-v2. Override via `model` param or CRG_EMBEDDING_MODEL env var (any sentence-transformers compatible model). Changing the model re-embeds all nodes automatically. After running this, semantic_search_nodes_tool will use vector similarity instead of keyword matching for much better results. Runs the blocking sentence-transformers / Gemini inference in a thread via ``asyncio.to_thread`` so the stdio event loop stays responsive — without this wrapper, embedding a large graph would silently hang the MCP server on Windows. See: #46, #136. Args: repo_root: Repository root path. Auto-detected if omitted. model: Embedding model name (HuggingFace ID or local path). Falls back to CRG_EMBEDDING_MODEL env var, then all-MiniLM-L6-v2. r.r[N)r9r:rr0r^s r/embed_graph_toolr_+s32""$Y/   )202c,tt|S)aGet aggregate statistics about the code knowledge graph. Shows total nodes, edges, languages, files, and last update time. Useful for checking if the graph is built and up to date. Args: repo_root: Repository root path. Auto-detected if omitted. r-)r$r0r-s r/list_graph_stats_toolrbKs &8&C DDr1c$t|tS)aGet a specific section from the LLM-optimized documentation reference. Returns only the requested section content for minimal token usage. Use this before answering any user question about the plugin. Available sections: usage, review-delta, review-pr, commands, legal, watch, embeddings, languages, troubleshooting. Args: section_name: The section to retrieve (e.g. "review-delta", "usage"). ) section_namer.)rr+)rds r/get_docs_section_toolreZs AS TTr1c 4t||||t|S)aFind functions, classes, or files exceeding a line-count threshold. Useful for decomposition audits, code quality checks, and enforcing size limits during code review. Results are ordered by line count. Args: min_lines: Minimum line count to flag. Default: 50. kind: Optional filter: Function, Class, File, or Test. file_path_pattern: Filter by file path substring (e.g. "components/"). limit: Maximum results. Default: 50. repo_root: Repository root path. Auto-detected if omitted.  min_linesrYfile_path_patternrZr.)rr0rgs r/find_large_functions_toolrjls$( $:K1)< r1c4tt|||||S)aList execution flows in the codebase, sorted by criticality. Each flow represents a call chain starting from an entry point (HTTP handler, CLI command, test function, etc.). Use this to understand the main execution paths through the codebase. Args: sort_by: Sort column: criticality, depth, node_count, file_count, or name. limit: Maximum flows to return. Default: 50. kind: Optional filter by entry point kind (e.g. "Test", "Function"). detail_level: "standard" (default) returns full flow data; "minimal" returns only name, criticality, and node_count per flow. repo_root: Repository root path. Auto-detected if omitted. )r.sort_byrZrYrJ)r#r0)rlrZrYrJr.s r/list_flows_toolrms#, $Y/TX! r1c2t|||t|S)a@Get detailed information about a single execution flow. Returns the full call path with each step's function name, file, and line numbers. Optionally includes source code snippets for each step. Provide either flow_id (from list_flows_tool) or flow_name to search by name. Args: flow_id: Database ID of the flow. flow_name: Name to search for (partial match). Ignored if flow_id given. include_source: Include source code snippets for each step. Default: False. repo_root: Repository root path. Auto-detected if omitted. flow_id flow_namerSr.)rr0ros r/ get_flow_toolrrs!( 9%1CI1N r1c0t||t|S)aFind execution flows affected by changed files. Identifies which execution flows pass through nodes in the changed files. Useful during code review to understand which user-facing or critical paths are impacted by a change. Auto-detects changed files from git if not specified. Args: changed_files: List of changed file paths (relative to repo root). Auto-detected if omitted. base: Git ref for auto-detecting changes. Default: HEAD~1. repo_root: Repository root path. Auto-detected if omitted. rEr6r.)rr0rts r/get_affected_flows_toolrus" ##$:LY:W r1c2tt||||S)aList detected code communities in the codebase. Each community represents a cluster of related code entities (functions, classes) detected via the Leiden algorithm or file-based grouping. Use this to understand the high-level structure of the codebase. Args: sort_by: Sort column: size, cohesion, or name. min_size: Minimum community size to include. Default: 0. detail_level: "standard" (default) returns full community data; "minimal" returns only name, size, and cohesion per community. repo_root: Repository root path. Auto-detected if omitted. )r.rlmin_sizerJ)r"r0)rlrwrJr.s r/list_communities_toolrxs * !$Y/8! r1c2t|||t|S)adGet detailed information about a single code community. Returns community metadata including size, cohesion, dominant language, and member list. Optionally includes full node details for each member. Provide either community_id (from list_communities_tool) or community_name to search by name. Args: community_name: Name to search for (partial match). Ignored if community_id given. community_id: Database ID of the community. include_members: Include full member node details. Default: False. repo_root: Repository root path. Auto-detected if omitted. community_name community_idinclude_membersr.)rr0rzs r/get_community_toolr~s!* %L'3Ei3P r1c,tt|S)aNGenerate an architecture overview based on community structure. Builds a high-level view of the codebase architecture by analyzing community boundaries and cross-community coupling. Includes warnings for high coupling between communities. Args: repo_root: Repository root path. Auto-detected if omitted. r-)rr0r-s r/get_architecture_overview_toolrs *4Fy4Q RRr1c pKtjt||||t||d{S7w)uDetect changes and produce risk-scored, priority-ordered review guidance. Primary tool for code review. Maps git diffs to affected functions, flows, communities, and test coverage gaps. Returns risk scores and prioritized review items. Replaces get_review_context for change-aware reviews. Offloaded to a thread via ``asyncio.to_thread`` — runs `git diff` subprocesses and BFS traversals that can take several seconds on large repos. See: #46, #136. Args: base: Git ref to diff against. Default: HEAD~1. changed_files: List of changed file paths (relative to repo root). Auto-detected if omitted. include_source: Include source code snippets for changed functions. Default: False. max_depth: Impact radius depth for BFS traversal. Default: 2. repo_root: Repository root path. Auto-detected if omitted. detail_level: "standard" for full output, "minimal" for token-efficient summary. Default: standard. r6rErSrIr.rJN)r9r:rr0rs r/detect_changes_toolrs<8"" %$Y/l   s -646c 6t|||||t|S)aGraph-powered refactoring operations. Unified entry point for rename previews, dead code detection, and refactoring suggestions. Modes: - rename: Preview renaming a symbol. Returns an edit list and a refactor_id to pass to apply_refactor_tool. Requires old_name and new_name. - dead_code: Find unreferenced functions/classes (no callers, tests, or importers, and not entry points). - suggest: Get community-driven refactoring suggestions (move misplaced functions, remove dead code). Args: mode: Operation mode: "rename", "dead_code", or "suggest". old_name: (rename) Current symbol name to rename. new_name: (rename) Desired new name for the symbol. kind: (dead_code) Optional filter: Function or Class. file_pattern: (dead_code) Filter by file path substring. repo_root: Repository root path. Auto-detected if omitted. modeold_namenew_namerY file_patternr.)r'r0rs r/ refactor_toolr<s%<  Hx  8J98U r1c0t|t||S)a[Apply a previously previewed refactoring to source files. Takes a refactor_id from a prior refactor_tool(mode="rename") call and applies the exact string replacements to the target files. Previews expire after 10 minutes. Security: All edit paths are validated to be within the repo root. Only exact string replacements are performed (no regex, no eval). Args: refactor_id: The refactor ID from refactor_tool's response. repo_root: Repository root path. Auto-detected if omitted. dry_run: If True, return a unified diff of what would change without touching any files. The refactor_id remains valid so the same preview can be applied in a follow-up call without dry_run. Use this for a human-in-the-loop review before committing changes to disk. See: #176  refactor_idr.dry_run)r r0rs r/apply_refactor_toolr`s0 +=i+H r1chKtjtt||d{S7w)uGenerate a markdown wiki from the code community structure. Creates a wiki page for each detected community and an index page. Pages are written to .code-review-graph/wiki/ inside the repository. Only regenerates pages whose content has changed unless force=True. Offloaded to a thread via ``asyncio.to_thread`` — on large graphs the page-generation loop touches every community and issues many SQLite reads, which would block the MCP event loop. See: #46, #136. Args: repo_root: Repository root path. Auto-detected if omitted. force: If True, regenerate all pages even if content unchanged. Default: False. r.forceN)r9r:rr0rs r/generate_wiki_toolr~s3&""$Y/  r`c.t|t|S)aFRetrieve a specific wiki page by community name. Returns the markdown content of the wiki page for the given community. The wiki must have been generated first via generate_wiki_tool. Args: community_name: Community name to look up. repo_root: Repository root path. Auto-detected if omitted. r{r.)r r0rs r/get_wiki_page_toolrs %1CI1N r1c.tt||S)a`Find the most connected nodes in the codebase (architectural hotspots). Hub nodes have the highest total degree (in + out edges). Changes to them have disproportionate blast radius. Excludes File nodes. Args: top_n: Number of top hubs to return. Default: 10. repo_root: Repository root path. Auto-detected if omitted. r.top_n)rr0rr.s r/get_hub_nodes_toolrs $Y/u r1c.tt||S)aFind architectural chokepoints via betweenness centrality. Bridge nodes sit on shortest paths between many node pairs. If they break, multiple code regions lose connectivity. Uses sampling approximation for graphs > 5000 nodes. Args: top_n: Number of top bridges to return. Default: 10. repo_root: Repository root path. Auto-detected if omitted. r)rr0rs r/get_bridge_nodes_toolrs !$Y/u r1c,tt|S)a4Identify structural weaknesses in the codebase graph. Finds isolated nodes (disconnected), thin communities (< 3 members), untested hotspots (high-degree nodes without test coverage), and single-file communities. Args: repo_root: Repository root path. Auto-detected if omitted. r-)rr0r-s r/get_knowledge_gaps_toolrs #$Y/ r1c.tt||S)a|Find unexpected architectural coupling via composite surprise scoring. Scores edges by: cross-community (+0.3), cross-language (+0.2), peripheral-to-hub (+0.2), cross-test-boundary (+0.15), and unusual edge kinds (+0.15). Args: top_n: Number of top surprises to return. Default: 15. repo_root: Repository root path. Auto-detected if omitted. r)rr0rs r/get_surprising_connections_toolrs +$Y/u r1c,tt|S)a7Auto-generate review questions from graph analysis. Produces prioritized questions about: bridge nodes needing tests, untested hub nodes, surprising cross-community coupling, thin communities, and untested hotspots. Args: repo_root: Repository root path. Auto-detected if omitted. r-)rr0r-s r/get_suggested_questions_toolrs ($Y/ r1c <t||||t|xsdS)a}BFS/DFS traversal from best-matching node with token budget. Free-form graph exploration: finds the node best matching your query, then traverses outward via BFS or DFS up to the given depth, collecting connected nodes within the token budget. Args: query: Search string to find the starting node. mode: Traversal mode: "bfs" (breadth-first) or "dfs" (depth-first). Default: bfs. depth: Max traversal depth (1-6). Default: 3. token_budget: Approximate token limit for results. Default: 2000. repo_root: Repository root path. Auto-detected if omitted. rXrdepth token_budgetr.)r!r0rs r/traverse_graph_toolr s(. $e!$Y/52 r1ctS)zList all registered repositories in the multi-repo registry. Returns the list of repos registered at ~/.code-review-graph/registry.json. Use the CLI 'register' command to add repos. )r%r1r/list_repos_toolr(s   r1ct|||S)aSearch for code entities across all registered repositories. Runs hybrid search on each registered repo's graph database and merges the results by score. Register repos first with the CLI 'register' command. Args: query: Search string to match against node names. kind: Optional filter: File, Class, Function, Type, or Test. limit: Maximum results per repo. Default: 20. rXrYrZ)rrs r/cross_repo_search_toolr2s "D FFr1ct|S)zPre-commit review workflow using detect_changes, affected_flows, and test gaps. Produces a structured code review with risk levels and actionable findings. Args: base: Git ref to diff against. Default: HEAD~1. r6)r rs r/review_changesrEs !d ++r1ctS)zArchitecture documentation using communities, flows, and Mermaid diagrams. Generates a comprehensive architecture map with module summaries and coupling warnings. )rrr1r/architecture_maprQs # $$r1ct|S)zGuided debugging using search, flow tracing, and recent changes. Systematic debugging workflow that traces execution paths and identifies root causes. Args: description: Description of the issue to debug.  description)rrs r/ debug_issuerZs + 66r1ctS)zNew developer orientation using stats, architecture, and critical flows. Creates an onboarding guide covering codebase structure, key modules, and patterns. )r rr1r/onboard_developerrfs $ %%r1ct|S)zPR readiness check with risk scoring, test gaps, and dead code detection. Produces a merge readiness report with risk assessment and recommendations. Args: base: Git ref to diff against. Default: HEAD~1. r)r rs r/pre_merge_checkros "t ,,r1c|atjdk(r%ddl}|j|j t jdy)uRun the MCP server via stdio. On Windows, Python 3.8+ defaults to ``ProactorEventLoop``, which interacts poorly with ``concurrent.futures.ProcessPoolExecutor`` (used by ``full_build``) over a stdio MCP transport — the combination produces silent hangs on ``build_or_update_graph_tool`` and ``embed_graph_tool``. Switching to ``WindowsSelectorEventLoopPolicy`` before fastmcp starts its loop avoids the deadlock. See: #46, #136 win32rNstdio) transport)r+sysplatformr9set_event_loop_policyWindowsSelectorEventLoopPolicymcprun)r.r9s r/mainr{sC# ||w%%%&Lg&L&L&NOGGgGr1__main__)r. Optional[str]returnr)FNHEAD~1fullN) r5boolr.rr6strr7rr8zOptional[bool]rdict)TTTN) r>rr?rr@rr.rrr)rNNr) rDrrEOptional[list[str]]r.rr6rrr)NNrstandard) rErrIintr.rr6rrJrrr)Nr) rNrrOrr.rrJrrr)NrTNrr)rErrIrrSrrTrr.rr6rrJrrr)NNNr)rXrrYrrZrr.rr[rrJrrr)NN)r.rr[rrr)N)r.rrr)rdrrr)2NNrN) rhrrYrrirrZrr.rrr) criticalityrNrN) rlrrZrrYrrJrr.rrr)NNFN) rp Optional[int]rqrrSrr.rrr)NrN)rErr6rr.rrr)sizerrN) rlrrwrrJrr.rrr) r{rr|rr}rr.rrr)rNFrNr)r6rrErrSrrIrr.rrJrrr)renameNNNNN)rrrrrrrYrrrr.rrr)NF)rrr.rrrrr)r.rrrrr)r{rr.rrr) N)rrr.rrr)N)bfsiN) rXrrrrrrrr.rrr)rr)Nr)rXrrYrrZrrr)r)r6rr list[dict])rr)r)rrrr)r.r*rNone)Y__doc__ __future__rr9rtypingrfastmcprpromptsrrr r r toolsr r rrrrrrrrrrrrrrrrrrr r!r"r#r$r%r&r'r(r)r+__annotations__r0rtoolr;rArFrKrPrUr\r_rbrerjrmrrrurxr~rrrrrrrrrrrrrrpromptrrrrrr__name__rr1r/rs  # F"&J% :  I#)- $$$ $ $ ' $  $ $N#       8)-#  &     0)-#" &       2 $"       <)-!#"&       >#"           :#   ># E E  E  EUU U U"'+#  %       2 "#          6!# #      2)-#&   *"#      4$("&!# !    4# S S  S  S)- #"   &           F"""&#               F $  :#   2 $  $#   $#   &#  "#   &#  "#          : G G G G G G$,,%%77&&--& zFr1