TypeScript MCP Server

Servidor MCP TypeScript para refatoração com IA. Renomear símbolos, extrair funções, mover declarações, inline de variáveis, encontrar referências e corrigir diagnósticos — estritamente via o tsserver nativo

GitHub

Experimente este MCPPatrocinado

Documentação

ts-mcp-server

Um servidor leve de Model Context Protocol (MCP) para refatoração e inteligência de código em TypeScript e JavaScript. Cada ferramenta mapeia diretamente para um comando de protocolo tsserver — a saída é a resposta bruta e não modificada do compilador TypeScript. Renomeie símbolos, extraia funções, mova declarações entre arquivos, reorganize imports, navegue por hierarquias de tipos, explore grafos de chamadas, pesquise símbolos em todo o workspace, mapeie código gerado por IA para os locais corretos, descubra quais códigos de erro têm correções automáticas e muito mais — com cada import, require, re-exportação e referência atualizados automaticamente em todo o seu codebase.

Por quê

Assistentes de codificação com IA podem ler e escrever código, mas têm dificuldade com mudanças estruturais que se propagam por muitos arquivos. Renomear uma função, extrair um helper, mover um componente React ou reorganizar uma pasta significa atualizar cada referência e import que o utiliza. Perca uma e o build quebra.

ts-mcp-server dá a qualquer cliente compatível com MCP — VS Code Copilot, Claude Desktop, Cursor, Windsurf, Continue e outros — a capacidade de realizar essas refatorações de forma correta e completa, usando a própria infraestrutura do compilador TypeScript.

Recursos

40 ferramentas — cada uma com mapeamento 1:1 para um comando de protocolo nativo tsserver

Refatoração (14 ferramentas)

Renomear símbolos — variáveis, funções, classes, tipos, propriedades, interfaces, enums — todas as referências atualizadas em todos os arquivos
Renomear / mover arquivos e pastas — todos os caminhos de import atualizados automaticamente
Extrair função — extrai um trecho de código para uma nova função com parâmetros e tipo de retorno detectados automaticamente
Extrair constante — extrai uma expressão para uma constante nomeada com tipo inferido
Extrair tipo — extrai uma anotação de tipo inline para um alias de tipo nomeado
Inferir tipo de retorno — adiciona uma anotação explícita de tipo de retorno a uma função, inferida pelo TypeScript
Mover símbolo — move declarações de nível superior para outro arquivo, com todos os imports reconectados automaticamente
Inlinar variável — substitui todas as referências pelo inicializador da variável e exclui a declaração
Organizar imports — ordena, agrupa e remove imports não utilizados
Formatar — formata um trecho de código de acordo com as regras de formatação do TypeScript
Obter correções de código — recupera correções automáticas disponíveis para diagnósticos específicos (imports ausentes, incompatibilidades de tipo, etc.)
Obter correção de código combinada — aplica uma ação de correção geral para um código de erro específico em um arquivo
Obter diagnósticos — recupera erros de tipo, avisos e sugestões para qualquer arquivo
Encontrar todas as referências — localiza cada uso de um símbolo no projeto
Mapear código — mapeia trechos de código gerados por IA para um arquivo, substituindo declarações correspondentes por nome ou adicionando novas
Obter correções de código suportadas — lista cada código de erro que tem uma correção automática disponível, opcionalmente limitado a um projeto

Inteligência de Código (24 ferramentas)

Informação rápida — informações completas de tipo, documentação e tags JSDoc para qualquer símbolo (informação de hover)
Árvore de navegação — estrutura hierárquica completa de um arquivo (todas as declarações e seu aninhamento)
Ir para definição — salta para onde um símbolo é declarado
Definição e span delimitado — como definição, mas também retorna o span de texto do símbolo consultado
Encontrar definição de origem — navega para o código-fonte TypeScript real em vez de arquivos de declaração .d.ts
Ir para definição de tipo — salta para a definição do tipo, não para a declaração da variável
Ir para implementação — encontra implementações concretas de uma interface ou classe abstrata
Navegar para símbolo — pesquisa de símbolos em todo o workspace por nome
Referências de arquivo — encontra cada arquivo que importa um determinado arquivo (grafo de dependência reverso)
Preparar hierarquia de chamadas — obtém o ponto de entrada da hierarquia de chamadas para uma função/método
Chamadas recebidas — encontra todos os chamadores de uma função ("quem chama isso?")
Chamadas de saída — encontra todos os chamados de uma função ("o que isso chama?")
Informações do projeto — obtém o caminho do tsconfig.json, lista de arquivos e status do serviço de linguagem
Informação de conclusão — sugestões de autocompletar em uma posição
Detalhes da entrada de conclusão — documentação completa e assinatura de tipo para um item de conclusão
Ajuda de assinatura — informações de parâmetros de função e sobrecargas em um local de chamada
Destaques do documento — todas as ocorrências de um símbolo em um arquivo, com distinção de leitura/escrita
Obter refatorações aplicáveis — descobre quais refatorações estão disponíveis em uma posição ou seleção
Intervalo de seleção — obtém intervalos de seleção semanticamente significativos para expansão/redução inteligente de seleção
Sugestões de refatoração de movimentação — obtém arquivos de destino sugeridos ao mover um símbolo
Modelo de comentário de documentação — gera um modelo de comentário JSDoc para uma função/método
Spans de estrutura — obtém regiões recolhíveis em um arquivo
Dicas inlay — obtém dicas inlay (nomes de parâmetros, tipos inferidos) para um intervalo
Comentários TODO — encontra todos os comentários TODO/FIXME/HACK em um arquivo

Princípios de Design

Saída pura do tsserver — cada ferramenta retorna a resposta tsserver bruta e não modificada como JSON
Modo de pré-visualização — veja exatamente o que mudaria antes de aplicar qualquer coisa
Descoberta automática de projeto — tsconfig.json é detectado automaticamente; nenhuma configuração necessária
Suporte a múltiplos projetos — monorepos, referências de projeto e builds compostos funcionam imediatamente
Multiplataforma — Windows, macOS e Linux

Como Funciona

Por baixo dos panos, ts-mcp-server se comunica com o tsserver do TypeScript via Node IPC — o mesmo protocolo que o VS Code usa. Cada ferramenta é um wrapper fino que:

Passa sua entrada diretamente para um comando de protocolo tsserver
Retorna a resposta bruta — sem formatação, sem agrupamento, sem filtragem

Ferramentas de refatoração:

Ferramenta	comando(s) do 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`

Ferramentas de inteligência de código:

Ferramenta	comando do 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`

Não há regex, nem resolução de caminho personalizada, nem heurísticas, nem formatação de saída. O compilador TypeScript faz todo o trabalho.

Início Rápido

Instalação

npx ts-mcp-server

Configure Seu Cliente MCP

Adicione ts-mcp-server à configuração MCP do seu 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 — siga a documentação de servidor MCP de cada cliente usando o mesmo comando npx ts-mcp-server.

Desabilitando Ferramentas Individuais

Cada ferramenta pode ser desabilitada individualmente definindo seu nome como "false" no bloco env da sua configuração MCP. As ferramentas são habilitadas por padrão; apenas ferramentas explicitamente definidas como "false" são ignoradas na inicialização.

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"
      }
    }
  }
}

O nome da ferramenta em env deve corresponder exatamente ao nome da ferramenta listado na Referência de Ferramentas abaixo (por exemplo, "quickinfo", "getDiagnostics", "extractFunction"). Qualquer outro valor — incluindo omitir a chave completamente — mantém a ferramenta habilitada.

Referência de Ferramentas

`rename`

Renomeia um símbolo TypeScript/JavaScript e atualiza todas as referências no projeto.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo que contém o símbolo (absoluto ou relativo ao cwd)
`line`	`number`	✅	Número da linha baseado em 1 onde o símbolo aparece
`offset`	`number`	✅	Deslocamento de caractere baseado em 1 na linha
`newName`	`string`	✅	Novo nome para o símbolo
`preview`	`boolean`	✅	Se `true`, retorna as alterações sem aplicar

Exemplos:

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`

Renomeia ou move um arquivo ou diretório TypeScript/JavaScript e atualiza todos os caminhos de import no projeto.

Parâmetro	Tipo	Obrigatório	Descrição
`from`	`string`	✅	Caminho atual do arquivo ou diretório (absoluto ou relativo ao cwd)
`to`	`string`	✅	Novo caminho do arquivo ou diretório (absoluto ou relativo ao cwd)
`preview`	`boolean`	✅	Se `true`, retornar alterações sem aplicar

Exemplos:

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`

Encontre todos os usos de um símbolo em todo o projeto.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)
`line`	`number`	✅	Número da linha (base 1) onde o símbolo aparece
`offset`	`number`	✅	Deslocamento de caractere (base 1) na linha

Exemplos:

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

`getDiagnostics`

Obtenha todos os erros, avisos e sugestões para um arquivo. Retorna diagnósticos semânticos e diagnósticos de sugestão como matrizes separadas.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)

Exemplos:

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

Nota: Diagnósticos de código não utilizado (variáveis não utilizadas, importações não utilizadas) só aparecem se o seu tsconfig.json tiver noUnusedLocals e/ou noUnusedParameters habilitados.

`organizeImports`

Ordenar, consolidar e remover importações não utilizadas em um arquivo.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)
`preview`	`boolean`	✅	Se `true`, retornar alterações sem aplicar

Exemplos:

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

`getCodeFixes`

Obtenha correções de código disponíveis para códigos de erro específicos em um intervalo em um arquivo. Use getDiagnostics primeiro para descobrir códigos de erro e intervalos e, em seguida, passe-os aqui.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)
`startLine`	`number`	✅	Linha inicial (base 1) do intervalo de diagnóstico
`startOffset`	`number`	✅	Deslocamento inicial do caractere (base 1)
`endLine`	`number`	✅	Linha final (base 1) do intervalo de diagnóstico
`endOffset`	`number`	✅	Deslocamento final do caractere (base 1)
`errorCodes`	`number[]`	✅	Códigos de erro de diagnóstico para obter correções

Exemplos:

# 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`

Obtenha uma correção de código combinada que aplica todas as instâncias de uma correção em um arquivo em uma única ação. Retorna o conjunto completo de edições de arquivo como uma resposta CombinedCodeActions. Use getCodeFixes primeiro para descobrir os valores fixId disponíveis e, em seguida, passe o fixId aqui para obter a correção combinada para o arquivo inteiro.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)
`fixId`	`string`	✅	O fixId de uma correção de código (por exemplo, `"fixMissingImport"`, `"unusedIdentifier"`, `"inferFromUsage"`)

Exemplos:

# 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`

Extraia um intervalo de código selecionado para uma nova função. O TypeScript detecta automaticamente parâmetros e tipo de retorno. A resposta inclui renameFilename / renameLocation para que você possa acompanhar com rename para dar à função um nome significativo.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)
`startLine`	`number`	✅	Linha inicial (base 1) da seleção
`startOffset`	`number`	✅	Deslocamento inicial do caractere (base 1)
`endLine`	`number`	✅	Linha final (base 1) da seleção
`endOffset`	`number`	✅	Deslocamento final do caractere (base 1)
`preview`	`boolean`	✅	Se `true`, retornar alterações sem aplicar

Exemplos:

# 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`

Extraia uma expressão selecionada para uma constante nomeada. O TypeScript infere o tipo. A resposta inclui renameFilename / renameLocation para que você possa acompanhar com rename para dar à constante um nome significativo.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)
`startLine`	`number`	✅	Linha inicial (base 1) da expressão
`startOffset`	`number`	✅	Deslocamento inicial do caractere (base 1)
`endLine`	`number`	✅	Linha final (base 1) da expressão
`endOffset`	`number`	✅	Deslocamento final do caractere (base 1)
`preview`	`boolean`	✅	Se `true`, retornar alterações sem aplicar

Exemplos:

# 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`

Mova declarações de nível superior (funções, classes, tipos, constantes) para outro arquivo. Todas as importações em todo o projeto são reconectadas automaticamente. Se o arquivo de destino não existir, o tsserver o cria.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo de origem (absoluto ou relativo ao cwd)
`startLine`	`number`	✅	Linha inicial (base 1) da declaração
`startOffset`	`number`	✅	Deslocamento inicial do caractere (base 1)
`endLine`	`number`	✅	Linha final (base 1) da declaração
`endOffset`	`number`	✅	Deslocamento final do caractere (base 1)
`targetFile`	`string`	✅	Caminho do arquivo de destino (absoluto ou relativo ao cwd)
`preview`	`boolean`	✅	Se `true`, retornar alterações sem aplicar

Exemplos:

# 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`

Incorpore uma variável — substitua todas as referências pelo inicializador da variável e exclua a declaração. A posição deve estar no nome da variável em sua declaração ou em qualquer uso.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)
`line`	`number`	✅	Número da linha (base 1) da variável
`offset`	`number`	✅	Deslocamento de caractere (base 1) na linha
`preview`	`boolean`	✅	Se `true`, retornar alterações sem aplicar

Exemplos:

# 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`

Extraia uma anotação de tipo inline em um alias de tipo nomeado. Selecione o intervalo do tipo para extrair. A resposta inclui renameFilename / renameLocation para que você possa acompanhar com rename para dar ao tipo um nome significativo.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)
`startLine`	`number`	✅	Linha inicial (base 1) do intervalo do tipo
`startOffset`	`number`	✅	Deslocamento inicial do caractere (base 1)
`endLine`	`number`	✅	Linha final (base 1) do intervalo do tipo
`endOffset`	`number`	✅	Deslocamento final do caractere (base 1)
`preview`	`boolean`	✅	Se `true`, retornar alterações sem aplicar

Exemplos:

# 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`

Adicione uma anotação explícita de tipo de retorno a uma função, inferida pelo TypeScript. A posição deve estar no nome da função ou na palavra-chave da declaração (function, async, nome da variável da função de seta).

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)
`line`	`number`	✅	Número da linha (base 1) da função
`offset`	`number`	✅	Deslocamento de caractere (base 1) na linha
`preview`	`boolean`	✅	Se `true`, retornar alterações sem aplicar

Exemplos:

# 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`

Obtenha as informações completas do tipo, documentação e tags JSDoc para o símbolo em uma determinada posição. Esta é a informação de "hover".

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)
`line`	`number`	✅	Número da linha (base 1)
`offset`	`number`	✅	Deslocamento de caractere (base 1) na linha

Exemplos:

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

`navtree`

Obtenha a estrutura hierárquica completa de um arquivo — todas as classes, funções, variáveis, interfaces, aliases de tipo, enums e seu aninhamento.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)

Exemplos:

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

`definition`

Vá para a definição de um símbolo. Retorna o(s) local(is) do arquivo onde o símbolo é declarado.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)
`line`	`number`	✅	Número da linha baseado em 1
`offset`	`number`	✅	Deslocamento de caractere baseado em 1 na linha

Exemplos:

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

`typeDefinition`

Navegue até a definição do tipo, não a declaração da variável. Dado const user: UserProfile = ..., definition vai para a variável, mas typeDefinition vai para a interface UserProfile.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)
`line`	`number`	✅	Número da linha baseado em 1
`offset`	`number`	✅	Deslocamento de caractere baseado em 1 na linha

Exemplos:

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

`implementation`

Encontre implementações concretas de uma interface ou classe abstrata. Dada uma interface Serializable, retorna todas as classes que a implementam.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)
`line`	`number`	✅	Número da linha baseado em 1
`offset`	`number`	✅	Deslocamento de caractere baseado em 1 na linha

Exemplos:

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

`navto`

Pesquisa de símbolos em todo o workspace por nome. Recebe uma string de busca e retorna símbolos correspondentes em todos os arquivos do projeto, com suas localizações e tipos.

Parâmetro	Tipo	Obrigatório	Descrição
`searchValue`	`string`	✅	Nome do símbolo ou prefixo para pesquisar
`file`	`string`	—	Arquivo opcional para contexto do projeto (absoluto ou relativo ao cwd)
`maxResultCount`	`number`	—	Número máximo de resultados a retornar
`currentFileOnly`	`boolean`	—	Se `true`, pesquisar apenas no arquivo especificado

Exemplos:

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`

Encontre todos os arquivos que importam ou referenciam um determinado arquivo. O grafo de dependência reversa para um único arquivo.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)

Exemplos:

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

`prepareCallHierarchy`

Obtenha o(s) item(ns) da hierarquia de chamadas em uma posição — o ponto de entrada para consultas de hierarquia de chamadas. Retorna o nome da função/método, tipo, localização do arquivo e spans.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)
`line`	`number`	✅	Número da linha baseado em 1
`offset`	`number`	✅	Deslocamento de caractere baseado em 1 na linha

Exemplos:

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

`provideCallHierarchyIncomingCalls`

Encontre todas as funções/métodos que chamam a função na posição fornecida. Responde "quem chama isso?"

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)
`line`	`number`	✅	Número da linha baseado em 1
`offset`	`number`	✅	Deslocamento de caractere baseado em 1 na linha

Exemplos:

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

`provideCallHierarchyOutgoingCalls`

Encontre todas as funções/métodos que a função na posição fornecida chama. Responde "o que isso chama?"

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)
`line`	`number`	✅	Número da linha baseado em 1
`offset`	`number`	✅	Deslocamento de caractere baseado em 1 na linha

Exemplos:

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

`projectInfo`

Obtenha o caminho do tsconfig.json, a lista completa de arquivos no projeto e se o serviço de linguagem está ativo.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)
`needFileNameList`	`boolean`	—	Se `true`, incluir a lista de todos os arquivos no projeto (padrão: `true`)

Exemplos:

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

`completionInfo`

Obtenha sugestões de autocompletar em uma posição. Retorna todas as sugestões possíveis com seus tipos, texto de ordenação e texto de inserção. Útil para entender quais símbolos, métodos ou propriedades estão disponíveis em um local.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)
`line`	`number`	✅	Número da linha baseado em 1
`offset`	`number`	✅	Deslocamento de caractere baseado em 1 na linha
`prefix`	`string`	—	Prefixo opcional para filtrar sugestões
`triggerCharacter`	`string`	—	Caractere que acionou o autocompletar (ex.: `.`, `"`, `'`, `, `/`, `@`, `<`, `#`, )

Exemplos:

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`

Obtenha detalhes completos para entradas de sugestão específicas — documentação, assinatura de tipo completa, tags JSDoc e ações de código (como importações automáticas). Use como acompanhamento de completionInfo.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)
`line`	`number`	✅	Número da linha baseado em 1
`offset`	`number`	✅	Deslocamento de caractere baseado em 1 na linha
`entryNames`	`string[]`	✅	Nomes das entradas de sugestão para obter detalhes

Exemplos:

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

`signatureHelp`

Obtenha informações de assinatura de função/método em um local de chamada. Retorna nomes de parâmetros, tipos e documentação para cada sobrecarga. Use quando o cursor estiver dentro dos parênteses de uma chamada de função.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)
`line`	`number`	✅	Número da linha baseado em 1
`offset`	`number`	✅	Deslocamento de caractere baseado em 1 (dentro dos parênteses da chamada de função)
`triggerReason`	`object`	—	Opcional: `{ kind: "invoked" \| "retrigger" \| "characterTyped", triggerCharacter?: string }`

Exemplos:

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

`documentHighlights`

Encontre todas as ocorrências de um símbolo em um arquivo (ou conjunto de arquivos). Diferencia entre referências de leitura e escrita. Mais eficiente que references quando você só precisa de ocorrências locais.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)
`line`	`number`	✅	Número da linha baseado em 1
`offset`	`number`	✅	Deslocamento de caractere baseado em 1 na linha
`filesToSearch`	`string[]`	—	Opcional: limitar a pesquisa a estes arquivos

Exemplos:

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`

Descubra quais refatorações estão disponíveis em uma posição ou seleção. Use antes de tentar uma refatoração para ver o que é possível. Retorna uma lista de refatorações disponíveis com seus nomes de ação e descrições.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)
`startLine`	`number`	✅	Linha inicial da seleção baseada em 1
`startOffset`	`number`	✅	Deslocamento de caractere inicial baseado em 1
`endLine`	`number`	✅	Linha final da seleção baseada em 1
`endOffset`	`number`	✅	Deslocamento de caractere final baseado em 1
`triggerReason`	`string`	—	`"invoked"` ou `"implicit"`

Exemplos:

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`

Gere um modelo de comentário JSDoc para uma função, método ou classe em uma posição. Retorna o texto do modelo com @param, @returns, etc. com base na assinatura da função.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao cwd)
`line`	`number`	✅	Número da linha baseado em 1
`offset`	`number`	✅	Deslocamento de caractere baseado em 1 na linha

Exemplos:

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

`getOutliningSpans`

Obtenha regiões de recolhimento de código para um arquivo. Retorna a estrutura hierárquica dos blocos de código, incluindo seus tipos (comentário, região, código, imports). Útil para entender a estrutura e a complexidade do arquivo.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao diretório de trabalho)

Exemplos:

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

`provideInlayHints`

Obtenha dicas de inlay (anotações de tipo inline) para um intervalo. Mostra tipos inferidos, nomes de parâmetros em locais de chamada e tipos de retorno. Útil para entender o que o TypeScript infere sem anotações de tipo explícitas.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao diretório de trabalho)
`start`	`number`	✅	Deslocamento inicial (posição de caractere baseada em 0)
`length`	`number`	✅	Comprimento do intervalo em caracteres

Exemplos:

# 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`

Encontre todos os marcadores de comentário configurados, como TODO, FIXME, HACK e outros, em um arquivo. Retorna a localização e o texto de cada comentário correspondente.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao diretório de trabalho)
`descriptors`	`{text: string, priority: number}[]`	✅	Matriz de marcadores de comentário para pesquisar (por exemplo, TODO, FIXME)

Exemplos:

# 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`

Como definition, mas também retorna o intervalo de texto do símbolo consultado. Útil para entender exatamente quais caracteres constituem o símbolo.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao diretório de trabalho)
`line`	`number`	✅	Número da linha baseado em 1
`offset`	`number`	✅	Deslocamento de caractere baseado em 1 na linha

Exemplos:

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

`findSourceDefinition`

Navegue até o código-fonte TypeScript real em vez dos arquivos de declaração .d.ts. Útil ao trabalhar com bibliotecas que possuem source maps ou quando você deseja ver a implementação em vez de apenas as declarações de tipo.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao diretório de trabalho)
`line`	`number`	✅	Número da linha baseado em 1
`offset`	`number`	✅	Deslocamento de caractere baseado em 1 na linha

Exemplos:

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

`selectionRange`

Obtenha intervalos de seleção semanticamente significativos para seleção inteligente de expandir/recolher. Retorna intervalos aninhados que representam construções sintáticas progressivamente maiores (expressão → declaração → bloco → função).

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao diretório de trabalho)
`locations`	`{line: number, offset: number}[]`	✅	Matriz de posições para obter intervalos de seleção

Exemplos:

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`

Formate um intervalo de código de acordo com as regras de formatação do TypeScript. Aplica indentação, espaçamento e quebras de linha consistentes.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao diretório de trabalho)
`line`	`number`	✅	Linha inicial do intervalo baseada em 1
`offset`	`number`	✅	Deslocamento de caractere inicial baseado em 1
`endLine`	`number`	✅	Linha final do intervalo baseada em 1
`endOffset`	`number`	✅	Deslocamento de caractere final baseado em 1
`options`	`object`	—	Opções de formatação (tabSize, indentSize, etc.)
`preview`	`boolean`	✅	Se `true`, retorna alterações sem aplicá-las

Exemplos:

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`

Obtenha arquivos de destino sugeridos ao mover um símbolo para outro arquivo. Retorna tanto um nome de arquivo novo sugerido quanto arquivos existentes que seriam bons destinos. Use isso antes de moveSymbol para escolher o melhor local de destino.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao diretório de trabalho)
`startLine`	`number`	✅	Linha inicial da declaração baseada em 1
`startOffset`	`number`	✅	Deslocamento de caractere inicial baseado em 1
`endLine`	`number`	✅	Linha final da declaração baseada em 1
`endOffset`	`number`	✅	Deslocamento de caractere final baseado em 1

Exemplos:

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`

Retorna a lista de todos os códigos de erro que possuem correções automáticas disponíveis. Use isso como uma ferramenta de descoberta antes de chamar getCodeFixes — informa quais códigos de erro o tsserver pode corrigir. Opcionalmente, escopo a consulta ao projeto de um arquivo específico.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	—	Caminho de arquivo opcional (absoluto ou relativo ao diretório de trabalho). Se fornecido, escopo ao projeto do arquivo.

Exemplos:

# Get all fixable error codes globally
getSupportedCodeFixes

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

`mapCode`

Mapeie trechos de código gerados por IA em um arquivo, substituindo declarações correspondentes por nome ou anexando novas. Projetado para fluxos de trabalho de geração de código por IA, onde você deseja mesclar novo código em um arquivo existente sem duplicar declarações.

Parâmetro	Tipo	Obrigatório	Descrição
`file`	`string`	✅	Caminho do arquivo (absoluto ou relativo ao diretório de trabalho)
`contents`	`string[]`	✅	Trechos de código para mapear no arquivo. Cada um é analisado independentemente. Funções e classes são correspondidas por nome.
`focusLocations`	`object[][]`	—	Matrizes aninhadas de intervalos `{start, end}` (linha/deslocamento baseados em 1) usadas para habilitar correspondência baseada em nome. Sem isso, o código é sempre anexado ao final do arquivo.
`preview`	`boolean`	✅	Se `true`, retorna alterações sem aplicá-las

Como funciona a correspondência:

Sem focusLocations → o código é sempre anexado ao final do arquivo (nenhuma correspondência tentada)
Com focusLocations → o TypeScript procura declarações com nomes correspondentes no escopo apontado
A correspondência funciona para: funções, classes, métodos, interfaces (nós com uma propriedade .name)
A correspondência NÃO funciona para: declarações const/let/var (VariableStatement não tem .name)
Quando uma correspondência é encontrada, o intervalo da primeira à última declaração correspondente é substituído
Quando nenhuma correspondência é encontrada, o código é anexado ao final do escopo

Limitações:

Chamar com múltiplas entradas contents aplica apenas a primeira correspondência — chame uma vez por declaração para substituir várias
Substituições de const/let/var não são suportadas; use edição de arquivo padrão

Exemplos:

# 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

Linguagens e Frameworks Suportados

ts-mcp-server funciona com qualquer projeto que o serviço de linguagem do TypeScript entenda:

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

Se o seu projeto tem um tsconfig.json (ou jsconfig.json), funciona.

Requisitos do Sistema

Requisito	Versão
Node.js	22 ou posterior (LTS atual)
TypeScript	6.x (instalado automaticamente como dependência)
SO	Windows, macOS, Linux

Nenhuma dependência adicional ou ferramentas globais são necessárias. O servidor agrupa tudo o que precisa.

FAQ

Funciona sem um tsconfig.json? Sim. O TypeScript criará um projeto inferido, mas a configuração explícita dá melhores resultados.

Ele atualiza package.json ou arquivos que não são de código? Não. Ele atualiza declarações de importação e exportação TypeScript/JavaScript e entradas relacionadas a caminhos em tsconfig.json (files, include, exclude, paths).

Posso usá-lo com projetos somente JavaScript? Sim. Adicione um jsconfig.json (que é equivalente a tsconfig.json com allowJs: true) e o servidor descobrirá seu projeto.

Funciona com aliases de caminho (@/components/...)? Sim. tsserver resolve aliases de caminho definidos nas configurações paths e baseUrl do tsconfig.json.

A saída é modificada ou formatada? Não. Cada ferramenta retorna a resposta tsserver bruta e não modificada serializada como JSON. Nada é truncado, simplificado, agrupado ou filtrado.