TypeScript Definition Resolver Utility

This Model Context Protocol (MCP) service empowers AI-driven code environments to resolve the definitive locations of TypeScript entities across a project structure. It is especially valuable for tracing the foundational implementation of imported constructs, such as interfaces, classes, or functions, within a TypeScript ecosystem.

Capabilities

• Resolves definitive origins for TypeScript language elements.
• Supports tracing definitions embedded in third-party packages.
• Output includes both the definition's geographical coordinates and the source text excerpt.
• Integrates with AI code assistants via the standard stdio communication mechanism.

Requirements

• Bun version 1.2.2 or newer.
• Node.js runtime environment for executing the compiled backend.

Setup Guide

Automated Installation via Smithery

Install the TypeScript Definition Resolver for local AI client execution using Smithery:

bash npx -y @smithery/cli install @runninghare/ts-def-mcp --client claude

Manual Compilation Steps

1. Acquire necessary dependencies: bash bun install

2. Produce the runnable artifacts: bash bun run build

Execution

Launch the standard input/output server: bash node dist/run.js

Tool Specification

The backend exposes a function named find_typescript_definition with the following attributes:

• Function Identifier: find_typescript_definition
• Activation Trigger: /ts-def (Recommended for explicit invocation in editors like Cursor to mandate symbol resolution)
• Objective: Ascertain the authoritative definition location for specified TypeScript constructs within the project tree.

Mandatory Input Arguments

The invocation necessitates three arguments:

1. file_path (string):
2. The fully qualified, absolute path pointing to the file currently under inspection.

3. Illustration: /opt/project/source/main.ts

4. line_content (string):

5. The totality of the source line where the target symbol resides.
6. Crucial for accurately anchoring the search within the file.

7. Must be an exact textual match to the corresponding line in the file.

8. column_number (number):

9. The 1-based index indicating the starting position of the symbol's first character on that line.
10. Must precisely map to the symbol's commencement column.

Operational Examples

1. Tracing an External Dependency Symbol

If the source contains: typescript import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

To locate the definition of StdioServerTransport, starting at column index 10, the input payload should be:

{ "file_path": "~/my-mcp-project/src/index.ts", "line_content": "import { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";", "column_number": 10 }

This request yields a result structure detailing the origin, such as:

[ { "file": "~/my-mcp-project/node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio.d.ts", "type": "Definition", "location": "Line 9, Column 22", "codeSnippet": " 8 /\n 9 > export declare class StdioServerTransport implements Transport {\n 10 + private _stdin;\n 11 + private _stdout;\n 12 + private _readBuffer;\n 13 + private _started;\n 14 + constructor(_stdin?: Readable, _stdout?: Writable);\n 15 + onclose?: () => void;\n 16 + onerror?: (error: Error) => void;\n 17 + onmessage?: (message: JSONRPCMessage) => void;\n 18 + _ondata: (chunk: Buffer) => void;\n 19 + _onerror: (error: Error) => void;\n 20 + /\n 21 + * Starts listening for messages on stdin.\n 22 + /\n 23 + start(): Promise;\n 24 + private processReadBuffer;\n 25 + close(): Promise;\n 26 + send(message: JSONRPCMessage): Promise;\n 27 }\n" } ]

1. Resolving a Local Declaration

In the scenario of a local class instantiation: typescript class MyService { private transport: StdioServerTransport; }

To find the base definition of StdioServerTransport (starting at column 20), submit:

{ "file_path": "/path/to/project/src/service.ts", "line_content": " private transport: StdioServerTransport;", "column_number": 20 }

Output Schema

The utility returns a JSON array containing objects detailing: - The canonical file identifier where the definition resides. - The numerical line index of the declaration. - The textual excerpt surrounding the definition.

Claude Desktop Visualization

Development Notes

This utility originated from a project scaffold generated by bun init utilizing Bun version 1.2.2. Bun provides a high-performance, consolidated runtime for JavaScript operations.

Local Debugging Execution

Execute the backend interactively using Bun: bash bun run index.ts

Licensing

[Insert your chosen license document details here]

Contribution Guidelines

[Insert contribution instructions here]

WIKIPEDIA: XMLHttpRequest (XHR) represents an application programming interface, structured as a JavaScript object, designed to facilitate the transmission of HTTP requests from a web browser to a remote server. Its methods enable browser-based applications to initiate server communications subsequent to page loading completion, and subsequently retrieve relayed data. XMLHttpRequest is a fundamental constituent of the Ajax programming paradigm. Prior to Ajax adoption, standard hyperlinks and form submissions constituted the principal means of server interchange, frequently resulting in the full replacement of the currently displayed page.

== Historical Context == The underlying concept for XMLHttpRequest was first formulated in the year 2000 by the development team at Microsoft Outlook. This concept was subsequently realized and integrated into the Internet Explorer 5 browser release (1999). However, the initial invocation syntax did not employ the XMLHttpRequest identifier; instead, developers utilized the ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP") object instantiations. As of Internet Explorer 7 (released in 2006), universal support for the standard XMLHttpRequest identifier has been established across all contemporary browsers. The XMLHttpRequest identifier has since become the de facto standard utilized by all major browser engines, including Mozilla's Gecko rendering engine (adopted in 2002), Safari version 1.2 (2004), and Opera version 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) published the initial Working Draft specification pertaining to the XMLHttpRequest object on April 5, 2006. Subsequently, on February 25, 2008, the W3C issued the Level 2 specification Working Draft. This Level 2 revision introduced enhancements such as methods for tracking event progression, mechanisms for facilitating cross-site requests, and support for processing raw byte streams. By the close of 2011, the features defined in the Level 2 specification were merged back into the primary specification document. In late 2012, responsibility for ongoing maintenance was transferred to the WHATWG group, which maintains a continuously updated living document utilizing the Web IDL specification language.

== Operational Methodology == Generally, dispatching a network request using XMLHttpRequest involves several sequential programming stages.

First, an XMLHttpRequest object instance must be created by invoking its constructor: Next, the open method is called to define the transaction type (e.g., GET/POST), specify the target URI, and mandate whether the operation should be synchronous or asynchronous: For asynchronous operations, an event handler must be configured to receive notifications regarding changes in the request's state: The transmission is initiated by executing the send method, optionally passing payload data: Finally, the system must listen to state transitions via the registered event listener. Upon successful server data receipt, the payload is typically housed in the responseText attribute. When the object concludes its processing, its state transitions to 4, the terminal "done" state. Beyond these fundamental steps, XMLHttpRequest provides numerous configuration levers to govern request transmission parameters and response handling. Custom header fields can be programmatically injected into the request to communicate server expectations, and data can be uploaded by including it within the send argument. The incoming response data can be parsed directly from JSON format into functional JavaScript objects, or processed incrementally as data streams arrive rather than waiting for the entire transmission to conclude. Moreover, a request can be forcibly terminated prematurely or configured with a time limit to ensure failure upon timeout.

== Inter-Origin Communication ==

In the nascent phases of the World Wide Web's evolution, it was recognized that mechanisms existed allowing breaches of the same-origin policy, which severely restricted client-side script access to resources outside the originating domain, leading to potential sec