kucherenko__jscpd/docs/ai-ready.md

AI-Ready Integrations

jscpd integrates into AI-powered development workflows through three complementary mechanisms: the AI reporter, agent skills, and an MCP server.

AI Reporter

The ai reporter produces compact, token-efficient output designed to be piped directly into an LLM prompt or agentic pipeline. It uses common-path-prefix compression and omits code fragments and colors — just the clone locations and a summary.

jscpd --reporters ai /path/to/source

Example Output

src/utils/ auth.ts:10-25 ~ helpers.ts:40-55
src/utils/auth.ts 30-45 ~ 80-95
src/ utils/auth.ts:10-25 ~ api/routes.ts:5-20
---
23 clones · 4.2% duplication

Token Efficiency

Benchmarked on the fixtures/ directory (212 clones, 347 files):

Reporter	Output size	Estimated tokens
console (default)	~21,800 chars	~5,400
ai	~4,500 chars	~1,100

~79% fewer tokens than the default console reporter.

Codebase Summary

Add --summary for a compact refactoring-hotspot overview — top files and folders by tokens, lines, size, and a complexity estimate. In the ai reporter each entry is one line with all metrics inline, so an agent gets the full picture for a handful of tokens:

Summary by tokens (321 files, 129 folders):
files (tokens/lines/size/cx/dup%):
src/core/files.ts 2052/363/11.4K/80/0.0%
...
folders (files/tokens/lines/size):
src/core 8/5264/843/26.5K
...

jscpd --reporters ai --summary --no-tips /path/to/source

See rust.md for the metric definitions and --summary-top / --summary-by options.

When an agent only needs the complexity ranking, --complexity skips clone detection and prints the same compact rows without the duplication column:

Complexity by complexity (6 files, 3 folders):
files (tokens/lines/size/cx):
src/rates.ts 182/35/757/11
...
folders (files/tokens/lines/size/mean cx):
src 4/557/83/2.2K/5
...

jscpd --reporters ai --complexity --no-tips /path/to/source

To hand an agent one kind of clone, combine --reporters ai with --kind, e.g. --ignore-identifiers --kind renamed for copies that differ only in names.

Agent Skills

jscpd ships AI agent skills that teach coding assistants how to use jscpd, refactor detected duplications, and clean up a codebase more broadly.

jscpd — Tool Reference Skill

Covers all CLI options, the AI reporter output format, and configuration file syntax.

npx skills add kucherenko/jscpd --skill jscpd

dry-refactoring — Refactoring Workflow Skill

A guided process for reading clone output, choosing the right extraction strategy, applying the refactor, and verifying the clone is eliminated.

npx skills add kucherenko/jscpd --skill dry-refactoring

codebase-refactoring — Codebase Health Workflow Skill

A broader pass for "clean up this codebase" requests: fix duplication first (delegates to dry-refactoring), then find and remove or refactor dead code (--dead-code), then find and simplify the largest/most complex files (--complexity) — prioritized from --health/--dashboard and re-measured at the end.

npx skills add kucherenko/jscpd --skill codebase-refactoring

After installation, ask your agent to "find and fix code duplication" for the focused pass, or "clean up this codebase" for the broader one, and it will invoke jscpd with the right options and act on the results.

MCP Server

jscpd speaks the Model Context Protocol (MCP), exposing detection capabilities as tools that AI assistants can call directly from the editor. Start the server once against your codebase, then let your AI assistant check any snippet for duplication on demand — no CLI invocation needed.

stdio transport (Rust v5)

The jscpd/cpd binary serves MCP over stdio directly (jscpd --mcp or cpd --mcp) — the transport most MCP clients spawn-and-manage themselves, with no port and no network policy. The project is scanned once at startup (log line on stderr); snippet checks run against in-memory token hashes, so they answer without a rescan.

jscpd --mcp /path/to/project
# All detection options apply to the scan and to snippet checks:
jscpd --mcp --min-tokens 30 --format javascript,typescript /path/to/project

Client configuration (Claude Desktop, Claude Code, Cursor, APM, ...):

{
  "mcpServers": {
    "jscpd": {
      "command": "cpd",
      "args": ["--mcp", "/path/to/project"]
    }
  }
}

The server implements MCP protocol revision 2025-06-18 (also accepting 2025-03-26 and 2024-11-05 clients) and exposes four tools:

• check_duplication(code, format, limit?, similarity?) — check a snippet against the scanned project; with similarity (a ratio in (0, 1], JavaScript/TypeScript only; 1 means exact matches only, and the server's --similarity is the default) the response also lists project functions structurally similar to each function in the snippet, best first, under similar; format accepts format names (javascript) or file extensions (js)
• get_file_clones(path, limit?) — clones involving one file, for file-scoped refactoring; path is scan-root-relative (as shown in results) or absolute
• get_statistics() — totals and per-format statistics from the last scan
• check_current_directory(limit?) — re-scan the configured paths and return updated counts plus the clone list

Tool results are compact JSON in a text content block. Every clone/match list is sorted biggest-first (by tokens) and capped by the optional limit argument (default 100) — the accompanying clones/count field always reports the untruncated total, and truncation is flagged with a note.

HTTP transport

There is no HTTP transport in v5. jscpd-server — MCP over Streamable HTTP plus a REST API, for several clients sharing one long-lived server — is part of jscpd v4 and is maintained on the master-v4 branch (npm install -g jscpd-server).