@knip/mcp 0.0.1

package/docs/writing-a-plugin/inputs.md

@@ -0,0 +1,162 @@
+---
+title: Inputs
+sidebar:
+  order: 2
+---
+
+You may have noticed functions like `toDeferResolve` and `toEntry`. They're a
+way for plugins to tell what they've found and how Knip should handle those. The
+more precise a plugin can be, the better it is for results and performance.
+Here's an overview of all input type functions:
+
+- [toEntry][1]
+- [toProductionEntry][2]
+- [toProject][3]
+- [toDependency][4]
+- [toProductionDependency][5]
+- [toDeferResolve][6]
+- [toDeferResolveEntry][7]
+- [toConfig][8]
+- [toBinary][9]
+- [toAlias][10]
+- [Options][11]
+
+## toEntry
+
+An `entry` input is just like an `entry` in the configuration. It should either
+be an absolute or relative path, and glob patterns are allowed.
+
+## toProductionEntry
+
+A production `entry` input is just like an `production` in the configuration. It
+should either be an absolute or relative path, and it can have glob patterns.
+
+## toProject
+
+A `project` input is the equivalent of `project` patterns in the configuration.
+It should either be an absolute or relative path, and (negated) glob patterns
+are allowed.
+
+## toDependency
+
+The `dependency` indicates the entry is a dependency, belonging in either the
+`"dependencies"` or `"devDependencies"` section of `package.json`.
+
+## toProductionDependency
+
+The production `dependency` indicates the entry is a production dependency,
+expected to be listed in `"dependencies"`.
+
+## toDeferResolve
+
+The `deferResolve` input type is used to defer the resolution of a specifier.
+This could be resolved to a dependency or an entry file. For instance, the
+specifier `"input"` could be resolved to `"input.js"`, `"input.tsx"`,
+`"input/index.js"` or the `"input"` package name. Local files are added as entry
+files, package names are external dependencies.
+
+If this does not lead to a resolution, the specifier will be reported under
+"unresolved imports".
+
+## toDeferResolveEntry
+
+The `deferResolveEntry` input type is similar to `deferResolve`, but it's used
+for entry files only (not dependencies) and unresolved inputs are ignored. It's
+different from `toEntry` as glob patterns are not supported.
+
+## toConfig
+
+The `config` input type is a way for plugins to reference a configuration file
+that should be handled by a different plugin. For instance, Angular
+configurations might contain references to `tsConfig` and `karmaConfig` files,
+so these `config` files can then be handled by the TypeScript and Karma plugins,
+respectively.
+
+Example:
+
+```ts
+toConfig('typescript', './path/to/tsconfig.json');
+```
+
+For instance, the Angular plugin uses this to tell Knip about its `tsConfig`
+value in `angular.json` projects.
+
+## toBinary
+
+The `binary` input type isn't used by plugins directly, but by the shell script
+parser (through the `getInputsFromScripts` helper). Think of GitHub Actions
+workflow YAML files or husky scripts. Using this input type, a binary is
+"assigned" to the dependency that has it as a `"bin"` in their `package.json`.
+
+## toAlias
+
+The `alias` input type adds path aliases to the core module resolver. They're
+added to `compilerOptions.paths` so the syntax is identical.
+
+## Options
+
+When creating inputs from specifiers, an extra `options` object as the second
+argument can be provided.
+
+### dir
+
+The optional `dir` option assigns the input to a different workspace. For
+instance, GitHub Action workflows are always stored in the root workspace, and
+support `working-directory` in job steps. For example:
+
+```yaml
+jobs:
+  stylelint:
+    runs-on: ubuntu-latest
+    steps:
+      - run: npx esbuild
+        working-directory: packages/app
+```
+
+The GitHub Action plugin understands `working-directory` and adds this `dir` to
+the input:
+
+```ts
+toDependency('esbuild', { dir: 'packages/app' });
+```
+
+Knip now understands `esbuild` is a dependency of the workspace in the
+`packages/app` directory.
+
+### optional
+
+Use the `optional` flag to indicate the dependency is optional. Then, a
+dependency won't be flagged as unlisted if it isn't.
+
+### allowIncludeExports
+
+By default, exports of entry files such as `src/index.ts` or the files in
+`package.json#exports` are not reported as unused. When using the
+`--include-entry-exports` flag or `isIncludeExports: true` option, unused
+exports on such entry files are also reported.
+
+Exports of entry files coming from plugins are not included in the analysis,
+even with the option enabled. This is because certain tools and frameworks
+consume named exports from entry files, causing false positives.
+
+The `allowIncludeExports` option allows the exports of entry files to be
+reported as unused when using `--include-entry-exports`. This option is
+typically used with the [toProductionEntry][2] input type.
+
+Example:
+
+```ts
+toProductionEntry('./entry.ts', { allowIncludeExports: true });
+```
+
+[1]: #toentry
+[2]: #toproductionentry
+[3]: #toproject
+[4]: #todependency
+[5]: #toproductiondependency
+[6]: #todeferresolve
+[7]: #todeferresolveentry
+[8]: #toconfig
+[9]: #tobinary
+[10]: #toalias
+[11]: #options

package/license

@@ -0,0 +1,15 @@
+ISC License (ISC)
+
+Copyright 2022-2025 Lars Kappert
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@knip/mcp",
+  "version": "0.0.1",
+  "description": "Knip MCP Server",
+  "type": "module",
+  "bin": {
+    "knip-mcp": "./src/cli.js"
+  },
+  "exports": {
+    ".": "./src/server.js",
+    "./tools": "./src/tools.js"
+  },
+  "files": [
+    "src",
+    "docs"
+  ],
+  "keywords": [
+    "knip",
+    "mcp",
+    "model-context-protocol"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/webpro-nl/knip",
+    "directory": "packages/mcp-server"
+  },
+  "author": "Lars Kappert <lars@webpro.nl>",
+  "license": "ISC",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.24.3",
+    "zod": "^4.1.11",
+    "knip": "5.75.0"
+  },
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "scripts": {}
+}

package/src/cli.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { mcpServer } from './server.js';
+
+function disconnect() {
+  mcpServer.close();
+  process.exitCode = 0;
+}
+
+await mcpServer.connect(new StdioServerTransport());
+
+process.on('SIGINT', disconnect);
+process.on('SIGTERM', disconnect);

package/src/curated-resources.js

@@ -0,0 +1,62 @@
+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',
+  },
+  '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',
+    path: 'guides/handling-issues.mdx',
+  },
+  'monorepos-and-workspaces': {
+    name: 'Monorepos & Workspaces',
+    description: 'Multi-package repo? Configure workspaces and cross-references here',
+    path: 'features/monorepos-and-workspaces.md',
+  },
+  'production-mode': {
+    name: 'Production Mode',
+    description: 'Exclude tests, stories, devDependencies with --production and --strict flags',
+    path: 'features/production-mode.md',
+  },
+  compilers: {
+    name: 'Compilers',
+    description: 'Using .vue, .svelte, .astro, .mdx files? Configure compilers to parse them',
+    path: 'features/compilers.md',
+  },
+  'configuration-reference': {
+    name: 'Configuration Reference',
+    description: 'Complete reference of all config options: entry, project, ignore, plugins, etc.',
+    path: 'reference/configuration.md',
+  },
+  'plugins-explanation': {
+    name: 'Plugins',
+    description: 'Config files showing as unused? Understand plugin config vs entry files',
+    path: 'explanations/plugins.md',
+  },
+  'entry-files': {
+    name: 'Entry Files',
+    description: 'Understand how Knip discovers entry files and default patterns per plugin',
+    path: 'explanations/entry-files.md',
+  },
+  'plugin-list': {
+    name: 'Plugin List',
+    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',
+  },
+};

package/src/server.js

@@ -0,0 +1,129 @@
+process.env.NO_COLOR = '1';
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { CURATED_RESOURCES } from './curated-resources.js';
+import {
+  DOC_TOOL_DESCRIPTION,
+  DOC_TOOL_TOPIC_DESCRIPTION,
+  ERROR_HINT,
+  RUN_KNIP_TOOL_DESCRIPTION,
+  WORKFLOW,
+} from './texts.js';
+import { getDocs, readContent } from './tools.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
+
+const DOCS = 'knip://docs';
+
+class MCP {
+  constructor() {
+    this.server = new McpServer({ name: 'Knip', version: pkg.version });
+    this.#registerPrompts();
+    this.#registerResources();
+    this.#registerTools();
+  }
+
+  #registerPrompts() {
+    const resources = Object.entries(CURATED_RESOURCES).map(([id, doc]) => ({
+      uri: `${DOCS}/${id}`,
+      name: doc.name,
+      description: doc.description,
+    }));
+
+    this.server.registerPrompt(
+      'knip-configure',
+      {
+        description: 'Set up and optimize Knip configuration. Guides through initial setup and iterative refinement.',
+        arguments: [{ name: 'cwd', description: 'Working directory (default: current directory)', required: false }],
+      },
+      async ({ cwd }) => ({
+        messages: [
+          {
+            role: 'user',
+            content: {
+              type: 'text',
+              text: `Help me configure Knip for ${cwd || 'this project'}.\n\n${WORKFLOW}`,
+            },
+          },
+        ],
+        resources,
+      })
+    );
+  }
+
+  #registerResources() {
+    for (const [id, doc] of Object.entries(CURATED_RESOURCES)) {
+      const uri = `${DOCS}/${id}`;
+      this.server.registerResource(
+        doc.name,
+        uri,
+        { description: doc.description, mimeType: 'text/markdown' },
+        async () => ({ contents: [{ uri, mimeType: 'text/markdown', text: readContent(doc.path) }] })
+      );
+    }
+
+    this.server.registerResource(
+      'docs',
+      new ResourceTemplate(`${DOCS}/{+path}`, { list: undefined }),
+      { description: 'Get Knip documentation page by path', mimeType: 'text/markdown' },
+      async (uri, { path }) => {
+        const result = getDocs(path);
+        if ('content' in result) return { content: [{ type: 'text', text: result.content }] };
+        const errorText = `Documentation not found: ${path}`;
+        return { contents: [{ uri, mimeType: 'text/plain', text: errorText }] };
+      }
+    );
+  }
+
+  #registerTools() {
+    this.server.registerTool(
+      'knip-run',
+      {
+        description: RUN_KNIP_TOOL_DESCRIPTION,
+        inputSchema: {
+          cwd: z.string().optional().describe('Working directory (default: workspace root)'),
+        },
+      },
+      async opts => {
+        try {
+          const cwd = opts.cwd || process.cwd();
+          const results = await getResults(cwd);
+          return { content: [{ type: 'text', text: JSON.stringify(results) }] };
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          return {
+            content: [{ type: 'text', text: JSON.stringify({ error: message, hint: ERROR_HINT }) }],
+            isError: true,
+          };
+        }
+      }
+    );
+
+    this.server.registerTool(
+      'knip-docs',
+      { description: DOC_TOOL_DESCRIPTION, inputSchema: { topic: z.string().describe(DOC_TOOL_TOPIC_DESCRIPTION) } },
+      async ({ topic }) => {
+        const docs = getDocs(topic);
+        if ('content' in docs) return { content: [{ type: 'text', text: docs.content }] };
+        return { content: [{ type: 'text', text: docs.error }], isError: true };
+      }
+    );
+  }
+
+  connect(transport) {
+    return this.server.connect(transport);
+  }
+
+  close() {
+    return this.server.close();
+  }
+}
+
+const mcpServer = new MCP();
+
+export { mcpServer };

package/src/texts.js

@@ -0,0 +1,76 @@
+import { CURATED_RESOURCES } from './curated-resources.js';
+
+export const WORKFLOW = `Workflow:
+1. Read essential documentation resources to understand Knip configuration
+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 no hints remain and false positives are minimized
+
+Essential resources:
+- configuring-project-files (must read to configure entry patterns)
+- handling-issues (comprehensive guide to deal with any reported issue type)
+- configuration-reference (all knip.json configuration options)
+
+For direct "run knip" or "clean up codebase" requests: Always make sure to run this workflow first.
+
+Important (potential next steps after workflow is finished):
+- Before suggesting fixes/solutions, make sure to consult "handling-issues" and "reference/jsdoc-tsdoc-tags"
+- Read "getting-started" and "reference/cli" to install knip and start using Knip from CLI
+- If requested to clean up, consult "features/auto-fix"
+- Knip does not find/fix unused variables/imports within files (use another linter for that)
+`;
+
+// pkg.contributes.languageModelTools[0].modelDescription
+export const RUN_KNIP_TOOL_DESCRIPTION = `Run Knip and return configuration hints and issues.
+
+Returns:
+- configurationHints: Ordered suggestions to improve configuration (address these first)
+- counters: Summary counts of each issue type
+- files: List of unused files
+- issues: Detailed issues by type (dependencies, exports, types, etc.)
+- configFile: Current config file status
+
+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.
+
+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 knip.dev.`;
+
+// pkg.contributes.languageModelTools[1].inputSchema.properties.topic.description
+export const DOC_TOOL_TOPIC_DESCRIPTION =
+  'Topic key (e.g. "configuring-project-files") for curated resources, or path (e.g. "explanations/plugins") for all available docs';
+
+export const ERROR_HINT = `For unexpected errors (exit code 2) such as "error loading file":
+- Consult docs: known-issues and configuration-reference
+- If no config file exists, create knip.json in root: {"$schema":"https://unpkg.com/knip@5/schema.json"}
+- Damage control for "error loading file":
+  1) First try to disable the related plugin's config file:
+     - E.g. vite: { config: [] }
+     - In a monorepo use e.g. { workspaces: { "packages/lib": { vite: { config: [] } } } }
+     - If this succeeds, add the file as a regular entry point
+  2) Then try to disable the related plugin:
+     - E.g. vite: false
+     - In a monorepo use e.g. { workspaces: { "packages/lib": { vite: false } } }
+     - If this succeeds, add the file as a regular entry point
+  3) As a last resort, ignore the workspace: ignoreWorkspaces: ["packages/lib"]
+- Run knip again`;
+
+export const CONFIG_REVIEW_HINT = `Review the existing configuration for potential improvements:
+
+- Never use "ignore" patterns (hides real issues!), always prefer specific solutions, other ignore* options are allowed
+- Many unused exported types? Add: ignoreExportsUsedInFile: { interface: true, type: true } (prefer this over other ignore* options)
+- Remove ignore patterns that don't match any files
+- Redundant ignore patterns: Knip respects .gitignore by default (node_modules, dist, build, .git)
+- Remove entry patterns covered by config defaults and plugins
+- Config files (e.g. vite.config.ts) showing as unused? Enable/disable the plugin explicitly
+- 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)`;

package/src/tools.js

@@ -0,0 +1,68 @@
+import { existsSync, readFileSync } from 'node:fs';
+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 } from './texts.js';
+
+export { ERROR_HINT } from './texts.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const docsDir = join(__dirname, '../docs');
+
+/**
+ * @param {import('knip/session').Results} results
+ * @param {{ cwd: string, configFilePath: string | undefined }} options
+ */
+export function buildResults(results, options) {
+  return {
+    configFile: options.configFilePath
+      ? { exists: true, filePath: options.configFilePath, reviewHint: CONFIG_REVIEW_HINT }
+      : { exists: false, locations: KNIP_CONFIG_LOCATIONS },
+    configurationHints: finalizeConfigurationHints(results, options),
+    counters: results.counters,
+    files: Array.from(results.issues.files),
+    issues: Object.fromEntries(Object.entries(results.issues).filter(([key]) => key !== 'files' && key !== '_files')),
+  };
+}
+
+/**
+ * @param {string} cwd
+ */
+export async function getResults(cwd) {
+  const options = await createOptions({ cwd, isSession: true, isUseTscFiles: false });
+  const session = await createSession(options);
+  return buildResults(session.getResults(), options);
+}
+
+/** @param {string} filePath */
+export function readContent(filePath) {
+  try {
+    const content = readFileSync(join(docsDir, filePath), 'utf-8');
+    return content.replace(/^---[\s\S]*?---\n/, '');
+  } catch (error) {
+    return `Error reading ${filePath}: ${error.message}`;
+  }
+}
+
+/**
+ * @param {string} topic
+ * @returns {{ content: string } | { error: string }}
+ */
+export function getDocs(topic) {
+  const content = findDocPage(topic);
+  if (content) return { content };
+  return { error: `Documentation not found: ${topic}. Available: ${Object.keys(CURATED_RESOURCES).join(', ')}` };
+}
+
+/** @param {string} topic */
+function findDocPage(topic) {
+  if (CURATED_RESOURCES[topic]) return readContent(CURATED_RESOURCES[topic].path);
+
+  for (const ext of ['.md', '.mdx']) {
+    const filePath = join(docsDir, `${topic}${ext}`);
+    if (existsSync(filePath)) return readContent(`${topic}${ext}`);
+  }
+
+  return null;
+}