@kazee-ds/mcp 0.0.0-stage → 0.1.3

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@kazee-ds/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.3",
+  "description": "Versioned React and Vue documentation tools for Kazee Design System agents",
+  "type": "module",
+  "bin": {
+    "kazee-mcp": "./bin/kazee-mcp.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "dist",
+    "README.md"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.16.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "zod": "4.6.6"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.3",
+    "publint": "^0.3.25",
+    "@types/react": "^19.3.0",
+    "react": "^19.3.0",
+    "vue": "^3.5.32",
+    "vue-tsc": "^3.3.12",
+    "@kazee-ds/react": "0.5.0",
+    "@kazee-ds/vue": "0.5.0",
+    "@kazee-ds/styles": "0.5.0",
+    "@kazee-ds/tokens": "0.4.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/kazee.indonesia/kazee-design-system.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://kazee-design-system-023417.gitlab.io",
+  "scripts": {
+    "build": "node scripts/build.mjs && node --check bin/kazee-mcp.mjs && node --check src/server.mjs",
+    "test": "node --test test/*.test.mjs",
+    "lint:package": "publint --strict"
+  }
 }

package/src/catalog.mjs

@@ -0,0 +1,66 @@
+import { readFileSync } from 'node:fs';
+
+export function loadCatalog() {
+  return JSON.parse(readFileSync(new URL('../dist/catalog.json', import.meta.url), 'utf8'));
+}
+export function selectCatalog(data, framework, version) {
+  const catalog = data.catalogs.find((item) => item.version === version);
+  if (!catalog || !catalog.frameworks[framework])
+    throw new Error(
+      `Unsupported ${framework} version ${version}. Supported exact versions: ${data.catalogs.map((item) => item.version).join(', ')}. Read the installed public package.json version or lockfile; do not guess or use a semver range.`,
+    );
+  return catalog;
+}
+export function selectComponent(catalog, framework, name) {
+  const component = Object.values(catalog.frameworks[framework]).find(
+    (item) => item.name.toLowerCase() === name.toLowerCase(),
+  );
+  if (!component)
+    throw new Error(
+      `${name} is not exported by @kazee-ds/${framework}@${catalog.version}. Use list_components for this exact version; do not import another library's component under the Kazee name.`,
+    );
+  return component;
+}
+export function context(catalog, framework) {
+  return {
+    framework,
+    version: catalog.version,
+    catalogStatus: catalog.status,
+    package: `@kazee-ds/${framework}`,
+    packages: catalog.packages,
+    provenance: catalog.provenance,
+    warning:
+      catalog.status === 'release-candidate'
+        ? 'This catalog was prepared from the current workspace. Registry publication is not verified by this offline server. The workspace selector is not an installation version; use matching local packed packages for testing.'
+        : undefined,
+  };
+}
+export function themeVariables(catalog, theme, query, limit) {
+  const flat = (tree, prefix = []) =>
+    Object.entries(tree).flatMap(([key, value]) =>
+      typeof value === 'string'
+        ? [{ name: `--ds-${[...prefix, key].join('-')}`, value }]
+        : flat(value, [...prefix, key]),
+    );
+  const primitive = new Map(flat(catalog.tokens.primitive).map((item) => [item.name, item.value]));
+  const semantic = flat(catalog.tokens.semantic[theme]).map((item) => ({
+    ...item,
+    cssValue: item.value.replace(
+      /\{([a-z0-9.-]+)\}/gi,
+      (_, ref) => `var(--ds-${ref.replaceAll('.', '-')})`,
+    ),
+    resolvedValue: item.value.replace(
+      /\{([a-z0-9.-]+)\}/gi,
+      (_, ref) => primitive.get(`--ds-${ref.replaceAll('.', '-')}`) ?? `{${ref}}`,
+    ),
+  }));
+  const filtered = semantic.filter((item) => item.name.toLowerCase().includes(query.toLowerCase()));
+  return {
+    theme,
+    total: filtered.length,
+    variables: filtered.slice(0, limit),
+    truncated: filtered.length > limit,
+    usage:
+      'Use semantic --ds-* variables. Import @kazee-ds/styles/index.css once; it includes tokens. Switch themes with data-theme="light" or data-theme="dark" on a surrounding root. Application charts, maps and word clouds can consume these variables.',
+  };
+}

package/src/guides.mjs

@@ -0,0 +1,60 @@
+export const REGISTRY = 'https://registry.npmjs.org/';
+export const guides = {
+  workflow:
+    'Read get_catalog_versions, then the installed public @kazee-ds/react or @kazee-ds/vue package.json version (or exact lockfile version). Pass framework and that exact version to tools. A -workspace selector is only for explicitly reviewing this unpublished checkout or matching local packed artifacts; never substitute it for an installed registry release. Search list_components, read get_component_docs and get_component_examples before editing. Use public Kazee imports, never guessed HeroUI/Reka/React Aria props or package internals. Implement in the application. Run its existing lint, typecheck and build, then check keyboard, disabled/loading, clear/reset and relevant responsive interactions. Report missing or unrun checks. Stop dependency exploration after successful checks unless there is a concrete error. MCP tools return documentation; they do not execute commands, install packages, inspect the project, or validate its UI.',
+  composition:
+    'Compose product dashboards in the application using Card, Tabs, controls and menus. Data fetching, routing, permissions, sorting, export actions, ranking, platform markers, avatar fallback and sentiment segments remain application-owned. Avatar is not currently exported. ECharts/map/word-cloud integration stays in the application. DataTable emits sort requests; it does not sort or fetch rows. Shortcut strings are display hints; register shortcuts in the application.',
+  styling:
+    'Import @kazee-ds/styles/index.css once in the global application entry point. Use semantic --ds-* CSS variables and data-theme light/dark. Use documented component size/variant props and slots. Some components deliberately do not forward arbitrary HTML attributes; consult their API. Card and native table composition allow application layout wrappers. Preserve accessible names on icon-only controls. Use reduced-motion preferences; do not disable accessibility checks to obtain visual parity.',
+  frameworks:
+    'React uses callbacks such as onPress/onChange and isDisabled/isRequired; Vue uses @press, v-model, disabled/required and named/scoped slots. These are Kazee-specific contracts, not interchangeable HeroUI or shadcn APIs. Select chooses fixed options; Combobox provides searchable single selection in the newer catalog. Read the versioned props/events/slots rather than borrowing upstream API names.',
+  toast:
+    'Toast and ToastProvider are currently workspace-only additions, not exported by the immutable registry-verified 0.4.0 release. When matching local packed artifacts or reviewing this checkout, use createToastManager and one ToastProvider per manager; useToast accesses the nearest provider. Import the shared stylesheet once. Use semantic tone neutral/info/success/warning/danger, duration zero for persistent content, and explicit action altText. Promise updates retain the same ID and never recreate a dismissed notification. Hover/focus/window blur/hidden document pause remaining time; queued notifications start timing only when visible. Alt+T focuses the region and Escape closes one while focus is inside it. Critical errors and required responses belong in persistent application UI. New package versions and a separately verified MCP catalog are required before registry consumers can adopt Toast; this server does not publish them.',
+};
+export function installation(catalog, framework, manager, serverVersion) {
+  const workspace = catalog.provenance.source === 'workspace';
+  const registry = catalog.provenance.registry ?? REGISTRY;
+  const legacy = registry !== REGISTRY;
+  const dependencies = `@kazee-ds/${framework}@${catalog.packages[framework]} @kazee-ds/styles@${catalog.packages.styles}`;
+  const lint = `@kazee-ds/eslint-config@${catalog.packages['eslint-config']}`;
+  const commands =
+    manager === 'pnpm'
+      ? [`pnpm add --save-exact ${dependencies}`, `pnpm add --save-dev --save-exact ${lint}`]
+      : manager === 'yarn'
+        ? [`yarn add --exact ${dependencies}`, `yarn add --dev --exact ${lint}`]
+        : [
+            `npm install --save-exact ${dependencies}`,
+            `npm install --save-dev --save-exact ${lint}`,
+          ];
+  return {
+    mode: workspace
+      ? 'workspace-local'
+      : catalog.status === 'registry-verified'
+        ? 'verified-release'
+        : 'release-candidate',
+    publication: workspace
+      ? 'This is an unpublished workspace preview. Build and install matching local packed .tgz artifacts. The catalog selector is not a registry version; installing the same manifest version from the registry does not provide these workspace changes.'
+      : catalog.status === 'registry-verified'
+        ? 'This version was verified against registry archives when the catalog was built.'
+        : 'Publish matching packages before using the registry commands below. For local verification, install packed .tgz files of these exact candidate versions instead. This server does not publish or install anything.',
+    registry,
+    npmrc: `@kazee-ds:registry=${registry}\n${legacy ? '//gitlab.com/api/v4/projects/87560456/packages/npm/:_authToken=${KAZEE_DS_NPM_TOKEN}\n' : ''}`,
+    credentials: legacy
+      ? 'This historical release belongs to the private GitLab registry. Supply KAZEE_DS_NPM_TOKEN through your shell or secret manager. Never paste its value into MCP calls, source, frontend code or .mcp.json.'
+      : 'Public npm installation requires no read token or npm login. Publishing credentials belong only in the release environment, never in frontend code or consumer MCP configuration.',
+    requirements:
+      framework === 'react'
+        ? 'React and React DOM >=19, ESM. Install React/React DOM in the application. Next.js modules using hooks need a client boundary.'
+        : 'Vue >=3.4, ESM. Install Vue in the application. Nuxt global CSS belongs in its css configuration.',
+    commands: workspace ? [] : commands,
+    stylesheet: "import '@kazee-ds/styles/index.css';",
+    lint: "Merge consumerConfig() from '@kazee-ds/eslint-config' into the existing ESLint flat config after its parsers; include lint in CI. Installing the package alone does not enable the rules.",
+    mcp: {
+      mcpServers: { kazee: { command: 'npx', args: ['-y', `@kazee-ds/mcp@${serverVersion}`] } },
+    },
+    mcpPublication:
+      'The npx configuration requires this MCP package version to have been published. Before publication use node with the absolute local bin/kazee-mcp.mjs path. Merge the kazee entry into existing MCP configuration; preserve other servers. Client configuration formats differ; .mcp.json is the Claude Code project format.',
+    verification:
+      'Run existing application lint, typecheck and build. Then verify actual component interactions in a browser. Do not claim production adoption from an isolated consumer test.',
+  };
+}

package/src/server.mjs

@@ -0,0 +1,210 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import {
+  context,
+  loadCatalog,
+  selectCatalog,
+  selectComponent,
+  themeVariables,
+} from './catalog.mjs';
+import { guides, installation } from './guides.mjs';
+
+const framework = z
+  .enum(['react', 'vue'])
+  .describe('Application framework. React JSX and Vue SFC APIs are different.');
+const version = z
+  .string()
+  .regex(/^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/)
+  .max(60)
+  .describe(
+    'Exact installed Kazee framework version, not a range. Read get_catalog_versions first; never silently substitute latest. A -workspace selector is only for explicitly reviewing the unpublished checkout or matching local packed artifacts.',
+  );
+const component = z
+  .string()
+  .trim()
+  .min(1)
+  .max(80)
+  .describe('Public component name from list_components.');
+const annotations = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+};
+const response = (value) => ({
+  content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+  structuredContent: value,
+});
+export function createServer(data = loadCatalog()) {
+  const server = new McpServer(
+    { name: 'kazee-design-system', version: data.serverVersion },
+    {
+      instructions:
+        'Read-only, offline Kazee Design System reference for React/Vue. Start with get_catalog_versions. Use exact installed package versions. A -workspace selector is only for explicitly reviewing this unpublished checkout or matching local packed artifacts; it is not a registry installation version. Request public docs/examples before implementation; do not scan dependency internals. Release candidates are explicitly marked and do not prove registry publication. Documentation tools never install, modify files, execute commands, read credentials or inspect your project.',
+    },
+  );
+  function tool(name, description, inputSchema, handler) {
+    server.registerTool(name, { description, inputSchema, annotations }, async (args) => {
+      try {
+        return response(handler(args));
+      } catch (error) {
+        return { isError: true, content: [{ type: 'text', text: error.message }] };
+      }
+    });
+  }
+  tool(
+    'get_catalog_versions',
+    'Start here: list exact Kazee versions, framework coverage and publication provenance. An offline server cannot know later releases.',
+    {},
+    () => ({
+      serverVersion: data.serverVersion,
+      offline: true,
+      versions: data.catalogs.map((catalog) => ({
+        version: catalog.version,
+        status: catalog.status,
+        packages: catalog.packages,
+        components: Object.fromEntries(
+          Object.entries(catalog.frameworks).map(([key, value]) => [
+            key,
+            Object.keys(value).length,
+          ]),
+        ),
+        provenance: catalog.provenance,
+      })),
+      next: 'Read the installed public package.json or lockfile version. Pass that exact version to list_components, docs and examples. For an intentional review of this unpublished checkout, explicitly choose the workspace preview selector instead; do not use it as a registry installation version.',
+    }),
+  );
+  tool(
+    'list_components',
+    'Browse or search public components by name, function, Indonesian/English keyword, category, or aliases. Empty search lists the versioned catalog. No upstream component is invented.',
+    {
+      framework,
+      version,
+      query: z.string().trim().max(120).default(''),
+      category: z.string().max(40).optional(),
+    },
+    ({ framework, version, query, category }) => {
+      const catalog = selectCatalog(data, framework, version);
+      const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+      const components = Object.values(catalog.frameworks[framework])
+        .filter(
+          (item) =>
+            (!category || item.category === category) &&
+            terms.every((term) =>
+              [item.name, item.description, ...item.keywords]
+                .join(' ')
+                .toLowerCase()
+                .includes(term),
+            ),
+        )
+        .map(({ name, category, description }) => ({ name, category, description }));
+      return {
+        ...context(catalog, framework),
+        total: components.length,
+        components,
+        next: components.length
+          ? 'Read get_component_docs and get_component_examples for the selected component.'
+          : 'No matching Kazee component in this version. Do not invent an import; use application composition or review another supported version.',
+      };
+    },
+  );
+  tool(
+    'get_component_docs',
+    'Get exact versioned public props, discriminated variants, events, slots, related types and constraints. Generated from package declarations; use these contracts instead of headless-library APIs.',
+    { framework, version, component },
+    ({ framework, version, component }) => {
+      const catalog = selectCatalog(data, framework, version);
+      const { examples, ...docs } = selectComponent(catalog, framework, component);
+      return {
+        ...context(catalog, framework),
+        ...docs,
+        exampleIds: examples.map((item) => item.id),
+        guidance: guides.frameworks,
+      };
+    },
+  );
+  tool(
+    'get_component_examples',
+    'Get complete, typechecked React .tsx or Vue .vue modules using only public Kazee imports. Select an exampleId from docs, or omit it for all examples of this component/version.',
+    {
+      framework,
+      version,
+      component,
+      exampleId: z.string().trim().min(1).max(80).optional(),
+    },
+    ({ framework, version, component, exampleId }) => {
+      const catalog = selectCatalog(data, framework, version);
+      const item = selectComponent(catalog, framework, component);
+      const examples = item.examples.filter((item) => !exampleId || item.id === exampleId);
+      if (!examples.length)
+        throw new Error(
+          `Unknown example ${exampleId}. Available: ${item.examples.map((item) => item.id).join(', ')}`,
+        );
+      return { ...context(catalog, framework), component: item.name, examples };
+    },
+  );
+  tool(
+    'get_theme_variables',
+    'Search semantic CSS variables with actual light/dark token values for this package version. Uses bundled data; does not inspect or mutate application themes.',
+    {
+      framework,
+      version,
+      theme: z.enum(['light', 'dark']).default('light'),
+      query: z.string().max(100).default(''),
+      limit: z.number().int().min(1).max(100).default(40),
+    },
+    ({ framework, version, theme, query, limit }) => {
+      const catalog = selectCatalog(data, framework, version);
+      return { ...context(catalog, framework), ...themeVariables(catalog, theme, query, limit) };
+    },
+  );
+  tool(
+    'get_installation',
+    'Return version-pinned installation, registry-specific guidance, global CSS, lint and MCP setup. New public npm releases need no read token; historical GitLab catalogs keep their original registry. Read-only documentation: no installation, credential access or file writes occur.',
+    {
+      framework,
+      version,
+      packageManager: z.enum(['npm', 'pnpm', 'yarn']).default('npm'),
+    },
+    ({ framework, version, packageManager }) => {
+      const catalog = selectCatalog(data, framework, version);
+      return {
+        ...context(catalog, framework),
+        ...installation(catalog, framework, packageManager, data.serverVersion),
+      };
+    },
+  );
+  tool(
+    'get_guides',
+    'Read Kazee agent workflow, styling, React/Vue differences, Toast lifecycle, or dashboard application-composition boundaries.',
+    { topic: z.enum(['workflow', 'styling', 'frameworks', 'composition', 'toast']) },
+    ({ topic }) => ({ topic, guide: guides[topic] }),
+  );
+  server.registerResource(
+    'workflow',
+    'kazee://guides/workflow',
+    { description: 'Kazee agent workflow and public API boundaries', mimeType: 'text/plain' },
+    async (uri) => ({
+      contents: [{ uri: uri.href, mimeType: 'text/plain', text: guides.workflow }],
+    }),
+  );
+  server.registerResource(
+    'versions',
+    'kazee://catalog/versions',
+    { description: 'Bundled version/catalog provenance', mimeType: 'application/json' },
+    async (uri) => ({
+      contents: [
+        {
+          uri: uri.href,
+          mimeType: 'application/json',
+          text: JSON.stringify(
+            data.catalogs.map(({ version, status, packages }) => ({ version, status, packages })),
+            null,
+            2,
+          ),
+        },
+      ],
+    }),
+  );
+  return server;
+}