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
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
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
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.