typeprobe

typeprobe

typeprobe asks the TypeScript compiler what it infers (types, completions, type errors) so that AI coding agents and tests don't have to guess. It comes as:

• an MCP server for coding agents (Claude Code, Codex, Cursor, VS Code, Gemini CLI, any stdio client),
• typeprobe/testing, which returns inferred types as strings for snapshot tests,
• a CLI and a synchronous library API.

typeprobe was called prinfer until 4.0.0. See Migrating from prinfer.

Quick start

Give your agent the compiler:

npx -y typeprobe setup claude    # or codex, cursor, vscode, gemini; see Install

The agent can now call hover_by_name(file: "src/utils.ts", name: "names") and get Type: string[] back, or diagnostics(file) after an edit.

Lock the types your API infers in a test (Vitest, Jest, Bun, or any runner with snapshots):

import { expect, test } from "vitest"; // or "bun:test"

import { inferredType } from "typeprobe/testing"; import { groupBy, type User } from "../src/users";

const users: User[] = [{ name: "Ada", role: "admin" }]; const byRole = groupBy(users, (user) => user.role);

test("groupBy keys the result by the callback's return type", () => { expect(inferredType(import.meta.url, { name: "byRole" })) .toMatchInlineSnapshot("Record "); });

Write the matcher empty (toMatchInlineSnapshot()) and the runner fills it in. A refactor that changes the type fails the test.

Install

Every command runs through npx, so nothing needs installing first. After npm i -g typeprobe, drop the npx -y prefix: setup then registers the typeprobe-mcp binary, which skips npx's package check on each launch.

Claude Code. The plugin bundles the MCP server and a skill that tells Claude when to use it:

/plugin marketplace add clockblocker/typeprobe

/plugin install typeprobe@typeprobe

Other clients, or Claude Code without the plugin:

| Client | Command | Writes | | :- | :- | :- | | Claude Code | npx -y typeprobe setup claude | claude mcp add; --scope project for a shared .mcp.json | | Codex | npx -y typeprobe setup codex | codex mcp add (~/.codex/config.toml) | | Cursor | npx -y typeprobe setup cursor | ~/.cursor/mcp.json; --scope project: .cursor/mcp.json | | VS Code | npx -y typeprobe setup vscode | code --add-mcp; --scope project: .vscode/mcp.json | | Gemini CLI | npx -y typeprobe setup gemini | ~/.gemini/settings.json; --scope project: .gemini/settings.json |

Any other MCP client: typeprobe is a stdio server started with npx -y typeprobe mcp.

{

"mcpServers": { "typeprobe": { "command": "npx", "args": ["-y", "typeprobe", "mcp"] } } }

It is also listed in the MCP Registry as io.github.clockblocker/typeprobe and on Smithery.

Setup options:

• --print shows the command or config change without applying it.
• --npx registers npx -y typeprobe mcp even when typeprobe-mcp is installed. Use it when the client can't find typeprobe-mcp; editors started outside a shell often miss nvm, fnm, or volta paths.
• Re-running setup updates the typeprobe entry's command and leaves other servers alone. JSON configs keep keys you added to the entry, such as env. A JSON config that doesn't parse is left untouched, and setup prints the entry to add by hand.
• A prinfer entry from before the rename is replaced rather than kept next to the new one: claude and codex remove it, and JSON configs swap it for typeprobe in place, keeping its other keys (with PRINFER_* env names renamed to TYPEPROBE_*).
• On Windows the server is registered as cmd /c npx -y typeprobe mcp (or cmd /c typeprobe-mcp), because clients launch it without a shell and can't run npm's .cmd shims.

Tell the agent when to use it

Tool descriptions only go so far; agents still reach for tsc or write annotations by hand. Add a short usage block to your instructions file (the Claude Code plugin ships the same guidance as a skill):

npx -y typeprobe setup agents-md                  # ./AGENTS.md

npx -y typeprobe setup agents-md --file CLAUDE.md

The block sits between and ; re-running updates it in place, and replaces a block prinfer wrote ( ).

MCP tools

| Tool | Use it for | | :- | :- | | hover_by_name | The type of a named symbol. Start here. | | hover | The type of a token on a line: callback parameters, expressions, repeated names. | | batch_hover | Up to 100 lookups, across files, in one call. | | completions | What TypeScript offers at a cursor, such as string-literal union members. | | diagnostics | Type errors in one file, without checking the whole project. | | annotations | Annotations TypeScript would infer anyway. |

Shared parameters:

• file is absolute or relative to the server's working directory. Lines and columns are 1-based.
• project is a tsconfig.json path; the default is the nearest one above the file.
• backend (typescript7 by default, or typescript6) on the hover tools and diagnostics. If a call fails or looks wrong on TypeScript 7, retry it with typescript6. See Backends and compilers.
• Hover tools take include_docs (JSDoc), include_cost (see Type cost budgets), full, and max_chars. Type text is capped at 4000 characters per type, and a cut type ends with a line like … truncated: 187 chars total, union of 4 members. Pass max_chars: N to see more (0 for no limit). full: true turns off TypeScript's own truncation ({ ...; }, ... 12 more ...) and lists every overload. Structured content is never cut.

hover_by_name

hover_by_name(file: "src/utils.ts", name: "names")

hover_by_name(file: "src/utils.ts", name: "names", line: 11) # line picks among same-named symbols

Type: string[]

Name: names Kind: const Position: 11:14

When a name is declared more than once, the lookup prefers declarations and says which it picked: Matched line 8 of 2 declarations (also 12); pass line to choose. The structured result lists the others as alternatives: [{ line, column, kind }]. A line that matches none fails with SYMBOL_NOT_FOUND and lists the declaration lines in declaredAt. A line where the name is used rather than declared, such as box.value in an if, gives the type there, narrowed by the code around it.

Overloaded functions show the first signature, then up to three more (full: true lists all; structured overloads always has every one):

Type: (value: string): number (+1 overload)

Overloads: (value: number): string Returns: number Name: parse Kind: function Position: 1:17

hover

Pass text copied from the line and typeprobe finds the column. Whole identifiers match first: on users.map((user) => user.name), text: "user" skips users and hits the callback parameter, and occurrence: 2 picks the next user. Only when the line has no whole-identifier match is text matched as a substring. column works in place of text. Generic calls show their instantiated types, as in an editor.

hover(file: "src/utils.ts", line: 11, text: "user")

Type: { id: number; name: string; }

Name: user Kind: parameter Position: 11:33 Target: "user" at 11:33

If the text isn't on the line, the error quotes the line:

Error [SYMBOL_NOT_FOUND]: Text "nope" not found on line 11 of /project/src/utils.ts

Nearby identifiers: name, names, map, user, users Suggestion: Line 11 reads: "export const names = users.map((user) => user.name);". Copy text exactly from it, or give a column instead.

batch_hover

Each item is {name, line?}, {line, text, occurrence?}, or {line, column}, with an optional file that overrides the shared top-level file. Failures are per item, including a missing file, so one bad lookup doesn't lose the rest.

batch_hover(file: "src/utils.ts", positions: [

{name: "users"}, {line: 11, text: "user"}, {file: "src/missing.ts", line: 1, column: 1} ])

Batch hover results: 2 succeeded, 1 failed

--- src/utils.ts:users:6 --- Type: { id: number; name: string; }[] ...

--- src/missing.ts:1:1 --- Error [FILE_NOT_FOUND]: File not found: /project/src/missing.ts Suggestion: Check the path. Relative paths resolve against the MCP server's working directory (/project); pass an absolute path to be sure.

A line or column outside the file is an INVALID_ARGUMENT error that gives the valid range.

Hover results

Every hover returns the same fields on every backend and surface:

• signature: the type text alone, on one line, without the declaration keyword or name an editor hover starts with. string[] for a variable, (value: string): number for a function, the instantiated signature for a call. Type aliases keep their name and type parameters (type Event = { kind: "open"; ... } | ...); interfaces and classes are their name (Box ). Optional members read as tsc writes them in declarations: digits?: number, with | undefined only where the source wrote it or the type isn't the annotation's (an instantiated generic, a Partial ).
• display: the editor's hover text (const names: string[]). Only the TypeScript 7 language server reports it.
• kind: the editor's label (function, method, const, parameter, property, type, interface, class, enum, ...), plus call for the callee of a call.
• returnType, documentation, overloads, unionMembers, and alternatives when they apply.
• cost: { instantiations, types } with include_cost: true.
• compiler: { name, version, source }, the compiler that answered.

completions

The cursor sits before the character at column; for a string union, put it just inside the opening quote.

completions(file: "src/utils.ts", line: 14, column: 30)

completions(file: "src/utils.ts", line: 20, column: 1, prefix: "use", limit: 20)

Entries come in TypeScript's ranking: locals, members, and literal values first, then globals (keywords after other entries of the same rank), then auto-imports. At most limit come back (default 50, up to 500); when more match, the text ends with … 947 more; pass prefix to narrow, or raise limit and the structured result has total and truncated: true.

prefix keeps names that start with it, ignoring case. Without it, the text typed left of the cursor filters the list as in an editor (after use in useSt, only use… names); prefix: "" turns that off. At a key of an object literal that accepts any key (Record ), typeprobe returns no entries and a note saying so, instead of every global. completions always runs on TypeScript 6.

diagnostics

Run it on each file you edited; the edit is done when none reports an error.

diagnostics(file: "src/utils.ts")

diagnostics(file: "src/utils.ts", include_suggestions: true) # also TS6133 unused variables etc.

src/utils.ts:16:14 error TS2322: Type 'string' is not assignable to type 'number'.

1 error, 0 warnings.

A clean file returns No type errors.

annotations

annotations(file: "src/utils.ts")

src/utils.ts:2:55 redundant return type of format: declared string, inferred string (exported)

src/utils.ts:14:19 widening drink: declared Drink, inferred "tea" (exported) 2 redundant, 2 widening (5 annotations checked). redundant: delete the annotation; the type stays the same. widening: the annotation is wider than the inferred type; keep it if the wider type is intended.

A redundant annotation can be deleted without changing the type. A `w