docs: fundamental knowledge (#30)

Author: huozhi

package.json

@@ -16,7 +16,8 @@
   ],
   "scripts": {
     "dev": "tsc --watch",
-    "build": "tsc && cp -r src/mcp-prompts/*.md dist/mcp-prompts/ && cp -r src/mcp-resources/nextjs-16-knowledge dist/mcp-resources/",
+    "copy-resources": "node scripts/copy-resources.js",
+    "build": "tsc && npm run copy-resources",
     "prepublishOnly": "pnpm run clean && pnpm run build",
     "clean": "rm -rf dist",
     "test": "vitest run",

scripts/copy-resources.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * Copy resources script
+ * Copies all MCP resource files and directories from src to dist
+ *
+ * Usage: node scripts/copy-resources.js
+ */
+
+const fs = require('fs')
+const path = require('path')
+
+// Define resources to copy
+const resources = [
+  {
+    type: 'files',
+    src: 'src/mcp-prompts/*.md',
+    dest: 'dist/mcp-prompts/'
+  },
+  {
+    type: 'dir',
+    src: 'src/mcp-resources/nextjs-16-knowledge',
+    dest: 'dist/mcp-resources/nextjs-16-knowledge'
+  },
+  {
+    type: 'dir',
+    src: 'src/mcp-resources/nextjs-fundamentals-knowledge',
+    dest: 'dist/mcp-resources/nextjs-fundamentals-knowledge'
+  }
+]
+
+/**
+ * Copy a file
+ */
+function copyFile(src, dest) {
+  const destDir = path.dirname(dest)
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true })
+  }
+  fs.copyFileSync(src, dest)
+  console.log(`  ✓ ${path.relative(process.cwd(), dest)}`)
+}
+
+/**
+ * Copy files matching a glob pattern
+ */
+function copyFiles(pattern, destDir) {
+  const srcDir = path.dirname(pattern)
+  const filename = path.basename(pattern)
+
+  if (!fs.existsSync(srcDir)) {
+    console.warn(`  ⚠ Source directory not found: ${srcDir}`)
+    return
+  }
+
+  const files = fs.readdirSync(srcDir).filter(file => {
+    if (filename === '*.md') return file.endsWith('.md')
+    return file === filename
+  })
+
+  if (files.length === 0) {
+    console.warn(`  ⚠ No files matching ${pattern}`)
+    return
+  }
+
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true })
+  }
+
+  files.forEach(file => {
+    const src = path.join(srcDir, file)
+    const dest = path.join(destDir, file)
+    copyFile(src, dest)
+  })
+}
+
+/**
+ * Copy a directory recursively
+ */
+function copyDir(src, dest) {
+  if (!fs.existsSync(src)) {
+    console.warn(`  ⚠ Source directory not found: ${src}`)
+    return
+  }
+
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true })
+  }
+
+  const items = fs.readdirSync(src)
+
+  items.forEach(item => {
+    const srcPath = path.join(src, item)
+    const destPath = path.join(dest, item)
+    const stat = fs.statSync(srcPath)
+
+    if (stat.isDirectory()) {
+      copyDir(srcPath, destPath)
+    } else {
+      copyFile(srcPath, destPath)
+    }
+  })
+}
+
+/**
+ * Main function
+ */
+function main() {
+  console.log('📦 Copying MCP resources...\n')
+
+  resources.forEach(resource => {
+    if (resource.type === 'files') {
+      console.log(`Copying markdown files: ${resource.src}`)
+      copyFiles(resource.src, resource.dest)
+    } else if (resource.type === 'dir') {
+      console.log(`Copying directory: ${resource.src}`)
+      copyDir(resource.src, resource.dest)
+    }
+  })
+
+  console.log('\n✅ Resources copied successfully!')
+}
+
+main()

src/index.ts

@@ -22,6 +22,11 @@ import {
   readKnowledgeSection,
   isNextjs16KnowledgeUri,
 } from "./mcp-resources/nextjs-16-knowledge.js"
+import {
+  getNextjsFundamentalsResources,
+  readFundamentalsSection,
+  isNextjsFundamentalsUri,
+} from "./mcp-resources/nextjs-fundamentals-knowledge.js"
 
 async function main() {
   // Create MCP server instance
@@ -123,7 +128,9 @@ async function main() {
 
   // Register resources/list handler
   server.setRequestHandler(ListResourcesRequestSchema, async () => {
-    const resources = getNextjs16KnowledgeResources()
+    const nextjs16Resources = getNextjs16KnowledgeResources()
+    const fundamentalsResources = getNextjsFundamentalsResources()
+    const resources = [...nextjs16Resources, ...fundamentalsResources]
 
     return { resources }
   })
@@ -132,12 +139,16 @@ async function main() {
   server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
     const { uri } = request.params
 
-    if (!isNextjs16KnowledgeUri(uri)) {
-      throw new Error(`Unknown resource URI: ${uri}`)
-    }
-
     try {
-      const content = readKnowledgeSection(uri)
+      let content: string
+
+      if (isNextjs16KnowledgeUri(uri)) {
+        content = readKnowledgeSection(uri)
+      } else if (isNextjsFundamentalsUri(uri)) {
+        content = readFundamentalsSection(uri)
+      } else {
+        throw new Error(`Unknown resource URI: ${uri}`)
+      }
 
       return {
         contents: [

src/mcp-resources/nextjs-fundamentals-knowledge.ts

@@ -0,0 +1,70 @@
+import type { Resource } from "@modelcontextprotocol/sdk/types.js"
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+/**
+ * Next.js Fundamentals Knowledge Base Resources
+ *
+ * These resources provide comprehensive documentation about fundamental Next.js
+ * concepts that are often confusing for developers, split into logical sections
+ * for efficient context management.
+ */
+
+export interface FundamentalsSection {
+  file: string
+  uri: string
+  name: string
+  description: string
+  mimeType: string
+}
+
+export const NEXTJS_FUNDAMENTALS_SECTIONS: FundamentalsSection[] = [
+  {
+    file: "01-use-client.md",
+    uri: "nextjs-fundamentals://knowledge/use-client",
+    name: "Understanding 'use client' Directive",
+    description:
+      "Learn when and why to use 'use client' in Server Components. Includes: when to mark components as client-only, why props must be serializable (functions/classes can't cross server-client boundary), composition patterns (moving 'use client' down tree, passing Server Components as children, context providers), common anti-patterns and fixes (wrapping entire app, passing functions from server), Server Actions as alternative to callbacks, React hooks that require 'use client', browser APIs, optimization checklist, and decision tree for Server vs Client components. Use this when confused about server/client boundaries, serialization errors, hydration issues, or deciding where to add 'use client'",
+    mimeType: "text/markdown",
+  },
+]
+
+/**
+ * Convert a fundamentals section definition to an MCP Resource
+ */
+export function fundamentalsSectionToResource(section: FundamentalsSection): Resource {
+  return {
+    uri: section.uri,
+    name: section.name,
+    description: section.description,
+    mimeType: section.mimeType,
+  }
+}
+
+/**
+ * Get all available Next.js fundamentals resources
+ */
+export function getNextjsFundamentalsResources(): Resource[] {
+  return NEXTJS_FUNDAMENTALS_SECTIONS.map(fundamentalsSectionToResource)
+}
+
+/**
+ * Read the content of a specific fundamentals section
+ */
+export function readFundamentalsSection(uri: string): string {
+  const section = NEXTJS_FUNDAMENTALS_SECTIONS.find((s) => s.uri === uri)
+
+  if (!section) {
+    throw new Error(`Unknown fundamentals section: ${uri}`)
+  }
+
+  const filePath = join(__dirname, "nextjs-fundamentals-knowledge", section.file)
+  return readFileSync(filePath, "utf-8")
+}
+
+/**
+ * Check if a URI is a Next.js fundamentals knowledge resource
+ */
+export function isNextjsFundamentalsUri(uri: string): boolean {
+  return uri.startsWith("nextjs-fundamentals://knowledge/")
+}