TypeScript MCP Server

Servidor MCP de TypeScript para refactorización impulsada por IA. Renombrar símbolos, extraer funciones, mover declaraciones, variables en línea, buscar referencias y corregir diagnósticos — estrictamente a través del tsserver nativo

GitHub

Prueba este MCPPatrocinado

Documentación

ts-mcp-server

Un servidor ligero de Model Context Protocol (MCP) para refactorización e inteligencia de código en TypeScript y JavaScript. Cada herramienta se asigna directamente a un comando de protocolo tsserver — la salida es la respuesta cruda y sin modificar del compilador de TypeScript. Renombra símbolos, extrae funciones, mueve declaraciones entre archivos, reorganiza importaciones, navega jerarquías de tipos, explora grafos de llamadas, busca símbolos en todo tu espacio de trabajo, ubica código generado por IA en las posiciones correctas, descubre qué códigos de error tienen correcciones automáticas, y más — con cada import, require, re-exportación y referencia actualizados automáticamente en todo tu código base.

Por qué

Los asistentes de codificación con IA pueden leer y escribir código, pero les cuestan los cambios estructurales que se propagan a través de muchos archivos. Renombrar una función, extraer un helper, mover un componente de React o reorganizar una carpeta implica actualizar cada referencia e importación que lo toque. Si te pierdes una, la compilación falla.

ts-mcp-server le da a cualquier cliente compatible con MCP — VS Code Copilot, Claude Desktop, Cursor, Windsurf, Continue, y otros — la capacidad de realizar estas refactorizaciones de forma correcta y completa, utilizando la propia infraestructura del compilador de TypeScript.

Características

40 herramientas — cada una es un mapeo 1:1 a un comando nativo del protocolo tsserver

Refactorización (14 herramientas)

Renombrar símbolos — variables, funciones, clases, tipos, propiedades, interfaces, enums — todas las referencias actualizadas en cada archivo
Renombrar / mover archivos y carpetas — todas las rutas de importación actualizadas automáticamente
Extraer función — extrae un rango de código en una nueva función con parámetros y tipo de retorno auto-detectados
Extraer constante — extrae una expresión en una constante nombrada con tipo inferido
Extraer tipo — extrae una anotación de tipo en línea en un alias de tipo nombrado
Inferir tipo de retorno — añade una anotación explícita de tipo de retorno a una función, inferida por TypeScript
Mover símbolo — mueve declaraciones de nivel superior a otro archivo, todas las importaciones reconectadas automáticamente
En línea variable — reemplaza todas las referencias con el inicializador de la variable y elimina la declaración
Organizar importaciones — ordena, combina y elimina importaciones no utilizadas
Formatear — formatea un rango de código según las reglas de formato de TypeScript
Obtener correcciones de código — recupera auto-correcciones disponibles para diagnósticos específicos (importaciones faltantes, desajustes de tipo, etc.)
Obtener corrección de código combinada — aplica una acción de corrección total para un código de error específico en un archivo
Obtener diagnósticos — recupera errores de tipo, advertencias y sugerencias para cualquier archivo
Encontrar todas las referencias — localiza cada uso de un símbolo en el proyecto
Mapear código — mapea fragmentos de código generados por IA en un archivo, reemplazando declaraciones coincidentes por nombre o añadiendo nuevas
Obtener correcciones de código soportadas — lista cada código de error que tiene una corrección automática disponible, opcionalmente limitado a un proyecto

Inteligencia de código (24 herramientas)

Información rápida — información completa de tipo, documentación y etiquetas JSDoc para cualquier símbolo (información al pasar el cursor)
Árbol de navegación — estructura jerárquica completa de un archivo (todas las declaraciones y su anidamiento)
Ir a definición — salta a donde se declara un símbolo
Definición y span delimitado — como definición, pero también devuelve el span de texto del símbolo consultado
Encontrar definición de fuente — navega al código fuente real de TypeScript en lugar de archivos de declaración .d.ts
Ir a definición de tipo — salta a la definición del tipo, no a la declaración de la variable
Ir a implementación — encuentra implementaciones concretas de una interfaz o clase abstracta
Navegar a símbolo — búsqueda de símbolos en todo el espacio de trabajo por nombre
Referencias de archivo — encuentra cada archivo que importa un archivo dado (grafo de dependencias inverso)
Preparar jerarquía de llamadas — obtiene el punto de entrada de la jerarquía de llamadas para una función/método
Llamadas entrantes — encuentra todos los llamadores de una función ("¿quién llama a esto?")
Llamadas salientes — encuentra todos los llamados de una función ("¿qué llama a esto?")
Información del proyecto — obtiene la ruta de tsconfig.json, la lista de archivos y el estado del servicio de lenguaje
Información de autocompletado — sugerencias de autocompletado en una posición
Detalles de entrada de autocompletado — documentación completa y firma de tipo para un elemento de autocompletado
Ayuda de firma — información de parámetros de función y sobrecargas en un sitio de llamada
Resaltados de documento — todas las apariciones de un símbolo dentro de un archivo, con distinción de lectura/escritura
Obtener refactorizaciones aplicables — descubre qué refactorizaciones están disponibles en una posición o selección
Rango de selección — obtiene rangos de selección semánticamente significativos para expandir/contraer selección inteligente
Sugerencias de refactorización al mover — obtiene archivos de destino sugeridos al mover un símbolo
Plantilla de comentario de documento — genera una plantilla de comentario JSDoc para una función/método
Spans de esquema — obtiene regiones plegables en un archivo
Sugerencias incrustadas — obtiene sugerencias incrustadas (nombres de parámetros, tipos inferidos) para un rango
Comentarios TODO — encuentra todos los comentarios TODO/FIXME/HACK en un archivo

Principios de diseño

Salida pura de tsserver — cada herramienta devuelve la respuesta cruda y sin modificar de tsserver como JSON
Modo de vista previa — ve exactamente qué cambiaría antes de aplicar cualquier cosa
Descubrimiento automático de proyectos — tsconfig.json se detecta automáticamente; no se necesita configuración
Soporte multi-proyecto — monorepos, referencias de proyecto y compilaciones compuestas funcionan de inmediato
Multiplataforma — Windows, macOS y Linux

Cómo funciona

Internamente, ts-mcp-server se comunica con el tsserver de TypeScript a través de Node IPC — el mismo protocolo que usa VS Code. Cada herramienta es un envoltorio delgado que:

Pasa tu entrada directamente a un comando de protocolo tsserver
Devuelve la respuesta cruda — sin formato, sin agrupación, sin filtrado

Herramientas de refactorización:

Herramienta	Comando(s) de tsserver
`rename`	`rename-full` → `renameLocations-full`
`renameFileOrDirectory`	`getEditsForFileRename-full`
`references`	`references`
`getDiagnostics`	`semanticDiagnosticsSync` + `suggestionDiagnosticsSync`
`organizeImports`	`organizeImports-full`
`getCodeFixes`	`getCodeFixes`
`extractFunction`	`getEditsForRefactor-full`
`extractConstant`	`getEditsForRefactor-full`
`extractType`	`getEditsForRefactor-full`
`inferReturnType`	`getEditsForRefactor-full`
`moveSymbol`	`getEditsForRefactor-full`
`inlineVariable`	`getEditsForRefactor-full`
`format`	`format`
`mapCode`	`mapCode`
`getSupportedCodeFixes`	`getSupportedCodeFixes`

Herramientas de inteligencia de código:

Herramienta	Comando de tsserver
`quickinfo`	`quickinfo`
`navtree`	`navtree`
`definition`	`definition`
`typeDefinition`	`typeDefinition`
`implementation`	`implementation`
`navto`	`navto`
`fileReferences`	`fileReferences`
`prepareCallHierarchy`	`prepareCallHierarchy`
`provideCallHierarchyIncomingCalls`	`provideCallHierarchyIncomingCalls`
`provideCallHierarchyOutgoingCalls`	`provideCallHierarchyOutgoingCalls`
`projectInfo`	`projectInfo`
`completionInfo`	`completionInfo`
`completionEntryDetails`	`completionEntryDetails`
`signatureHelp`	`signatureHelp`
`documentHighlights`	`documentHighlights`
`getApplicableRefactors`	`getApplicableRefactors`
`getCombinedCodeFix`	`getCombinedCodeFix`
`getOutliningSpans`	`getOutliningSpans`
`todoComments`	`todoComments`
`docCommentTemplate`	`docCommentTemplate`
`provideInlayHints`	`provideInlayHints`
`definitionAndBoundSpan`	`definitionAndBoundSpan`
`findSourceDefinition`	`findSourceDefinition`
`selectionRange`	`selectionRange`
`getMoveToRefactoringFileSuggestions`	`getMoveToRefactoringFileSuggestions`

No hay regex, ni resolución de rutas personalizada, ni heurísticas, ni formato de salida. El compilador de TypeScript hace todo el trabajo.

Inicio rápido

Instalación

npx ts-mcp-server

Configura tu cliente MCP

Añade ts-mcp-server a la configuración MCP de tu cliente.

VS Code (.vscode/mcp.json):

{
  "servers": {
    "ts-mcp-server": {
      "command": "npx",
      "args": ["ts-mcp-server"]
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "ts-mcp-server": {
      "command": "npx",
      "args": ["ts-mcp-server"]
    }
  }
}

Cursor, Windsurf, Continue — sigue la documentación del servidor MCP de cada cliente usando el mismo comando npx ts-mcp-server.

Deshabilitar herramientas individuales

Cada herramienta se puede deshabilitar individualmente estableciendo su nombre a "false" en el bloque env de tu configuración MCP. Las herramientas están habilitadas por defecto; solo las herramientas establecidas explícitamente a "false" se omiten al inicio.

VS Code (.vscode/mcp.json):

{
  "servers": {
    "ts-mcp-server": {
      "command": "npx",
      "args": ["ts-mcp-server"],
      "env": {
        "todoComments": "false",
        "getOutliningSpans": "false",
        "docCommentTemplate": "false"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "ts-mcp-server": {
      "command": "npx",
      "args": ["ts-mcp-server"],
      "env": {
        "todoComments": "false",
        "getOutliningSpans": "false",
        "docCommentTemplate": "false"
      }
    }
  }
}

El nombre de la herramienta en env debe coincidir exactamente con el nombre de la herramienta como se lista en la Referencia de herramientas a continuación (por ejemplo, "quickinfo", "getDiagnostics", "extractFunction"). Cualquier otro valor — incluido omitir la clave por completo — deja la herramienta habilitada.

Referencia de herramientas

`rename`

Renombra un símbolo de TypeScript/JavaScript y actualiza todas las referencias en el proyecto.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo que contiene el símbolo (absoluta o relativa al directorio de trabajo)
`line`	`number`	✅	Número de línea basado en 1 donde aparece el símbolo
`offset`	`number`	✅	Desplazamiento de carácter basado en 1 en la línea
`newName`	`string`	✅	Nuevo nombre para el símbolo
`preview`	`boolean`	✅	Si es `true`, devuelve los cambios sin aplicarlos

Ejemplos:

rename  file="src/utils/helpers.ts"  line=5  offset=17  newName="formatCurrency"
rename  file="src/components/Button.tsx"  line=10  offset=17  newName="PrimaryButton"
rename  file="src/types.ts"  line=3  offset=11  newName="UserProfile"
rename  file="src/utils/helpers.ts"  line=5  offset=17  newName="formatCurrency"  preview=true

`renameFileOrDirectory`

Renombra o mueve un archivo o directorio de TypeScript/JavaScript y actualiza todas las rutas de importación en el proyecto.

Parámetro	Tipo	Requerido	Descripción
`from`	`string`	✅	Ruta actual del archivo o directorio (absoluta o relativa al cwd)
`to`	`string`	✅	Nueva ruta del archivo o directorio (absoluta o relativa al cwd)
`preview`	`boolean`	✅	Si `true`, devolver los cambios sin aplicarlos

Ejemplos:

renameFileOrDirectory  from="src/utils/helpers.ts"  to="src/utils/string-helpers.ts"
renameFileOrDirectory  from="src/Button.tsx"  to="src/components/ui/Button.tsx"
renameFileOrDirectory  from="src/components/primitives"  to="src/components/ui"
renameFileOrDirectory  from="src/old-name.ts"  to="src/new-name.ts"  preview=true

`references`

Encuentra todos los usos de un símbolo en todo el proyecto.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa al cwd)
`line`	`number`	✅	Número de línea basado en 1 donde aparece el símbolo
`offset`	`number`	✅	Desplazamiento de carácter basado en 1 en la línea

Ejemplos:

references  file="src/utils/helpers.ts"  line=5  offset=17
references  file="src/types.ts"  line=3  offset=11

`getDiagnostics`

Obtén todos los errores, advertencias y sugerencias de un archivo. Devuelve diagnósticos semánticos y diagnósticos de sugerencias como matrices separadas.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa al cwd)

Ejemplos:

getDiagnostics  file="src/utils/helpers.ts"
getDiagnostics  file="src/components/Button.tsx"

Nota: Los diagnósticos de código no utilizado (variables no utilizadas, importaciones no utilizadas) solo aparecen si tu tsconfig.json tiene noUnusedLocals y/o noUnusedParameters habilitados.

`organizeImports`

Ordena, combina y elimina importaciones no utilizadas en un archivo.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa al cwd)
`preview`	`boolean`	✅	Si `true`, devolver los cambios sin aplicarlos

Ejemplos:

organizeImports  file="src/utils/helpers.ts"
organizeImports  file="src/components/Button.tsx"  preview=true

`getCodeFixes`

Obtén correcciones de código disponibles para códigos de error específicos en un rango de un archivo. Usa getDiagnostics primero para descubrir códigos de error y rangos, y luego pásalos aquí.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa al cwd)
`startLine`	`number`	✅	Línea de inicio basada en 1 del rango de diagnóstico
`startOffset`	`number`	✅	Desplazamiento de carácter de inicio basado en 1
`endLine`	`number`	✅	Línea de fin basada en 1 del rango de diagnóstico
`endOffset`	`number`	✅	Desplazamiento de carácter de fin basado en 1
`errorCodes`	`number[]`	✅	Códigos de error de diagnóstico para los que obtener correcciones

Ejemplos:

# Get fixes for a "Cannot find name" error (code 2304) at line 10
getCodeFixes  file="src/app.ts"  startLine=10  startOffset=1  endLine=10  endOffset=20  errorCodes=[2304]

# Get fixes for multiple error codes
getCodeFixes  file="src/app.ts"  startLine=5  startOffset=1  endLine=5  endOffset=30  errorCodes=[2304, 2552]

`getCombinedCodeFix`

Obtén una corrección de código combinada que aplica todas las instancias de una corrección en un archivo en una sola acción. Devuelve el conjunto completo de ediciones del archivo como respuesta CombinedCodeActions. Usa getCodeFixes primero para descubrir los valores fixId disponibles, y luego pasa el fixId aquí para obtener la corrección combinada para todo el archivo.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa al cwd)
`fixId`	`string`	✅	El fixId de una corrección de código (p. ej., `"fixMissingImport"`, `"unusedIdentifier"`, `"inferFromUsage"`)

Ejemplos:

# Get the combined "add all missing imports" fix for a file
getCombinedCodeFix  file="src/app.ts"  fixId="fixMissingImport"

# Get the combined "remove all unused variables" fix for a file
getCombinedCodeFix  file="src/app.ts"  fixId="unusedIdentifier"

`extractFunction`

Extrae un rango de código seleccionado en una nueva función. TypeScript detecta automáticamente los parámetros y el tipo de retorno. La respuesta incluye renameFilename / renameLocation para que puedas continuar con rename para darle a la función un nombre significativo.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa al cwd)
`startLine`	`number`	✅	Línea de inicio basada en 1 de la selección
`startOffset`	`number`	✅	Desplazamiento de carácter de inicio basado en 1
`endLine`	`number`	✅	Línea de fin basada en 1 de la selección
`endOffset`	`number`	✅	Desplazamiento de carácter de fin basado en 1
`preview`	`boolean`	✅	Si `true`, devolver los cambios sin aplicarlos

Ejemplos:

# Extract lines 10-15 into a function
extractFunction  file="src/app.ts"  startLine=10  startOffset=1  endLine=15  endOffset=1

# Preview the extraction
extractFunction  file="src/app.ts"  startLine=10  startOffset=1  endLine=15  endOffset=1  preview=true

`extractConstant`

Extrae una expresión seleccionada en una constante con nombre. TypeScript infiere el tipo. La respuesta incluye renameFilename / renameLocation para que puedas continuar con rename para darle a la constante un nombre significativo.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa al cwd)
`startLine`	`number`	✅	Línea de inicio basada en 1 de la expresión
`startOffset`	`number`	✅	Desplazamiento de carácter de inicio basado en 1
`endLine`	`number`	✅	Línea de fin basada en 1 de la expresión
`endOffset`	`number`	✅	Desplazamiento de carácter de fin basado en 1
`preview`	`boolean`	✅	Si `true`, devolver los cambios sin aplicarlos

Ejemplos:

# Extract an expression into a constant
extractConstant  file="src/app.ts"  startLine=8  startOffset=12  endLine=8  endOffset=35

# Preview the extraction
extractConstant  file="src/app.ts"  startLine=8  startOffset=12  endLine=8  endOffset=35  preview=true

`moveSymbol`

Mueve declaraciones de nivel superior (funciones, clases, tipos, constantes) a otro archivo. Todas las importaciones del proyecto se reconectan automáticamente. Si el archivo de destino no existe, tsserver lo crea.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo de origen (absoluta o relativa al cwd)
`startLine`	`number`	✅	Línea de inicio basada en 1 de la declaración
`startOffset`	`number`	✅	Desplazamiento de carácter de inicio basado en 1
`endLine`	`number`	✅	Línea de fin basada en 1 de la declaración
`endOffset`	`number`	✅	Desplazamiento de carácter de fin basado en 1
`targetFile`	`string`	✅	Ruta del archivo de destino (absoluta o relativa al cwd)
`preview`	`boolean`	✅	Si `true`, devolver los cambios sin aplicarlos

Ejemplos:

# Move a function to a utility file
moveSymbol  file="src/app.ts"  startLine=20  startOffset=1  endLine=35  endOffset=2  targetFile="src/utils/helpers.ts"

# Move a type to a shared types file
moveSymbol  file="src/components/Button.tsx"  startLine=1  startOffset=1  endLine=5  endOffset=2  targetFile="src/types.ts"

# Preview the move
moveSymbol  file="src/app.ts"  startLine=20  startOffset=1  endLine=35  endOffset=2  targetFile="src/utils/helpers.ts"  preview=true

`inlineVariable`

Inserta una variable en línea: reemplaza todas las referencias con el inicializador de la variable y elimina la declaración. La posición debe estar en el nombre de la variable en su declaración o en cualquier uso.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa al cwd)
`line`	`number`	✅	Número de línea basado en 1 de la variable
`offset`	`number`	✅	Desplazamiento de carácter basado en 1 en la línea
`preview`	`boolean`	✅	Si `true`, devolver los cambios sin aplicarlos

Ejemplos:

# Inline a variable
inlineVariable  file="src/app.ts"  line=12  offset=7

# Preview the inlining
inlineVariable  file="src/app.ts"  line=12  offset=7  preview=true

`extractType`

Extrae una anotación de tipo en línea en un alias de tipo con nombre. Selecciona el intervalo de tipo a extraer. La respuesta incluye renameFilename / renameLocation para que puedas continuar con rename para darle al tipo un nombre significativo.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa al cwd)
`startLine`	`number`	✅	Línea de inicio basada en 1 del intervalo de tipo
`startOffset`	`number`	✅	Desplazamiento de carácter de inicio basado en 1
`endLine`	`number`	✅	Línea de fin basada en 1 del intervalo de tipo
`endOffset`	`number`	✅	Desplazamiento de carácter de fin basado en 1
`preview`	`boolean`	✅	Si `true`, devolver los cambios sin aplicarlos

Ejemplos:

# Extract an inline object type into a type alias
# Given: function process(user: { id: number; name: string }) { ... }
# Select the span "{ id: number; name: string }"
extractType  file="src/app.ts"  startLine=5  startOffset=26  endLine=5  endOffset=56

# Preview the extraction
extractType  file="src/app.ts"  startLine=5  startOffset=26  endLine=5  endOffset=56  preview=true

`inferReturnType`

Añade una anotación de tipo de retorno explícita a una función, inferida por TypeScript. La posición debe estar en el nombre de la función o en la palabra clave de declaración (function, async, nombre de variable de función flecha).

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa al cwd)
`line`	`number`	✅	Número de línea basado en 1 de la función
`offset`	`number`	✅	Desplazamiento de carácter basado en 1 en la línea
`preview`	`boolean`	✅	Si `true`, devolver los cambios sin aplicarlos

Ejemplos:

# Add return type to a function that currently has none
# Given: function greet(name: string) { return `Hello, ${name}!`; }
# After: function greet(name: string): string { return `Hello, ${name}!`; }
inferReturnType  file="src/app.ts"  line=10  offset=10

# Preview the change
inferReturnType  file="src/app.ts"  line=10  offset=10  preview=true

`quickinfo`

Obtén la información completa del tipo, la documentación y las etiquetas JSDoc del símbolo en una posición determinada. Esta es la información de "hover".

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa al cwd)
`line`	`number`	✅	Número de línea basado en 1
`offset`	`number`	✅	Desplazamiento de carácter basado en 1 en la línea

Ejemplos:

quickinfo  file="src/utils/helpers.ts"  line=5  offset=17
quickinfo  file="src/types.ts"  line=3  offset=11

`navtree`

Obtén la estructura jerárquica completa de un archivo: todas las clases, funciones, variables, interfaces, alias de tipo, enumeraciones y su anidamiento.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa al cwd)

Ejemplos:

navtree  file="src/utils/helpers.ts"
navtree  file="src/components/Button.tsx"

`definition`

Ir a la definición de un símbolo. Devuelve la(s) ubicación(es) del archivo donde se declara el símbolo.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa a cwd)
`line`	`number`	✅	Número de línea (base 1)
`offset`	`number`	✅	Desplazamiento de carácter (base 1) en la línea

Ejemplos:

definition  file="src/app.ts"  line=10  offset=5
definition  file="src/components/Button.tsx"  line=3  offset=15

`typeDefinition`

Navega a la definición del tipo, no a la declaración de la variable. Dado const user: UserProfile = ..., definition va a la variable, pero typeDefinition va a la interfaz UserProfile.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa a cwd)
`line`	`number`	✅	Número de línea (base 1)
`offset`	`number`	✅	Desplazamiento de carácter (base 1) en la línea

Ejemplos:

typeDefinition  file="src/app.ts"  line=10  offset=12
typeDefinition  file="src/services/api.ts"  line=5  offset=8

`implementation`

Encuentra implementaciones concretas de una interfaz o clase abstracta. Dada una interfaz Serializable, devuelve todas las clases que la implementan.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa a cwd)
`line`	`number`	✅	Número de línea (base 1)
`offset`	`number`	✅	Desplazamiento de carácter (base 1) en la línea

Ejemplos:

implementation  file="src/types.ts"  line=1  offset=18
implementation  file="src/interfaces/repository.ts"  line=3  offset=18

`navto`

Búsqueda de símbolos en todo el espacio de trabajo por nombre. Toma una cadena de búsqueda y devuelve los símbolos coincidentes en todos los archivos del proyecto con sus ubicaciones y tipos.

Parámetro	Tipo	Requerido	Descripción
`searchValue`	`string`	✅	Nombre del símbolo o prefijo a buscar
`file`	`string`	—	Archivo opcional para contexto del proyecto (absoluto o relativo a cwd)
`maxResultCount`	`number`	—	Número máximo de resultados a devolver
`currentFileOnly`	`boolean`	—	Si `true`, solo busca en el archivo especificado

Ejemplos:

navto  searchValue="User"  file="src/app.ts"
navto  searchValue="handle"  file="src/app.ts"  maxResultCount=10
navto  searchValue="Button"  file="src/components/Button.tsx"  currentFileOnly=true

`fileReferences`

Encuentra todos los archivos que importan o referencian un archivo dado. El grafo de dependencias inverso para un solo archivo.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa a cwd)

Ejemplos:

fileReferences  file="src/utils/helpers.ts"
fileReferences  file="src/types.ts"

`prepareCallHierarchy`

Obtén los elementos de la jerarquía de llamadas en una posición: el punto de entrada para consultas de jerarquía de llamadas. Devuelve el nombre de la función/método, el tipo, la ubicación del archivo y los intervalos.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa a cwd)
`line`	`number`	✅	Número de línea (base 1)
`offset`	`number`	✅	Desplazamiento de carácter (base 1) en la línea

Ejemplos:

prepareCallHierarchy  file="src/services/api.ts"  line=10  offset=17
prepareCallHierarchy  file="src/utils/helpers.ts"  line=5  offset=17

`provideCallHierarchyIncomingCalls`

Encuentra todas las funciones/métodos que llaman a la función en la posición dada. Responde "¿quién llama a esto?"

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa a cwd)
`line`	`number`	✅	Número de línea (base 1)
`offset`	`number`	✅	Desplazamiento de carácter (base 1) en la línea

Ejemplos:

provideCallHierarchyIncomingCalls  file="src/services/api.ts"  line=10  offset=17
provideCallHierarchyIncomingCalls  file="src/utils/helpers.ts"  line=5  offset=17

`provideCallHierarchyOutgoingCalls`

Encuentra todas las funciones/métodos que la función en la posición dada llama. Responde "¿qué llama esto?"

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa a cwd)
`line`	`number`	✅	Número de línea (base 1)
`offset`	`number`	✅	Desplazamiento de carácter (base 1) en la línea

Ejemplos:

provideCallHierarchyOutgoingCalls  file="src/services/api.ts"  line=10  offset=17
provideCallHierarchyOutgoingCalls  file="src/utils/helpers.ts"  line=5  offset=17

`projectInfo`

Obtén la ruta de tsconfig.json, la lista completa de archivos en el proyecto y si el servicio de lenguaje está activo.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa a cwd)
`needFileNameList`	`boolean`	—	Si `true`, incluye la lista de todos los archivos en el proyecto (predeterminado: `true`)

Ejemplos:

projectInfo  file="src/app.ts"
projectInfo  file="src/app.ts"  needFileNameList=false

`completionInfo`

Obtén sugerencias de autocompletado en una posición. Devuelve todas las finalizaciones posibles con sus tipos, texto de ordenación y texto de inserción. Útil para entender qué símbolos, métodos o propiedades están disponibles en una ubicación.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa a cwd)
`line`	`number`	✅	Número de línea (base 1)
`offset`	`number`	✅	Desplazamiento de carácter (base 1) en la línea
`prefix`	`string`	—	Prefijo opcional para filtrar finalizaciones
`triggerCharacter`	`string`	—	Carácter que activó la finalización (p. ej., `.`, `"`, `'`, `, `/`, `@`, `<`, `#`, )

Ejemplos:

completionInfo  file="src/app.ts"  line=10  offset=15
completionInfo  file="src/app.ts"  line=10  offset=15  prefix="get"
completionInfo  file="src/app.ts"  line=10  offset=15  triggerCharacter="."

`completionEntryDetails`

Obtén detalles completos para entradas de finalización específicas: documentación, firma de tipo completa, etiquetas JSDoc y acciones de código (como autoimportaciones). Úsalo como seguimiento de completionInfo.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa a cwd)
`line`	`number`	✅	Número de línea (base 1)
`offset`	`number`	✅	Desplazamiento de carácter (base 1) en la línea
`entryNames`	`string[]`	✅	Nombres de las entradas de finalización para obtener detalles

Ejemplos:

completionEntryDetails  file="src/app.ts"  line=10  offset=15  entryNames=["map","filter"]
completionEntryDetails  file="src/app.ts"  line=5  offset=10  entryNames=["useState"]

`signatureHelp`

Obtén información de la firma de función/método en un sitio de llamada. Devuelve nombres de parámetros, tipos y documentación para cada sobrecarga. Úsalo cuando el cursor esté dentro de los paréntesis de una llamada a función.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa a cwd)
`line`	`number`	✅	Número de línea (base 1)
`offset`	`number`	✅	Desplazamiento de carácter (base 1) (dentro de los paréntesis de la llamada a función)
`triggerReason`	`object`	—	Opcional: `{ kind: "invoked" \| "retrigger" \| "characterTyped", triggerCharacter?: string }`

Ejemplos:

signatureHelp  file="src/app.ts"  line=12  offset=20
signatureHelp  file="src/app.ts"  line=12  offset=20  triggerReason={"kind":"invoked"}

`documentHighlights`

Encuentra todas las apariciones de un símbolo dentro de un archivo (o conjunto de archivos). Distingue entre referencias de lectura y escritura. Más eficiente que references cuando solo necesitas apariciones locales.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa a cwd)
`line`	`number`	✅	Número de línea (base 1)
`offset`	`number`	✅	Desplazamiento de carácter (base 1) en la línea
`filesToSearch`	`string[]`	—	Opcional: limitar la búsqueda a estos archivos

Ejemplos:

documentHighlights  file="src/app.ts"  line=10  offset=5
documentHighlights  file="src/app.ts"  line=10  offset=5  filesToSearch=["src/app.ts","src/utils.ts"]

`getApplicableRefactors`

Descubre qué refactorizaciones están disponibles en una posición o selección. Úsalo antes de intentar una refactorización para ver qué es posible. Devuelve una lista de refactorizaciones disponibles con sus nombres de acción y descripciones.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa a cwd)
`startLine`	`number`	✅	Línea de inicio (base 1) de la selección
`startOffset`	`number`	✅	Desplazamiento de carácter inicial (base 1)
`endLine`	`number`	✅	Línea final (base 1) de la selección
`endOffset`	`number`	✅	Desplazamiento de carácter final (base 1)
`triggerReason`	`string`	—	Opcional: `"invoked"` o `"implicit"`

Ejemplos:

getApplicableRefactors  file="src/app.ts"  startLine=10  startOffset=1  endLine=15  endOffset=1
getApplicableRefactors  file="src/app.ts"  startLine=8  startOffset=12  endLine=8  endOffset=35

`docCommentTemplate`

Genera una plantilla de comentario JSDoc para una función, método o clase en una posición. Devuelve el texto de la plantilla con @param, @returns, etc., según la firma de la función.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa a cwd)
`line`	`number`	✅	Número de línea (base 1)
`offset`	`number`	✅	Desplazamiento de carácter (base 1) en la línea

Ejemplos:

docCommentTemplate  file="src/utils/helpers.ts"  line=10  offset=1
docCommentTemplate  file="src/services/api.ts"  line=25  offset=10

`getOutliningSpans`

Obtén regiones de plegado de código para un archivo. Devuelve la estructura jerárquica de los bloques de código, incluidos sus tipos (comentario, región, código, importaciones). Útil para entender la estructura y complejidad del archivo.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa a cwd)

Ejemplos:

getOutliningSpans  file="src/app.ts"
getOutliningSpans  file="src/components/Button.tsx"

`provideInlayHints`

Obtiene inlay hints (anotaciones de tipo en línea) para un rango. Muestra tipos inferidos, nombres de parámetros en los sitios de llamada y tipos de retorno. Útil para entender qué infiere TypeScript sin anotaciones de tipo explícitas.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa a cwd)
`start`	`number`	✅	Desplazamiento inicial (posición de carácter basada en 0)
`length`	`number`	✅	Longitud del rango en caracteres

Ejemplos:

# Get inlay hints for the first 1000 characters of a file
provideInlayHints  file="src/app.ts"  start=0  length=1000

# Get inlay hints for a specific range
provideInlayHints  file="src/utils/helpers.ts"  start=500  length=200

`todoComments`

Encuentra todos los marcadores de comentario configurados (TODO, FIXME, HACK y otros) en un archivo. Devuelve la ubicación y el texto de cada comentario coincidente.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa a cwd)
`descriptors`	`{text: string, priority: number}[]`	✅	Matriz de marcadores de comentario a buscar (p. ej., TODO, FIXME)

Ejemplos:

# Find all TODO and FIXME comments
todoComments  file="src/app.ts"  descriptors=[{"text":"TODO","priority":1},{"text":"FIXME","priority":0}]

# Find TODO, FIXME, and HACK comments
todoComments  file="src/app.ts"  descriptors=[{"text":"TODO","priority":2},{"text":"FIXME","priority":1},{"text":"HACK","priority":0}]

`definitionAndBoundSpan`

Igual que definition, pero también devuelve el intervalo de texto del símbolo consultado. Útil para entender exactamente qué caracteres constituyen el símbolo.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa a cwd)
`line`	`number`	✅	Número de línea basado en 1
`offset`	`number`	✅	Desplazamiento de carácter basado en 1 en la línea

Ejemplos:

definitionAndBoundSpan  file="src/app.ts"  line=10  offset=5
definitionAndBoundSpan  file="src/types.ts"  line=3  offset=11

`findSourceDefinition`

Navega al código fuente real de TypeScript en lugar de los archivos de declaración .d.ts. Útil cuando se trabaja con librerías que tienen source maps o cuando se quiere ver la implementación en lugar de solo las declaraciones de tipos.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa a cwd)
`line`	`number`	✅	Número de línea basado en 1
`offset`	`number`	✅	Desplazamiento de carácter basado en 1 en la línea

Ejemplos:

findSourceDefinition  file="src/app.ts"  line=10  offset=5
findSourceDefinition  file="src/services/api.ts"  line=3  offset=15

`selectionRange`

Obtiene rangos de selección semánticamente significativos para la selección inteligente de expandir/contraer. Devuelve intervalos anidados que representan construcciones sintácticas progresivamente más grandes (expresión → sentencia → bloque → función).

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa a cwd)
`locations`	`{line: number, offset: number}[]`	✅	Matriz de posiciones para obtener rangos de selección

Ejemplos:

selectionRange  file="src/app.ts"  locations=[{"line":10,"offset":5}]
selectionRange  file="src/app.ts"  locations=[{"line":10,"offset":5},{"line":20,"offset":10}]

`format`

Formatea un rango de código según las reglas de formato de TypeScript. Aplica sangría, espaciado y saltos de línea consistentes.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa a cwd)
`line`	`number`	✅	Línea de inicio del rango basada en 1
`offset`	`number`	✅	Desplazamiento de carácter de inicio basado en 1
`endLine`	`number`	✅	Línea de fin del rango basada en 1
`endOffset`	`number`	✅	Desplazamiento de carácter de fin basado en 1
`options`	`object`	—	Opciones de formato (tabSize, indentSize, etc.)
`preview`	`boolean`	✅	Si `true`, devuelve los cambios sin aplicarlos

Ejemplos:

format  file="src/app.ts"  line=1  offset=1  endLine=50  endOffset=1
format  file="src/app.ts"  line=10  offset=1  endLine=20  endOffset=1  preview=true
format  file="src/app.ts"  line=1  offset=1  endLine=100  endOffset=1  options={"tabSize":4}

`getMoveToRefactoringFileSuggestions`

Obtiene archivos de destino sugeridos al mover un símbolo a otro archivo. Devuelve tanto un nombre de archivo nuevo sugerido como archivos existentes que serían buenos destinos. Usa esto antes de moveSymbol para elegir la mejor ubicación de destino.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa a cwd)
`startLine`	`number`	✅	Línea de inicio de la declaración basada en 1
`startOffset`	`number`	✅	Desplazamiento de carácter de inicio basado en 1
`endLine`	`number`	✅	Línea de fin de la declaración basada en 1
`endOffset`	`number`	✅	Desplazamiento de carácter de fin basado en 1

Ejemplos:

getMoveToRefactoringFileSuggestions  file="src/app.ts"  startLine=20  startOffset=1  endLine=35  endOffset=2
getMoveToRefactoringFileSuggestions  file="src/components/Button.tsx"  startLine=1  startOffset=1  endLine=5  endOffset=2

`getSupportedCodeFixes`

Devuelve la lista de todos los códigos de error que tienen correcciones automáticas disponibles. Úsalo como herramienta de descubrimiento antes de llamar a getCodeFixes: te indica qué códigos de error puede corregir tsserver. Opcionalmente, limita la consulta al proyecto de un archivo específico.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	—	Ruta de archivo opcional (absoluta o relativa a cwd). Si se proporciona, limita al proyecto del archivo.

Ejemplos:

# Get all fixable error codes globally
getSupportedCodeFixes

# Get fixable error codes scoped to a specific project
getSupportedCodeFixes  file="src/app.ts"

`mapCode`

Mapea fragmentos de código generados por IA en un archivo, reemplazando declaraciones coincidentes por nombre o añadiendo nuevas. Diseñado para flujos de trabajo de generación de código con IA donde se quiere fusionar código nuevo en un archivo existente sin duplicar declaraciones.

Parámetro	Tipo	Requerido	Descripción
`file`	`string`	✅	Ruta del archivo (absoluta o relativa a cwd)
`contents`	`string[]`	✅	Fragmentos de código a mapear en el archivo. Cada uno se analiza de forma independiente. Las funciones y clases se comparan por nombre.
`focusLocations`	`object[][]`	—	Matrices anidadas de intervalos `{start, end}` (línea/desplazamiento basados en 1) utilizadas para habilitar la coincidencia por nombre. Sin esto, el código siempre se añade al final del archivo.
`preview`	`boolean`	✅	Si `true`, devuelve los cambios sin aplicarlos

Cómo funciona la coincidencia:

Sin focusLocations → el código siempre se añade al final del archivo (no se intenta ninguna coincidencia)
Con focusLocations → TypeScript busca declaraciones con nombres coincidentes en el ámbito señalado
La coincidencia funciona para: funciones, clases, métodos, interfaces (nodos con una propiedad .name)
La coincidencia NO funciona para: declaraciones const/let/var (VariableStatement no tiene .name)
Cuando se encuentra una coincidencia, se reemplaza el rango desde la primera hasta la última sentencia coincidente
Cuando no se encuentra ninguna coincidencia, el código se añade al final del ámbito

Limitaciones:

Llamar con múltiples entradas contents solo aplica la primera coincidencia: llama una vez por declaración para reemplazar varias
No se admiten reemplazos de const/let/var; usa la edición estándar de archivos en su lugar

Ejemplos:

# Replace an existing function (focusLocations enables name-based matching)
mapCode  file="src/utils.ts"  contents=["export function add(a: number, b: number, c = 0) { return a + b + c; }"]  focusLocations=[[{"start":{"line":1,"offset":1},"end":{"line":1,"offset":1}}]]

# Append a new function (no focusLocations — always appends)
mapCode  file="src/utils.ts"  contents=["export function multiply(a: number, b: number) { return a * b; }"]

# Preview before applying
mapCode  file="src/utils.ts"  contents=["export function add(a: number, b: number) { return a + b; }"]  focusLocations=[[{"start":{"line":1,"offset":1},"end":{"line":1,"offset":1}}]]  preview=true

Lenguajes y Frameworks Compatibles

ts-mcp-server funciona con cualquier proyecto que el servicio de lenguaje de TypeScript entienda:

TypeScript (.ts, .tsx, .mts, .cts)
JavaScript (.js, .jsx, .mjs, .cjs)
React / Next.js / Remix / Astro
Vue (bloques de script)
Node.js / Express / Fastify / NestJS
Angular
Svelte (bloques de script)
Electron
React Native
Monorepos (Turborepo, Nx, Lerna, pnpm workspaces)

Si tu proyecto tiene un tsconfig.json (o jsconfig.json), funciona.

Requisitos del Sistema

Requisito	Versión
Node.js	22 o posterior (LTS actual)
TypeScript	6.x (se instala automáticamente como dependencia)
SO	Windows, macOS, Linux

No se requieren dependencias adicionales ni herramientas globales. El servidor incluye todo lo que necesita.

Preguntas Frecuentes

¿Funciona sin un tsconfig.json? Sí. TypeScript creará un proyecto inferido, pero una configuración explícita da mejores resultados.

¿Actualiza package.json o archivos que no son de código? No. Actualiza sentencias de importación y exportación de TypeScript/JavaScript, y entradas relacionadas con rutas en tsconfig.json (files, include, exclude, paths).

¿Puedo usarlo con proyectos solo de JavaScript? Sí. Añade un jsconfig.json (que es equivalente a tsconfig.json con allowJs: true) y el servidor descubrirá tu proyecto.

¿Funciona con alias de rutas (@/components/...)? Sí. tsserver resuelve los alias de rutas definidos en la configuración de tsconfig.json de paths y baseUrl.

¿Se modifica o formatea la salida? No. Cada herramienta devuelve la respuesta tsserver cruda y sin modificar serializada como JSON. Nada se trunca, simplifica, agrupa ni filtra.