reduce prompt token size by reorganizing the knowledge (#64)

Author: huozhi

.github/workflows/typecheck.yml .github/workflows/ci.yml.github/workflows/typecheck.yml renamed to .github/workflows/ci.yml

@@ -1,4 +1,4 @@
-name: Type Check
+name: CI
 
 on:
   pull_request:
@@ -9,7 +9,7 @@ on:
       - main
 
 jobs:
-  typecheck:
+  test:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
@@ -29,3 +29,7 @@ jobs:
 
       - name: Run type check
         run: pnpm run typecheck
+
+      - name: Run tests
+        run: pnpm test
+

package.json

@@ -26,7 +26,8 @@
     "prepublishOnly": "pnpm run clean && pnpm run build",
     "clean": "rm -rf dist",
     "start": "node dist/stdio.js",
-    "test": "vitest run --exclude '**/upgrade.test.ts'",
+    "test": "vitest run --exclude 'test/e2e/**'",
+    "test:e2e": "vitest run test/e2e",
     "eval": "vitest run test/e2e/upgrade.test.ts",
     "typecheck": "tsc --noEmit"
   },

scripts/copy-resources.js

@@ -1,90 +1,81 @@
 #!/usr/bin/env node
 /**
  * Copy resources script
- * Scans all .md files in src/ and copies them to a flat dist/resources/ directory
- * Ensures all .md filenames are unique
+ * Preserves directory structure from src/resources/ to dist/resources/
+ * Copies .md files from src/prompts/ to dist/resources/prompts/
  *
  * Usage: node scripts/copy-resources.js
  */
 
 const fs = require('fs')
 const path = require('path')
 
-const SRC_DIR = 'src'
+const SRC_RESOURCES_DIR = 'src/resources'
+const SRC_PROMPTS_DIR = 'src/prompts'
 const DEST_DIR = 'dist/resources'
 
 /**
- * Recursively find all .md files in a directory
+ * Recursively copy .md files while preserving directory structure
  */
-function findMarkdownFiles(dir, fileList = []) {
-  const files = fs.readdirSync(dir)
+function copyMarkdownFiles(srcDir, destDir, relativePath = '') {
+  if (!fs.existsSync(srcDir)) {
+    return []
+  }
+
+  const files = fs.readdirSync(srcDir)
+  const copiedFiles = []
 
   files.forEach(file => {
-    const filePath = path.join(dir, file)
-    const stat = fs.statSync(filePath)
+    const srcPath = path.join(srcDir, file)
+    const stat = fs.statSync(srcPath)
 
     if (stat.isDirectory()) {
-      findMarkdownFiles(filePath, fileList)
+      // Recursively copy subdirectories
+      const newRelativePath = path.join(relativePath, file)
+      const copied = copyMarkdownFiles(srcPath, destDir, newRelativePath)
+      copiedFiles.push(...copied)
     } else if (file.endsWith('.md')) {
-      fileList.push(filePath)
+      // Copy .md file preserving structure
+      const destPath = path.join(destDir, relativePath, file)
+      const destDirPath = path.dirname(destPath)
+      
+      if (!fs.existsSync(destDirPath)) {
+        fs.mkdirSync(destDirPath, { recursive: true })
+      }
+      
+      fs.copyFileSync(srcPath, destPath)
+      const relativeDestPath = path.relative(destDir, destPath)
+      copiedFiles.push(relativeDestPath)
     }
   })
 
-  return fileList
-}
-
-/**
- * Check for duplicate filenames
- */
-function checkDuplicates(files) {
-  const filenames = new Map()
-  const duplicates = []
-
-  files.forEach(filePath => {
-    const filename = path.basename(filePath)
-    if (filenames.has(filename)) {
-      duplicates.push({
-        filename,
-        paths: [filenames.get(filename), filePath]
-      })
-    } else {
-      filenames.set(filename, filePath)
-    }
-  })
-
-  return duplicates
+  return copiedFiles
 }
 
 /**
  * Main function
  */
 function main() {
-  console.log('📦 Scanning for markdown files in src/...\n')
-
-  const markdownFiles = findMarkdownFiles(SRC_DIR)
-  console.log(`Found ${markdownFiles.length} markdown files\n`)
-
-  const duplicates = checkDuplicates(markdownFiles)
-  if (duplicates.length > 0) {
-    console.error('❌ Error: Duplicate markdown filenames found:\n')
-    duplicates.forEach(({ filename, paths }) => {
-      console.error(`  ${filename}:`)
-      paths.forEach(p => console.error(`    - ${p}`))
-    })
-    console.error('\nAll .md files must have unique names.')
-    process.exit(1)
-  }
+  console.log('📦 Copying markdown files with preserved structure...\n')
 
+  // Ensure destination directory exists
   if (!fs.existsSync(DEST_DIR)) {
     fs.mkdirSync(DEST_DIR, { recursive: true })
   }
 
-  console.log(`Copying to ${DEST_DIR}...\n`)
-  markdownFiles.forEach(srcPath => {
-    const filename = path.basename(srcPath)
-    const destPath = path.join(DEST_DIR, filename)
-    fs.copyFileSync(srcPath, destPath)
-    console.log(`  ✓ ${filename}`)
+  // Copy resources with preserved structure
+  console.log('Copying from src/resources/...')
+  const resourceFiles = copyMarkdownFiles(SRC_RESOURCES_DIR, DEST_DIR)
+  
+  // Copy prompt .md files to prompts/ subdirectory
+  console.log('Copying from src/prompts/...')
+  const promptFiles = copyMarkdownFiles(SRC_PROMPTS_DIR, DEST_DIR, 'prompts')
+
+  const allFiles = [...resourceFiles, ...promptFiles]
+  
+  console.log(`\nCopied ${allFiles.length} files:\n`)
+  allFiles.forEach(file => {
+    console.log(`  ✓ ${file}`)
   })
 
   console.log('\n✅ Resources copied successfully!')

src/prompts/enable-cache-components-prompt.md

@@ -10,44 +10,44 @@ PROJECT: {{PROJECT_PATH}}
 
 The following resources are available from the Next.js MCP server. Load them on-demand to reduce token usage:
 
-- `nextjs16://knowledge/overview` - Critical errors AI agents make, quick reference (START HERE)
-- `nextjs16://knowledge/core-mechanics` - Fundamental paradigm shift, cacheComponents
-- `nextjs16://knowledge/public-caches` - Public cache mechanics using 'use cache'
-- `nextjs16://knowledge/private-caches` - Private cache mechanics using 'use cache: private'
-- `nextjs16://knowledge/runtime-prefetching` - Prefetch configuration and stale time rules
-- `nextjs16://knowledge/request-apis` - Async params, searchParams, cookies(), headers()
-- `nextjs16://knowledge/cache-invalidation` - updateTag(), revalidateTag() patterns
-- `nextjs16://knowledge/advanced-patterns` - cacheLife(), cacheTag(), draft mode
-- `nextjs16://knowledge/build-behavior` - What gets prerendered, static shells
-- `nextjs16://knowledge/error-patterns` - Common errors and solutions
-- `nextjs16://knowledge/test-patterns` - Real test-driven patterns from 125+ fixtures
-- `nextjs16://knowledge/reference` - Mental models, API reference, checklists
+- `cache-components://overview` - Critical errors AI agents make, quick reference (START HERE)
+- `cache-components://core-mechanics` - Fundamental paradigm shift, cacheComponents
+- `cache-components://public-caches` - Public cache mechanics using 'use cache'
+- `cache-components://private-caches` - Private cache mechanics using 'use cache: private'
+- `cache-components://runtime-prefetching` - Prefetch configuration and stale time rules
+- `cache-components://request-apis` - Async params, searchParams, cookies(), headers()
+- `cache-components://cache-invalidation` - updateTag(), revalidateTag() patterns
+- `cache-components://advanced-patterns` - cacheLife(), cacheTag(), draft mode
+- `cache-components://build-behavior` - What gets prerendered, static shells
+- `cache-components://error-patterns` - Common errors and solutions
+- `cache-components://test-patterns` - Real test-driven patterns from 125+ fixtures
+- `cache-components://reference` - Mental models, API reference, checklists
 
 **How to Access Resources (MANDATORY - ALWAYS LOAD):**
 
-Resources use the URI scheme `nextjs16://knowledge/...` and are served by this MCP server.
+Resources use the URI scheme `cache-components://...` and are served by this MCP server.
 
 **CRITICAL: You MUST load resources at each phase phase - this is not optional.**
 
 To load a resource, use the ReadMcpResourceTool with:
 - server: `"next-devtools"` (or whatever your server is configured as)
-- uri: `"nextjs16://knowledge/[resource-name]"` from the list above
+- uri: `"cache-components://[resource-name]"` from the list above
 
 **MANDATORY Resource Loading Schedule:**
 
 You MUST load these resources at the specified phases:
 
-- **BEFORE Phase 1-2:** ALWAYS load `nextjs16://knowledge/overview` first
+- **BEFORE Phase 1-2:** ALWAYS load `cache-components://overview` first
   - Provides critical context and error patterns AI agents make
   - Must be loaded before any configuration changes
 
 - **During Phase 5 (Error Fixing):** ALWAYS load error-specific resources as needed
-  - When fixing blocking route errors → Load `nextjs16://knowledge/error-patterns`
-  - When configuring caching → Load `nextjs16://knowledge/advanced-patterns`
-  - When using dynamic params → Load `nextjs16://knowledge/core-mechanics`
+  - When fixing blocking route errors → Load `cache-components://error-patterns`
+  - When configuring caching → Load `cache-components://advanced-patterns`
+  - When using dynamic params → Load `cache-components://core-mechanics`
   - Do NOT guess or use generic patterns - load the specific resource
 
-- **During Phase 6 (Verification):** ALWAYS load `nextjs16://knowledge/build-behavior`
+- **During Phase 6 (Verification):** ALWAYS load `cache-components://build-behavior`
   - Provides build verification strategies and troubleshooting
 
 **Why This Matters:**
@@ -213,7 +213,7 @@ Then navigate to **"Cache Components Examples"** → **"Decision Guide: Static v
 
 BEFORE doing anything, you MUST load:
 ```
-ReadMcpResourceTool(server="next-devtools", uri="nextjs16://knowledge/overview")
+ReadMcpResourceTool(server="next-devtools", uri="cache-components://overview")
 ```
 
 This provides critical context about Cache Components and common mistakes.
@@ -428,8 +428,8 @@ Build verification is always reliable and doesn't require dev server or browser
 
 You MUST load these resources to understand errors and fix them correctly:
 ```
-ReadMcpResourceTool(server="next-devtools", uri="nextjs16://knowledge/error-patterns")
-ReadMcpResourceTool(server="next-devtools", uri="nextjs16://knowledge/advanced-patterns")
+ReadMcpResourceTool(server="next-devtools", uri="cache-components://error-patterns")
+ReadMcpResourceTool(server="next-devtools", uri="cache-components://advanced-patterns")
 ```
 
 Do NOT guess or apply generic patterns. Use the exact code examples and strategies from these resources.
@@ -926,7 +926,7 @@ Then:
 
 You MUST load:
 ```
-ReadMcpResourceTool(server="next-devtools", uri="nextjs16://knowledge/build-behavior")
+ReadMcpResourceTool(server="next-devtools", uri="cache-components://build-behavior")
 ```
 
 This provides build verification strategies and troubleshooting guidance.

src/prompts/enable-cache-components.ts

@@ -1,7 +1,6 @@
 import { type InferSchema, type PromptMetadata } from "xmcp"
 import { z } from "zod"
 import { readResourceFile } from "../_internal/resource-path"
-import { loadKnowledgeResources } from "../_internal/resource-loader"
 
 export const schema = {
   project_path: z
@@ -21,48 +20,10 @@ export const metadata: PromptMetadata = {
 export default function getEnableCacheComponentsPrompt(args: InferSchema<typeof schema>): string {
   const projectPath = args.project_path || process.cwd()
 
-  let promptTemplate = readResourceFile("enable-cache-components-prompt.md")
-
-  const resources = loadKnowledgeResources()
-
-  function toTitleCase(camelCase: string): string {
-    return camelCase
-      .replace(/([A-Z])/g, " $1")
-      .replace(/^./, (str) => str.toUpperCase())
-      .trim()
-  }
-
-  const resourceEntries = Object.entries(resources)
-    .map(
-      ([key, content], index) => `
-## 📚 Resource ${index + 1}: ${toTitleCase(key)}
-${content}
-
----`
-    )
-    .join("\n")
-
-  const embeddedKnowledge = `
-# ═══════════════════════════════════════════════════════════════════
-# EMBEDDED KNOWLEDGE BASE (Preloaded for Cache Components Enablement)
-# ═══════════════════════════════════════════════════════════════════
-${resourceEntries}
-
-# ═══════════════════════════════════════════════════════════════════
-# END OF KNOWLEDGE BASE
-# ═══════════════════════════════════════════════════════════════════
-`
+  let promptTemplate = readResourceFile("prompts/enable-cache-components-prompt.md")
 
+  // Replace template variables
   promptTemplate = promptTemplate.replace(/{{PROJECT_PATH}}/g, projectPath)
 
-  const insertionPoint = promptTemplate.indexOf("---\n\n# ENABLE WORKFLOW:")
-  if (insertionPoint !== -1) {
-    promptTemplate =
-      promptTemplate.slice(0, insertionPoint) +
-      embeddedKnowledge +
-      "\n" +
-      promptTemplate.slice(insertionPoint)
-  }
-
   return promptTemplate
 }

src/prompts/upgrade-nextjs-16.ts

@@ -40,7 +40,7 @@ export default function getUpgradeNextjs16Prompt(args: InferSchema<typeof schema
 
   const codemodCommandNote = `**Note**: Next.js 16 stable (version ${version}) is now available.`
 
-  let promptTemplate = readResourceFile("upgrade-nextjs-16-prompt.md")
+  let promptTemplate = readResourceFile("prompts/upgrade-nextjs-16-prompt.md")
 
   // TODO: load next.js16 knowledge base resources
   promptTemplate = promptTemplate.replace(/{{PROJECT_PATH}}/g, projectPath)