MCP ts-morph Refactoring Tools

Instructions

Implementation Reference

• src/mcp/tools/register-find-references-tool.ts:47-103 (handler)

  The tool handler function that extracts arguments, calls the findSymbolReferences helper, formats definition and references into a markdown-like text response, handles errors, and includes performance metrics.
  async (args) => { const startTime = performance.now(); let message = ""; let isError = false; let duration = "0.00"; // duration を外で宣言・初期化 try { const { tsconfigPath, targetFilePath, position } = args; const { references, definition } = await findSymbolReferences({ tsconfigPath: tsconfigPath, targetFilePath: targetFilePath, position, }); let resultText = ""; if (definition) { resultText += "Definition:\n"; resultText += `- ${definition.filePath}:${definition.line}:${definition.column}\n`; resultText += ` \`\`\`typescript\n ${definition.text}\n \`\`\`\n\n`; } else { resultText += "Definition not found.\n\n"; } if (references.length > 0) { resultText += `References (${references.length} found):\n`; const formattedReferences = references .map( (ref) => `- ${ref.filePath}:${ref.line}:${ref.column}\n \`\`\`typescript\n ${ref.text}\n \`\`\`\``, ) .join("\n\n"); resultText += formattedReferences; } else { resultText += "References not found."; } message = resultText.trim(); } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); message = `Error during reference search: ${errorMessage}`; isError = true; } finally { const endTime = performance.now(); duration = ((endTime - startTime) / 1000).toFixed(2); // duration を更新 } // finally の外で return する const finalMessage = `${message}\nStatus: ${ isError ? "Failure" : "Success" }\nProcessing time: ${duration} seconds`; return { content: [{ type: "text", text: finalMessage }], isError: isError, }; },
• src/ts-morph/find-references.ts:19-95 (helper)

  Main helper function that uses ts-morph to find the identifier at the given position, retrieve its references and definition, extract locations and line texts, deduplicate definition from references, and sort references.
  export async function findSymbolReferences({ tsconfigPath, targetFilePath, position, }: { tsconfigPath: string; targetFilePath: string; position: { line: number; column: number }; }): Promise<{ references: ReferenceLocation[]; definition: ReferenceLocation | null; }> { const project = initializeProject(tsconfigPath); // targetFilePath は絶対パスである想定 const identifierNode = findIdentifierNode(project, targetFilePath, position); // findReferencesAsNodes() は定義箇所を含まない場合がある const referenceNodes: Node[] = identifierNode.findReferencesAsNodes(); let definitionLocation: ReferenceLocation | null = null; const definitions = identifierNode.getDefinitionNodes(); if (definitions.length > 0) { const defNode = definitions[0]; const defSourceFile = defNode.getSourceFile(); const defStartPos = defNode.getStart(); const { line: defLine, column: defColumn } = defSourceFile.getLineAndColumnAtPos(defStartPos); const lineText = getLineText(defSourceFile, defLine); definitionLocation = { filePath: defSourceFile.getFilePath(), line: defLine, column: defColumn, text: lineText.trim(), }; } const references: ReferenceLocation[] = []; for (const refNode of referenceNodes) { const refSourceFile = refNode.getSourceFile(); const refStartPos = refNode.getStart(); const { line: refLine, column: refColumn } = refSourceFile.getLineAndColumnAtPos(refStartPos); if ( definitionLocation && refLine !== undefined && refColumn !== undefined && refSourceFile.getFilePath() === definitionLocation.filePath && refLine === definitionLocation.line && refColumn === definitionLocation.column ) { continue; // 定義箇所と同じであればスキップ } if (refLine === undefined || refColumn === undefined) continue; const filePath = refSourceFile.getFilePath(); const lineText = getLineText(refSourceFile, refLine); references.push({ filePath, line: refLine, column: refColumn, text: lineText.trim(), }); } references.sort((a, b) => { if (a.filePath !== b.filePath) { return a.filePath.localeCompare(b.filePath); } return a.line - b.line; }); return { references, definition: definitionLocation }; }
• src/mcp/tools/register-find-references-tool.ts:33-46 (schema)

  Input schema for the tool parameters using Zod: tsconfigPath, targetFilePath, and position object with line and column.
  { tsconfigPath: z .string() .describe("Absolute path to the project's tsconfig.json file."), targetFilePath: z .string() .describe("Absolute path to the file containing the symbol."), position: z .object({ line: z.number().describe("1-based line number."), column: z.number().describe("1-based column number."), }) .describe("The exact position of the symbol."), },
• src/mcp/tools/register-find-references-tool.ts:6-105 (registration)

  Registration function that calls server.tool to register 'find_references_by_tsmorph' with its description, input schema, and handler function.
  export function registerFindReferencesTool(server: McpServer): void { server.tool( "find_references_by_tsmorph", `[Uses ts-morph] Finds the definition and all references to a symbol at a given position throughout the project. Analyzes the project based on \`tsconfig.json\` to locate the definition and all usages of the symbol (function, variable, class, etc.) specified by its position. ## Usage Use this tool before refactoring to understand the impact of changing a specific symbol. It helps identify where a function is called, where a variable is used, etc. 1. Specify the **absolute path** to the project's \`tsconfig.json\`. 2. Specify the **absolute path** to the file containing the symbol you want to investigate. 3. Specify the exact **position** (line and column) of the symbol within the file. ## Parameters - tsconfigPath (string, required): Absolute path to the project's root \`tsconfig.json\` file. Essential for ts-morph to parse the project. **Must be an absolute path.** - targetFilePath (string, required): The absolute path to the file containing the symbol to find references for. **Must be an absolute path.** - position (object, required): The exact position of the symbol to find references for. - line (number, required): 1-based line number. - column (number, required): 1-based column number. ## Result - On success: Returns a message containing the definition location (if found) and a list of reference locations (file path, line number, column number, and line text). - On failure: Returns a message indicating the error.`, { tsconfigPath: z .string() .describe("Absolute path to the project's tsconfig.json file."), targetFilePath: z .string() .describe("Absolute path to the file containing the symbol."), position: z .object({ line: z.number().describe("1-based line number."), column: z.number().describe("1-based column number."), }) .describe("The exact position of the symbol."), }, async (args) => { const startTime = performance.now(); let message = ""; let isError = false; let duration = "0.00"; // duration を外で宣言・初期化 try { const { tsconfigPath, targetFilePath, position } = args; const { references, definition } = await findSymbolReferences({ tsconfigPath: tsconfigPath, targetFilePath: targetFilePath, position, }); let resultText = ""; if (definition) { resultText += "Definition:\n"; resultText += `- ${definition.filePath}:${definition.line}:${definition.column}\n`; resultText += ` \`\`\`typescript\n ${definition.text}\n \`\`\`\n\n`; } else { resultText += "Definition not found.\n\n"; } if (references.length > 0) { resultText += `References (${references.length} found):\n`; const formattedReferences = references .map( (ref) => `- ${ref.filePath}:${ref.line}:${ref.column}\n \`\`\`typescript\n ${ref.text}\n \`\`\`\``, ) .join("\n\n"); resultText += formattedReferences; } else { resultText += "References not found."; } message = resultText.trim(); } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); message = `Error during reference search: ${errorMessage}`; isError = true; } finally { const endTime = performance.now(); duration = ((endTime - startTime) / 1000).toFixed(2); // duration を更新 } // finally の外で return する const finalMessage = `${message}\nStatus: ${ isError ? "Failure" : "Success" }\nProcessing time: ${duration} seconds`; return { content: [{ type: "text", text: finalMessage }], isError: isError, }; }, ); }
• src/ts-morph/find-references.ts:7-12 (schema)

  TypeScript interface defining the structure of reference and definition locations returned by findSymbolReferences.
  export interface ReferenceLocation { filePath: string; line: number; column: number; text: string; }