reference-typescript

Instructions

Implementation Reference

• src/index.ts:17-45 (registration)

  Dynamically registers the 'reference-typescript' MCP tool (and all others) by iterating over docFiles config, calling server.tool with the tool name, description, and a handler that reads the corresponding markdown file.

  docFiles.forEach(({ folder, file, name, description }) => {
    server.tool(
      name,
      description,
      async () => {
        try {
          const content = await readMarkdownFile(path.join(folder, file));
          return {
            content: [
              {
                type: "text",
                text: content
              }
            ]
          };
        } catch (error) {
          const errorMessage = error instanceof Error ? error.message : String(error);
          return {
            content: [
              {
                type: "text",
                text: `Error reading ${file}: ${errorMessage}`
              }
            ]
          };
        }
      }
    );
  });

• src/index.ts:21-43 (handler)

  The handler function executed when the 'reference-typescript' tool is called. Reads the markdown content from 'reference/using_typescript.md' and returns it as MCP content block, with fallback error message.

  async () => {
    try {
      const content = await readMarkdownFile(path.join(folder, file));
      return {
        content: [
          {
            type: "text",
            text: content
          }
        ]
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      return {
        content: [
          {
            type: "text",
            text: `Error reading ${file}: ${errorMessage}`
          }
        ]
      };
    }
  }

• src/documentReader.ts:14-61 (helper)

  Core helper function that implements file reading logic: checks cache first, then fetches from GitHub (with caching), falls back to local files. Called by the tool handler with filename 'reference/using_typescript.md'.

  export async function readMarkdownFile(filename: string): Promise<string> {
    const filePath = path.join(docsFolder, filename);
    if (!filePath.startsWith(docsFolder)) {
      throw new Error("Invalid file path");
    }
    
    // Get current commit info if we don't have it yet
    if (!mainBranchInfo) {
      try {
        const commitInfo = await fetchMainBranchInformation();
        const cacheKey = `${commitInfo.sha.substring(0, 7)}-${commitInfo.timestamp}`;
        mainBranchInfo = {
          ...commitInfo,
          cacheKey
        };
      } catch (shaError) {
        console.error('Failed to get GitHub commit info, falling back to direct fetch');
      }
    }
    
    // Try to read from cache first if we have commit info
    if (mainBranchInfo) {
      const cachedFilePath = path.join(cacheFolder, mainBranchInfo.cacheKey, filename);
      try {
        const content = await fs.promises.readFile(cachedFilePath, "utf-8");
        console.error(`Using cached content for ${mainBranchInfo.cacheKey}: ${filename}`);
        return content;
      } catch (cacheError) {
        // Cache miss, continue to fetch from GitHub
      }
    }
    
    // Fetch from GitHub
    try {
      return await fetchFromGitHub(filename, mainBranchInfo?.cacheKey);
    } catch (githubError) {
      console.error(`GitHub fetch failed: ${githubError}, attempting to read from local files...`);
      
      // Fallback: read from local files
      try {
        return await fs.promises.readFile(filePath, "utf-8");
      } catch (localError) {
        const githubErrorMessage = githubError instanceof Error ? githubError.message : String(githubError);
        const localErrorMessage = localError instanceof Error ? localError.message : String(localError);
        throw new Error(`Failed to read file from GitHub (${githubErrorMessage}) and locally (${localErrorMessage})`);
      }
    }
  }

• src/config.ts:95-99 (schema)

  Configuration entry defining the 'reference-typescript' tool: specifies the source file path, tool name, and description used in registration.

  {
    folder: 'reference', file: 'using_typescript.md',
    name: 'reference-typescript',
    description: 'TypeScript integration guide - covers type definitions, strongly typed targets/values/outlets, and best practices for using Stimulus with TypeScript'
  },

• src/utils.ts:50-74 (helper)

  Supporting utility for fetching markdown content directly from GitHub raw URL and caching it locally, used by readMarkdownFile.

  export async function fetchFromGitHub(filename: string, cacheKey?: string): Promise<string> {
    const githubUrl = `${GITHUB_RAW_BASE_URL}/${filename}`;
    const response = await fetch(githubUrl);
    
    if (!response.ok) {
      throw new Error(`GitHub fetch failed: ${response.status} ${response.statusText}`);
    }
    
    const content = await response.text();
    
    // Cache the content with cache key if available
    if (cacheKey) {
      try {
        const cacheFolder = path.resolve(__dirname, "../cache");
        const cachedFilePath = path.join(cacheFolder, cacheKey, filename);
        await fs.promises.mkdir(path.dirname(cachedFilePath), { recursive: true });
        await fs.promises.writeFile(cachedFilePath, content, "utf-8");
        console.error(`Cached GitHub content for ${cacheKey}: ${filename}`);
      } catch (cacheError) {
        console.error(`Failed to cache content: ${cacheError}`);
      }
    }
    
    return content;
  }