@vargov/mcp 0.0.0-stage → 0.1.0

package/dist/data.js

@@ -0,0 +1,148 @@
+// Loads the bundled data (./data) once and builds the indexes the tools use.
+// The server never reads the network: every fact comes from these files.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const here = dirname(fileURLToPath(import.meta.url)); // dist/
+export const DATA_DIR = join(here, '..', 'data');
+export const LANGS = ['ru', 'en', 'de', 'it', 'fr', 'es', 'vi', 'ar'];
+export const FAMILIES = ['lighting', 'decorative', 'sculptural-decor', 'floor-table-lamps'];
+/**
+ * Ready scenes: compositions that open in the configurator as a ready-made 3D model, not as a
+ * calculated cloud of elements. Since 26.10.2026 the configurator publishes them in open-skus.json as `scenes`
+ * (source: scene3d in its model data); this constant is only the fallback for an older open-skus.json without the field.
+ * Before that field existed the public sources named one:
+ *  - en/llms.txt and knowledge/whats-new-2026-10.md (vargov-ai-kb): "the ready scene LC0406-1 — a wall light
+ *    whose composition is ready-made rather than calculated, so there is no layout and no ceiling setting-out";
+ *  - open-skus.json `rule`: "ready-made pieces shown as their own 3D model, e.g. the LC0406-1 wall sconce".
+ * The 1:1 drawing count published by the brand (345 of 360) = 360 − 10 ribbons − 4 frames − this 1 ready scene;
+ * test/smoke.mjs checks that equation against the bundled data.
+ */
+const READY_SCENES = ['LC0406-1'];
+function readText(name) {
+    const file = join(DATA_DIR, name);
+    return existsSync(file) ? readFileSync(file, 'utf8') : null;
+}
+function readJson(name, required) {
+    const txt = readText(name);
+    if (txt === null) {
+        if (required)
+            throw new Error(`vargov-mcp: required data file missing: ${join(DATA_DIR, name)} — run "npm run update-data"`);
+        return null;
+    }
+    return JSON.parse(txt);
+}
+/** Normalises user input to the catalogue code form: "lc0564" → "LC0564", " LC 0406-1 " → "LC0406-1", "564" → "LC0564". */
+export function normalizeCode(input) {
+    let s = String(input ?? '').trim().toUpperCase().replace(/\s+/g, '');
+    if (/^\d{1,4}(-\d)?$/.test(s)) {
+        const [num, suffix] = s.split('-');
+        s = 'LC' + num.padStart(4, '0') + (suffix ? '-' + suffix : '');
+    }
+    return s;
+}
+/**
+ * `lit` is a hint derived from public labels, not a measured property:
+ * true for the "lighting" family and for any type label that mentions light / lamp / backlit / luminaire.
+ */
+export function isLit(p) {
+    if (p.category === 'lighting')
+        return true;
+    return /\b(light|lamp|backlit|luminaire|illuminat)/i.test(p.type?.en ?? '');
+}
+function lower(s) {
+    return typeof s === 'string' ? s.toLowerCase().normalize('NFC') : '';
+}
+function joinLangs(rec, langs) {
+    if (!rec)
+        return '';
+    return langs.map((l) => lower(rec[l])).filter(Boolean).join(' \n ');
+}
+let cached = null;
+export function getData() {
+    if (cached)
+        return cached;
+    const products = readJson('products.json', true);
+    const open = readJson('open-skus.json', true);
+    const sketchfabRaw = readJson('sketchfab-models.json', false);
+    const orgRaw = readJson('organization.jsonld', true);
+    const brandFacts = readJson('brand-facts.json', false);
+    const manifest = readJson('manifest.json', false);
+    const llmsEn = readText('llms-en.txt') ?? '';
+    const llmsRu = readText('llms-ru.txt') ?? '';
+    const llmsConfigurator = readText('llms-configurator.txt');
+    const graph = orgRaw['@graph'] ?? [];
+    const pick = (type) => graph.find((n) => n['@type'] === type) ?? null;
+    const openSet = new Set(open.skus.map((s) => s.toUpperCase()));
+    const ribbons = new Set();
+    const chains = new Set();
+    for (const [sku, s] of Object.entries(open.series ?? {})) {
+        if (s.ribbon)
+            ribbons.add(sku.toUpperCase());
+        if (s.chain)
+            chains.add(sku.toUpperCase());
+    }
+    const frames = new Set((open.frames ?? []).map((s) => s.toUpperCase()));
+    const readyScenes = new Set((open.scenes ?? READY_SCENES).map((s) => s.toUpperCase()).filter((s) => openSet.has(s)));
+    const kindOf = (code) => {
+        if (!openSet.has(code))
+            return null;
+        if (ribbons.has(code))
+            return 'ribbon';
+        if (chains.has(code))
+            return 'chain';
+        if (frames.has(code))
+            return 'frame';
+        if (readyScenes.has(code))
+            return 'ready-scene';
+        return 'cloud';
+    };
+    const otherLangs = LANGS.filter((l) => l !== 'ru' && l !== 'en');
+    const entries = products.map((p) => {
+        const code = p.code.toUpperCase();
+        return {
+            p,
+            code,
+            nameRu: `${p.type?.ru ?? p.category_label?.ru ?? ''} ${p.code}`.trim(),
+            nameEn: `${p.type?.en ?? p.category_label?.en ?? ''} ${p.code}`.trim(),
+            lit: isLit(p),
+            configurable: openSet.has(code),
+            kind: kindOf(code),
+            f: {
+                code: `${code.toLowerCase()} ${lower(p.slug)}`,
+                type: [joinLangs(p.type, LANGS), lower(p.category_label?.ru), lower(p.category_label?.en), lower(p.category)].join(' '),
+                where: joinLangs(p.where_it_works, ['ru', 'en']),
+                style: joinLangs(p.style, ['ru', 'en']),
+                desc: joinLangs(p.description, ['ru', 'en']) + ' ' + joinLangs(p.made_to_order, ['ru', 'en']),
+                other: [p.description, p.where_it_works, p.style].map((r) => joinLangs(r, otherLangs)).join(' '),
+            },
+        };
+    });
+    const byCode = new Map();
+    for (const e of entries)
+        byCode.set(e.code, e);
+    const sketchfab = new Map();
+    for (const [code, item] of Object.entries(sketchfabRaw?.items ?? {}))
+        sketchfab.set(code.toUpperCase(), item);
+    cached = {
+        products,
+        entries,
+        byCode,
+        open,
+        openSet,
+        ribbons,
+        chains,
+        frames,
+        readyScenes,
+        sketchfab,
+        organization: pick('Organization'),
+        person: pick('Person'),
+        store: pick('Store'),
+        brandFacts,
+        llmsEn,
+        llmsRu,
+        llmsConfigurator,
+        manifest,
+    };
+    return cached;
+}

package/dist/index.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// Entry point: MCP server over stdio. Nothing but the protocol goes to stdout; diagnostics go to stderr.
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { getData } from './data.js';
+import { SERVER_NAME, SERVER_VERSION, createServer } from './server.js';
+async function main() {
+    const d = getData(); // fail fast if data/ is missing
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write(`${SERVER_NAME} ${SERVER_VERSION}: ${d.products.length} compositions, ${d.openSet.size} open in the configurator; stdio ready\n`);
+}
+main().catch((err) => {
+    process.stderr.write(`${SERVER_NAME}: fatal: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/server.js

@@ -0,0 +1,101 @@
+// Registers the tools and resources on an McpServer. Transport is chosen by index.ts.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { bimGuide } from './bim.js';
+import { brandFacts } from './brand.js';
+import { SEARCH_LIMIT_DEFAULT, SEARCH_LIMIT_MAX, buildConfiguratorLink, compositionCard, isLinkError, searchCompositions } from './catalog.js';
+import { FAMILIES, LANGS, getData } from './data.js';
+export const SERVER_NAME = 'vargov-design';
+export const SERVER_VERSION = '0.1.0';
+const LangSchema = z.enum(LANGS);
+function textResult(payload, isError = false) {
+    const text = typeof payload === 'string' ? payload : JSON.stringify(payload, null, 1);
+    return { content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) };
+}
+export function createServer() {
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, {
+        instructions: 'Vargov®Design: 605 made-to-order light and decorative compositions (codes LC0001…LC0602). ' +
+            'Use search_compositions to find candidates for a room, get_composition for the card, build_configurator_link to open the 3D configurator with the plan dimensions and ceiling height, how_to_get_bim for the IFC4/FBX steps, brand_facts for the brand card. ' +
+            'The brand publishes no prices, no materials and no composition dimensions: every composition is scaled to the room; quotes come per request. All data is bundled; the server makes no network calls.',
+    });
+    server.registerTool('search_compositions', {
+        title: 'Search Vargov®Design compositions',
+        description: 'Search the Vargov®Design catalogue: 605 made-to-order light and decorative compositions, codes LC0001…LC0602. ' +
+            'Full-text over codes, type labels and the brand\'s own texts (description, where it works, style) in Russian and English; other site languages are matched too. ' +
+            'Filters: family (lighting | decorative | sculptural-decor | floor-table-lamps); lit (true = the lighting family or a type label mentioning light/lamp/backlit — a hint derived from labels, not a measured property); ' +
+            'awarded (has a listed award); configurable (opens in the 3D configurator with a full calculation: IFC4, FBX, PDF specification, tender sheet — 360 of 605). ' +
+            'Returns compact rows: code, names RU/EN, family, type, flags, site pages, cover image, English snippet. ' +
+            'Then use get_composition for details and build_configurator_link to open the configurator with the room plan. No prices, materials or composition dimensions are published.',
+        inputSchema: {
+            query: z.string().max(300).optional().describe('Words or a code, e.g. "hotel lobby", "birds", "гостиная", "LC0564"'),
+            family: z.enum(FAMILIES).optional(),
+            lit: z.boolean().optional().describe('true: light-emitting (hint from labels); false: decorative/unlit'),
+            awarded: z.boolean().optional(),
+            configurable: z.boolean().optional().describe('true: opens in the configurator with a full calculation (IFC4/FBX/PDF/tender sheet)'),
+            limit: z.number().int().min(1).max(SEARCH_LIMIT_MAX).optional().describe(`default ${SEARCH_LIMIT_DEFAULT}, max ${SEARCH_LIMIT_MAX}`),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    }, async (args) => textResult(searchCompositions(args)));
+    server.registerTool('get_composition', {
+        title: 'Composition card',
+        description: 'Everything the public dataset knows about one composition by its code (LC0564, lc0564, "564" are all accepted): names RU/EN, family and type, the brand\'s texts in the requested language (default en; ru de it fr es vi ar available), ' +
+            'site pages in 8 languages, cover image, 3D models (3ddd/3dsky, Sketchfab), awards, whether it is certified (fact only), ' +
+            'and the configurator status: opens with a full calculation or is calculated individually; kind (cloud of elements / ribbon / chain / on a frame / ready scene); IFC4, FBX, PDF and tender-sheet exports; whether the 1:1 ceiling drawing exists; ready links. ' +
+            'No price, no materials, no composition dimensions — they are not published.',
+        inputSchema: {
+            code: z.string().min(1).max(20).describe('Catalogue code, e.g. LC0564 or LC0406-1'),
+            lang: LangSchema.optional().describe('Language of the texts, default en'),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    }, async ({ code, lang }) => {
+        const card = compositionCard(code, lang ?? 'en');
+        if (!card)
+            return textResult({ error: `Code "${code}" is not in the catalogue (LC0001…LC0602, some with a -1/-2 suffix). Use search_compositions.` }, true);
+        return textResult(card);
+    });
+    server.registerTool('build_configurator_link', {
+        title: 'Configurator link with room dimensions',
+        description: 'Builds a link that opens the Vargov®Design 3D configurator on a composition with the plan dimensions and the room ceiling height already filled in. ' +
+            'Only codes that open with a full calculation are accepted (360 of 605; others return an error with the product page). ' +
+            'lengthMm → the "Length" field of the plan, widthMm → the "Width" field, both integer millimetres, at least 300 (the plan is the zone the composition is laid out in, not a product size); ' +
+            'heightMm → height of the cloud of elements (optional); ceilingMm → room ceiling height (optional, default 2700 in the configurator; it goes into the IFC4 file and AR); ' +
+            'lang → interface language (ru opens configurator.vargov.ru, other languages vargov.design); openOnFormStep → open scrolled to the "Composition form" step. ' +
+            'The visitor then picks element sizes, colours and the form; the configurator\'s "Share" button returns a link that reopens that exact calculation.',
+        inputSchema: {
+            code: z.string().min(1).max(20),
+            lengthMm: z.number().optional().describe('Plan length, integer mm, ≥ 300'),
+            widthMm: z.number().optional().describe('Plan width, integer mm, ≥ 300'),
+            heightMm: z.number().optional().describe('Height of the cloud of elements, integer mm (optional)'),
+            ceilingMm: z.number().optional().describe('Room ceiling height, integer mm (optional; configurator default 2700)'),
+            lang: LangSchema.optional().describe('ru en de it fr es vi ar; default en'),
+            openOnFormStep: z.boolean().optional().describe('true: add step=form to open scrolled to the form step'),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    }, async (args) => {
+        const r = buildConfiguratorLink(args);
+        return isLinkError(r) ? textResult(r, true) : textResult(r);
+    });
+    server.registerTool('how_to_get_bim', {
+        title: 'How to get IFC4 (BIM) and FBX',
+        description: 'Step-by-step: where the "Download IFC (BIM)" and "Download FBX (3ds Max)" buttons are (step "3D composition scheme" → "Documents" drawer), what the IFC4 and FBX files contain and what they do not (no textures/UV, BIM properties only in IFC4, ceiling fixing points as IfcDiscreteAccessory objects), ' +
+            'and when the 1:1 ceiling drawing opens (only after the production brief is started in production). With a code, the answer starts with the status of that composition (full calculation / calculated individually; ribbon, chain, frame, ready scene). Text in English or Russian.',
+        inputSchema: {
+            code: z.string().max(20).optional().describe('Optional catalogue code to prefix the guide with that composition\'s status'),
+            lang: z.enum(['en', 'ru']).optional().describe('en (default) or ru'),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    }, async ({ code, lang }) => textResult(bimGuide(code, lang ?? 'en')));
+    server.registerTool('brand_facts', {
+        title: 'Brand card',
+        description: 'Compact card of Vargov®Design: founder and founding year, catalogue size and families, configurator scope (full calculation, 1:1 drawing), the awards count and list, certification, trademarks, showroom, contacts, dealers page, site languages, links to llms.txt of the site, the knowledge base and the configurator, the open dataset on Hugging Face. Numbers are computed from the bundled data.',
+        inputSchema: { lang: z.enum(['en', 'ru']).optional().describe('en (default) or ru for the wording fields') },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    }, async ({ lang }) => textResult(brandFacts(lang ?? 'en')));
+    const d = getData();
+    server.registerResource('llms-vargov-en', 'llms://vargov', { title: 'Vargov®Design llms.txt (English)', description: 'en/llms.txt of the public knowledge base vargov3-spec/vargov-ai-kb: brand facts, catalogue, configurator, awards, contacts.', mimeType: 'text/plain' }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: 'text/plain', text: d.llmsEn }] }));
+    server.registerResource('llms-vargov-ru', 'llms://vargov/ru', { title: 'Vargov®Design llms.txt (Russian)', description: 'llms.txt of the public knowledge base, Russian.', mimeType: 'text/plain' }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: 'text/plain', text: d.llmsRu }] }));
+    if (d.llmsConfigurator) {
+        server.registerResource('llms-vargov-configurator', 'llms://vargov/configurator', { title: 'Vargov®Design configurator llms.txt', description: 'llms.txt of the 3D configurator (vargov.design): what it is, what it exports, which pages are open.', mimeType: 'text/plain' }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: 'text/plain', text: d.llmsConfigurator ?? '' }] }));
+    }
+    return server;
+}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@vargov/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "mcpName": "io.github.vargov3-spec/vargov-mcp",
+  "description": "MCP server for AI assistants: the Vargov®Design catalogue (605 made-to-order light and decorative compositions), configurator links with room dimensions, how to get IFC4 (BIM) and FBX files, brand facts. Offline: all data is bundled.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Vargov®Design (https://vargov.ru)",
+  "main": "dist/index.js",
+  "bin": {
+    "vargov-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "data",
+    "README.md",
+    "LICENSE",
+    "DATA-LICENSE.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "test": "node test/smoke.mjs",
+    "update-data": "node scripts/update-data.mjs",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "lighting-design",
+    "interior-design",
+    "bim",
+    "ifc4",
+    "vargov",
+    "lighting",
+    "architecture",
+    "3d-configurator"
+  ],
+  "homepage": "https://vargov.ru/en",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.0.0"
+  }
+}