@lightward/mechanic-mcp 0.1.1

package/README.md

@@ -0,0 +1,61 @@
+# mechanic-mcp
+
+Mechanic MCP server for the task library and docs. Built for writing and customizing Mechanic tasks (Shopify automation app: https://apps.shopify.com/mechanic). Offline by default (bundled data), serving public URLs for tasks (https://tasks.mechanic.dev) and docs (https://learn.mechanic.dev).
+
+## User guide
+- Requirements: Node.js 18+, MCP-capable client (Cursor, Claude Desktop, Codex, Gemini CLI, etc.).
+- What you can ask: find tasks; fetch task code (subscriptions + script/JS blocks); find docs; suggest similar tasks; get doc content; help writing or customizing Mechanic tasks.
+- Setup (use `npx mechanic-mcp@latest`):
+  - Cursor:
+    ```json
+    {
+      "mcpServers": {
+        "mechanic-mcp": {
+          "command": "npx",
+          "args": ["-y", "mechanic-mcp@latest"]
+        }
+      }
+    }
+    ```
+  - Claude Desktop:
+    ```json
+    {
+      "mcpServers": {
+        "mechanic-mcp": {
+          "command": "npx",
+          "args": ["-y", "mechanic-mcp@latest"]
+        }
+      }
+    }
+    ```
+  - Codex (`~/.codex/config.toml`):
+    ```toml
+    [mcp_servers.mechanic-mcp]
+    command = "npx"
+    args = ["-y", "mechanic-mcp@latest"]
+    ```
+  - Gemini CLI: same JSON as Cursor/Claude.
+- Tools:
+  - `search_tasks`: returns public URL, tags, subscriptions/subscriptions_template, options.
+  - `search_docs`: returns public URL/sourceUrl.
+  - `get_task` (tasks only): script + subscriptions + options + JS blocks; not full JSON.
+  - `get_doc` (docs only): full markdown.
+  - `similar_tasks`: related tasks by tags/subscriptions/title.
+  - `refresh_index`: rebuild (not needed for packaged data).
+- Usage notes: cite public URLs (no local paths/.md); prefer GraphQL in code; when sharing code, return subscriptions + script/JS (relevant bits), not full JSON.
+
+## For maintainers
+- Bundled data: `dist/data/index.json.gz`, `records.json.gz`, `manifest.json` (users don’t need source repos).
+- Regenerate (if needed):
+  ```bash
+  MECHANIC_DOCS_PATH=/path/to/mechanic-docs MECHANIC_TASKS_PATH=/path/to/mechanic-tasks npm run build:data
+  npm run build
+  ```
+- Tests: `npm run test:smoke`, `npm run test:smoke-doc`, `npm run test:smoke-task`.
+- Publish: bump version, `npm publish`.
+
+## Env (optional)
+- `MECHANIC_DATA_PATH` (default `dist/data`), `MECHANIC_DOCS_PATH`, `MECHANIC_TASKS_PATH`, repo URLs/branches, sync interval.
+
+## Runtime
+- Loads bundled index/records from `MECHANIC_DATA_PATH`; `refresh_index` rebuilds if you opt in. Stdio transport; TF-IDF search with fuzzy + pagination; no network calls for search/resources.

package/dist/config.js

@@ -0,0 +1,33 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const env = process.env;
+function resolvePath(value, fallback) {
+    if (value && path.isAbsolute(value)) {
+        return value;
+    }
+    if (value) {
+        return path.resolve(value);
+    }
+    return fallback;
+}
+export function loadConfig() {
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    const projectRoot = path.resolve(moduleDir, '..');
+    return {
+        docs: {
+            url: env.MECHANIC_DOCS_REPO_URL,
+            branch: env.MECHANIC_DOCS_BRANCH || 'main',
+            localPath: resolvePath(env.MECHANIC_DOCS_PATH, path.resolve(projectRoot, 'mechanic-docs')),
+        },
+        tasks: {
+            url: env.MECHANIC_TASKS_REPO_URL,
+            branch: env.MECHANIC_TASKS_BRANCH || 'main',
+            localPath: resolvePath(env.MECHANIC_TASKS_PATH, path.resolve(projectRoot, 'mechanic-tasks')),
+        },
+        syncIntervalMinutes: Number(env.MECHANIC_SYNC_MINUTES || 30),
+        index: {
+            maxDocs: Number(env.MECHANIC_INDEX_MAX_DOCS || 20000),
+        },
+        dataDir: resolvePath(env.MECHANIC_DATA_PATH, path.resolve(projectRoot, 'dist', 'data')),
+    };
+}

package/dist/core/docs.js

@@ -0,0 +1,66 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { walkFiles } from './fs.js';
+const DOC_EXTENSIONS = new Set(['.md', '.mdx']);
+function toTags(value) {
+    if (Array.isArray(value)) {
+        return value.map(String);
+    }
+    if (typeof value === 'string') {
+        return value.split(',').map((tag) => tag.trim()).filter(Boolean);
+    }
+    return [];
+}
+function firstHeading(content) {
+    const lines = content.split('\n');
+    for (const line of lines) {
+        const match = /^#{1,3}\s+(.*)$/.exec(line.trim());
+        if (match) {
+            return match[1].trim();
+        }
+    }
+    return undefined;
+}
+function extractHeadings(content) {
+    return content
+        .split('\n')
+        .map((line) => /^#{1,3}\s+(.*)$/.exec(line.trim()))
+        .filter((match) => Boolean(match))
+        .map((match) => match[1].trim());
+}
+export async function loadDocs(root) {
+    let files = [];
+    try {
+        files = await walkFiles(root, (file) => DOC_EXTENSIONS.has(path.extname(file)));
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === 'ENOENT') {
+            console.error(`Docs path not found (${root}); returning no docs.`);
+            return [];
+        }
+        throw error;
+    }
+    const records = await Promise.all(files.map(async (filePath) => {
+        const raw = await fs.readFile(filePath, 'utf8');
+        const parsed = matter(raw);
+        const relPath = path.relative(root, filePath);
+        const heading = firstHeading(parsed.content);
+        const title = parsed.data.title || heading || path.basename(filePath, path.extname(filePath));
+        const urlPath = relPath.replace(/\\/g, '/');
+        const record = {
+            id: `doc:${relPath}`,
+            kind: 'doc',
+            title,
+            path: `https://learn.mechanic.dev/${urlPath}`,
+            section: relPath.split(path.sep)[0],
+            tags: toTags(parsed.data.tags),
+            headings: extractHeadings(parsed.content),
+            content: parsed.content,
+            sourceUrl: `https://learn.mechanic.dev/${urlPath}`,
+        };
+        return record;
+    }));
+    return records;
+}

package/dist/core/engine.js

@@ -0,0 +1,60 @@
+import { loadDocs } from './docs.js';
+import { loadTasks } from './tasks.js';
+import { buildIndex, searchAdvanced } from './indexer.js';
+import { gunzipSync } from 'node:zlib';
+import fs from 'node:fs';
+import path from 'node:path';
+async function loadRecordsFromBundle(dataDir) {
+    try {
+        const recordsPath = path.join(dataDir, 'records.json.gz');
+        const raw = fs.readFileSync(recordsPath);
+        const json = gunzipSync(raw).toString('utf-8');
+        return JSON.parse(json);
+    }
+    catch (error) {
+        return null;
+    }
+}
+export async function hydrateStore(config, prebuiltIndex, bundledRecords) {
+    const records = bundledRecords ||
+        (await (async () => {
+            const [docs, tasks] = await Promise.all([loadDocs(config.docs.localPath), loadTasks(config.tasks.localPath)]);
+            return [...docs, ...tasks];
+        })());
+    const index = prebuiltIndex || buildIndex(records);
+    return {
+        records,
+        index,
+        lastIndexed: new Date(),
+    };
+}
+export function searchStore(store, query, kind, limit) {
+    return searchAdvanced(store.index, {
+        query,
+        kind,
+        limit,
+    });
+}
+export function searchStoreAdvanced(store, options) {
+    return searchAdvanced(store.index, options);
+}
+export function loadPrebuiltIndex(dataDir) {
+    try {
+        const indexPath = path.join(dataDir, 'index.json.gz');
+        const raw = fs.readFileSync(indexPath);
+        const json = gunzipSync(raw).toString('utf-8');
+        return JSON.parse(json);
+    }
+    catch (error) {
+        // eslint-disable-next-line no-console
+        console.warn(`Failed to load prebuilt index from ${dataDir}: ${error}`);
+        return null;
+    }
+}
+export async function loadBundledRecords(dataDir) {
+    const records = await loadRecordsFromBundle(dataDir);
+    if (!records) {
+        console.warn(`No bundled records found in ${dataDir}`);
+    }
+    return records;
+}

package/dist/core/fs.js

@@ -0,0 +1,18 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+export async function walkFiles(root, predicate) {
+    const entries = await fs.readdir(root, { withFileTypes: true });
+    const results = [];
+    for (const entry of entries) {
+        const fullPath = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            const nested = await walkFiles(fullPath, predicate);
+            results.push(...nested);
+            continue;
+        }
+        if (entry.isFile() && predicate(fullPath)) {
+            results.push(fullPath);
+        }
+    }
+    return results;
+}

package/dist/core/git.js

@@ -0,0 +1,36 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+async function pathExists(target) {
+    try {
+        await fs.access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function ensureRepoCloned(config) {
+    const hasGitDir = await pathExists(path.join(config.localPath, '.git'));
+    if (hasGitDir) {
+        return;
+    }
+    if (!config.url) {
+        // No git repo and no URL provided: assume caller is pointing at a static/local path and skip cloning.
+        return;
+    }
+    await fs.mkdir(config.localPath, { recursive: true });
+    await execFileAsync('git', ['clone', '--branch', config.branch, config.url, config.localPath]);
+}
+export async function syncRepo(config) {
+    if (!config.url) {
+        // No remote; assume local path is already present and skip sync.
+        return;
+    }
+    await ensureRepoCloned(config);
+    await execFileAsync('git', ['fetch', '--prune'], { cwd: config.localPath });
+    await execFileAsync('git', ['checkout', config.branch], { cwd: config.localPath });
+    await execFileAsync('git', ['reset', '--hard', `origin/${config.branch}`], { cwd: config.localPath });
+}

package/dist/core/indexer.js

@@ -0,0 +1,253 @@
+const STOP_WORDS = new Set([
+    'a',
+    'an',
+    'and',
+    'for',
+    'from',
+    'in',
+    'of',
+    'on',
+    'or',
+    'the',
+    'to',
+    'with',
+]);
+const FIELD_CONFIG = {
+    title: {
+        weight: 5,
+        extractor: (item) => item.title,
+    },
+    tags: {
+        weight: 3.5,
+        extractor: (item) => item.tags.join(' '),
+    },
+    content: {
+        weight: 1.5,
+        extractor: (item) => item.content,
+    },
+    slug: {
+        weight: 4,
+        extractor: (item) => (item.kind === 'task' ? item.slug : ''),
+    },
+    headings: {
+        weight: 3,
+        extractor: (item) => (item.kind === 'doc' ? item.headings.join(' ') : ''),
+    },
+    section: {
+        weight: 2,
+        extractor: (item) => (item.kind === 'doc' ? item.section ?? '' : ''),
+    },
+    events: {
+        weight: 2,
+        extractor: (item) => (item.kind === 'task' ? item.events.join(' ') : ''),
+    },
+    actions: {
+        weight: 2,
+        extractor: (item) => (item.kind === 'task' ? item.actions.join(' ') : ''),
+    },
+    scopes: {
+        weight: 2,
+        extractor: (item) => (item.kind === 'task' ? item.scopes.join(' ') : ''),
+    },
+};
+function normalizeText(value) {
+    if (value === null || value === undefined)
+        return '';
+    if (Array.isArray(value))
+        return value.join(' ');
+    return String(value);
+}
+function tokenize(text) {
+    return normalizeText(text)
+        .toLowerCase()
+        .replace(/[_/]+/g, ' ')
+        .split(/[^a-z0-9]+/g)
+        .filter(Boolean)
+        .filter((token) => !STOP_WORDS.has(token));
+}
+function countTokens(text) {
+    return tokenize(text).reduce((counts, token) => {
+        counts[token] = (counts[token] || 0) + 1;
+        return counts;
+    }, {});
+}
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (!a.length)
+        return b.length;
+    if (!b.length)
+        return a.length;
+    const dp = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1));
+    for (let i = 0; i <= a.length; i += 1)
+        dp[i][0] = i;
+    for (let j = 0; j <= b.length; j += 1)
+        dp[0][j] = j;
+    for (let i = 1; i <= a.length; i += 1) {
+        for (let j = 1; j <= b.length; j += 1) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
+        }
+    }
+    return dp[a.length][b.length];
+}
+function indexRecord(item) {
+    const fieldText = {};
+    const tokenFreq = {};
+    Object.entries(FIELD_CONFIG).forEach(([field, config]) => {
+        const text = normalizeText(config.extractor(item));
+        fieldText[field] = text;
+        tokenFreq[field] = countTokens(text);
+    });
+    return {
+        id: item.id,
+        kind: item.kind,
+        path: item.path,
+        tags: item.tags,
+        fieldText,
+        tokenFreq,
+        raw: item,
+    };
+}
+function buildDocFrequency(indexed) {
+    const docFreq = {};
+    indexed.forEach((doc) => {
+        const seen = new Set();
+        Object.values(doc.tokenFreq).forEach((fieldTokens) => {
+            Object.keys(fieldTokens).forEach((token) => seen.add(token));
+        });
+        seen.forEach((token) => {
+            docFreq[token] = (docFreq[token] || 0) + 1;
+        });
+    });
+    return docFreq;
+}
+export function buildIndex(records) {
+    const docs = records.map(indexRecord);
+    const docFreq = buildDocFrequency(docs);
+    return {
+        documents: docs,
+        docFreq,
+        totalDocuments: docs.length,
+    };
+}
+function fuzzyMatchToken(token, docFreq, maxEdits, limit) {
+    const vocabulary = Object.keys(docFreq);
+    const candidates = [];
+    for (const vocabToken of vocabulary) {
+        const distance = levenshtein(token, vocabToken);
+        if (distance > maxEdits)
+            continue;
+        const weight = distance === 0 ? 1 : distance === 1 ? 0.6 : 0.3;
+        candidates.push({ token: vocabToken, distance, weight });
+    }
+    if (!candidates.find((c) => c.distance === 0)) {
+        candidates.push({ token, distance: 0, weight: 1 });
+    }
+    candidates.sort((a, b) => {
+        if (a.distance !== b.distance)
+            return a.distance - b.distance;
+        return (docFreq[b.token] || 0) - (docFreq[a.token] || 0);
+    });
+    return candidates.slice(0, limit);
+}
+function buildTokenCandidates(tokens, docFreq, fuzzy, maxEdits, maxCandidates) {
+    return tokens.map((token) => ({
+        queryToken: token,
+        candidates: fuzzy
+            ? fuzzyMatchToken(token, docFreq, maxEdits, maxCandidates)
+            : [{ token, distance: 0, weight: 1 }],
+    }));
+}
+function scoreDocument(doc, tokenCandidates, built, kind) {
+    if (kind && doc.kind !== kind) {
+        return null;
+    }
+    const { docFreq, totalDocuments } = built;
+    let score = 0;
+    const matches = [];
+    tokenCandidates.forEach(({ candidates }) => {
+        candidates.forEach(({ token, weight }) => {
+            const idf = Math.log(1 + totalDocuments / (1 + (docFreq[token] || 0)));
+            Object.entries(doc.tokenFreq).forEach(([field, freqMap]) => {
+                const freq = freqMap[token] || 0;
+                if (freq === 0)
+                    return;
+                const fieldWeight = FIELD_CONFIG[field]?.weight ?? 1;
+                const fieldScore = freq * fieldWeight * idf * weight;
+                score += fieldScore;
+                matches.push({ field, token });
+            });
+        });
+    });
+    if (tokenCandidates.length > 0 && score === 0) {
+        return null;
+    }
+    return { score, matches };
+}
+function buildSnippet(text, queryTokens, length = 200) {
+    if (!text)
+        return '';
+    const lower = text.toLowerCase();
+    for (const token of queryTokens) {
+        const idx = lower.indexOf(token);
+        if (idx !== -1) {
+            const start = Math.max(0, idx - Math.floor(length / 2));
+            const end = Math.min(text.length, start + length);
+            const prefix = start > 0 ? '…' : '';
+            const suffix = end < text.length ? '…' : '';
+            return `${prefix}${text.slice(start, end).trim()}${suffix}`;
+        }
+    }
+    return text.slice(0, length).trim();
+}
+function buildDocSnippet(item, queryTokens) {
+    if (item.kind === 'doc') {
+        const heading = item.headings[0] || item.title;
+        const excerpt = buildSnippet(item.content, queryTokens);
+        return `${heading}: ${excerpt}`;
+    }
+    // For tasks, use docs content if present as intro
+    return buildSnippet(item.content, queryTokens);
+}
+function parseQuery(query) {
+    return tokenize(query);
+}
+export function searchAdvanced(built, options) {
+    const { query, kind, limit = 10, offset = 0, fuzzy = true, fuzzyMaxEdits = 1, fuzzyMaxCandidates = 3, tags, subscriptions, } = options;
+    const tokens = parseQuery(query);
+    const tokenCandidates = buildTokenCandidates(tokens, built.docFreq, fuzzy, fuzzyMaxEdits, fuzzyMaxCandidates);
+    const snippetTokens = tokenCandidates.flatMap((t) => t.candidates.map((c) => c.token));
+    const scored = [];
+    built.documents.forEach((doc) => {
+        if (tags && tags.length > 0) {
+            const docTags = (doc.raw.kind === 'task' ? doc.raw.tags : doc.tags) || [];
+            const lower = docTags.map((t) => t.toLowerCase());
+            const hasAll = tags.every((t) => lower.includes(t.toLowerCase()));
+            if (!hasAll)
+                return;
+        }
+        if (subscriptions && subscriptions.length > 0 && doc.raw.kind === 'task') {
+            const subs = (doc.raw.events || []).map((s) => s.toLowerCase()).join(' ');
+            const templates = (doc.raw.subscriptions_template || '').toLowerCase();
+            const combined = `${subs} ${templates}`;
+            const hasAllSubs = subscriptions.every((s) => combined.includes(s.toLowerCase()));
+            if (!hasAllSubs)
+                return;
+        }
+        const scoredDoc = scoreDocument(doc, tokenCandidates, built, kind);
+        if (!scoredDoc)
+            return;
+        scored.push({ doc, score: scoredDoc.score, matches: scoredDoc.matches });
+    });
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(offset, offset + limit).map(({ doc, score }) => ({
+        id: doc.id,
+        kind: doc.kind,
+        title: doc.raw.title,
+        path: doc.path,
+        snippet: buildDocSnippet(doc.raw, snippetTokens),
+        tags: doc.tags,
+        score,
+    }));
+}

package/dist/core/tasks.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+const TASKS_SUBDIR = 'tasks';
+async function readTasks(root) {
+    const taskDir = path.join(root, TASKS_SUBDIR);
+    let entries;
+    try {
+        entries = await fs.readdir(taskDir, { withFileTypes: true });
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === 'ENOENT') {
+            console.error(`Tasks path not found (${taskDir}); returning no tasks.`);
+            return [];
+        }
+        throw error;
+    }
+    const tasks = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.json')) {
+            continue;
+        }
+        if (entry.name.startsWith('.')) {
+            continue;
+        }
+        const filePath = path.join(taskDir, entry.name);
+        const raw = await fs.readFile(filePath, 'utf8');
+        const json = JSON.parse(raw);
+        const handle = entry.name.replace(/\.json$/, '');
+        const tags = Array.isArray(json.tags) ? json.tags.map(String) : [];
+        const subscriptions = Array.isArray(json.subscriptions) ? json.subscriptions.map(String) : [];
+        const options = json.options;
+        const script = json.script;
+        const onlineJs = json.online_store_javascript;
+        const orderJs = json.order_status_javascript;
+        const subsTemplate = json.subscriptions_template;
+        const pathPublic = `https://tasks.mechanic.dev/${handle}`;
+        const record = {
+            id: `task:${handle}`,
+            kind: 'task',
+            slug: handle,
+            title: json.name || handle,
+            path: pathPublic,
+            summary: json.docs || '',
+            tags,
+            events: subscriptions,
+            actions: [],
+            scopes: [],
+            risk: 'unknown',
+            options,
+            script,
+            online_store_javascript: onlineJs ?? null,
+            order_status_javascript: orderJs ?? null,
+            subscriptions_template: subsTemplate,
+            content: [
+                json.docs || '',
+                json.subscriptions_template || '',
+                json.script || '',
+                json.online_store_javascript || '',
+                json.order_status_javascript || '',
+            ]
+                .filter(Boolean)
+                .join('\n\n'),
+        };
+        tasks.push(record);
+    }
+    return tasks;
+}
+export async function loadTasks(root) {
+    return readTasks(root);
+}

package/dist/data/manifest.json

@@ -0,0 +1,12 @@
+{
+  "builtAt": "2025-12-02T04:31:30.664Z",
+  "counts": {
+    "docs": 312,
+    "tasks": 357,
+    "total": 669
+  },
+  "sources": {
+    "docsPath": "/Users/msodomsky/dev/mechanic-docs",
+    "tasksPath": "/Users/msodomsky/dev/mechanic-tasks"
+  }
+}

package/dist/index.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import fs from 'node:fs';
+import { loadConfig } from './config.js';
+import { hydrateStore, loadPrebuiltIndex, loadBundledRecords } from './core/engine.js';
+import { syncRepo } from './core/git.js';
+import { startMcpServer } from './mcp/server.js';
+async function bootstrap() {
+    if (process.argv.includes('--help') || process.argv.includes('-h')) {
+        console.log('Usage: mechanic-mcp (runs MCP server on stdio)');
+        console.log('Environment: MECHANIC_DATA_PATH (defaults to dist/data with bundled index/records).');
+        console.log('Tools: search_tasks, search_docs, get_task, get_doc, similar_tasks, refresh_index.');
+        process.exit(0);
+    }
+    const config = loadConfig();
+    // Keep a mutable reference so refresh can swap it.
+    const prebuiltIndex = loadPrebuiltIndex(config.dataDir);
+    const bundledRecords = await loadBundledRecords(config.dataDir);
+    let store = await hydrateStore(config, prebuiltIndex, bundledRecords);
+    const refresh = async () => {
+        // If we have bundled records, skip repo sync; otherwise sync and rebuild.
+        if (!bundledRecords) {
+            await Promise.all([syncRepo(config.docs), syncRepo(config.tasks)]);
+            store = await hydrateStore(config, prebuiltIndex, bundledRecords);
+        }
+    };
+    // Initial sync happens before serving.
+    await refresh();
+    // Background sync.
+    const intervalMs = config.syncIntervalMinutes * 60 * 1000;
+    const timer = setInterval(() => {
+        refresh().catch((error) => {
+            console.error('Periodic refresh failed', error);
+        });
+    }, intervalMs);
+    const stop = await startMcpServer({
+        getStore: () => store,
+        refresh,
+    });
+    // Log manifest info if present
+    const manifestPath = path.join(config.dataDir, 'manifest.json');
+    if (fs.existsSync(manifestPath)) {
+        try {
+            const manifestRaw = fs.readFileSync(manifestPath, 'utf-8');
+            const manifest = JSON.parse(manifestRaw);
+            console.error('Data manifest', manifest);
+        }
+        catch (error) {
+            console.error(`Unable to read manifest at ${manifestPath}: ${error}`);
+        }
+    }
+    const shutdown = async () => {
+        clearInterval(timer);
+        await stop();
+    };
+    const handleSignal = async (signal) => {
+        console.error(`Received ${signal}, shutting down...`);
+        await shutdown();
+        process.exit(0);
+    };
+    process.on('SIGINT', handleSignal);
+    process.on('SIGTERM', handleSignal);
+    return { shutdown };
+}
+bootstrap().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+});

package/dist/mcp/server.js

@@ -0,0 +1,291 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { searchStoreAdvanced } from '../core/engine.js';
+import { searchInputSchema, searchResponseSchema, taskIdSchema, taskDetailSchema, docIdSchema, docDetailSchema, similarTasksInputSchema, similarTasksResponseSchema, } from '../schemas.js';
+import { encodeUri, decodeUri } from '../util/uri.js';
+export async function startMcpServer(options) {
+    const { getStore, refresh } = options;
+    const store = getStore();
+    const mcp = new McpServer({
+        name: 'mechanic-mcp',
+        version: '0.1.0',
+    }, {
+        capabilities: {
+            resources: {},
+            tools: {},
+        },
+        instructions: [
+            'You are an assistant helping developers write and customize Mechanic tasks in Liquid.',
+            'Use search_tasks for task library queries; use search_docs for Mechanic docs. Use get_task for tasks only, get_doc or resources/read for docs.',
+            'Inputs: query (required); limit<=50; offset>=0; fuzzyMaxEdits<=2; fuzzyMaxCandidates<=5.',
+            'Docs are resources; tasks are tools. Resource URIs are percent-encoded from list_resources.',
+            'Always use public URLs: tasks.mechanic.dev/{handle} for tasks, learn.mechanic.dev/{path} for docs. Never cite local repo paths or .md filenames.',
+            'Prefer Shopify GraphQL in code examples; REST is deprecated in Mechanic tasks.',
+            'Recommend existing library tasks first; build new only if no close match.',
+            'For task code, return subscriptions + script/JS (relevant bits), not full JSON; include the public task URL.',
+        ].join('\n'),
+    });
+    // Tool: search_tasks (tasks only)
+    mcp.registerTool('search_tasks', {
+        description: 'Search Mechanic tasks',
+        inputSchema: searchInputSchema.omit({ scope: true }),
+        outputSchema: searchResponseSchema,
+    }, async (input) => {
+        const hits = searchStoreAdvanced(getStore(), {
+            query: input.query,
+            kind: 'task',
+            limit: input.limit,
+            offset: input.offset,
+            fuzzy: input.fuzzy,
+            fuzzyMaxEdits: input.fuzzyMaxEdits,
+            fuzzyMaxCandidates: input.fuzzyMaxCandidates,
+            tags: input.tags,
+            subscriptions: input.subscriptions,
+        });
+        const hitsWithUrl = hits.map((hit) => ({
+            ...hit,
+            url: `https://tasks.mechanic.dev/${hit.id.replace(/^task:/, '')}`,
+            subscriptions: getStore()
+                .records.filter((r) => r.id === hit.id && r.kind === 'task')
+                .flatMap((r) => ('events' in r ? r.events : [])),
+            subscriptions_template: getStore()
+                .records.filter((r) => r.id === hit.id && r.kind === 'task')
+                .map((r) => ('subscriptions_template' in r ? r.subscriptions_template : undefined))
+                .find(Boolean),
+            options: getStore()
+                .records.filter((r) => r.id === hit.id && r.kind === 'task')
+                .map((r) => ('options' in r ? r.options : undefined))
+                .find(Boolean),
+        }));
+        const nextOffset = hits.length === input.limit ? input.offset + input.limit : undefined;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        items: hitsWithUrl,
+                        nextOffset,
+                    }, null, 2),
+                },
+            ],
+            structuredContent: {
+                items: hitsWithUrl,
+                nextOffset,
+            },
+        };
+    });
+    // Tool: search_docs (docs only)
+    mcp.registerTool('search_docs', {
+        description: 'Search Mechanic docs (generated task documentation)',
+        inputSchema: searchInputSchema.omit({ scope: true }),
+        outputSchema: searchResponseSchema,
+    }, async (input) => {
+        const hits = searchStoreAdvanced(getStore(), {
+            query: input.query,
+            kind: 'doc',
+            limit: input.limit,
+            offset: input.offset,
+            fuzzy: input.fuzzy,
+            fuzzyMaxEdits: input.fuzzyMaxEdits,
+            fuzzyMaxCandidates: input.fuzzyMaxCandidates,
+            tags: input.tags,
+            subscriptions: input.subscriptions,
+        });
+        const hitsWithUrl = hits.map((hit) => ({
+            ...hit,
+            url: `https://learn.mechanic.dev/${hit.path}`,
+            sourceUrl: `https://learn.mechanic.dev/${hit.path}`,
+        }));
+        const nextOffset = hits.length === input.limit ? input.offset + input.limit : undefined;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        items: hitsWithUrl,
+                        nextOffset,
+                    }, null, 2),
+                },
+            ],
+            structuredContent: {
+                items: hitsWithUrl,
+                nextOffset,
+            },
+        };
+    });
+    // Tool: get_task (full payload)
+    mcp.registerTool('get_task', {
+        description: 'Tasks only: fetch by handle/id with full payload (script, options, subscriptions).',
+        inputSchema: z.object({ id: taskIdSchema }),
+        outputSchema: taskDetailSchema,
+    }, async (input) => {
+        const normalizedId = input.id.startsWith('task:') ? input.id : `task:${input.id}`;
+        const record = getStore().records.find((r) => r.id === normalizedId);
+        if (!record || record.kind !== 'task') {
+            return {
+                content: [{ type: 'text', text: `Task not found or not a task: ${input.id}` }],
+                isError: true,
+                structuredContent: undefined,
+            };
+        }
+        const handle = record.slug || record.id.replace(/^task:/, '');
+        const url = `https://tasks.mechanic.dev/${handle}`;
+        const subscriptions = record.events || [];
+        // The task JSON isn't stored wholesale; we surface what we have
+        const detail = {
+            id: record.id,
+            handle,
+            name: record.title,
+            tags: record.tags,
+            url,
+            subscriptions,
+            subscriptions_template: record.subscriptions_template,
+            options: record.options,
+            script: record.script,
+            online_store_javascript: record.online_store_javascript || undefined,
+            order_status_javascript: record.order_status_javascript || undefined,
+        };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(detail, null, 2) }],
+            structuredContent: taskDetailSchema.parse(detail),
+        };
+    });
+    // Tool: similar_tasks
+    mcp.registerTool('similar_tasks', {
+        description: 'Find similar tasks by tags/subscriptions/title content.',
+        inputSchema: similarTasksInputSchema,
+        outputSchema: similarTasksResponseSchema,
+    }, async (input) => {
+        const allTasks = getStore().records.filter((r) => r.kind === 'task');
+        const target = allTasks.find((r) => r.id === input.handle || r.id === `task:${input.handle}` || r.slug === input.handle);
+        if (!target) {
+            return {
+                content: [{ type: 'text', text: `Task not found: ${input.handle}` }],
+                structuredContent: undefined,
+            };
+        }
+        const targetTags = new Set((target.tags || []).map((t) => t.toLowerCase()));
+        const targetSubs = new Set((target.events || []).map((s) => s.toLowerCase()));
+        const targetTitle = target.title.toLowerCase();
+        const scored = [];
+        allTasks.forEach((r) => {
+            if (r.id === target.id)
+                return;
+            let score = 0;
+            const tagsLower = (r.tags || []).map((t) => t.toLowerCase());
+            tagsLower.forEach((t) => {
+                if (targetTags.has(t))
+                    score += 2;
+            });
+            const subsLower = (r.events || []).map((s) => s.toLowerCase());
+            subsLower.forEach((s) => {
+                if (targetSubs.has(s))
+                    score += 1;
+            });
+            if (targetTitle && r.title.toLowerCase().includes(targetTitle.split(' ')[0] || '')) {
+                score += 0.5;
+            }
+            if (score > 0) {
+                scored.push({ r, score });
+            }
+        });
+        scored.sort((a, b) => b.score - a.score);
+        const top = scored.slice(0, input.limit).map(({ r }) => {
+            const handle = r.slug || r.id.replace(/^task:/, '');
+            return {
+                id: r.id,
+                kind: r.kind,
+                title: r.title,
+                path: r.path,
+                url: `https://tasks.mechanic.dev/${handle}`,
+                snippet: r.kind === 'task' ? r.summary || '' : '',
+                tags: r.tags,
+                score: 0,
+            };
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ items: top }, null, 2) }],
+            structuredContent: { items: top },
+        };
+    });
+    // Tool: get_doc (docs only)
+    mcp.registerTool('get_doc', {
+        description: 'Docs only: fetch by id/path (use search_docs to find ids).',
+        inputSchema: z.object({ id: docIdSchema }),
+        outputSchema: docDetailSchema,
+    }, async (input) => {
+        const normalizedId = input.id.startsWith('doc:') ? input.id : `doc:${input.id}`;
+        const record = getStore().records.find((r) => r.id === normalizedId);
+        if (!record || record.kind !== 'doc') {
+            return {
+                content: [{ type: 'text', text: `Doc not found or not a doc: ${input.id}` }],
+                isError: true,
+                structuredContent: undefined,
+            };
+        }
+        const detail = {
+            id: record.id,
+            title: record.title,
+            path: record.path,
+            url: record.sourceUrl,
+            content: record.content,
+        };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(detail, null, 2) }],
+            structuredContent: docDetailSchema.parse(detail),
+        };
+    });
+    // Doc resources only
+    const docResources = getStore()
+        .records.filter((r) => r.kind === 'doc')
+        .map((doc) => {
+        const uri = `mechanic-docs://${encodeUri(doc.id)}`;
+        return {
+            uri,
+            name: doc.title,
+            description: doc.sourceUrl || doc.path,
+            mimeType: 'text/markdown',
+        };
+    });
+    docResources.forEach((res) => {
+        mcp.registerResource(res.name, res.uri, {
+            description: res.description,
+            mimeType: res.mimeType,
+        }, async () => {
+            const decodedId = decodeUri(res.uri.replace(/^mechanic-docs:\/\//, ''));
+            const record = getStore().records.find((r) => r.id === decodedId);
+            if (!record || record.kind !== 'doc') {
+                return { contents: [] };
+            }
+            return {
+                contents: [
+                    {
+                        uri: res.uri,
+                        mimeType: 'text/markdown',
+                        text: record.content,
+                    },
+                ],
+            };
+        });
+    });
+    // Tool: refresh_index
+    mcp.registerTool('refresh_index', {
+        description: 'Refresh and rebuild the index from source data',
+        inputSchema: z.object({}),
+    }, async () => {
+        await refresh();
+        return { content: [{ type: 'text', text: 'Refreshed index' }] };
+    });
+    const transport = new StdioServerTransport();
+    await mcp.connect(transport);
+    const currentStore = getStore();
+    const docCount = currentStore.records.filter((item) => item.kind === 'doc').length;
+    const taskCount = currentStore.records.filter((item) => item.kind === 'task').length;
+    console.error(`MCP server ready (docs=${docCount}, tasks=${taskCount}) on stdio`);
+    return async () => {
+        await mcp.close();
+        transport.close();
+        console.error('MCP server stopped.');
+    };
+}

package/dist/schemas.js

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+const scopeEnum = z
+    .enum(['all', 'task', 'doc', 'docs'])
+    .optional()
+    .transform((value) => {
+    if (value === 'docs')
+        return 'doc';
+    return value;
+});
+export const searchInputSchema = z.object({
+    query: z.string().min(1),
+    limit: z.number().int().min(1).max(50).default(10),
+    offset: z.number().int().min(0).default(0),
+    scope: scopeEnum,
+    sort: z.enum(['relevance']).optional().default('relevance'),
+    tags: z.array(z.string()).optional(),
+    subscriptions: z.array(z.string()).optional(),
+    fuzzy: z.boolean().optional().default(true),
+    fuzzyMaxEdits: z.number().int().min(0).max(2).optional().default(1),
+    fuzzyMaxCandidates: z.number().int().min(1).max(5).optional().default(3),
+});
+export const searchHitSchema = z.object({
+    id: z.string(),
+    kind: z.enum(['doc', 'task']),
+    title: z.string(),
+    path: z.string(),
+    url: z.string().optional(),
+    subscriptions: z.array(z.string()).optional(),
+    subscriptions_template: z.string().optional(),
+    options: z.record(z.any()).optional(),
+    sourceUrl: z.string().optional(),
+    snippet: z.string(),
+    tags: z.array(z.string()),
+    score: z.number(),
+});
+export const searchResponseSchema = z.object({
+    items: z.array(searchHitSchema),
+    nextOffset: z.number().int().min(0).optional(),
+});
+export const taskIdSchema = z.string().min(1);
+export const taskDetailSchema = z.object({
+    id: z.string(),
+    handle: z.string(),
+    name: z.string(),
+    tags: z.array(z.string()),
+    url: z.string(),
+    subscriptions: z.array(z.string()),
+    subscriptions_template: z.string().optional(),
+    options: z.record(z.any()).optional(),
+    script: z.string().optional(),
+    online_store_javascript: z.string().optional(),
+    order_status_javascript: z.string().optional(),
+});
+export const docIdSchema = z.string().min(1);
+export const docDetailSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    path: z.string(),
+    url: z.string().optional(),
+    content: z.string(),
+});
+export const similarTasksInputSchema = z.object({
+    handle: z.string().min(1),
+    limit: z.number().int().min(1).max(20).default(5),
+});
+export const similarTasksResponseSchema = z.object({
+    items: z.array(searchHitSchema.extend({
+        url: z.string(),
+    })),
+});
+export const resourceRequestSchema = z.object({
+    uri: z.string().min(1),
+});
+export const taskResourceSchema = z.object({
+    id: z.string(),
+    kind: z.literal('task'),
+    slug: z.string(),
+    title: z.string(),
+    path: z.string(),
+    summary: z.string().optional(),
+    tags: z.array(z.string()),
+    events: z.array(z.string()),
+    actions: z.array(z.string()),
+    scopes: z.array(z.string()),
+    risk: z.enum(['read', 'write', 'mixed', 'unknown']),
+    content: z.string(),
+});
+export const docResourceSchema = z.object({
+    id: z.string(),
+    kind: z.literal('doc'),
+    title: z.string(),
+    path: z.string(),
+    section: z.string().optional(),
+    tags: z.array(z.string()),
+    headings: z.array(z.string()),
+    content: z.string(),
+});

package/dist/tests/doc-resource.smoke.js

@@ -0,0 +1,17 @@
+import { strict as assert } from 'node:assert';
+import { loadConfig } from '../config.js';
+import { hydrateStore, loadPrebuiltIndex, loadBundledRecords } from '../core/engine.js';
+async function main() {
+    const config = loadConfig();
+    const prebuilt = loadPrebuiltIndex(config.dataDir);
+    const records = await loadBundledRecords(config.dataDir);
+    const store = await hydrateStore(config, prebuilt, records);
+    assert(store.records.some((r) => r.kind === 'doc'), 'Expected docs in bundled records');
+    // eslint-disable-next-line no-console
+    console.log('Doc resource smoke passed.');
+}
+main().catch((error) => {
+    // eslint-disable-next-line no-console
+    console.error(error);
+    process.exitCode = 1;
+});

package/dist/tests/get-task.smoke.js

@@ -0,0 +1,19 @@
+import { strict as assert } from 'node:assert';
+import { loadConfig } from '../config.js';
+import { hydrateStore, loadPrebuiltIndex, loadBundledRecords } from '../core/engine.js';
+async function main() {
+    const config = loadConfig();
+    const prebuilt = loadPrebuiltIndex(config.dataDir);
+    const bundled = await loadBundledRecords(config.dataDir);
+    const store = await hydrateStore(config, prebuilt, bundled);
+    const taskId = 'task:abandoned-checkout-emails';
+    const task = store.records.find((r) => r.id === taskId);
+    assert(task && task.kind === 'task', 'Expected abandoned-checkout-emails task');
+    assert(task.subscriptions_template, 'Expected subscriptions_template');
+    assert(task.script || task.content, 'Expected script/content');
+    console.log('get_task smoke passed.');
+}
+main().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+});

package/dist/tests/smoke.js

@@ -0,0 +1,46 @@
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadConfig } from '../config.js';
+import { hydrateStore, loadPrebuiltIndex, loadBundledRecords, searchStoreAdvanced } from '../core/engine.js';
+async function run() {
+    const config = loadConfig();
+    const prebuilt = loadPrebuiltIndex(config.dataDir);
+    const bundled = await loadBundledRecords(config.dataDir);
+    const store = await hydrateStore(config, prebuilt, bundled);
+    const searchAndAssert = (query, kind) => {
+        const hits = searchStoreAdvanced(store, {
+            query,
+            kind,
+            limit: 3,
+            fuzzy: true,
+        });
+        assert(hits.length > 0, `Expected hits for query "${query}"`);
+        return hits;
+    };
+    // Task search
+    const taskHits = searchAndAssert('abandoned checkout', 'task');
+    const taskIds = taskHits.map((h) => h.id);
+    assert(taskIds.some((id) => id.includes('abandoned')), 'Expected an abandoned checkout task');
+    // Doc search
+    const docHits = searchAndAssert('subscription', 'doc');
+    assert(docHits.some((h) => h.id.startsWith('doc:')), 'Expected doc hits');
+    // Filter-only via kind and pagination
+    const paged = searchStoreAdvanced(store, {
+        query: 'checkout',
+        kind: 'task',
+        limit: 1,
+        offset: 1,
+    });
+    assert(paged.length === 1, 'Expected one result on paged query');
+    // Manifest existence
+    const manifestPath = path.join(config.dataDir, 'manifest.json');
+    assert(fs.existsSync(manifestPath), 'Manifest should exist');
+    // eslint-disable-next-line no-console
+    console.log('Smoke tests passed.');
+}
+run().catch((error) => {
+    // eslint-disable-next-line no-console
+    console.error(error);
+    process.exitCode = 1;
+});

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/util/uri.js

@@ -0,0 +1,11 @@
+export function encodeUri(id) {
+    return encodeURIComponent(id);
+}
+export function decodeUri(uri) {
+    try {
+        return decodeURIComponent(uri);
+    }
+    catch (error) {
+        return uri;
+    }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@lightward/mechanic-mcp",
+  "version": "0.1.1",
+  "description": "Mechanic MCP server for docs and task library search",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mechanic-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/data/index.json.gz",
+    "dist/data/records.json.gz",
+    "dist/data/manifest.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "build:data": "tsx scripts/build-data.ts",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "lint": "eslint . --ext .ts",
+    "test:smoke": "node dist/tests/smoke.js",
+    "test:smoke-doc": "node dist/tests/doc-resource.smoke.js",
+    "test:smoke-task": "node dist/tests/get-task.smoke.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.24.0",
+    "gray-matter": "^4.0.3",
+    "yaml": "^2.4.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "eslint": "^8.57.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.4.0"
+  }
+}