webnav-ts-mcp 0.1.0

package/dist/shared/notices.js

@@ -0,0 +1,83 @@
+/**
+ * Out-of-band messages for the agent, appended to tool results.
+ *
+ * Two kinds: one-shot notices posted while a call runs (e.g. "restarted the
+ * language server because tsconfig.json changed") and a sticky one while the
+ * server's own source files differ from what it started with. A stdio MCP
+ * server can't reload itself, so the most it can do about stale code is say
+ * so on every call.
+ */
+import fs from "node:fs";
+import path from "node:path";
+const RECHECK_MS = 2000;
+function sourceStamp(dirs) {
+    const found = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            }
+            else if (entry.name.endsWith(".js")) {
+                try {
+                    const st = fs.statSync(full, { bigint: true });
+                    found.push(`${full}:${st.mtimeNs}:${st.size}`);
+                }
+                catch { }
+            }
+        }
+    };
+    for (const dir of dirs) {
+        walk(dir);
+    }
+    return found.sort().join("\n");
+}
+export class NoticeBoard {
+    serverName;
+    sourceDirs;
+    recheckMs;
+    startedWith;
+    pending = [];
+    checkedAt = Date.now();
+    stale = false;
+    constructor(serverName, sourceDirs, recheckMs = RECHECK_MS) {
+        this.serverName = serverName;
+        this.sourceDirs = sourceDirs;
+        this.recheckMs = recheckMs;
+        this.startedWith = sourceStamp(sourceDirs);
+    }
+    post(message) {
+        if (!this.pending.includes(message)) {
+            this.pending.push(message);
+        }
+    }
+    codeIsStale() {
+        // A stat walk per tool call adds up; a few seconds' lag in noticing an edit is fine.
+        const now = Date.now();
+        if (now - this.checkedAt >= this.recheckMs) {
+            this.checkedAt = now;
+            this.stale = sourceStamp(this.sourceDirs) !== this.startedWith;
+        }
+        return this.stale;
+    }
+    /** One-shot notices posted since the last call, plus the sticky stale-code line. */
+    drain() {
+        const notices = this.pending;
+        this.pending = [];
+        if (this.codeIsStale()) {
+            notices.push(`the ${this.serverName} server's own code changed since it started; restart the MCP servers to use the new version.`);
+        }
+        return notices;
+    }
+    annotate(text) {
+        const notices = this.drain();
+        return notices.length === 0 ? text : text + notices.map((n) => `\n\n[${this.serverName}] ${n}`).join("");
+    }
+}

package/dist/shared/params.js

@@ -0,0 +1,33 @@
+/**
+ * Param-name aliases for MCP tools: agents often guess `query` vs `name`.
+ *
+ * Throwing a `ToolInputError` (rendered as tool text) beats the framework's
+ * opaque schema-validation wall, which made agents abandon the MCP after one
+ * wrong guess.
+ */
+import { ToolInputError } from "./errors.js";
+export function resolveNameQuery(options) {
+    const { preferred, example } = options;
+    const params = { [preferred]: undefined, ...options.params };
+    let value = params[preferred];
+    if (!value) {
+        for (const [key, candidate] of Object.entries(params)) {
+            if (key !== preferred && candidate) {
+                value = candidate;
+                break;
+            }
+        }
+    }
+    if (value) {
+        return value;
+    }
+    const others = Object.keys(params).filter((key) => key !== preferred);
+    const hint = `Pass \`${preferred}\` (e.g. ${preferred}='${example}')`;
+    if (others.length === 0) {
+        throw new ToolInputError(`${hint}.`);
+    }
+    const alias = others.length === 1
+        ? `\`${others[0]}\` is accepted as an alias`
+        : `aliases accepted: ${others.map((key) => `\`${key}\``).join(", ")}`;
+    throw new ToolInputError(`${hint}; ${alias}.`);
+}

package/dist/shared/paths.js

@@ -0,0 +1,37 @@
+/** Path helpers: symlink-resolving normalisation and containment checks. */
+import fs from "node:fs";
+import path from "node:path";
+/** Like Python's `Path.resolve()`: absolute, symlinks resolved when the path exists. */
+export function resolveReal(p) {
+    const abs = path.resolve(p);
+    try {
+        return fs.realpathSync(abs);
+    }
+    catch {
+        return abs;
+    }
+}
+/** `child` relative to `parent` when it sits inside it (or equals it), else `undefined`. */
+export function relativeWithin(child, parent) {
+    const rel = path.relative(parent, child);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        return undefined;
+    }
+    return rel;
+}
+export function toPosix(p) {
+    return p.split(path.sep).join("/");
+}
+/** Component-wise path ordering, matching how Python orders `Path` objects. */
+export function comparePaths(a, b) {
+    const pa = a.split(path.sep);
+    const pb = b.split(path.sep);
+    for (let i = 0; i < Math.min(pa.length, pb.length); i++) {
+        const x = pa[i];
+        const y = pb[i];
+        if (x !== y) {
+            return x < y ? -1 : 1;
+        }
+    }
+    return pa.length - pb.length;
+}

package/dist/shared/resolve.js

@@ -0,0 +1,398 @@
+/**
+ * Name-based symbol resolution for the composite tools (`symbol_info`): a
+ * `workspace/symbol` lookup with tiered ranking, dotted `Class.method`
+ * resolution via `documentSymbol`, and disambiguation by `file_path`, so the
+ * tools take a name instead of a hand-computed position.
+ */
+import path from "node:path";
+import { isToolError, ToolInputError } from "./errors.js";
+import { isExcluded } from "./exclude.js";
+import { filterWorkspaceSymbols, isHierarchicalDocumentSymbols, matchTier, pyRepr, rankWorkspaceSymbols, symbolKindLabel, toSymbolTree, uriToPath, uriToRelative, workspaceSymbolPosition, } from "./format.js";
+import { LINE_BREAK_RE, readTextStrict } from "./text.js";
+// SymbolKind values that are class members: a candidate with one of these gets
+// qualified as `Class.member` in an ambiguity listing.
+const MEMBER_KINDS = new Set([6, 7, 9]); // Method, Property, Constructor
+const CLASS_KIND = 5;
+/** No single confident match for a name-based symbol query: not found, or ambiguous. */
+export class SymbolResolutionError extends ToolInputError {
+    name = "SymbolResolutionError";
+}
+function resolvedFromSymbol(sym) {
+    const [uri, line, column] = workspaceSymbolPosition(sym);
+    const rng = sym.location?.range ?? {};
+    const startLine = rng.start?.line ?? line;
+    const endLine = rng.end?.line ?? startLine;
+    return {
+        name: sym.name || "?",
+        kind: sym.kind,
+        uri,
+        line,
+        column,
+        rangeStartLine: startLine,
+        rangeEndLine: endLine,
+    };
+}
+function memberSpan(sym) {
+    const rng = sym.location?.range ?? {};
+    const start = rng.start?.line ?? 0;
+    return [start, rng.end?.line ?? start];
+}
+/** Hierarchical `DocumentSymbol` named `name` (any depth), preferring the one whose identifier sits on `line`. */
+function findNamedNode(symbols, name, line) {
+    const found = [];
+    const walk = (nodes) => {
+        for (const node of nodes) {
+            if (String(node.name) === name) {
+                found.push(node);
+            }
+            walk(node.children ?? []);
+        }
+    };
+    walk(symbols);
+    for (const node of found) {
+        const sel = (node.selectionRange ?? node.range)?.start;
+        if ((sel?.line ?? -1) === line) {
+            return node;
+        }
+    }
+    return found[0];
+}
+function resolvedFromHierarchicalNode(memberName, node, uri) {
+    const selStart = node.selectionRange?.start ?? node.range?.start ?? {};
+    const rng = node.range ?? {};
+    const startLine = rng.start?.line ?? 0;
+    const endLine = rng.end?.line ?? startLine;
+    return {
+        name: memberName,
+        kind: node.kind,
+        uri,
+        line: selStart.line ?? startLine,
+        column: selStart.character ?? 0,
+        rangeStartLine: startLine,
+        rangeEndLine: endLine,
+    };
+}
+/** The Class node of a `toSymbolTree` hierarchy whose range contains `targetLine`, innermost first. */
+function enclosingClassName(nodes, targetLine) {
+    for (const node of nodes) {
+        if (!(node.startLine <= targetLine && targetLine <= node.endLine)) {
+            continue;
+        }
+        const inner = enclosingClassName(node.children, targetLine);
+        if (inner !== undefined) {
+            return inner;
+        }
+        return node.kind === CLASS_KIND ? node.name : undefined;
+    }
+    return undefined;
+}
+/** For Method/Property/Constructor candidates, resolve their enclosing class so an ambiguity listing can show `Class.member`. */
+async function qualifyCandidates(client, workspaceRoot, candidates) {
+    const qualified = new Map();
+    const trees = new Map();
+    for (const [i, sym] of candidates.entries()) {
+        if (sym.kind === undefined || !MEMBER_KINDS.has(sym.kind)) {
+            continue;
+        }
+        const rel = uriToRelative(sym.location?.uri ?? "", workspaceRoot);
+        let tree = trees.get(rel);
+        if (tree === undefined) {
+            try {
+                tree = toSymbolTree(await client.documentSymbol(rel));
+            }
+            catch (error) {
+                if (!isToolError(error)) {
+                    throw error;
+                }
+                tree = [];
+            }
+            trees.set(rel, tree);
+        }
+        const className = enclosingClassName(tree, memberSpan(sym)[0]);
+        if (className) {
+            qualified.set(i, className);
+        }
+    }
+    return qualified;
+}
+async function formatCandidates(client, candidates, workspaceRoot) {
+    const shown = candidates.slice(0, 10);
+    const qualified = await qualifyCandidates(client, workspaceRoot, shown);
+    return shown
+        .map((sym, i) => {
+        const name = sym.name || "?";
+        const qualifier = qualified.get(i);
+        const display = qualifier ? `${qualifier}.${name}` : name;
+        const [uri, line, col] = workspaceSymbolPosition(sym);
+        const rel = uri ? uriToRelative(uri, workspaceRoot) : "?";
+        return `${display}  [${symbolKindLabel(sym.kind)}]  (${rel}:${line + 1}:${col + 1})`;
+    })
+        .join("\n");
+}
+const notFound = (query) => new SymbolResolutionError(`No symbol found matching ${pyRepr(query)}.`);
+async function ambiguous(client, query, candidates, workspaceRoot) {
+    const sameFile = new Set(candidates.map((c) => c.location?.uri ?? "")).size === 1;
+    // Narrowing by file_path still leaves several same-named symbols in one file
+    // (a module-level function and a same-named class method), so point at the
+    // position-based escape hatch instead of advice that won't help.
+    const hint = sameFile
+        ? "these all live in the same file; use search_symbol to get exact line/column, then hover/definition/references with that position"
+        : "pass file_path to disambiguate";
+    return new SymbolResolutionError(`${candidates.length} symbols match ${pyRepr(query)}; ${hint}:\n${await formatCandidates(client, candidates, workspaceRoot)}`);
+}
+function matchesFile(sym, workspaceRoot, filePath) {
+    const rel = uriToRelative(sym.location?.uri ?? "", workspaceRoot);
+    const target = filePath.replaceAll("\\", "/");
+    return rel === target || rel.endsWith(`/${target}`) || target.endsWith(`/${rel}`);
+}
+async function exactCandidates(client, workspaceRoot, name, filePath) {
+    const symbols = await client.workspaceSymbol(name);
+    // Same filter as search_symbol: drop export-list Variable twins and identical
+    // (name, kind, file) dupes so `symbol_info("foo")` isn't ambiguous between
+    // `function foo` and `export { foo }`.
+    const ranked = filterWorkspaceSymbols(rankWorkspaceSymbols(symbols, name));
+    let exact = ranked.filter((s) => matchTier(s.name ?? "", name) <= 1);
+    // Prefer a case-exact match over a merely case-insensitive one when both exist.
+    const caseExact = exact.filter((s) => matchTier(s.name ?? "", name) === 0);
+    if (caseExact.length > 0) {
+        exact = caseExact;
+    }
+    if (filePath !== undefined) {
+        const narrowed = exact.filter((s) => matchesFile(s, workspaceRoot, filePath));
+        if (exact.length > 0 && narrowed.length === 0) {
+            // Silently answering with a symbol from a different file than the one the
+            // caller named would be a confidently wrong result.
+            throw new SymbolResolutionError(`No symbol ${pyRepr(name)} in ${pyRepr(filePath)}; ${exact.length} match(es) elsewhere:\n` +
+                (await formatCandidates(client, exact, workspaceRoot)));
+        }
+        exact = narrowed;
+    }
+    return exact;
+}
+async function resolveSimple(client, workspaceRoot, query, filePath) {
+    const exact = await exactCandidates(client, workspaceRoot, query, filePath);
+    const [only, ...rest] = exact;
+    if (only === undefined) {
+        throw notFound(query);
+    }
+    if (rest.length > 0) {
+        throw await ambiguous(client, query, exact, workspaceRoot);
+    }
+    return resolvedFromSymbol(only);
+}
+async function resolveDotted(client, workspaceRoot, query, filePath) {
+    // `Outer.Inner.method`: the first segment is looked up workspace-wide, the
+    // rest are walked down through that symbol's document-symbol tree.
+    const [first = "", ...parts] = query.split(".");
+    const memberName = parts[parts.length - 1] ?? "";
+    const container = await resolveSimple(client, workspaceRoot, first, filePath);
+    const relPath = uriToRelative(container.uri, workspaceRoot);
+    const members = await client.documentSymbol(relPath);
+    if (isHierarchicalDocumentSymbols(members)) {
+        let found = findNamedNode(members, container.name, container.line);
+        for (const part of parts) {
+            found = (found?.children ?? []).find((c) => String(c.name) === part);
+        }
+        if (found) {
+            return resolvedFromHierarchicalNode(memberName, found, container.uri);
+        }
+    }
+    else {
+        // Flat `SymbolInformation`: narrow by range containment one segment at a time.
+        let span = [container.rangeStartLine, container.rangeEndLine];
+        let match;
+        for (const part of parts) {
+            const candidates = members.filter((m) => {
+                const [start, end] = memberSpan(m);
+                return (String(m.name ?? "") === part &&
+                    span[0] <= start &&
+                    start <= span[1] &&
+                    !(start === span[0] && end === span[1]));
+            });
+            if (candidates.length > 1) {
+                throw await ambiguous(client, query, candidates, workspaceRoot);
+            }
+            const [only] = candidates;
+            if (only === undefined) {
+                match = undefined;
+                break;
+            }
+            match = only;
+            span = memberSpan(only);
+        }
+        if (match) {
+            return resolvedFromSymbol(match);
+        }
+    }
+    // Inherited members only make sense for a plain `Class.member` query.
+    const inherited = parts.length === 1 ? await resolveInherited(client, workspaceRoot, container, memberName) : undefined;
+    if (inherited === undefined) {
+        throw notFound(query);
+    }
+    return inherited;
+}
+// Guards against pathological (or cyclic) hierarchies; real class graphs are far smaller.
+const MAX_CLASSES_VISITED = 64;
+/**
+ * Names in the `extends`/`implements` clauses of a declaration, with their offsets in `text`.
+ * `text` starts at the declaration's name; the clause list ends at the first `{` outside any `<...>`/`(...)`.
+ * Generic arguments (`Base<T>`) are skipped, `a.B` yields `B`, and call expressions
+ * (`extends mixin(Base)`) are ignored because there is no class to follow.
+ */
+export function heritageNames(text) {
+    const found = [];
+    let inHeritage = false;
+    let depth = 0;
+    let candidate;
+    const flush = () => {
+        if (candidate) {
+            found.push(candidate);
+        }
+        candidate = undefined;
+    };
+    // `=>` is one token so its `>` doesn't close a type-parameter list (`<T extends () => void>`).
+    for (const match of text.matchAll(/=>|[A-Za-z_$][\w$]*|[<>(){}[\],.]/g)) {
+        const token = match[0];
+        const offset = match.index ?? 0;
+        if (token === "{" && depth === 0) {
+            break; // the class/interface body; a `{` inside `<...>` is an object type and doesn't end the header
+        }
+        if (token === "<" || token === "(" || token === "{" || token === "[") {
+            if (token === "(" && depth === 0) {
+                candidate = undefined; // `extends mixin(Base)`
+            }
+            depth++;
+        }
+        else if (token === ">" || token === ")" || token === "}" || token === "]") {
+            depth = Math.max(0, depth - 1);
+        }
+        else if (depth > 0 || token === "=>") {
+            // inside type arguments or call arguments
+        }
+        else if (token === ",") {
+            flush();
+        }
+        else if (token === ".") {
+            // qualified name: the last segment replaces the previous one
+        }
+        else if (token === "extends" || token === "implements") {
+            flush();
+            inHeritage = true;
+        }
+        else if (inHeritage) {
+            candidate = { name: token, offset };
+        }
+    }
+    flush();
+    return found;
+}
+function offsetToPosition(text, offset) {
+    const before = text.slice(0, offset);
+    const line = before.split("\n").length - 1;
+    return { line, character: offset - (before.lastIndexOf("\n") + 1) };
+}
+/** Where each class named in `node`'s `extends`/`implements` clauses is declared. */
+async function heritageTargets(client, workspaceRoot, relPath, node) {
+    const sel = (node.selectionRange ?? node.range)?.start;
+    if (!sel) {
+        return [];
+    }
+    const lines = readTextStrict(path.resolve(workspaceRoot, relPath)).split(LINE_BREAK_RE);
+    const startOffset = lines.slice(0, sel.line ?? 0).reduce((sum, l) => sum + l.length + 1, 0) + (sel.character ?? 0);
+    const source = lines.join("\n");
+    const text = source.slice(startOffset, startOffset + 2000);
+    const targets = [];
+    for (const { name, offset } of heritageNames(text)) {
+        const at = offsetToPosition(text, offset);
+        const line = (sel.line ?? 0) + at.line;
+        const character = at.line === 0 ? (sel.character ?? 0) + at.character : at.character;
+        let locations;
+        try {
+            locations = await client.definition(relPath, line + 1, character + 1);
+        }
+        catch (error) {
+            if (!isToolError(error)) {
+                throw error;
+            }
+            continue;
+        }
+        for (const loc of locations) {
+            const uri = loc.uri ?? loc.targetUri ?? "";
+            const rng = loc.targetSelectionRange ?? loc.range ?? loc.targetRange;
+            const abs = uriToPath(uri);
+            // Vendored/library bases (`extends HTMLElement`) have no source worth walking.
+            if (!uri || isExcluded(abs, workspaceRoot) || abs.endsWith(".d.ts")) {
+                continue;
+            }
+            targets.push({ uri, name, line: rng?.start?.line ?? 0 });
+        }
+    }
+    return targets;
+}
+/**
+ * `Class.member` where `member` is inherited. Follows `extends`/`implements`
+ * clauses breadth-first (resolving each named base with `textDocument/definition`,
+ * across files) and returns the first base that declares `member` directly.
+ * TypeScript 7's language server has no type hierarchy request, so the
+ * clauses are read from the source instead.
+ */
+async function resolveInherited(client, workspaceRoot, container, memberName) {
+    const queue = [{ uri: container.uri, name: container.name, line: container.line }];
+    const seen = new Set([`${container.uri}\0${container.name}\0${container.line}`]);
+    while (queue.length > 0 && seen.size <= MAX_CLASSES_VISITED) {
+        const current = queue.shift();
+        const relPath = uriToRelative(current.uri, workspaceRoot);
+        let members;
+        let bases;
+        try {
+            members = await client.documentSymbol(relPath);
+            const node = isHierarchicalDocumentSymbols(members)
+                ? findNamedNode(members, current.name, current.line)
+                : undefined;
+            bases = node ? await heritageTargets(client, workspaceRoot, relPath, node) : [];
+        }
+        catch (error) {
+            if (!isToolError(error)) {
+                throw error;
+            }
+            continue;
+        }
+        for (const base of bases) {
+            const key = `${base.uri}\0${base.name}\0${base.line}`;
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            queue.push(base);
+            try {
+                const baseMembers = await client.documentSymbol(uriToRelative(base.uri, workspaceRoot));
+                if (!isHierarchicalDocumentSymbols(baseMembers)) {
+                    continue;
+                }
+                const baseNode = findNamedNode(baseMembers, base.name, base.line);
+                const member = (baseNode?.children ?? []).find((c) => String(c.name) === memberName);
+                if (member) {
+                    return resolvedFromHierarchicalNode(memberName, member, base.uri);
+                }
+            }
+            catch (error) {
+                if (!isToolError(error)) {
+                    throw error;
+                }
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve a name (or dotted `Class.method`) to a single symbol position.
+ *
+ * Throws `SymbolResolutionError` (a `ToolInputError`) when nothing matches or
+ * several symbols tie on an exact name: callers should pass `file_path` to
+ * disambiguate rather than guess.
+ */
+export function resolveSymbol(client, workspaceRoot, query, filePath) {
+    return query.includes(".")
+        ? resolveDotted(client, workspaceRoot, query, filePath)
+        : resolveSimple(client, workspaceRoot, query, filePath);
+}

package/dist/shared/text.js

@@ -0,0 +1,29 @@
+/** Text helpers shared by the file readers and formatters. */
+import fs from "node:fs";
+import { Utf8DecodeError } from "./errors.js";
+// `ignoreBOM: true` keeps a leading BOM in the text, so offsets match what the
+// language server is sent (and what the Python implementation reported).
+const strictUtf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+/** Read a file as UTF-8, failing (like Python's `read_text`) instead of substituting U+FFFD. */
+export function readTextStrict(filePath) {
+    const bytes = fs.readFileSync(filePath);
+    try {
+        return strictUtf8.decode(bytes);
+    }
+    catch {
+        throw new Utf8DecodeError("invalid UTF-8 byte sequence");
+    }
+}
+/** Line terminators as LSP defines them (`\r\n`, `\r`, `\n`). */
+export const LINE_BREAK_RE = /\r\n|\r|\n/;
+/** Lines of `text` without terminators; a trailing terminator doesn't add an empty last line. */
+export function splitLines(text) {
+    const lines = text.split(LINE_BREAK_RE);
+    if (lines.length > 0 && lines[lines.length - 1] === "") {
+        lines.pop();
+    }
+    return lines;
+}
+export function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}