Improve mcp guidance

webpro · webpro · commit 67483f0ac6ea · 2026-06-16T07:07:55.000+02:00
diff --git a/packages/knip/src/reporters/util/configuration-hints.ts b/packages/knip/src/reporters/util/configuration-hints.ts
@@ -99,11 +99,16 @@ interface ProcessedHint extends ConfigurationHint {
   message: string;
 }
 
+const UNCONFIGURED_MIN_FILES = 20;
+const UNCONFIGURED_MIN_RATIO = 0.2;
+
 export const finalizeConfigurationHints = (
   results: Results,
   options: { cwd: string; configFilePath?: string }
 ): ProcessedHint[] => {
-  if (results.counters.files > 20) {
+  const { files, processed } = results.counters;
+  const unusedFileRatio = processed > 0 ? files / processed : 0;
+  if (files > UNCONFIGURED_MIN_FILES && unusedFileRatio > UNCONFIGURED_MIN_RATIO) {
     const workspaces = results.includedWorkspaceDirs
       .sort(byPathDepth)
       .reverse()
diff --git a/packages/mcp-server/src/curated-resources.js b/packages/mcp-server/src/curated-resources.js
@@ -1,24 +1,36 @@
+/** @type {Record<string, { name: string; description: string; path: string; featured?: boolean }>} */
 export const CURATED_RESOURCES = {
-  'getting-started': {
-    name: 'Getting Started',
-    description: 'New to Knip? Start here for installation and first run',
-    path: 'overview/getting-started.mdx',
-  },
   configuration: {
     name: 'Configuration',
     description: 'Understand configuration basics, defaults, and file locations',
     path: 'overview/configuration.md',
   },
+  'configuration-hints': {
+    name: 'Configuration Hints',
+    description: 'Decode the configurationHints from knip-run: each hint type and how to resolve it',
+    path: 'reference/configuration-hints.md',
+  },
   'configuring-project-files': {
     name: 'Configuring Project Files',
     description: 'READ FIRST for unused files or false positives. Covers entry/project patterns',
     path: 'guides/configuring-project-files.md',
   },
   'handling-issues': {
     name: 'Handling Issues',
-    description: 'How to handle each issue type: files, dependencies, exports, types, duplicates',
+    description: 'How to resolve each issue type: files, dependencies, exports, types, duplicates',
     path: 'guides/handling-issues.mdx',
   },
+  'known-issues': {
+    name: 'Known Issues',
+    description: 'Errors or unexpected behavior? Check workarounds for common problems',
+    path: 'reference/known-issues.md',
+  },
+  'issue-types': {
+    name: 'Issue Types',
+    description:
+      'Decode knip-run output: every issue type, what it means and its key (files, dependencies, exports, …)',
+    path: 'reference/issue-types.md',
+  },
   'monorepos-and-workspaces': {
     name: 'Monorepos & Workspaces',
     description: 'Multi-package repo? Configure workspaces and cross-references here',
@@ -29,11 +41,21 @@ export const CURATED_RESOURCES = {
     description: 'Exclude tests, stories, devDependencies with --production and --strict flags',
     path: 'features/production-mode.md',
   },
+  'rules-and-filters': {
+    name: 'Rules & Filters',
+    description: 'Focus or mute issue types with --include/--exclude and rules',
+    path: 'features/rules-and-filters.md',
+  },
   compilers: {
     name: 'Compilers',
     description: 'Using .vue, .svelte, .astro, .mdx files? Configure compilers to parse them',
     path: 'features/compilers.md',
   },
+  'jsdoc-tsdoc-tags': {
+    name: 'JSDoc & TSDoc Tags',
+    description: 'Keep an export but exclude it from the report with @public/@internal and custom tags',
+    path: 'reference/jsdoc-tsdoc-tags.md',
+  },
   'configuration-reference': {
     name: 'Configuration Reference',
     description: 'Complete reference of all config options: entry, project, ignore, plugins, etc.',
@@ -54,9 +76,4 @@ export const CURATED_RESOURCES = {
     description: 'Check if a plugin exists for your tool (Jest, Vitest, ESLint, etc.)',
     path: 'reference/plugins.md',
   },
-  'known-issues': {
-    name: 'Known Issues',
-    description: 'Errors or unexpected behavior? Check workarounds for common problems',
-    path: 'reference/known-issues.md',
-  },
 };
diff --git a/packages/mcp-server/src/texts.js b/packages/mcp-server/src/texts.js
@@ -3,52 +3,57 @@ import { CURATED_RESOURCES } from './curated-resources.js';
 export const WORKFLOW = `Workflow:
 
 1. Read essential documentation resources:
+   - how-knip-works (the mental model: entry files, module graph, reachability)
    - configuring-project-files (must read to configure entry patterns)
    - plugins-explanation (understand entries added by auto-detected plugins)
-   - handling-issues (comprehensive guide to deal with any reported issue type)
+   - handling-issues (comprehensive guide to resolve any reported issue type)
    - configuration-reference (all knip.json configuration options)
-2. Run analysis (knip-run) to get configuration hints and issues
-3. Address the hints by adjusting knip.json
-4. Repeat steps 2-3 until hints are gone and false positives are minimized
+2. Run analysis (knip-run): returns configurationHints (decode with configuration-hints) and issues keyed by type (decode with issue-types)
+3. Address the configuration hints by adjusting knip.json
+4. Repeat steps 2-3 until configuration hints are gone and remaining issues are genuine findings
+
+You're done when there are no configuration hints and the issues are genuine (or zero). Many projects need NO knip.json: Knip auto-detects plugins, so configFile exists:false with zero hints is a good, complete result. Don't add configuration just to have it.
 
 Important notes:
 - For prompts like "run knip" or "clean up codebase" or "no more slop": always run workflow to configure Knip first.
 - If you hit errors (not lint issues), consult: known-issues
-- Before suggesting fixes/solutions, consult: handling-issues and reference/jsdoc-tsdoc-tags
-- For cleanup, consult: features/auto-fix
-- To install Knip and start using it from CLI, consult: getting-started and reference/cli
+- Before suggesting fixes/solutions, consult: handling-issues and jsdoc-tsdoc-tags
+- Prefer specific solutions over "ignore"; to focus or mute issue types, consult: rules-and-filters
+- For cleanup, consult: auto-fix
+- To install Knip and start using it from CLI, consult: getting-started and cli
 - Knip does not remove unused imports/variables inside files (use a linter)
 `;
 
 // pkg.contributes.languageModelTools[0].modelDescription
 export const RUN_KNIP_TOOL_DESCRIPTION = `Run Knip and return configuration hints and issues.
 
 Returns:
+- totalIssues: Total number of issues found (0 = clean)
 - configurationHints: Ordered suggestions to improve configuration (address these first)
-- counters: Summary counts of each issue type
+- counters: Per-issue-type totals
+- maybeUnconfigured: true when a high unused-file count suggests entry/project may be incomplete (review configurationHints)
+- truncated: true when the sample was capped; read counters for totals, or scope with workspace to see the rest
 - enabledPlugins: Auto-detected plugins per workspace
-- files: List of unused files
-- issues: Detailed issues by type (dependencies, exports, types, etc.)
-- configFile: Current config file status
+- files: Unused files (sample, might be capped)
+- issues: Issues per type, i.e. dependencies, exports, types, etc. (sample, capped per type)
+- configFile: Config file status (exists:false is normal when plugins auto-configure)
 
 Options:
 - cwd: Working directory (defaults to the process cwd)
-- workspace: Scope run to array of workspaces
+- workspace: Scope run to array of workspaces (to drill into a package when truncated)
 
 Iterate: adjust knip.json based on hints, run again until no hints remain and false positives are minimized.`;
 
 // pkg.contributes.languageModelTools[1].modelDescription
-export const DOC_TOOL_DESCRIPTION = `Get Knip documentation by topic.
-
-If registered resources are unavailable, use this tool.
+export const DOC_TOOL_DESCRIPTION = `Fetch a Knip doc by topic id, or by any docs path. Consult it to resolve a finding, hint, or error instead of guessing.
 
 Available topics (use these IDs):
 ${Object.entries(CURATED_RESOURCES)
   .map(([id, doc]) => `- ${id}: ${doc.description}`)
   .join('\n')}
+}
 
-Can also fetch any doc by path (e.g. "reference/cli" or "guides/troubleshooting").
-Use this instead of fetching from https://knip.dev.`;
+Full descriptions are registered as MCP resources; any page is also reachable by path (e.g. "guides/troubleshooting"). Use this instead of fetching from https://knip.dev.`;
 
 // pkg.contributes.languageModelTools[1].inputSchema.properties.topic.description
 export const DOC_TOOL_TOPIC_DESCRIPTION =
@@ -61,15 +66,18 @@ export const ERROR_HINT = `For unexpected errors (exit code 2) such as "Error lo
 - Apply a workaround, then run knip-run again`;
 
 export const UNCONFIGURED_HINT =
-  'Issues are suppressed because the project is not yet configured. Reported issues might be false positives. Address configuration hints first, then re-run to get the actual issues.';
+  'Many unused files were found. This often means entry/project patterns are not configured yet (so some results may be false positives), but could mean real dead code. A capped sample of issues is shown — see `counters` for true totals. Address the configurationHints first, then re-run; or scope with `workspace` to analyze one package at a time.';
 
-export const CONFIG_REVIEW_HINT = `Review the existing configuration for potential improvements:
+export const CONFIG_REVIEW_HINT = `Review the configuration for improvements that apply to the issues you see (skip the ones that don't):
 
-- Never use "ignore" patterns (hides real issues!), always prefer specific solutions; other ignore* options are allowed
+- Avoid the broad "ignore" option (file globs); it hides real issues, so prefer specific fixes. Targeted ignoreDependencies/ignoreBinaries/ignoreUnresolved are fine for justified, known false positives
 - Many unused exported types → try ignoreExportsUsedInFile: { interface: true, type: true }
 - Remove ignore patterns that don't match any files
 - Remove redundant ignore patterns — Knip respects .gitignore (node_modules, dist, build, .git)
 - Remove entry patterns covered by config defaults and auto-detected plugins
 - Config files (e.g. vite.config.ts) showing as unused → try enable or disable the plugin explicitly (vite: true)
 - Dependencies matching Node.js builtins: add to ignoreDependencies (e.g. buffer, process)
 - Unresolved imports from path aliases: add paths to Knip config (tsconfig.json semantics)`;
+
+export const CLEAN_HINT =
+  'No issues and no configuration hints: Knip is happy. Many projects need no knip.json (plugins are auto-detected), so this is a complete, successful result with nothing more to configure.';
diff --git a/packages/mcp-server/src/tools.js b/packages/mcp-server/src/tools.js
@@ -3,7 +3,8 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createOptions, createSession, finalizeConfigurationHints, KNIP_CONFIG_LOCATIONS } from 'knip/session';
 import { CURATED_RESOURCES } from './curated-resources.js';
-import { CONFIG_REVIEW_HINT, UNCONFIGURED_HINT } from './texts.js';
+import { CLEAN_HINT, CONFIG_REVIEW_HINT, UNCONFIGURED_HINT } from './texts.js';
+import { transformForAgent } from './transform.js';
 
 export { ERROR_HINT } from './texts.js';
 
@@ -25,32 +26,70 @@ export function getErrorMessage(error) {
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const docsDir = join(__dirname, './docs');
 
+const MAX_UNUSED_FILES = 50;
+const MAX_ISSUES_PER_TYPE = 50;
+
 /**
  * @param {import('knip/session').Results} results
  * @param {{ cwd: string, configFilePath: string | undefined }} options
  */
 export function buildResults(results, options) {
   const configurationHints = finalizeConfigurationHints(results, options);
 
-  const isSuppressIssues =
-    results.counters.total >= 10 &&
-    configurationHints.some(hint => hint.type === 'top-level-unconfigured' || hint.type === 'workspace-unconfigured');
+  const maybeUnconfigured = configurationHints.some(
+    hint => hint.type === 'top-level-unconfigured' || hint.type === 'workspace-unconfigured'
+  );
 
   const configFile = options.configFilePath
     ? { exists: true, filePath: options.configFilePath }
     : { exists: false, locations: KNIP_CONFIG_LOCATIONS };
 
-  const reviewHint = isSuppressIssues ? UNCONFIGURED_HINT : options.configFilePath ? CONFIG_REVIEW_HINT : undefined;
-  const files = isSuppressIssues ? null : Object.keys(results.issues.files);
-  const issues = isSuppressIssues
-    ? null
-    : Object.fromEntries(Object.entries(results.issues).filter(([key]) => key !== 'files' && key !== '_files'));
+  const counters = Object.fromEntries(
+    Object.entries(results.counters).filter(([key]) => key !== 'processed' && key !== 'total')
+  );
+
+  const totalIssues = Object.values(counters).reduce((sum, count) => sum + count, 0);
+  const isClean = totalIssues === 0 && configurationHints.length === 0;
+  const reviewHint = maybeUnconfigured
+    ? UNCONFIGURED_HINT
+    : isClean
+      ? CLEAN_HINT
+      : options.configFilePath && totalIssues > 0
+        ? CONFIG_REVIEW_HINT
+        : undefined;
+
+  let truncated = false;
+
+  const unusedFiles = Object.keys(results.issues.files);
+  const files = unusedFiles.slice(0, MAX_UNUSED_FILES);
+  if (unusedFiles.length > files.length) truncated = true;
+
+  const issues = {};
+  for (const [type, byFile] of Object.entries(results.issues)) {
+    if (type === 'files' || type === '_files') continue;
+    const items = [];
+    for (const [file, symbols] of Object.entries(byFile)) {
+      for (const issue of Object.values(symbols)) {
+        items.push({
+          file,
+          symbol: issue.symbol,
+          line: issue.line ?? issue.symbols?.[0]?.line,
+          ...(issue.parentSymbol ? { parent: issue.parentSymbol } : {}),
+        });
+      }
+    }
+    if (items.length === 0) continue;
+    if (items.length > MAX_ISSUES_PER_TYPE) truncated = true;
+    issues[type] = items.slice(0, MAX_ISSUES_PER_TYPE);
+  }
 
   return {
     reviewHint,
-    issuesSuppressed: isSuppressIssues,
+    maybeUnconfigured,
+    truncated,
     configurationHints,
-    counters: results.counters,
+    counters,
+    totalIssues,
     configFile,
     enabledPlugins: results.enabledPlugins,
     files,
@@ -72,7 +111,7 @@ export async function getResults(cwd, workspace) {
 export function readContent(filePath) {
   try {
     const content = readFileSync(join(docsDir, filePath), 'utf-8');
-    return content.replace(/^---[\s\S]*?---\n/, '');
+    return transformForAgent(content, filePath);
   } catch (error) {
     return `Error reading ${filePath}: ${error instanceof Error ? error.message : String(error)}`;
   }
@@ -90,9 +129,7 @@ export function getDocs(topic) {
 
 /** @param {string} topic */
 function findDocPage(topic) {
-  /** @type {Record<string, { name: string; description: string; path: string }>} */
-  const resources = CURATED_RESOURCES;
-  if (resources[topic]) return readContent(resources[topic].path);
+  if (CURATED_RESOURCES[topic]) return readContent(CURATED_RESOURCES[topic].path);
 
   for (const ext of ['.md', '.mdx']) {
     const filePath = join(docsDir, `${topic}${ext}`);
diff --git a/packages/mcp-server/src/transform.js b/packages/mcp-server/src/transform.js
@@ -0,0 +1,90 @@
+import { posix } from 'node:path';
+
+const DOC_LINK = /\.(md|mdx)(#.*)?$/;
+const ASIDE = /^:::(tip|note|caution|danger|warning)(?:\[([^\]]*)\])?\s*$/;
+const FENCE = /^(\s*)(`{3,}|~{3,})/;
+const ESM = /^(import|export)\b/;
+const TAB_ITEM = /^\s*<TabItem\s+[^>]*label=["']([^"']+)["'][^>]*>\s*$/;
+const TAG_LINE = /^\s*<\/?[A-Za-z][\w.-]*(?:\s[^<>]*)?\/?>\s*$/;
+
+/**
+ * Rewrite a relative doc link into a knip-docs topic path, so an agent can pass
+ * it straight back to the `knip-docs` tool. Leaves external/anchor/site links as-is.
+ * e.g. `../reference/integrations.md#filters` on a `guides/` page → `reference/integrations#filters`
+ * @param {string} target
+ * @param {string} dir
+ * @returns {string}
+ */
+function rewriteLink(target, dir) {
+  if (/^(https?:|mailto:|tel:|#|\/)/.test(target)) return target;
+  if (!DOC_LINK.test(target)) return target;
+  const [path, anchor] = target.split('#');
+  const resolved = posix.normalize(posix.join(dir, path)).replace(/\.(md|mdx)$/, '');
+  return anchor ? `${resolved}#${anchor}` : resolved;
+}
+
+/**
+ * Make a doc page self-contained for an agent reading it cold via MCP: strip
+ * frontmatter and MDX import/export statements, flatten `<Tabs>`/`<TabItem>` and
+ * Starlight asides to plain markdown, drop remaining standalone JSX/HTML tags,
+ * and rewrite relative doc links to `knip-docs` topic paths. Code fences are left
+ * untouched (incl. nested longer fences).
+ * @param {string} content
+ * @param {string} filePath relative path under the docs dir, e.g. `guides/handling-issues.mdx`
+ * @returns {string}
+ */
+export function transformForAgent(content, filePath) {
+  const dir = posix.dirname(filePath);
+  const body = content.replace(/^---[\s\S]*?---\n/, '');
+  const out = [];
+  let fence = null;
+  let inEsm = false;
+  let esmDepth = 0;
+
+  for (const line of body.split('\n')) {
+    const f = line.match(FENCE);
+    if (f) {
+      const marker = f[2];
+      if (!fence) fence = marker;
+      else if (marker[0] === fence[0] && marker.length >= fence.length) fence = null;
+      out.push(line);
+      continue;
+    }
+    if (fence) {
+      out.push(line);
+      continue;
+    }
+
+    // Drop MDX import/export statements, balancing braces to span multi-line ones
+    if (!inEsm && ESM.test(line)) inEsm = true;
+    if (inEsm) {
+      for (const ch of line) {
+        if (ch === '{') esmDepth++;
+        else if (ch === '}') esmDepth--;
+      }
+      if (esmDepth <= 0) {
+        inEsm = false;
+        esmDepth = 0;
+      }
+      continue;
+    }
+
+    const tab = line.match(TAB_ITEM);
+    const aside = line.match(ASIDE);
+    if (tab) {
+      out.push(`**${tab[1]}**`);
+    } else if (aside) {
+      out.push(`**${aside[2] || aside[1][0].toUpperCase() + aside[1].slice(1)}**`);
+    } else if (/^:::\s*$/.test(line) || TAG_LINE.test(line)) {
+      // drop aside close and any standalone tag (<Tabs>, </TabItem>, <Card>, <video>, <source/>, …)
+    } else {
+      out.push(
+        line
+          .replace(/\]\(([^)\s]+)(\s+"[^"]*")?\)/g, (_m, t, title) => `](${rewriteLink(t, dir)}${title || ''})`)
+          .replace(/^(\[[^\]]+\]:\s+)(\S+)(.*)$/, (_m, pre, t, rest) => `${pre}${rewriteLink(t, dir)}${rest}`)
+      );
+    }
+  }
+
+  return out.join('\n');
+}
