@pythoughts/vue-skills-mcp 0.1.0

package/README.md

@@ -0,0 +1,63 @@
+# vue-skills MCP server
+
+Part of [Pythoughts-labs/vue3-best-practices](https://github.com/Pythoughts-labs/vue3-best-practices).
+
+Exposes the Vue 3 best-practice skills in this repo as MCP tools, so any MCP
+coding agent can fetch them while working on Vue.
+
+## Tools
+
+- **`vue_best_practices`** — primary tool. No args → full index (every skill's
+  workflow + its reference filenames). Pass `skill` to scope to one. Its
+  description is written to fire on any Vue signal (`.vue`, `<script setup>`,
+  Pinia, Vue Router, Vitest, Vue SSR…).
+- **`get_vue_reference`** — full content of one reference file (deep dive).
+
+Progressive disclosure: the index returns overviews + a reference list; the
+agent pulls only the references it needs.
+
+## Setup
+
+```bash
+cd mcp && npm install
+```
+
+Register the server with your agent. Replace `<REPO>` with this repo's absolute
+path.
+
+### Claude Code
+
+```bash
+claude mcp add vue-skills -- node <REPO>/mcp/index.mjs
+```
+
+### Cursor / Windsurf (`~/.cursor/mcp.json` or `mcp_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "vue-skills": { "command": "node", "args": ["<REPO>/mcp/index.mjs"] }
+  }
+}
+```
+
+`VUE_SKILLS_DIR` overrides where skills are read from (defaults to `../skills`).
+
+## About "automatic"
+
+MCP has no push trigger — an agent calls a tool when it judges the tool's
+description relevant. There is no way to *force* a call. This server maximizes
+the chance by engineering `vue_best_practices`'s description to match any Vue
+signal. To make it reliable, add one line to your project's agent rules
+(`AGENTS.md`, `.cursorrules`, Claude Code `CLAUDE.md`):
+
+> Before any Vue work, call the `vue_best_practices` MCP tool and apply it.
+
+That rule is the actual "always fetch on Vue work" guarantee; the MCP server is
+what makes the content callable.
+
+## Test
+
+```bash
+npm test
+```

package/index.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// MCP server exposing the Vue 3 best-practice skills in this repo.
+// Any MCP client (Claude Code, Cursor, Windsurf, ...) can call these tools.
+// The agent decides when to call; the tool descriptions are written so a Vue
+// signal (a .vue file, <script setup>, Pinia, Vue Router, Vite+Vue) triggers it.
+
+import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Resolution order: VUE_SKILLS_DIR override, then the bundled skills/ shipped
+// inside the published package, then ../skills for in-repo (dev) use.
+function resolveSkillsDir() {
+  if (process.env.VUE_SKILLS_DIR) return resolve(process.env.VUE_SKILLS_DIR);
+  const bundled = join(__dirname, "skills");
+  return existsSync(bundled) ? bundled : join(__dirname, "..", "skills");
+}
+const SKILLS_DIR = resolveSkillsDir();
+
+// --- Discover skills at startup -------------------------------------------
+// Build an explicit name -> {description, skillMd, references{name->path}} map.
+// References are served only from this prebuilt map, so an agent-supplied name
+// can never traverse outside the skills directory.
+function loadSkills(root) {
+  const skills = {};
+  let dirs;
+  try {
+    dirs = readdirSync(root).filter((d) => statSync(join(root, d)).isDirectory());
+  } catch (err) {
+    throw new Error(`Cannot read skills dir "${root}": ${err.message}`);
+  }
+  for (const name of dirs) {
+    const skillPath = join(root, name, "SKILL.md");
+    let skillMd;
+    try {
+      skillMd = readFileSync(skillPath, "utf8");
+    } catch {
+      continue; // not a skill dir
+    }
+    const references = {};
+    for (const refDir of ["references", "reference"]) {
+      const full = join(root, name, refDir);
+      try {
+        for (const f of readdirSync(full)) {
+          if (f.endsWith(".md")) references[f] = join(full, f);
+        }
+      } catch {
+        // dir absent; ignore
+      }
+    }
+    skills[name] = { description: parseDescription(skillMd), skillMd, references };
+  }
+  if (Object.keys(skills).length === 0) {
+    throw new Error(`No skills with a SKILL.md found under "${root}"`);
+  }
+  return skills;
+}
+
+function parseDescription(md) {
+  const m = md.match(/^description:\s*(.+)$/m);
+  return m ? m[1].trim() : "(no description)";
+}
+
+const SKILLS = loadSkills(SKILLS_DIR);
+const SKILL_NAMES = Object.keys(SKILLS).sort();
+
+// --- Server ---------------------------------------------------------------
+const server = new McpServer({ name: "vue-skills", version: "1.0.0" });
+
+const TRIGGER =
+  "Call this IMMEDIATELY and BEFORE writing or editing any code when you detect " +
+  "Vue work: a .vue file, Composition API, <script setup>, Options API, Vue Router, " +
+  "Pinia, Vite + Vue, Vue testing (Vitest/Vue Test Utils/Playwright), Vue JSX, or " +
+  "Vue SSR/hydration. Returns the current Vue 3 best-practice index so you apply " +
+  "up-to-date patterns instead of relying on training data.";
+
+// Primary auto-trigger tool: returns the full best-practice index.
+server.tool(
+  "vue_best_practices",
+  TRIGGER +
+    " With no arguments, returns every skill's overview (the actionable workflow) " +
+    "plus the list of deep-dive reference files. Pass `skill` to get one skill's " +
+    "overview only. Pull a reference's full content with the `get_vue_reference` tool.",
+  { skill: z.enum(SKILL_NAMES).optional().describe("Limit output to one skill.") },
+  async ({ skill }) => {
+    const names = skill ? [skill] : SKILL_NAMES;
+    const sections = names.map((name) => {
+      const s = SKILLS[name];
+      const refs = Object.keys(s.references).sort();
+      const refList = refs.length
+        ? `\n\nReference files (fetch via get_vue_reference("${name}", <file>)):\n` +
+          refs.map((r) => `- ${r}`).join("\n")
+        : "";
+      return `\n\n${"=".repeat(72)}\n# SKILL: ${name}\n${"=".repeat(72)}\n\n${s.skillMd}${refList}`;
+    });
+    const header = skill
+      ? `Vue best-practice skill: ${skill}`
+      : `Vue 3 best-practice index — ${SKILL_NAMES.length} skills. Read the overviews, ` +
+        `then fetch only the reference files relevant to your task.`;
+    return { content: [{ type: "text", text: header + sections.join("") }] };
+  }
+);
+
+// Drill-down tool: full content of one reference file.
+server.tool(
+  "get_vue_reference",
+  "Return the full content of one Vue best-practice reference file (deep-dive on a " +
+    "specific pattern). Use the skill name and reference filename listed by " +
+    "vue_best_practices.",
+  {
+    skill: z.enum(SKILL_NAMES).describe("Skill that owns the reference."),
+    reference: z.string().describe("Reference filename, e.g. reactivity.md"),
+  },
+  async ({ skill, reference }) => {
+    const path = SKILLS[skill]?.references[reference];
+    if (!path) {
+      const available = Object.keys(SKILLS[skill]?.references ?? {}).sort();
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text:
+              `No reference "${reference}" in skill "${skill}". ` +
+              `Available: ${available.join(", ") || "(none)"}`,
+          },
+        ],
+      };
+    }
+    return { content: [{ type: "text", text: readFileSync(path, "utf8") }] };
+  }
+);
+
+await server.connect(new StdioServerTransport());
+console.error(`vue-skills MCP ready: ${SKILL_NAMES.length} skills from ${SKILLS_DIR}`);

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@pythoughts/vue-skills-mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "MCP server exposing the Vue 3 best-practice skills so any MCP coding agent can fetch them automatically on Vue work.",
+  "author": "Mohamed Elkholy (elkaix)",
+  "license": "MIT",
+  "homepage": "https://github.com/Pythoughts-labs/vue3-best-practices",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Pythoughts-labs/vue3-best-practices.git",
+    "directory": "mcp"
+  },
+  "bin": {
+    "vue-skills-mcp": "./index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "skills"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node index.mjs",
+    "test": "node smoke-test.mjs",
+    "prepack": "rm -rf skills && cp -R ../skills ./skills",
+    "postpack": "rm -rf skills"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  }
+}

package/skills/create-adaptable-composable/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: create-adaptable-composable
+description: Create a library-grade Vue composable that accepts maybe-reactive inputs (MaybeRef / MaybeRefOrGetter) so callers can pass a plain value, ref, or getter. Normalize inputs with toValue()/toRef() inside reactive effects (watch/watchEffect) to keep behavior predictable and reactive. Use this skill when user asks for creating adaptable or reusable composables.
+license: MIT
+metadata:
+  author: github.com/Pythoughts-labs
+  version: "17.0.0"
+compatibility: Requires Vue 3 (or above) or Nuxt 3 (or above) project
+---
+
+# Create Adaptable Composable
+
+Adaptable composables are reusable functions that can accept both reactive and non-reactive inputs. This allows developers to use the composable in a variety of contexts without worrying about the reactivity of the inputs.
+
+Steps to design an adaptable composable in Vue.js:
+1. Confirm the composable's purpose and API design and expected inputs/outputs.
+2. Identify inputs params that should be reactive (MaybeRef / MaybeRefOrGetter).
+3. Use `toValue()` or `toRef()` to normalize inputs inside reactive effects.
+4. Implement the core logic of the composable using Vue's reactivity APIs.
+
+## Core Type Concepts
+
+### Type Utilities
+
+```ts
+/**
+ * value or writable ref (value/ref/shallowRef/writable computed)
+ */
+export type MaybeRef<T = any> = T | Ref<T> | ShallowRef<T> | WritableComputedRef<T>;
+
+/**
+ * MaybeRef<T> + ComputedRef<T> + () => T
+ */
+export type MaybeRefOrGetter<T = any> = MaybeRef<T> | ComputedRef<T> | (() => T);
+```
+
+### Policy and Rules
+
+- Read-only, computed-friendly input: use `MaybeRefOrGetter`
+- Needs to be writable / two-way input: use `MaybeRef`
+- Parameter might be a function value (callback/predicate/comparator): do not use `MaybeRefOrGetter`, or you may accidentally invoke it as a getter.
+- DOM/Element targets: if you want computed/derived targets, use `MaybeRefOrGetter`.
+
+When `MaybeRefOrGetter` or `MaybeRef` is used: 
+- resolve reactive value using `toRef()` (e.g. watcher source)
+- resolve non-reactive value using `toValue()`
+
+### Examples
+
+Adaptable `useDocumentTitle` Composable: read-only title parameter
+
+```ts
+import { watch, toRef } from 'vue'
+import type { MaybeRefOrGetter } from 'vue'
+
+export function useDocumentTitle(title: MaybeRefOrGetter<string>) {
+  watch(toRef(title), (t) => {
+    document.title = t
+  }, { immediate: true })
+}
+```
+
+Adaptable `useCounter` Composable: two-way writable count parameter
+
+```ts
+import { watch, toRef } from 'vue'
+import type { MaybeRef } from 'vue'
+
+function useCounter(count: MaybeRef<number>) {
+  const countRef = toRef(count)
+  function add() {
+    countRef.value++
+  }
+  return { add }
+}
+```

package/skills/vue-best-practices/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: vue-best-practices
+description: MUST be used for Vue.js tasks. Strongly recommends Composition API with `<script setup>` and TypeScript as the standard approach. Covers Vue 3, SSR, Volar, vue-tsc. Load for any Vue, .vue files, Vue Router, Pinia, or Vite with Vue work. ALWAYS use Composition API unless the project explicitly requires Options API.
+license: MIT
+metadata:
+  author: github.com/Pythoughts-labs
+  version: "18.1.0"
+---
+
+# Vue Best Practices Workflow
+
+Use this skill as an instruction set. Follow the workflow in order unless the user explicitly asks for a different order.
+
+## Core Principles
+- **Keep state predictable:** one source of truth, derive everything else.
+- **Make data flow explicit:** Props down, Events up for most cases.
+- **Favor small, focused components:** easier to test, reuse, and maintain.
+- **Avoid unnecessary re-renders:** use computed properties and watchers wisely.
+- **Readability counts:** write clear, self-documenting code.
+
+## 1) Confirm architecture before coding (required)
+
+- Default stack: Vue 3 + Composition API + `<script setup lang="ts">`.
+- If the project explicitly uses Options API, load `vue-options-api-best-practices` skill if available.
+- If the project explicitly uses JSX, load `vue-jsx-best-practices` skill if available.
+
+### 1.1 Must-read core references (required)
+
+- Before implementing any Vue task, make sure to read and apply these core references:
+  - `references/reactivity.md`
+  - `references/sfc.md`
+  - `references/component-data-flow.md`
+  - `references/composables.md`
+- Keep these references in active working context for the entire task, not only when a specific issue appears.
+
+### 1.2 Plan component boundaries before coding (required)
+
+Create a brief component map before implementation for any non-trivial feature.
+
+- Define each component's single responsibility in one sentence.
+- Keep entry/root and route-level view components as composition surfaces by default.
+- Move feature UI and feature logic out of entry/root/view components unless the task is intentionally a tiny single-file demo.
+- Define props/emits contracts for each child component in the map.
+- Prefer a feature folder layout (`components/<feature>/...`, `composables/use<Feature>.ts`) when adding more than one component.
+
+## 2) Apply essential Vue foundations (required)
+
+These are essential, must-know foundations. Apply all of them in every Vue task using the core references already loaded in section `1.1`.
+
+### Reactivity
+
+- Must-read reference from `1.1`: [reactivity](references/reactivity.md)
+- Keep source state minimal (`ref`/`reactive`), derive everything possible with `computed`.
+- Use watchers for side effects if needed.
+- Avoid recomputing expensive logic in templates.
+
+### SFC structure and template safety
+
+- Must-read reference from `1.1`: [sfc](references/sfc.md)
+- Keep SFC sections in this order: `<script>` → `<template>` → `<style>`.
+- Keep SFC responsibilities focused; split large components.
+- Keep templates declarative; move branching/derivation to script.
+- Apply Vue template safety rules (`v-html`, list rendering, conditional rendering choices).
+
+### Keep components focused
+
+Split a component when it has **more than one clear responsibility** (e.g. data orchestration + UI, or multiple independent UI sections).
+
+- Prefer **smaller components + composables** over one “mega component”
+- Move **UI sections** into child components (props in, events out).
+- Move **state/side effects** into composables (`useXxx()`).
+
+Apply objective split triggers. Split the component if **any** condition is true:
+
+- It owns both orchestration/state and substantial presentational markup for multiple sections.
+- It has 3+ distinct UI sections (for example: form, filters, list, footer/status).
+- A template block is repeated or could become reusable (item rows, cards, list entries).
+
+Entry/root and route view rule:
+
+- Keep entry/root and route view components thin: app shell/layout, provider wiring, and feature composition.
+- Do not place full feature implementations in entry/root/view components when those features contain independent parts.
+- For CRUD/list features (todo, table, catalog, inbox), split at least into:
+  - feature container component
+  - input/form component
+  - list (and/or item) component
+  - footer/actions or filter/status component
+- Allow a single-file implementation only for very small throwaway demos; if chosen, explicitly justify why splitting is unnecessary.
+
+### Component data flow
+
+- Must-read reference from `1.1`: [component-data-flow](references/component-data-flow.md)
+- Use props down, events up as the primary model.
+- Use `v-model` only for true two-way component contracts.
+- Use provide/inject only for deep-tree dependencies or shared context.
+- Keep contracts explicit and typed with `defineProps`, `defineEmits`, and `InjectionKey` as needed.
+
+### Composables
+
+- Must-read reference from `1.1`: [composables](references/composables.md)
+- Extract logic into composables when it is reused, stateful, or side-effect heavy.
+- Keep composable APIs small, typed, and predictable.
+- Separate feature logic from presentational components.
+
+## 3) Consider optional features only when requirements call for them
+
+### 3.1 Standard optional features
+
+Do not add these by default. Load the matching reference only when the requirement exists.
+
+- Slots: parent needs to control child content/layout -> [component-slots](references/component-slots.md)
+- Fallthrough attributes: wrapper/base components must forward attrs/events safely -> [component-fallthrough-attrs](references/component-fallthrough-attrs.md)
+- Built-in component `<KeepAlive>` for stateful view caching -> [component-keep-alive](references/component-keep-alive.md)
+- Built-in component `<Teleport>` for overlays/portals -> [component-teleport](references/component-teleport.md)
+- Built-in component `<Suspense>` for async subtree fallback boundaries -> [component-suspense](references/component-suspense.md)
+- Animation-related features: pick the simplest approach that matches the required motion behavior.
+  - Built-in component `<Transition>` for enter/leave effects -> [transition](references/component-transition.md)
+  - Built-in component `<TransitionGroup>` for animated list mutations -> [transition-group](references/component-transition-group.md)
+  - Class-based animation for non-enter/leave effects -> [animation-class-based-technique](references/animation-class-based-technique.md)
+  - State-driven animation for user-input-driven animation -> [animation-state-driven-technique](references/animation-state-driven-technique.md)
+
+### 3.2 Less-common optional features
+
+Use these only when there is explicit product or technical need.
+
+- Directives: behavior is DOM-specific and not a good composable/component fit -> [directives](references/directives.md)
+- Async components: heavy/rarely-used UI should be lazy loaded -> [component-async](references/component-async.md)
+- Render functions only when templates cannot express the requirement -> [render-functions](references/render-functions.md)
+- Plugins when behavior must be installed app-wide -> [plugins](references/plugins.md)
+- State management patterns: app-wide shared state crosses feature boundaries -> [state-management](references/state-management.md)
+
+## 4) Run performance optimization after behavior is correct
+
+Performance work is a post-functionality pass. Do not optimize before core behavior is implemented and verified.
+
+- Large list rendering bottlenecks -> [perf-virtualize-large-lists](references/perf-virtualize-large-lists.md)
+- Static subtrees re-rendering unnecessarily -> [perf-v-once-v-memo-directives](references/perf-v-once-v-memo-directives.md)
+- Over-abstraction in hot list paths -> [perf-avoid-component-abstraction-in-lists](references/perf-avoid-component-abstraction-in-lists.md)
+- Expensive updates triggered too often -> [updated-hook-performance](references/updated-hook-performance.md)
+
+## 5) Final self-check before finishing
+
+- Core behavior works and matches requirements.
+- All must-read references were read and applied.
+- Reactivity model is minimal and predictable.
+- SFC structure and template rules are followed.
+- Components are focused and well-factored, splitting when needed.
+- Entry/root and route view components remain composition surfaces unless there is an explicit small-demo exception.
+- Component split decisions are explicit and defensible (responsibility boundaries are clear).
+- Data flow contracts are explicit and typed.
+- Composables are used where reuse/complexity justifies them.
+- Moved state/side effects into composables if applicable
+- Optional features are used only when requirements demand them.
+- Performance changes were applied only after functionality was complete.