gitnexus 1.4.0 → 1.4.1

package/dist/mcp/tools.js

@@ -7,15 +7,19 @@
 export const GITNEXUS_TOOLS = [
     {
         name: 'list_repos',
-        description: `List all indexed repositories available to GitNexus.
-
-Returns each repo's name, path, indexed date, last commit, and stats.
-
-WHEN TO USE: First step when multiple repos are indexed, or to discover available repos.
-AFTER THIS: READ gitnexus://repo/{name}/context for the repo you want to work with.
-
-When multiple repos are indexed, you MUST specify the "repo" parameter
-on other tools (query, context, impact, etc.) to target the correct one.`,
+        description: `List all indexed repositories available to GitNexus.
+
+Returns each repo's name, branch, indexed date, last commit, and stats.
+
+WHEN TO USE: First step when multiple repos are indexed, or to discover available repos.
+AFTER THIS: READ gitnexus://repo/{name}/context for the repo you want to work with.
+
+When multiple repos are indexed, you MUST specify the "repo" parameter
+on other tools (query, context, impact, etc.) to target the correct one.
+
+BRANCH HANDLING: The same repo can be indexed on different branches. Non-default
+branches appear as "owner/repo@branch" in the list. Use that exact name as the
+"repo" parameter in other tools to target the correct branch's graph.`,
         inputSchema: {
             type: 'object',
             properties: {},
@@ -24,17 +28,17 @@ on other tools (query, context, impact, etc.) to target the correct one.`,
     },
     {
         name: 'query',
-        description: `Query the code knowledge graph for execution flows related to a concept.
-Returns processes (call chains) ranked by relevance, each with its symbols and file locations.
-
-WHEN TO USE: Understanding how code works together. Use this when you need execution flows and relationships, not just file matches. Complements grep/IDE search.
-AFTER THIS: Use context() on a specific symbol for 360-degree view (callers, callees, categorized refs).
-
-Returns results grouped by process (execution flow):
-- processes: ranked execution flows with relevance priority
-- process_symbols: all symbols in those flows with file locations and module (functional area)
-- definitions: standalone types/interfaces not in any process
-
+        description: `Query the code knowledge graph for execution flows related to a concept.
+Returns processes (call chains) ranked by relevance, each with its symbols and file locations.
+
+WHEN TO USE: Understanding how code works together. Use this when you need execution flows and relationships, not just file matches. Complements grep/IDE search.
+AFTER THIS: Use context() on a specific symbol for 360-degree view (callers, callees, categorized refs).
+
+Returns results grouped by process (execution flow):
+- processes: ranked execution flows with relevance priority
+- process_symbols: all symbols in those flows with file locations and module (functional area)
+- definitions: standalone types/interfaces not in any process
+
 Hybrid ranking: BM25 keyword + semantic vector search, ranked by Reciprocal Rank Fusion.`,
         inputSchema: {
             type: 'object',
@@ -45,68 +49,59 @@ Hybrid ranking: BM25 keyword + semantic vector search, ranked by Reciprocal Rank
                 limit: { type: 'number', description: 'Max processes to return (default: 5)', default: 5 },
                 max_symbols: { type: 'number', description: 'Max symbols per process (default: 10)', default: 10 },
                 include_content: { type: 'boolean', description: 'Include full symbol source code (default: false)', default: false },
-                repo: { type: 'string', description: 'Repository name or path. Omit if only one repo is indexed.' },
+                repo: { type: 'string', description: 'Repository name (e.g. "owner/repo"). For repos indexed on a specific branch, append @branch (e.g. "owner/repo@develop"). Omit if only one repo is indexed. Use list_repos to see available repos.' },
             },
             required: ['query'],
         },
     },
     {
         name: 'cypher',
-        description: `Execute Cypher query against the code knowledge graph.
-
-WHEN TO USE: Complex structural queries that search/explore can't answer. READ gitnexus://repo/{name}/schema first for the full schema.
-AFTER THIS: Use context() on result symbols for deeper context.
-
-SCHEMA:
-- Nodes: File, Folder, Function, Class, Interface, Method, CodeElement, Community, Process
-- Multi-language nodes (use backticks): \`Struct\`, \`Enum\`, \`Trait\`, \`Impl\`, etc.
-- All edges via single CodeRelation table with 'type' property
-- Edge types: CONTAINS, DEFINES, CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, OVERRIDES, MEMBER_OF, STEP_IN_PROCESS
-- Edge properties: type (STRING), confidence (DOUBLE), reason (STRING), step (INT32)
-
-EXAMPLES:
-• Find callers of a function:
-  MATCH (a)-[:CodeRelation {type: 'CALLS'}]->(b:Function {name: "validateUser"}) RETURN a.name, a.filePath
-
-• Find community members:
-  MATCH (f)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community) WHERE c.heuristicLabel = "Auth" RETURN f.name
-
-• Trace a process:
-  MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process) WHERE p.heuristicLabel = "UserLogin" RETURN s.name, r.step ORDER BY r.step
-
-• Find all methods of a class:
-  MATCH (c:Class {name: "UserService"})-[r:CodeRelation {type: 'HAS_METHOD'}]->(m:Method) RETURN m.name, m.parameterCount, m.returnType
-
-• Find method overrides (MRO resolution):
-  MATCH (winner:Method)-[r:CodeRelation {type: 'OVERRIDES'}]->(loser:Method) RETURN winner.name, winner.filePath, loser.filePath, r.reason
-
-• Detect diamond inheritance:
-  MATCH (d:Class)-[:CodeRelation {type: 'EXTENDS'}]->(b1), (d)-[:CodeRelation {type: 'EXTENDS'}]->(b2), (b1)-[:CodeRelation {type: 'EXTENDS'}]->(a), (b2)-[:CodeRelation {type: 'EXTENDS'}]->(a) WHERE b1 <> b2 RETURN d.name, b1.name, b2.name, a.name
-
-OUTPUT: Returns { markdown, row_count } — results formatted as a Markdown table for easy reading.
-
-TIPS:
-- All relationships use single CodeRelation table — filter with {type: 'CALLS'} etc.
-- Community = auto-detected functional area (Leiden algorithm)
-- Process = execution flow trace from entry point to terminal
+        description: `Execute Cypher query against the code knowledge graph.
+
+WHEN TO USE: Complex structural queries that search/explore can't answer. READ gitnexus://repo/{name}/schema first for the full schema.
+AFTER THIS: Use context() on result symbols for deeper context.
+
+SCHEMA:
+- Nodes: File, Folder, Function, Class, Interface, Method, CodeElement, Community, Process
+- Multi-language nodes (use backticks): \`Struct\`, \`Enum\`, \`Trait\`, \`Impl\`, etc.
+- All edges via single CodeRelation table with 'type' property
+- Edge types: CONTAINS, DEFINES, CALLS, IMPORTS, EXTENDS, IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS
+- Edge properties: type (STRING), confidence (DOUBLE), reason (STRING), step (INT32)
+
+EXAMPLES:
+• Find callers of a function:
+  MATCH (a)-[:CodeRelation {type: 'CALLS'}]->(b:Function {name: "validateUser"}) RETURN a.name, a.filePath
+
+• Find community members:
+  MATCH (f)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community) WHERE c.heuristicLabel = "Auth" RETURN f.name
+
+• Trace a process:
+  MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process) WHERE p.heuristicLabel = "UserLogin" RETURN s.name, r.step ORDER BY r.step
+
+OUTPUT: Returns { markdown, row_count } — results formatted as a Markdown table for easy reading.
+
+TIPS:
+- All relationships use single CodeRelation table — filter with {type: 'CALLS'} etc.
+- Community = auto-detected functional area (Leiden algorithm)
+- Process = execution flow trace from entry point to terminal
 - Use heuristicLabel (not label) for human-readable community/process names`,
         inputSchema: {
             type: 'object',
             properties: {
                 query: { type: 'string', description: 'Cypher query to execute' },
-                repo: { type: 'string', description: 'Repository name or path. Omit if only one repo is indexed.' },
+                repo: { type: 'string', description: 'Repository name (e.g. "owner/repo"). For repos indexed on a specific branch, append @branch (e.g. "owner/repo@develop"). Omit if only one repo is indexed. Use list_repos to see available repos.' },
             },
             required: ['query'],
         },
     },
     {
         name: 'context',
-        description: `360-degree view of a single code symbol.
-Shows categorized incoming/outgoing references (calls, imports, extends, implements), process participation, and file location.
-
-WHEN TO USE: After query() to understand a specific symbol in depth. When you need to know all callers, callees, and what execution flows a symbol participates in.
-AFTER THIS: Use impact() if planning changes, or READ gitnexus://repo/{name}/process/{processName} for full execution trace.
-
+        description: `360-degree view of a single code symbol.
+Shows categorized incoming/outgoing references (calls, imports, extends, implements), process participation, and file location.
+
+WHEN TO USE: After query() to understand a specific symbol in depth. When you need to know all callers, callees, and what execution flows a symbol participates in.
+AFTER THIS: Use impact() if planning changes, or READ gitnexus://repo/{name}/process/{processName} for full execution trace.
+
 Handles disambiguation: if multiple symbols share the same name, returns candidates for you to pick from. Use uid param for zero-ambiguity lookup from prior results.`,
         inputSchema: {
             type: 'object',
@@ -115,40 +110,46 @@ Handles disambiguation: if multiple symbols share the same name, returns candida
                 uid: { type: 'string', description: 'Direct symbol UID from prior tool results (zero-ambiguity lookup)' },
                 file_path: { type: 'string', description: 'File path to disambiguate common names' },
                 include_content: { type: 'boolean', description: 'Include full symbol source code (default: false)', default: false },
-                repo: { type: 'string', description: 'Repository name or path. Omit if only one repo is indexed.' },
+                repo: { type: 'string', description: 'Repository name (e.g. "owner/repo"). For repos indexed on a specific branch, append @branch (e.g. "owner/repo@develop"). Omit if only one repo is indexed. Use list_repos to see available repos.' },
             },
             required: [],
         },
     },
     {
         name: 'detect_changes',
-        description: `Analyze uncommitted git changes and find affected execution flows.
-Maps git diff hunks to indexed symbols, then traces which processes are impacted.
-
-WHEN TO USE: Before committing — to understand what your changes affect. Pre-commit review, PR preparation.
-AFTER THIS: Review affected processes. Use context() on high-risk symbols. READ gitnexus://repo/{name}/process/{name} for full traces.
-
+        description: `Analyze code changes and find affected execution flows.
+Maps changed files to indexed symbols, then traces which processes are impacted.
+
+WHEN TO USE: Before committing — to understand what your changes affect. Pre-commit review, PR preparation.
+AFTER THIS: Review affected processes. Use context() on high-risk symbols. READ gitnexus://repo/{name}/process/{name} for full traces.
+
+FOR HUB USERS: The Hub server has no local git checkout. You MUST provide the changed_files
+parameter by running git diff locally first and passing the file list. Example:
+  1. Run \`git diff --name-only\` (or \`git diff HEAD --name-only\` for all changes)
+  2. Pass the resulting file paths as the changed_files array
+
 Returns: changed symbols, affected processes, and a risk summary.`,
         inputSchema: {
             type: 'object',
             properties: {
                 scope: { type: 'string', description: 'What to analyze: "unstaged" (default), "staged", "all", or "compare"', enum: ['unstaged', 'staged', 'all', 'compare'], default: 'unstaged' },
                 base_ref: { type: 'string', description: 'Branch/commit for "compare" scope (e.g., "main")' },
-                repo: { type: 'string', description: 'Repository name or path. Omit if only one repo is indexed.' },
+                changed_files: { type: 'array', items: { type: 'string' }, description: 'Pre-computed list of changed file paths (from local git diff). Required for Hub MCP — the server has no git checkout. The local MCP server ignores this and runs git diff itself.' },
+                repo: { type: 'string', description: 'Repository name (e.g. "owner/repo"). For repos indexed on a specific branch, append @branch (e.g. "owner/repo@develop"). Omit if only one repo is indexed. Use list_repos to see available repos.' },
             },
             required: [],
         },
     },
     {
         name: 'rename',
-        description: `Multi-file coordinated rename using the knowledge graph + text search.
-Finds all references via graph (high confidence) and regex text search (lower confidence). Preview by default.
-
-WHEN TO USE: Renaming a function, class, method, or variable across the codebase. Safer than find-and-replace.
-AFTER THIS: Run detect_changes() to verify no unexpected side effects.
-
-Each edit is tagged with confidence:
-- "graph": found via knowledge graph relationships (high confidence, safe to accept)
+        description: `Multi-file coordinated rename using the knowledge graph + text search.
+Finds all references via graph (high confidence) and regex text search (lower confidence). Preview by default.
+
+WHEN TO USE: Renaming a function, class, method, or variable across the codebase. Safer than find-and-replace.
+AFTER THIS: Run detect_changes() to verify no unexpected side effects.
+
+Each edit is tagged with confidence:
+- "graph": found via knowledge graph relationships (high confidence, safe to accept)
 - "text_search": found via regex text search (lower confidence, review carefully)`,
         inputSchema: {
             type: 'object',
@@ -158,32 +159,32 @@ Each edit is tagged with confidence:
                 new_name: { type: 'string', description: 'The new name for the symbol' },
                 file_path: { type: 'string', description: 'File path to disambiguate common names' },
                 dry_run: { type: 'boolean', description: 'Preview edits without modifying files (default: true)', default: true },
-                repo: { type: 'string', description: 'Repository name or path. Omit if only one repo is indexed.' },
+                repo: { type: 'string', description: 'Repository name (e.g. "owner/repo"). For repos indexed on a specific branch, append @branch (e.g. "owner/repo@develop"). Omit if only one repo is indexed. Use list_repos to see available repos.' },
             },
             required: ['new_name'],
         },
     },
     {
         name: 'impact',
-        description: `Analyze the blast radius of changing a code symbol.
-Returns affected symbols grouped by depth, plus risk assessment, affected execution flows, and affected modules.
-
-WHEN TO USE: Before making code changes — especially refactoring, renaming, or modifying shared code. Shows what would break.
-AFTER THIS: Review d=1 items (WILL BREAK). Use context() on high-risk symbols.
-
-Output includes:
-- risk: LOW / MEDIUM / HIGH / CRITICAL
-- summary: direct callers, processes affected, modules affected
-- affected_processes: which execution flows break and at which step
-- affected_modules: which functional areas are hit (direct vs indirect)
-- byDepth: all affected symbols grouped by traversal depth
-
-Depth groups:
-- d=1: WILL BREAK (direct callers/importers)
-- d=2: LIKELY AFFECTED (indirect)
-- d=3: MAY NEED TESTING (transitive)
-
-EdgeType: CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, OVERRIDES
+        description: `Analyze the blast radius of changing a code symbol.
+Returns affected symbols grouped by depth, plus risk assessment, affected execution flows, and affected modules.
+
+WHEN TO USE: Before making code changes — especially refactoring, renaming, or modifying shared code. Shows what would break.
+AFTER THIS: Review d=1 items (WILL BREAK). Use context() on high-risk symbols.
+
+Output includes:
+- risk: LOW / MEDIUM / HIGH / CRITICAL
+- summary: direct callers, processes affected, modules affected
+- affected_processes: which execution flows break and at which step
+- affected_modules: which functional areas are hit (direct vs indirect)
+- byDepth: all affected symbols grouped by traversal depth
+
+Depth groups:
+- d=1: WILL BREAK (direct callers/importers)
+- d=2: LIKELY AFFECTED (indirect)
+- d=3: MAY NEED TESTING (transitive)
+
+EdgeType: CALLS, IMPORTS, EXTENDS, IMPLEMENTS
 Confidence: 1.0 = certain, <0.8 = fuzzy match`,
         inputSchema: {
             type: 'object',
@@ -191,10 +192,10 @@ Confidence: 1.0 = certain, <0.8 = fuzzy match`,
                 target: { type: 'string', description: 'Name of function, class, or file to analyze' },
                 direction: { type: 'string', description: 'upstream (what depends on this) or downstream (what this depends on)' },
                 maxDepth: { type: 'number', description: 'Max relationship depth (default: 3)', default: 3 },
-                relationTypes: { type: 'array', items: { type: 'string' }, description: 'Filter: CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, OVERRIDES (default: usage-based)' },
+                relationTypes: { type: 'array', items: { type: 'string' }, description: 'Filter: CALLS, IMPORTS, EXTENDS, IMPLEMENTS (default: usage-based)' },
                 includeTests: { type: 'boolean', description: 'Include test files (default: false)' },
                 minConfidence: { type: 'number', description: 'Minimum confidence 0-1 (default: 0.7)' },
-                repo: { type: 'string', description: 'Repository name or path. Omit if only one repo is indexed.' },
+                repo: { type: 'string', description: 'Repository name (e.g. "owner/repo"). For repos indexed on a specific branch, append @branch (e.g. "owner/repo@develop"). Omit if only one repo is indexed. Use list_repos to see available repos.' },
             },
             required: ['target', 'direction'],
         },