@ingenx-io/valets-schema-mcp-server 0.1.0

package/index.js

@@ -0,0 +1,367 @@
+#!/usr/bin/env node
+/**
+ * @valets/schema MCP Server
+ *
+ * Exposes the Valets data model documentation to AI agents via the
+ * Model Context Protocol.
+ *
+ * Data strategy: fetch-first with bundled fallback.
+ *   - If VALETS_SCHEMA_URL is set, fetches live data from the deployed
+ *     Docusaurus site (static assets: /schemas.json, /llms.txt, etc.)
+ *   - Falls back to bundled data/ directory when offline or URL not set
+ *   - Fetched data is cached in memory with a configurable TTL (default 5 min)
+ *
+ * Tools:
+ *   - schema_overview    → llms.txt summary (start here)
+ *   - get_schema         → JSON Schema for a specific model or enum
+ *   - get_doc            → raw Markdown documentation for a model/enum/decision page
+ *   - search_docs        → keyword search across all doc pages
+ *   - list_decisions     → all data model decisions with status
+ *   - get_decision       → single decision detail
+ *   - get_openapi        → OpenAPI 3.1 spec (full or single component)
+ *
+ * Resources:
+ *   - valets://schemas.json    → full schema bundle
+ *   - valets://llms.txt        → LLM-optimized summary
+ *   - valets://openapi.yaml    → OpenAPI spec
+ *   - valets://decisions.json  → decision metadata
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const DATA_DIR = join(__dirname, "data");
+const BUNDLED_STATIC = join(DATA_DIR, "static");
+const BUNDLED_DOCS = join(DATA_DIR, "docs");
+
+const BASE_URL = process.env.VALETS_SCHEMA_URL?.replace(/\/+$/, "") || "";
+const CACHE_TTL_MS = parseInt(process.env.VALETS_CACHE_TTL || "300000", 10); // 5 min
+
+// ---------------------------------------------------------------------------
+// Fetch-first with bundled fallback
+// ---------------------------------------------------------------------------
+
+const _cache = new Map(); // key → { data, ts }
+
+/**
+ * Fetch a static asset from the deployed site, falling back to the
+ * bundled file. Results are cached in memory for CACHE_TTL_MS.
+ */
+async function fetchOrRead(remotePath, localPath) {
+  const cacheKey = remotePath;
+  const cached = _cache.get(cacheKey);
+  if (cached && Date.now() - cached.ts < CACHE_TTL_MS) {
+    return cached.data;
+  }
+
+  // Try remote fetch
+  if (BASE_URL) {
+    try {
+      const url = `${BASE_URL}${remotePath}`;
+      const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
+      if (res.ok) {
+        const data = await res.text();
+        _cache.set(cacheKey, { data, ts: Date.now() });
+        return data;
+      }
+    } catch {
+      // Network error — fall through to bundled
+    }
+  }
+
+  // Bundled fallback
+  if (existsSync(localPath)) {
+    const data = readFileSync(localPath, "utf8");
+    _cache.set(cacheKey, { data, ts: Date.now() });
+    return data;
+  }
+
+  throw new Error(`Cannot load ${remotePath}: no remote URL configured and bundled file not found at ${localPath}`);
+}
+
+// Convenience loaders for the four static assets
+async function loadSchemas() {
+  const raw = await fetchOrRead("/schemas.json", join(BUNDLED_STATIC, "schemas.json"));
+  return JSON.parse(raw);
+}
+
+async function loadDecisions() {
+  const raw = await fetchOrRead("/decisions.json", join(BUNDLED_STATIC, "decisions.json"));
+  return JSON.parse(raw);
+}
+
+async function loadLlmsTxt() {
+  return fetchOrRead("/llms.txt", join(BUNDLED_STATIC, "llms.txt"));
+}
+
+async function loadOpenapi() {
+  return fetchOrRead("/openapi.yaml", join(BUNDLED_STATIC, "openapi.yaml"));
+}
+
+// ---------------------------------------------------------------------------
+// Doc page loading (Markdown)
+// ---------------------------------------------------------------------------
+
+/** Known doc directories served by Docusaurus as raw Markdown. */
+const DOC_DIRS = ["models", "enums", "decisions", "collections", "triggers"];
+
+/**
+ * Load a doc page by slug. Tries fetching the raw .md from the site's
+ * source path, falls back to bundled docs/.
+ */
+async function loadDoc(slug) {
+  const localPath = join(BUNDLED_DOCS, `${slug}.md`);
+  // Docusaurus serves source Markdown at /docs/{slug} as HTML, not raw .md.
+  // So for docs we only use the bundled fallback (or a future raw endpoint).
+  if (existsSync(localPath)) {
+    return readFileSync(localPath, "utf8");
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Recursively list all .md files under a directory. */
+function listMarkdownFiles(dir) {
+  const results = [];
+  if (!existsSync(dir)) return results;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...listMarkdownFiles(full));
+    } else if (entry.name.endsWith(".md")) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+/** Get a short slug from a markdown file path. */
+function docSlug(filepath) {
+  return relative(BUNDLED_DOCS, filepath).replace(/\.md$/, "");
+}
+
+/** List all available doc slugs. */
+function allDocSlugs() {
+  return listMarkdownFiles(BUNDLED_DOCS).map(docSlug);
+}
+
+/** Fuzzy match: check if all query words appear in the text. */
+function fuzzyMatch(text, query) {
+  const words = query.toLowerCase().split(/\s+/);
+  const lower = text.toLowerCase();
+  return words.every((w) => lower.includes(w));
+}
+
+// ---------------------------------------------------------------------------
+// Server setup
+// ---------------------------------------------------------------------------
+
+const server = new McpServer({
+  name: "@valets/schema",
+  version: "0.2.0",
+});
+
+// ---------------------------------------------------------------------------
+// Tools
+// ---------------------------------------------------------------------------
+
+server.tool(
+  "schema_overview",
+  "Get a high-level overview of the entire Valets data model. Start here to understand what models and enums exist before drilling into specifics.",
+  {},
+  async () => ({
+    content: [{ type: "text", text: await loadLlmsTxt() }],
+  })
+);
+
+server.tool(
+  "get_schema",
+  "Get the JSON Schema definition for a specific model or enum. Use kebab-case names (e.g. 'order', 'payment-status', 'customer-payment').",
+  { name: z.string().describe("Schema name in kebab-case (e.g. 'order', 'payment-method', 'customer-payment-allocation')") },
+  async ({ name }) => {
+    const bundle = await loadSchemas();
+    const schema = bundle.schemas?.[name] || bundle.definitions?.[name];
+    if (!schema) {
+      const available = [
+        ...Object.keys(bundle.schemas || {}),
+        ...Object.keys(bundle.definitions || {}),
+      ];
+      return {
+        content: [{ type: "text", text: `Schema "${name}" not found.\n\nAvailable:\n${available.sort().map((n) => `  - ${n}`).join("\n")}` }],
+        isError: true,
+      };
+    }
+    return {
+      content: [{ type: "text", text: JSON.stringify(schema, null, 2) }],
+    };
+  }
+);
+
+server.tool(
+  "get_doc",
+  "Get the raw Markdown documentation for a schema page. Use slugs like 'models/order', 'enums/payment-status', 'decisions/summary'.",
+  { slug: z.string().describe("Document slug (e.g. 'models/order', 'enums/payment-method', 'decisions/summary')") },
+  async ({ slug }) => {
+    const content = await loadDoc(slug);
+    if (!content) {
+      const available = allDocSlugs();
+      return {
+        content: [{ type: "text", text: `Document "${slug}" not found.\n\nAvailable:\n${available.sort().map((s) => `  - ${s}`).join("\n")}` }],
+        isError: true,
+      };
+    }
+    return {
+      content: [{ type: "text", text: content }],
+    };
+  }
+);
+
+server.tool(
+  "search_docs",
+  "Search across all documentation pages for a keyword or phrase. Returns matching doc slugs with the first matching line for context.",
+  { query: z.string().describe("Search keyword or phrase (e.g. 'paymentMethod', 'loyalty', 'immutable')") },
+  async ({ query }) => {
+    const files = listMarkdownFiles(BUNDLED_DOCS);
+    const results = [];
+    for (const filepath of files) {
+      const content = readFileSync(filepath, "utf8");
+      if (fuzzyMatch(content, query)) {
+        const slug = docSlug(filepath);
+        const lines = content.split("\n");
+        const matchLine = lines.find((l) => fuzzyMatch(l, query)) || lines[0];
+        results.push({ slug, match: matchLine.trim().slice(0, 120) });
+      }
+    }
+    if (results.length === 0) {
+      return {
+        content: [{ type: "text", text: `No documents match "${query}".` }],
+      };
+    }
+    const text = results
+      .map((r) => `- **${r.slug}**: ${r.match}`)
+      .join("\n");
+    return {
+      content: [{ type: "text", text: `Found ${results.length} matching document(s):\n\n${text}` }],
+    };
+  }
+);
+
+server.tool(
+  "list_decisions",
+  "List all data model decisions (D00-D37+) with their status and summary.",
+  {},
+  async () => {
+    const data = await loadDecisions();
+    const lines = data.decisions.map((d) => {
+      return `- **${d.id}** [${d.status}] ${d.title}: ${d.decision}`;
+    });
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+    };
+  }
+);
+
+server.tool(
+  "get_decision",
+  "Get full details for a specific data model decision by ID (e.g. 'D12', 'D22').",
+  { id: z.string().describe("Decision ID (e.g. 'D01', 'D12', 'D22')") },
+  async ({ id }) => {
+    const data = await loadDecisions();
+    const decision = data.decisions.find(
+      (d) => d.id.toUpperCase() === id.toUpperCase()
+    );
+    if (!decision) {
+      return {
+        content: [{ type: "text", text: `Decision "${id}" not found. Use list_decisions to see all available.` }],
+        isError: true,
+      };
+    }
+    return {
+      content: [{ type: "text", text: JSON.stringify(decision, null, 2) }],
+    };
+  }
+);
+
+server.tool(
+  "get_openapi",
+  "Get the OpenAPI 3.1 specification. Optionally filter to a single component schema by name (PascalCase, e.g. 'Order', 'CustomerPayment').",
+  { component: z.string().optional().describe("Optional PascalCase component name to extract (e.g. 'Order', 'OrderCreate', 'PaymentMethod')") },
+  async ({ component }) => {
+    const yaml = await loadOpenapi();
+    if (!component) {
+      return { content: [{ type: "text", text: yaml }] };
+    }
+    const marker = `    ${component}:`;
+    const lines = yaml.split("\n");
+    const startIdx = lines.findIndex((l) => l === marker);
+    if (startIdx === -1) {
+      return {
+        content: [{ type: "text", text: `Component "${component}" not found in OpenAPI spec.` }],
+        isError: true,
+      };
+    }
+    const block = [lines[startIdx]];
+    for (let i = startIdx + 1; i < lines.length; i++) {
+      if (lines[i].match(/^    [A-Z]/) && !lines[i].startsWith("     ")) break;
+      block.push(lines[i]);
+    }
+    return {
+      content: [{ type: "text", text: block.join("\n") }],
+    };
+  }
+);
+
+// ---------------------------------------------------------------------------
+// Resources
+// ---------------------------------------------------------------------------
+
+server.resource(
+  "schemas-bundle",
+  "valets://schemas.json",
+  { description: "Consolidated JSON Schema bundle for all Valets models and enums", mimeType: "application/json" },
+  async () => ({
+    contents: [{ uri: "valets://schemas.json", text: await fetchOrRead("/schemas.json", join(BUNDLED_STATIC, "schemas.json")), mimeType: "application/json" }],
+  })
+);
+
+server.resource(
+  "llms-txt",
+  "valets://llms.txt",
+  { description: "LLM-optimized summary of the Valets data model", mimeType: "text/plain" },
+  async () => ({
+    contents: [{ uri: "valets://llms.txt", text: await loadLlmsTxt(), mimeType: "text/plain" }],
+  })
+);
+
+server.resource(
+  "openapi-spec",
+  "valets://openapi.yaml",
+  { description: "OpenAPI 3.1 specification for all Valets schemas", mimeType: "application/yaml" },
+  async () => ({
+    contents: [{ uri: "valets://openapi.yaml", text: await loadOpenapi(), mimeType: "application/yaml" }],
+  })
+);
+
+server.resource(
+  "decisions",
+  "valets://decisions.json",
+  { description: "Data model decisions metadata (D00-D37+)", mimeType: "application/json" },
+  async () => ({
+    contents: [{ uri: "valets://decisions.json", text: await fetchOrRead("/decisions.json", join(BUNDLED_STATIC, "decisions.json")), mimeType: "application/json" }],
+  })
+);
+
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@ingenx-io/valets-schema-mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server exposing @valets/schema documentation to AI agents",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "valets-schema-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "data/"
+  ],
+  "scripts": {
+    "bundle": "node bundle.js",
+    "prebuild": "node bundle.js",
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^4.3.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/IngenX-IO/valets-data-architecture.git",
+    "directory": "mcp-server"
+  },
+  "engines": {
+    "node": ">=20.0"
+  }
+}