@cloudgrid-io/mcp 0.4.6 → 0.5.0

package/src/docs-search.js

@@ -0,0 +1,176 @@
+// BM25 keyword search over the CloudGrid documentation corpus.
+//
+// Chunks markdown files by heading, builds an inverted index, and ranks by
+// BM25. The DocsSearch class exposes a clean .search(query) → results interface
+// so the backend can be swapped to semantic/embedding search later without
+// changing the tool contract.
+
+import { readFileSync, readdirSync } from "node:fs";
+
+const STOPWORDS = new Set([
+  "a", "an", "the", "and", "or", "but", "in", "on", "at", "to", "for",
+  "of", "with", "by", "from", "is", "it", "as", "be", "was", "are",
+  "this", "that", "not", "if", "do", "so", "no", "can", "will", "all",
+  "has", "had", "have", "each", "which", "their", "you", "your", "its",
+  "any", "more", "also", "than", "then", "what", "when", "how", "who",
+  "up", "out", "about", "into", "over", "just", "some", "only",
+]);
+
+function tokenize(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .split(/\s+/)
+    .filter((t) => t.length > 1 && !STOPWORDS.has(t));
+}
+
+function termFrequency(tokens) {
+  const tf = Object.create(null);
+  for (const t of tokens) tf[t] = (tf[t] || 0) + 1;
+  return tf;
+}
+
+/** Trim a markdown body to a readable snippet. */
+function makeSnippet(body, maxLen = 300) {
+  const clean = body
+    .replace(/```[\s\S]*?```/g, " ")
+    .replace(/\n+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  return clean.length <= maxLen ? clean : clean.slice(0, maxLen - 1) + "\u2026";
+}
+
+/** Split a markdown document into chunks by headings (# or ##). */
+function chunkMarkdown(source, content) {
+  const lines = content.split("\n");
+  const chunks = [];
+  let title = source;
+  let body = [];
+  let inFrontmatter = false;
+  let seenFirstLine = false;
+
+  for (const line of lines) {
+    // Skip YAML frontmatter (--- delimited block at the top).
+    if (line.trim() === "---" && !seenFirstLine) {
+      inFrontmatter = true;
+      seenFirstLine = true;
+      continue;
+    }
+    if (inFrontmatter) {
+      if (line.trim() === "---") inFrontmatter = false;
+      continue;
+    }
+    seenFirstLine = true;
+
+    const heading = line.match(/^(#{1,3})\s+(.+)/);
+    if (heading) {
+      if (body.length > 0) {
+        const text = body.join("\n").trim();
+        if (text) chunks.push({ title, body: text, source });
+      }
+      body = [];
+      title = heading[2].trim();
+    } else {
+      body.push(line);
+    }
+  }
+  const text = body.join("\n").trim();
+  if (text) chunks.push({ title, body: text, source });
+
+  return chunks;
+}
+
+export class DocsSearch {
+  constructor() {
+    /** @type {Array<{title: string, body: string, source: string, tokens: string[], tf: Record<string,number>}>} */
+    this.docs = [];
+    this.df = Object.create(null);
+    this.avgdl = 0;
+    this._built = false;
+  }
+
+  get size() {
+    return this.docs.length;
+  }
+
+  /** Add a single document chunk to the index. */
+  addDocument(title, body, source) {
+    // Weight the title 2x by repeating it in the token stream.
+    const tokens = tokenize(title + " " + title + " " + body);
+    this.docs.push({ title, body, source, tokens, tf: termFrequency(tokens) });
+  }
+
+  /** Compute document frequencies and average document length. Call after all adds. */
+  build() {
+    const N = this.docs.length;
+    if (N === 0) return;
+    this.avgdl = this.docs.reduce((sum, d) => sum + d.tokens.length, 0) / N;
+    this.df = Object.create(null);
+    for (const doc of this.docs) {
+      const seen = new Set(doc.tokens);
+      for (const t of seen) this.df[t] = (this.df[t] || 0) + 1;
+    }
+    this._built = true;
+  }
+
+  /**
+   * Search the corpus. Returns the top-K results ranked by BM25.
+   * @param {string} query
+   * @param {number} topK
+   * @returns {Array<{title: string, snippet: string, source: string, score: number}>}
+   */
+  search(query, topK = 5) {
+    if (!this._built) this.build();
+    const qTokens = tokenize(query);
+    if (qTokens.length === 0) return [];
+
+    const N = this.docs.length;
+    const k1 = 1.5;
+    const b = 0.75;
+
+    const scored = this.docs.map((doc) => {
+      let score = 0;
+      for (const qt of qTokens) {
+        const tf = doc.tf[qt] || 0;
+        const df = this.df[qt] || 0;
+        if (df === 0 || tf === 0) continue;
+        const idf = Math.log((N - df + 0.5) / (df + 0.5) + 1);
+        score +=
+          idf * ((tf * (k1 + 1)) / (tf + k1 * (1 - b + (b * doc.tokens.length) / this.avgdl)));
+      }
+      return { doc, score };
+    });
+
+    return scored
+      .filter((s) => s.score > 0)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, topK)
+      .map(({ doc, score }) => ({
+        title: doc.title,
+        snippet: makeSnippet(doc.body),
+        source: doc.source,
+        score: Math.round(score * 100) / 100,
+      }));
+  }
+}
+
+/**
+ * Load all .md files from src/corpus/, chunk by heading, and build the index.
+ * @param {DocsSearch} searchIndex
+ * @returns {DocsSearch}
+ */
+export function loadCorpus(searchIndex) {
+  const corpusDir = new URL("./corpus/", import.meta.url);
+  const files = readdirSync(corpusDir).filter((f) => f.endsWith(".md")).sort();
+
+  for (const file of files) {
+    const content = readFileSync(new URL(file, corpusDir), "utf-8");
+    const source = file.replace(/\.md$/, "");
+    for (const chunk of chunkMarkdown(source, content)) {
+      searchIndex.addDocument(chunk.title, chunk.body, chunk.source);
+    }
+  }
+
+  searchIndex.build();
+  return searchIndex;
+}

package/src/docs.js

@@ -0,0 +1,135 @@
+// CloudGrid MCP server — docs edition (public, read-only, no auth).
+//
+// A public documentation search server exposing search_cloudgrid_documentation
+// (and an optional cloudgrid_quickstart_guide) over MCP Streamable HTTP. The
+// same Express + StreamableHTTP pattern as the web edition (src/web.js),
+// stripped to the minimum: no auth, no OAuth, no session identity, no secrets.
+// Safe to expose anonymously.
+//
+// The corpus (src/corpus/*.md) is indexed at startup with BM25 keyword search.
+// The search backend is behind a clean interface so it can be swapped to
+// semantic/embedding search later without changing the tool contract.
+//
+// Run: PORT=8080 node src/docs.js     Health: GET /healthz
+
+import { readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import express from "express";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { DocsSearch, loadCorpus } from "./docs-search.js";
+
+const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url)));
+
+const PORT = Number(process.env.PORT || 8080);
+
+// Build the search index once at startup.
+const search = loadCorpus(new DocsSearch());
+
+// Load the quickstart guide verbatim.
+const QUICKSTART = readFileSync(new URL("./corpus/cookbook.md", import.meta.url), "utf-8");
+
+// ── Tool helpers (same convention as tools.js) ────────────────────────────────
+function ok(text) {
+  return { content: [{ type: "text", text }] };
+}
+
+function createDocsServer() {
+  const server = new McpServer({ name: "cloudgrid-docs", version });
+
+  server.tool(
+    "search_cloudgrid_documentation",
+    "Search CloudGrid documentation — guides, tutorials, CLI reference, MCP setup, and skill descriptions. Returns the most relevant doc chunks with title, snippet, and source path.",
+    {
+      query: z
+        .string()
+        .describe(
+          "The search query, e.g. 'deploy a database app' or 'add the MCP to Cursor'",
+        ),
+    },
+    async ({ query }) => {
+      const results = search.search(query, 5);
+      if (results.length === 0) {
+        return ok("No documentation matched your query. Try different keywords.");
+      }
+      const text = results
+        .map(
+          (r, i) => `### ${i + 1}. ${r.title}\n${r.snippet}\n_Source: ${r.source}_`,
+        )
+        .join("\n\n---\n\n");
+      return ok(text);
+    },
+  );
+
+  server.tool(
+    "cloudgrid_quickstart_guide",
+    "Get the CloudGrid quickstart guide — the canonical build-and-ship loop from scaffold to deploy to feedback.",
+    {},
+    async () => ok(QUICKSTART),
+  );
+
+  return server;
+}
+
+// ── HTTP server (mirrors src/web.js, no auth) ─────────────────────────────────
+const app = express();
+app.use(express.json());
+
+app.get("/healthz", (_req, res) => res.json({ ok: true, edition: "docs" }));
+
+const transports = Object.create(null);
+
+app.post("/mcp", async (req, res) => {
+  const sessionId = req.headers["mcp-session-id"];
+  let transport = sessionId ? transports[sessionId] : undefined;
+
+  if (transport) {
+    await transport.handleRequest(req, res, req.body);
+    return;
+  }
+
+  if (sessionId || !isInitializeRequest(req.body)) {
+    res.status(400).json({
+      jsonrpc: "2.0",
+      error: { code: -32000, message: "No valid session. Send an initialize request first." },
+      id: null,
+    });
+    return;
+  }
+
+  const newSessionId = randomUUID();
+  transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: () => newSessionId,
+    onsessioninitialized: (sid) => {
+      transports[sid] = transport;
+    },
+  });
+  transport.onclose = () => {
+    if (transport.sessionId) delete transports[transport.sessionId];
+  };
+  const server = createDocsServer();
+  await server.connect(transport);
+  await transport.handleRequest(req, res, req.body);
+});
+
+async function handleSessionRequest(req, res) {
+  const sessionId = req.headers["mcp-session-id"];
+  const transport = sessionId ? transports[sessionId] : undefined;
+  if (!transport) {
+    res.status(400).send("Invalid or missing session id");
+    return;
+  }
+  await transport.handleRequest(req, res);
+}
+
+app.get("/mcp", handleSessionRequest);
+app.delete("/mcp", handleSessionRequest);
+
+app.listen(PORT, () => {
+  // eslint-disable-next-line no-console
+  console.error(
+    `cloudgrid-docs edition listening on :${PORT} (POST /mcp, GET /healthz) — ${search.size} chunks indexed`,
+  );
+});

package/src/tools.js

@@ -90,6 +90,9 @@ function resolveBundledCli() {
   }
 }
 
+// Pin the CLI version for the lazy npx fallback so behaviour is reproducible.
+const CLI_NPX_PKG = "@cloudgrid-io/cli@^0.9.20";
+
 async function runCloudgrid(args, opts = {}) {
   const cwd = resolveCwd(opts.cwd);
   const execOpts = {
@@ -99,7 +102,15 @@ async function runCloudgrid(args, opts = {}) {
     ...(cwd ? { cwd } : {}),
   };
 
-  // 1. Try the bundled CLI (node <cliEntry> ...args)
+  const extract = (err) => {
+    const detail = [err && err.stdout, err && err.stderr, err && err.message]
+      .filter(Boolean)
+      .join("\n")
+      .trim();
+    return new Error(detail || "cloudgrid command failed");
+  };
+
+  // 1. Bundled CLI (the .mcpb ships it in its node_modules)
   const bundled = resolveBundledCli();
   if (bundled) {
     try {
@@ -110,29 +121,32 @@ async function runCloudgrid(args, opts = {}) {
       );
       return (stdout || stderr || "").trim() || "Done.";
     } catch (err) {
-      const detail = [err && err.stdout, err && err.stderr, err && err.message]
-        .filter(Boolean)
-        .join("\n")
-        .trim();
-      throw new Error(detail || "cloudgrid command failed");
+      throw extract(err);
     }
   }
 
-  // 2. Fallback: global `cloudgrid` on PATH
+  // 2. Global `cloudgrid` on PATH
   try {
     const { stdout, stderr } = await execFileAsync("cloudgrid", args, execOpts);
     return (stdout || stderr || "").trim() || "Done.";
   } catch (err) {
-    if (err && err.code === "ENOENT") {
-      throw new Error(
-        "The cloudgrid CLI is not installed. Install it with: npm install -g @cloudgrid-io/cli",
-      );
-    }
-    const detail = [err && err.stdout, err && err.stderr, err && err.message]
-      .filter(Boolean)
-      .join("\n")
-      .trim();
-    throw new Error(detail || "cloudgrid command failed");
+    if (!(err && err.code === "ENOENT")) throw extract(err);
+    // Not found — fall through to lazy npx fetch
+  }
+
+  // 3. Lazy fetch: npx -y @cloudgrid-io/cli@<pinned> <args>
+  //    One-time download; npx caches it for subsequent invocations.
+  console.error("cloudgrid-mcp: fetching the CloudGrid CLI (first use)…");
+  const npx = process.platform === "win32" ? "npx.cmd" : "npx";
+  try {
+    const { stdout, stderr } = await execFileAsync(
+      npx,
+      ["-y", CLI_NPX_PKG, ...args],
+      execOpts,
+    );
+    return (stdout || stderr || "").trim() || "Done.";
+  } catch (err) {
+    throw extract(err);
   }
 }