{
  "markdown": "# vue-harvest\n\nPoint it at a Vue project. It finds every component, figures out which ones are reusable, and extracts them. It also pulls out your design tokens (colors, spacing, typography) and gives you a visual report.\n\nThe hard cases that need judgment (store-coupled components, ambiguous dependencies) get handled by an MCP server that feeds structured analysis to an LLM.\n\n## What it does\n\n**Component extraction.** Parses every `.vue` file in a project using `@vue/compiler-sfc`. For each component it extracts the full interface (props, emits, slots), maps out the dependency graph, detects coupling issues, and scores a confidence level for safe extraction. Components above the threshold get auto-extracted into standalone bundles with rewritten imports and a manifest of peer dependencies.\n\n**Design token extraction.** Scans all CSS (scoped styles, standalone stylesheets) and pulls out colors, font families, font sizes, font weights, spacing values, border radii, and shadows. Outputs a CSS custom properties file, a JSON dump, and a visual HTML explorer showing swatches and scales.\n\n**MCP server.** Twelve tools that give an LLM the structured data it needs to reason about the harder cases: components in the 30-70% confidence range that could be extracted with some refactoring. The LLM can deep-analyze coupling, generate decoupling suggestions with before/after code, create composable wrappers for store-bound components, and do full rewrite-and-extract in one shot.\n\n## Install\n\n```bash\nnpm install -g vue-harvest\n\n# or run directly\nnpx vue-harvest analyze ./my-app\n```\n\nFor the MCP server:\n\n```bash\nnpm install -g vue-harvest-mcp\n```\n\n## CLI\n\n### `vue-harvest analyze [path]`\n\nFull analysis pipeline. Discovers `.vue` files, parses interfaces, builds the dependency graph, classifies every component, auto-extracts the safe ones, and generates a registry + catalog.\n\n```bash\nvue-harvest analyze\nvue-harvest analyze ./path/to/project\nvue-harvest analyze --threshold 60\nvue-harvest analyze --output ./harvested\nvue-harvest analyze --json | jq '.summary'\n```\n\nOutput goes to `.vue-harvest/` by default:\n\n```\n.vue-harvest/\n  registry.json       Component registry (shadcn-compatible format)\n  catalog.html        Browsable catalog with tier filters\n  analysis.json       Full analysis dump for the MCP server\n  SUMMARY.md          Human-readable report\n  components/         Extracted component bundles\n    Button/\n      Button.vue\n      manifest.json\n    Card/\n      Card.vue\n      manifest.json\n```\n\n### `vue-harvest list [path]`\n\nLists all components sorted by extraction confidence.\n\n```bash\nvue-harvest list\nvue-harvest list --tier primitive\nvue-harvest list --json\n```\n\n### `vue-harvest inspect <name>`\n\nFull breakdown of a single component: props, events, slots, dependencies, coupling issues, style analysis.\n\n```bash\nvue-harvest inspect Button\nvue-harvest inspect UserProfileCard --json\n```\n\n### `vue-harvest extract <name>`\n\nExtracts a specific component and all its local dependencies into a standalone bundle.\n\n```bash\nvue-harvest extract Button\nvue-harvest extract UserProfileCard --force\nvue-harvest extract Card --output ./my-components\n```\n\n### `vue-harvest tokens [path]`\n\nExtracts design system tokens from the project.\n\n```bash\nvue-harvest tokens\nvue-harvest tokens --json\nvue-harvest tokens --output ./design-system\n```\n\nOutputs:\n- `tokens.css` with CSS custom properties\n- `tokens.json` with the full token dataset\n- `design-system.html` with a visual explorer (color swatches, font scales, spacing visualization)\n\n### `vue-harvest init`\n\nCreates a `harvest.config.json` with detected project settings.\n\n## Configuration\n\nOptional. Place a `harvest.config.json` in the project root:\n\n```json\n{\n  \"include\": [\"**/*.vue\"],\n  \"exclude\": [\n    \"node_modules/**\",\n    \"dist/**\",\n    \"**/*.test.*\",\n    \"**/*.story.*\"\n  ],\n  \"extractionThreshold\": 70,\n  \"outDir\": \".vue-harvest\",\n  \"registry\": \"json\"\n}\n```\n\nPath aliases are auto-detected from `tsconfig.json`. If your project has `@` mapped to `./src`, vue-harvest picks that up.\n\n## Component classification\n\nEvery component gets classified into a reusability tier based on its interface, dependencies, and coupling:\n\n| Tier | Confidence | What it means |\n|------|-----------|---------------|\n| Primitive | 85-100% | Pure UI, no business logic. Button, Input, Card. |\n| Composite | 70-85% | Built from primitives, minimal logic. FormField, DataTable. |\n| Feature | 50-70% | Has business logic but potentially reusable. UserAvatar, SearchBar. |\n| Page-bound | 30-50% | Tightly coupled to a specific page or route. |\n| App-specific | 0-30% | Deeply coupled to app state. Not reusable as-is. |\n\nComponents at or above the extraction threshold (default 70%) are auto-extracted. The 30-70% band is where the MCP server comes in.\n\n## Coupling issues\n\nThe analyzer detects these coupling patterns:\n\n| Issue | Severity | Description |\n|-------|----------|-------------|\n| `direct-store-access` | warning | Imports a Pinia/Vuex store directly |\n| `hardcoded-api` | warning | Contains hardcoded API endpoint URLs |\n| `router-dependency` | info | Uses vue-router |\n| `i18n-dependency` | warning | Uses vue-i18n |\n| `global-inject` | warning | Uses `inject()` for app-level provides |\n| `env-variable` | warning | References `import.meta.env` |\n| `unscoped-css` | warning | Has unscoped styles that leak globally |\n| `deep-provide-chain` | warning | Relies on provide/inject chains |\n| `implicit-global` | warning | Uses globally registered components without importing them |\n| `side-effect-import` | warning | Has imports that execute side effects |\n\n## MCP server\n\n### Setup with Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"vue-harvest\": {\n      \"command\": \"vue-harvest-mcp\"\n    }\n  }\n}\n```\n\n### Setup with Claude Code\n\n```bash\nclaude mcp add vue-harvest vue-harvest-mcp\n```\n\n### Available tools\n\n| Tool | What it does |\n|------|-------------|\n| `analyze-project` | Runs the full pipeline on a project path |\n| `list-components` | Lists components with filters (tier, confidence range) |\n| `inspect-component` | Full analysis with source code |\n| `extract-component` | Extracts with force option |\n| `deep-analyze` | Structured coupling analysis for LLM reasoning |\n| `suggest-refactor` | Before/after code for decoupling |\n| `generate-wrapper` | Creates composable wrappers for store-bound components |\n| `adapt-and-extract` | Full rewrite + extract in one step |\n| `batch-triage` | Prioritizes all reviewable components with effort estimates |\n| `coupling-report` | Project-wide coupling patterns |\n| `analyze-design-system` | Extracts design tokens |\n| `get-design-tokens` | Returns tokens filtered by type |\n\n### Resources\n\nThe server exposes these as MCP resources after analysis:\n\n- `harvest://registry` : full registry JSON\n- `harvest://graph` : dependency graph\n- `harvest://summary` : analysis summary\n- `harvest://component/{name}` : individual component analysis\n- `harvest://design-system` : extracted design tokens\n\n### Prompts\n\n- `analyze-new-project` : guided first analysis\n- `extraction-sprint` : batch refactor and extract session\n- `refactor-component` : single component deep refactor\n- `extract-design-system` : design token extraction and analysis\n\n### Example conversations\n\n> \"Analyze my Vue project at /Users/me/projects/my-app\"\n\n> \"Show me all the components that need review\"\n\n> \"Deep analyze the UserProfileCard component and suggest how to decouple it from the auth store\"\n\n> \"Do an extraction sprint, go through all reviewable components and extract what you can\"\n\n> \"Extract the design system tokens and recommend a naming convention\"\n\n## Programmatic API\n\nvue-harvest exports its analysis engine for use in other tools:\n\n```typescript\nimport { analyze, writeOutput, analyzeTokens } from 'vue-harvest'\n\nconst report = await analyze('./my-vue-app', {\n  extractionThreshold: 0.6,\n})\n\nconsole.log(report.summary)\n// { totalFiles: 42, analyzed: 40, autoExtracted: 12, needsMCP: 8, ... }\n\nawait writeOutput(report)\n\n// Design tokens\nconst tokens = await analyzeTokens('./my-vue-app')\nconsole.log(tokens.palette)    // [{ hex: '#3b82f6', usageCount: 14 }, ...]\nconsole.log(tokens.spacing)    // ['4px', '8px', '12px', '16px', '24px']\n```\n\n## Architecture\n\n```\nvue-harvest (monorepo)\n  packages/\n    cli/                        Published as \"vue-harvest\" on npm\n      src/\n        types.ts                Type system shared across the whole project\n        index.ts                Pipeline orchestrator\n        cli.ts                  CLI entry point (citty)\n        analyzers/\n          sfc-analyzer.ts       SFC parsing, interface extraction, coupling detection\n          graph-builder.ts      Dependency graph with Tarjan's SCC for cycle detection\n          design-system-analyzer.ts   Token extraction from CSS\n        extractors/\n          component-extractor.ts   Import rewriting, file bundling, manifest generation\n        generators/\n          registry.ts           Registry JSON + catalog HTML generation\n        commands/               CLI command definitions\n        utils/\n          config.ts             Config resolution, alias detection from tsconfig\n      tests/\n        fixtures/               A real mini Vue project used as test input\n        unit/                   66 tests across 5 suites\n\n    mcp/                        Published as \"vue-harvest-mcp\" on npm\n      src/\n        index.ts                MCP server (12 tools, resources, prompts)\n```\n\nThe split between CLI and MCP is deliberate. The CLI handles everything deterministic: parsing, graph building, classification, extraction. The MCP handles the 20% that needs reasoning: decoupling suggestions, refactoring code generation, ambiguity resolution.\n\n## Development\n\n```bash\ngit clone https://github.com/virgilvox/vue-harvest.git\ncd vue-harvest\npnpm install\npnpm build\npnpm test\n```\n\nWatch mode for the CLI:\n\n```bash\npnpm --filter vue-harvest dev\n```\n\nRun a specific test file:\n\n```bash\nnpx vitest run packages/cli/tests/unit/sfc-analyzer.test.ts\n```\n\n## How it works internally\n\n1. **Discovery.** Globs for `.vue` files, reads `tsconfig.json` for path aliases.\n2. **SFC parsing.** `@vue/compiler-sfc` splits each file into template, script, and style blocks.\n3. **Interface extraction.** Regex-based extraction of `defineProps`, `defineEmits`, `<slot>` tags. Handles generic type syntax, `withDefaults`, and object syntax with nested options.\n4. **Dependency analysis.** `es-module-lexer` parses imports. Each import gets classified by kind (internal component, composable, store, util, external package, etc).\n5. **Coupling detection.** Pattern matching on the script and template AST for store access, hardcoded APIs, router usage, i18n, inject, env vars, unscoped CSS.\n6. **Classification.** Confidence scoring starts at 1.0 and gets penalized for coupling issues, store access, and page-path patterns. Boosted for props/slots interfaces and UI-path patterns.\n7. **Graph building.** Resolves import paths, builds adjacency lists, runs Tarjan's strongly connected components algorithm for cycle detection, computes transitive dependency closures.\n8. **Extraction.** For components above threshold: collects the component plus all its local deps (composables, utils, types, styles), rewrites import paths to be relative within the extracted bundle, generates a manifest listing peer dependencies and required globals.\n9. **Token extraction.** PostCSS value parser identifies colors (hex, rgb, hsl), font properties, spacing values, radii, and shadows from CSS declarations. Deduplicates, normalizes hex values, and groups by type.\n\n## License\n\nMIT\n",
  "bytes": 11716,
  "sha": "025323056f1c183033b15d44f86c72cfe511b3019b768bd762c9d91232495846",
  "repo_slug": "virgilvox/vue-harvest",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_virgilvox_vue_harvest_2b178ad9/readme"
}