handbook-state
Manage and sync state with the DOM using reactive programming patterns in Stimulus JS. Keep values and data attributes consistent for efficient UI updates.
Instructions
Learn how Stimulus manages state through values and data attributes - covers reactive programming patterns and keeping state in sync with the DOM
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- src/config.ts:45-50 (schema)Configuration entry defining the 'handbook-state' tool: specifies name, description, folder ('handbook'), and file ('05_managing_state.md') used for registration.{ folder: 'handbook', file: '05_managing_state.md', name: 'handbook-state', description: 'Learn how Stimulus manages state through values and data attributes - covers reactive programming patterns and keeping state in sync with the DOM' },
- src/index.ts:17-45 (registration)Dynamically registers the 'handbook-state' tool (among others) by iterating over docFiles from config.ts and calling server.tool(name, description, handler).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-41 (handler)Inline handler function executed when 'handbook-state' tool is called: reads markdown file using readMarkdownFile(path.join(folder, file)), returns content as MCP text block or 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)readMarkdownFile function: fetches document content from GitHub (with caching), falls back to local file; used by all doc tool handlers.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})`); } } }