Meta Agent Tools
PT

Back to the catalog

io.github.virgilvox/vue-harvest

Extract reusable component libraries and design tokens from Vue applications

Open source Open in the app JSON README (API)

About

Extract reusable component libraries and design tokens from Vue applications

Details

Kind
MCP servers
Topic
No topic detected
Publisher
virgilvox
Origin
official
Category
ferramentas
Transport
local
Version
0.0.3
Last push
2026-03-31T02:24:43Z
Repository state
ativo
Language
TypeScript
License
MIT
Added
2026-08-29 04:01:38
Updated
2026-08-29 04:01:38
Origin id
io.github.virgilvox/vue-harvest

README

# vue-harvest

Point 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.

The hard cases that need judgment (store-coupled components, ambiguous dependencies) get handled by an MCP server that feeds structured analysis to an LLM.

## What it does

**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.

**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.

**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.

## Install

```bash
npm install -g vue-harvest

# or run directly
npx vue-harvest analyze ./my-app
```

For the MCP server:

```bash
npm install -g vue-harvest-mcp
```

## CLI

### `vue-harvest analyze [path]`

Full analysis pipeline. Discovers `.vue` files, parses interfaces, builds the dependency graph, classifies every component, auto-extracts the safe ones, and generates a registry + catalog.

```bash
vue-harvest analyze
vue-harvest analyze ./path/to/project
vue-harvest analyze --threshold 60
vue-harvest analyze --output ./harvested
vue-harvest analyze --json | jq '.summary'
```

Output goes to `.vue-harvest/` by default:

```
.vue-harvest/
  registry.json       Component registry (shadcn-compatible format)
  catalog.html        Browsable catalog with tier filters
  analysis.json       Full analysis dump for the MCP server
  SUMMARY.md          Human-readable report
  components/         Extracted component bundles
    Button/
      Button.vue
      manifest.json
    Card/
      Card.vue
      manifest.json
```

### `vue-harvest list [path]`

Lists all components sorted by extraction confidence.

```bash
vue-harvest list
vue-harvest list --tier primitive
vue-harvest list --json
```

### `vue-harvest inspect <name>`

Full breakdown of a single component: props, events, slots, dependencies, coupling issues, style analysis.

```bash
vue-harvest inspect Button
vue-harvest inspect UserProfileCard --json
```

### `vue-harvest extract <name>`

Extracts a specific component and all its local dependencies into a standalone bundle.

```bash
vue-harvest extract Button
vue-harvest extract UserProfileCard --force
vue-harvest extract Card --output ./my-components
```

### `vue-harvest tokens [path]`

Extracts design system tokens from the project.

```bash
vue-harvest tokens
vue-harvest tokens --json
vue-harvest tokens --output ./design-system
```

Outputs:
- `tokens.css` with CSS custom properties
- `tokens.json` with the full token dataset
- `design-system.html` with a visual explorer (color swatches, font scales, spacing visualization)

### `vue-harvest init`

Creates a `harvest.config.json` with detected project settings.

## Configuration

Optional. Place a `harvest.config.json` in the project root:

```json
{
  "include": ["**/*.vue"],
  "exclude": [
    "node_modules/**",
    "dist/**",
    "**/*.test.*",
    "**/*.story.*"
  ],
  "extractionThreshold": 70,
  "outDir": ".vue-harvest",
  "registry": "json"
}
```

Path aliases are auto-detected from `tsconfig.json`. If your project has `@` mapped to `./src`, vue-harvest picks that up.

## Component classification

Every component gets classified into a reusability tier based on its interface, dependencies, and coupling:

| Tier | Confidence | What it means |
|------|-----------|---------------|
| Primitive | 85-100% | Pure UI, no business logic. Button, Input, Card. |
| Composite | 70-85% | Built from primitives, minimal logic. FormField, DataTable. |
| Feature | 50-70% | Has business logic but potentially reusable. UserAvatar, SearchBar. |
| Page-bound | 30-50% | Tightly coupled to a specific page or route. |
| App-specific | 0-30% | Deeply coupled to app state. Not reusable as-is. |

Components at or above the extraction threshold (default 70%) are auto-extracted. The 30-70% band is where the MCP server comes in.

## Coupling issues

The analyzer detects these coupling patterns:

| Issue | Severity | Description |
|-------|----------|-------------|
| `direct-store-access` | warning | Imports a Pinia/Vuex store directly |
| `hardcoded-api` | warning | Contains hardcoded API endpoint URLs |
| `router-dependency` | info | Uses vue-router |
| `i18n-dependency` | warning | Uses vue-i18n |
| `global-inject` | warning | Uses `inject()` for app-level provides |
| `env-variable` | warning | References `import.meta.env` |
| `unscoped-css` | warning | Has unscoped styles that leak globally |
| `deep-provide-chain` | warning | Relies on provide/inject chains |
| `implicit-global` | warning | Uses globally registered components without importing them |
| `side-effect-import` | warning | Has imports that execute side effects |

## MCP server

### Setup with Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "vue-harvest": {
      "command": "vue-harvest-mcp"
    }
  }
}
```

### Setup with Claude Code

```bash
claude mcp add vue-harvest vue-harvest-mcp
```

### Available tools

| Tool | What it does |
|------|-------------|
| `analyze-project` | Runs the full pipeline on a project path |
| `list-components` | Lists components with filters (tier, confidence range) |
| `inspect-component` | Full analysis with source code |
| `extract-component` | Extracts with force option |
| `deep-analyze` | Structured coupling analysis for LLM reasoning |
| `suggest-refactor` | Before/after code for decoupling |
| `generate-wrapper` | Creates composable wrappers for store-bound components |
| `adapt-and-extract` | Full rewrite + extract in one step |
| `batch-triage` | Prioritizes all reviewable components with effort estimates |
| `coupling-report` | Project-wide coupling patterns |
| `analyze-design-system` | Extracts design tokens |
| `get-design-tokens` | Returns tokens filtered by type |

### Resources

The server exposes these as MCP resources after analysis:

- `harvest://registry` : full registry JSON
- `harvest://graph` : dependency graph
- `harvest://summary` : analysis summary
- `harvest://component/{name}` : individual component analysis
- `harvest://design-system` : extracted design tokens

### Prompts

- `analyze-new-project` : guided first analysis
- `extraction-sprint` : batch refactor and extract session
- `refactor-component` : single component deep refactor
- `extract-design-system` : design token extraction and analysis

### Example conversations

> "Analyze my Vue project at /Users/me/projects/my-app"

> "Show me all the components that need review"

> "Deep analyze the UserProfileCard component and suggest how to decouple it from the auth store"

> "Do an extraction sprint, go through all reviewable components and extract what you can"

> "Extract the design system tokens and recommend a naming convention"

## Programmatic API

vue-harvest exports its analysis engine for use in other tools:

```typescript
import { analyze, writeOutput, analyzeTokens } from 'vue-harvest'

const report = await analyze('./my-vue-app', {
  extractionThreshold: 0.6,
})

console.log(report.summary)
// { totalFiles: 42, analyzed: 40, autoExtracted: 12, needsMCP: 8, ... }

await writeOutput(report)

// Design tokens
const tokens = await analyzeTokens('./my-vue-app')
console.log(tokens.palette)    // [{ hex: '#3b82f6', usageCount: 14 }, ...]
console.log(tokens.spacing)    // ['4px', '8px', '12px', '16px', '24px']
```

## Architecture

```
vue-harvest (monorepo)
  packages/
    cli/                        Published as "vue-harvest" on npm
      src/
        types.ts                Type system shared across the whole project
        index.ts                Pipeline orchestrator
        cli.ts                  CLI entry point (citty)
        analyzers/
          sfc-analyzer.ts       SFC parsing, interface extraction, coupling detection
          graph-builder.ts      Dependency graph with Tarjan's SCC for cycle detection
          design-system-analyzer.ts   Token extraction from CSS
        extractors/
          component-extractor.ts   Import rewriting, file bundling, manifest generation
        generators/
          registry.ts           Registry JSON + catalog HTML generation
        commands/               CLI command definitions
        utils/
          config.ts             Config resolution, alias detection from tsconfig
      tests/
        fixtures/               A real mini Vue project used as test input
        unit/                   66 tests across 5 suites

    mcp/                        Published as "vue-harvest-mcp" on npm
      src/
        index.ts                MCP server (12 tools, resources, prompts)
```

The 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.

## Development

```bash
git clone https://github.com/virgilvox/vue-harvest.git
cd vue-harvest
pnpm install
pnpm build
pnpm test
```

Watch mode for the CLI:

```bash
pnpm --filter vue-harvest dev
```

Run a specific test file:

```bash
npx vitest run packages/cli/tests/unit/sfc-analyzer.test.ts
```

## How it works internally

1. **Discovery.** Globs for `.vue` files, reads `tsconfig.json` for path aliases.
2. **SFC parsing.** `@vue/compiler-sfc` splits each file into template, script, and style blocks.
3. **Interface extraction.** Regex-based extraction of `defineProps`, `defineEmits`, `<slot>` tags. Handles generic type syntax, `withDefaults`, and object syntax with nested options.
4. **Dependency analysis.** `es-module-lexer` parses imports. Each import gets classified by kind (internal component, composable, store, util, external package, etc).
5. **Coupling detection.** Pattern matching on the script and template AST for store access, hardcoded APIs, router usage, i18n, inject, env vars, unscoped CSS.
6. **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.
7. **Graph building.** Resolves import paths, builds adjacency lists, runs Tarjan's strongly connected components algorithm for cycle detection, computes transitive dependency closures.
8. **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.
9. **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.

## License

MIT

More