MCP Multi-Context Hook Generator

This repo is fully modular, repo-agnostic, and can adapt dynamically to any frontend project. Full plan for a ready-to-use modular MCP prototype repo that adapts to any frontend project and can generate typed code matching its conventions. I’ll outline the repo structure, include all core files, and provide runnable code. # MCP - Multi-Context Hook Generator This tool automatically generates typed React hooks for your **Next.js + TypeScript project**, supporting: - Next.js REST API routes - API client functions - GraphQL queries & mutations - SWR / SWR Infinite - React Query --- ## Features - **Auto-imports API client functions**: No manual injection needed - **GraphQL extraction**: Generates hooks with inline gql strings - **SWR Infinite support**: For REST and GraphQL paginated queries - **Typed hooks**: Fully typed with return types from your API - **Flexible**: Works for any repo structure --- ## Installation ```bash npm install swr @tanstack/react-query @apollo/client ts-morph glob ``` --- ## Repository Structure MCP-Server ├─ crawler/ │ └─ api.ts │ • Scans app/api and api/ folders │ • Detects exported functions │ • Extracts: │ - methods │ - responseType │ - kind (REST / GraphQL) │ - environment (server / client / universal) │ • Returns ApiRoute[] │ ├─ generator/ │ └─ hooks.ts │ • Consumes ApiRoute[] │ • Generates typed hooks: │ - useSWR / useSWRInfinite (client) │ - useQuery / useMutation (GraphQL) │ - server-only functions │ • Supports REST, API clients, GraphQL queries/mutations │ ├─ mcp/ │ ├─ pageAnalyzer.ts │ │ • Scans app/pages or app/ for page.tsx files │ │ • Detects which hooks are used in each page │ │ • Reads environment of each hook │ │ • Infers render mode: SSR / ISR / CSR / SSG │ │ │ └─ generateDocs.ts │ • Produces Markdown per page: │ - Suggested render mode │ - Reasoning │ - Hook usage table │ - Optional SSR/ISR boilerplate │ ├─ CLI / entry point (mcp-server.ts) │ • Runs pipeline: │ 1. crawlApi(rootDir) │ 2. generateHooks(apiRoutes, options) │ 3. analyzePages(rootDir, apiRoutes) │ 4. generateDocs(outputDir, analyses) │ • Output: │ - hooks.ts (typed hooks) │ - mcp-docs/ (developer documentation) │ └─ config/ └─ mcp.config.ts • Options: - SWR infinite usage - GraphQL infinite queries - Page folders to analyze - Output directories --- How the Modules Interact Crawler (api.ts) Inputs: rootDir of project Outputs: ApiRoute[] with method names, environment, response type, kind Hooks Generator (hooks.ts) Inputs: ApiRoute[] Outputs: hooks.ts (typed, environment-aware hooks) Environment-aware: generates server-only, client-only, or universal hooks Page Analyzer (pageAnalyzer.ts) Inputs: ApiRoute[] + page files (page.tsx) Outputs: PageAnalysis[] with inferred render mode Logic: Mixed hooks → SSR Server-only → SSR/ISR Client-only → CSR No hooks → SSG Docs Generator (generateDocs.ts) Inputs: PageAnalysis[] Outputs: Markdown docs per page Includes: Render mode suggestion Reason Hook usage table Optional SSR/ISR boilerplate MCP-Server CLI Runs the full pipeline in sequence Provides a developer-ready output: Hooks to import and use Documentation to guide render mode choices ## How to Run ```bash pnpm install pnpm start # runs full MCP pipeline pnpm crawl # runs only crawler pnpm generate-hooks # runs only hooks generator ``` ## MCP automatically crawls the project: components, API routes, GraphQL, types AI tools (Copilot/ChatGPT) can query MCP for typed resources. Use scaffold-swr-hook tool to generate typed hooks dynamically. ## How It Works 1.Run MCP → it scans the repo and builds a universal project model. 2.Use tools dynamically via MCP API: SWR Hook: { "tool":"scaffold-swr-hook", "args":{"path":"/api/users","typeName":"User[]"} } GraphQL Hook: { "tool":"scaffold-graphql-hook", "args":{ "opName":"GetUser", "type":"query", "variablesType":"GetUserQueryVariables", "responseType":"GetUserQuery" } } Page: { "tool":"scaffold-page", "args":{"pageName":"Dashboard","components":["Navbar","UserCard"]} } 3.MCP generates typed hooks or pages matching repo style. 4.AI (Copilot/Cursor) can now query MCP for the latest types, components, API routes. How it Works Crawls the hooks/ folder (or any custom folder). Detects all .ts/.tsx files. Uses ts-morph to parse TypeScript AST. Filters functions starting with use (React hook convention). Infers return types if explicitly typed. Returns an array of: [ { name: "useUser", returnType: "{ data: User | undefined; error: any; isLoading: boolean }", path: "hooks/useUser.ts" }, { name: "useAuth", returnType: "{ user: AuthUser | null; login: Function; logout: Function }", path: "hooks/useAuth.ts" } ] 1️⃣ Basic run (full MCP pipeline, no AI) # Run all steps: crawl APIs, generate hooks, analyze pages, generate docs pnpm start --all Equivalent with npm: npm run start -- --all 2️⃣ Dry-run mode (preview only, no files written) pnpm start --all --dry-run Useful for testing pipeline without touching your repo Logs hook and doc previews to console 3️⃣ Enable AI cursor suggestions (Copilot / OpenAI) pnpm start --all --use-cursor-assist --ai-agent copilot Adds AI guidance comments in hooks (generateHooks.ts) Adds AI suggestions in page docs (generateDocs.ts) You can also pass openai in the CLI if you extend the CLI parsing for an API key 4️⃣ Disable auto render inference pnpm start --all --no-auto-infer Keeps your existing suggestedRenderMode for pages Useful if you want manual control for SSR/CSR/ISR 5️⃣ Combine dry-run + AI + custom agent pnpm start --all --dry-run --use-cursor-assist --ai-agent openai Safe preview AI suggestions included No files are written ✅ Notes All flags are optional; --all defaults to running everything. You can mix and match: --hooks --docs to run only specific steps. Dry-run is especially useful for CI pipelines, so you can validate MCP output without committing. MCP CLI Command Matrix Scenario Command Notes Full run, default pnpm start --all Runs all steps: crawl APIs, generate hooks, analyze pages, generate docs. Uses default suggested render modes, no AI guidance. Full run, dry-run preview pnpm start --all --dry-run Previews hooks/docs in console, no files written. Mirrors PR behavior in CI. Enable AI guidance (Copilot) pnpm start --all --use-cursor-assist --ai-agent copilot Adds AI suggestions in hooks/docs. No dry-run. Enable AI guidance (OpenAI) pnpm start --all --use-cursor-assist --ai-agent openai Uses OpenAI agent for suggestions (requires API integration if implemented). Disable auto render inference pnpm start --all --no-auto-infer Keeps your existing suggestedRenderMode values, ignores auto-detection based on server hooks. Partial run (only hooks) pnpm start --hooks Only generates typed hooks, skips pages/docs analysis. Partial run (only docs) pnpm start --docs Only generates docs from previous analysis/hooks, skips API crawling. Dry-run + AI guidance pnpm start --all --dry-run --use-cursor-assist --ai-agent copilot Previews all generated content with AI suggestions, safe for dev branch testing. Custom AI agent pnpm start --all --ai-agent custom Placeholder for your own AI logic or local LLM integration. Tips for Devs Dry-run first when testing new hooks or pages. Use AI guidance to get suggested SSR/ISR/CSR render modes. Partial runs are useful for fast iteration (--hooks or --docs). Auto-infer render should usually be on (--no-auto-infer only if you want manual override). You can combine multiple flags, e.g.: pnpm start --hooks --use-cursor-assist --ai-agent copilot --dry-run 🛠️ MCP Developer Guide The Modular Context Protocol (MCP) pipeline helps developers crawl APIs, generate typed hooks, analyze pages, and produce documentation automatically for Next.js + React projects. This guide explains local usage, AI features, and CI integration. 1️⃣ Installation # Clone your project git clone <your-repo-url> cd <your-repo> # Install dependencies using pnpm (recommended) npm install -g pnpm pnpm install ✅ MCP is fully compatible with npm or yarn, but pnpm is recommended for speed and caching. 2️⃣ Running MCP Locally Full pipeline pnpm start --all Crawls APIs Generates typed hooks (hooks/) Analyzes pages Generates docs (mcp-docs/) with suggested render modes (CSR/SSR/ISR) Dry-run (preview only) pnpm start --all --dry-run Logs hooks/docs previews in console Does not write any files Ideal for testing changes on feature branches Enable AI guidance pnpm start --all --use-cursor-assist --ai-agent copilot Adds AI suggestions for render mode and performance guidance Supported agents: copilot, openai, custom Combine with --dry-run to safely preview AI suggestions without writing files. Disable auto render inference pnpm start --all --no-auto-infer Keeps your existing suggestedRenderMode MCP won’t infer SSR/CSR/ISR based on server hooks Partial runs pnpm start --hooks # Only generate hooks pnpm start --docs # Only generate docs pnpm start --analyze # Only analyze pages Useful for fast iteration during development. 3️⃣ CI/CD Integration MCP integrates with GitHub Actions via .github/workflows/mcp.yml Feature branches run in dry-run mode to preview changes safely Main branch runs real generation and commits updated hooks/docs automatically # Key features - dry-run on PRs/feature branches - AI suggestions enabled - Node_modules + ts-morph cache for large projects - Automatic commit on main branch 4️⃣ Output Structure hooks/ # Generated typed hooks for all API routes mcp-docs/ # Markdown docs per page + summary.md Each page doc includes: Suggested render mode (CSR/SSR/ISR) Hooks used with environment type (client/server/universal) Optional SSR/ISR boilerplate code ⚡ AI guidance comments (if enabled) 5️⃣ Tips for Developers Always run dry-run first when testing new hooks or pages. Use AI guidance to pick optimal render modes. Partial runs help speed up iteration (--hooks / --docs). Feature branches → dry-run; Main branch → commit updates automatically. Large projects: caching node_modules and .mcp-cache speeds up MCP significantly. This README ensures your devs can run MCP locally exactly like CI and take advantage of AI suggestions safely.