Stimulus Docs MCP Server

Instructions

Implementation Reference

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

  The core handler function that executes the "reference-lifecycle" tool logic. It reads the markdown content for the specific file (lifecycle_callbacks.md) using readMarkdownFile and returns it as an MCP text content block, with fallback error handling. This handler is shared across all documentation tools.
  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:17-45 (registration)

  Dynamically registers the MCP tool named "reference-lifecycle" (and other doc tools) by iterating over the docFiles array from config.ts and calling server.tool with the name, description, and shared handler function.
  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/config.ts:80-84 (registration)

  Tool definition entry in docFiles array that specifies the name 'reference-lifecycle', description, folder 'reference', and file 'lifecycle_callbacks.md' used for registration and content retrieval.
  { folder: 'reference', file: 'lifecycle_callbacks.md', name: 'reference-lifecycle', description: 'Controller lifecycle callbacks reference - covers connect(), disconnect(), and target connection/disconnection callbacks for managing controller state' },
• src/documentReader.ts:14-61 (helper)

  Supporting utility function that implements the file reading logic for documentation files. Supports caching based on GitHub main branch commit, fetches from GitHub API, with local file fallback. Called by the tool handler to retrieve the content of lifecycle_callbacks.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})`); } } }