@jsswift/knowledge-mcp 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# JSswift knowledge MCP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Read the documentation of the `jsswift` package installed in your application. Requires Node.js 20+ and a JSswift release containing bundled documentation. No browser runtime is executed.
+
+Requires JSswift 1.0.44 or newer for bundled documentation. Configure an MCP stdio client with:
+
+```json
+{
+  "mcpServers": {
+    "jsswift": {
+      "command": "npx",
+      "args": ["-y", "--fetch-retries=0", "@jsswift/knowledge-mcp@latest"]
+    }
+  }
+}
+```
+
+The client must start the server in the app directory. Otherwise append `--project`, `/absolute/path/to/app` to `args`. Node package resolution supports ancestor node_modules, hoisted dependencies and package symlinks; for a monorepo with different app versions, point to the desired app. Each server connection serves one app.
+
+Search with `jsswift_search`, then read the returned IDs with `jsswift_read`. Both tools report the installed framework version. Resources expose the shared map and all indexed documents. Application APIs use `_.Toggle`, `_.signal`, `_.effect`, `_.computed`, `_.untracked`, and `_.batch`.
+
+Once the MCP package and its dependencies are cached or installed locally, documentation reads work offline. Initial `npx` execution requires downloading the package. Reconnect after upgrading JSswift. Missing documentation and version mismatches cause startup errors instead of silently using another release's documentation.
+
+For framework documentation development only, use `--docs /path/to/JSswift/documentions`; responses explicitly report `development` rather than an installed release.

package/dist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlos Malleux
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/server.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+
+// src/server.mjs
+import { McpServer } from "@modelcontextprotocol/server";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import * as z from "zod/v4";
+
+// ../knowledge.mjs
+import { readFile, realpath, readdir } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+var defaultRoot = fileURLToPath(new URL("../documentions/", import.meta.url));
+var tokens = (value) => String(value).normalize("NFD").replace(/[\u0300-\u036f]/g, "").toLowerCase().match(/[a-z0-9]+/g) ?? [];
+async function loadKnowledge(root = defaultRoot) {
+  const docsRoot = await realpath(root);
+  const map = JSON.parse(await readFile(path.join(docsRoot, "knowledge-map.json"), "utf8"));
+  if (map.schemaVersion !== 1 || map.scope !== "application-development") throw new Error("Unsupported knowledge map");
+  if (!Array.isArray(map.topics) || !Array.isArray(map.components)) throw new Error("Invalid knowledge collections");
+  const topicIds = /* @__PURE__ */ new Set();
+  for (const topic of map.topics) {
+    if (typeof topic.id !== "string" || topicIds.has(topic.id) || typeof topic.title !== "string" || !Array.isArray(topic.paths) || !topic.paths.length || !Array.isArray(topic.keywords) || topic.keywords.some((word) => typeof word !== "string")) throw new Error("Invalid or duplicate topic");
+    topicIds.add(topic.id);
+  }
+  for (const component of map.components) {
+    if (typeof component.id !== "string" || typeof component.name !== "string" || typeof component.summary !== "string" || !Array.isArray(component.keywords) || component.keywords.some((word) => typeof word !== "string") || !Array.isArray(component.topics) || !component.topics.length || component.topics.some((id) => !topicIds.has(id))) throw new Error("Invalid component entry");
+  }
+  const entries = /* @__PURE__ */ new Map();
+  const add = (entry) => {
+    if (entries.has(entry.id)) throw new Error(`Duplicate document ID: ${entry.id}`);
+    entries.set(entry.id, entry);
+  };
+  add({ id: "guide:index", kind: "guide", title: "Application documentation", path: map.entrypoint, keywords: ["start", "index"] });
+  for (const topic of map.topics) {
+    for (const docPath of topic.paths) {
+      const id = `guide:${docPath.replace(/\.md$/, "")}`;
+      const existing = entries.get(id);
+      if (existing) existing.keywords.push(...topic.keywords);
+      else add({ id, kind: "guide", title: topic.title, path: docPath, keywords: [...topic.keywords] });
+    }
+  }
+  for (const component of map.components) {
+    add({
+      id: `component:${component.id}`,
+      kind: "component",
+      title: component.name,
+      path: component.path,
+      summary: component.summary,
+      keywords: component.keywords,
+      topics: component.topics
+    });
+  }
+  async function safePath(relativePath) {
+    if (typeof relativePath !== "string" || path.isAbsolute(relativePath) || relativePath.split(/[\\/]/).includes("..")) {
+      throw new Error("Invalid documentation path");
+    }
+    const resolved = await realpath(path.join(docsRoot, relativePath));
+    if (!resolved.startsWith(docsRoot + path.sep)) throw new Error("Document outside documentation root");
+    return resolved;
+  }
+  for (const entry of entries.values()) {
+    if (!entry.path.endsWith(".md")) throw new Error(`Invalid document extension: ${entry.path}`);
+    const text = await readFile(await safePath(entry.path), "utf8");
+    if (entry.kind === "guide") entry.title = text.split("\n")[0].replace(/^# /, "");
+    if (entry.kind === "component") {
+      const block = text.match(/```json\s*([\s\S]*?)```/);
+      if (!block) throw new Error(`Missing component metadata: ${entry.path}`);
+      const metadata = JSON.parse(block[1]);
+      if (!metadata.signature?.startsWith(`_.${entry.title}(`) || !entry.keywords.includes(`_.${entry.title}`) || entry.keywords.some((word) => word.startsWith("JSswift."))) {
+        throw new Error(`Noncanonical application API: ${entry.path}; use _.${entry.title}`);
+      }
+      if (text.split("\n")[0] !== `# ${entry.title}` || (metadata.description ?? "") !== entry.summary) {
+        throw new Error(`Stale component map: ${entry.path}; run npm run knowledge:refresh`);
+      }
+    }
+  }
+  const files = (await readdir(path.join(docsRoot, "components"))).filter((name) => name.endsWith(".md") && name !== "README.md");
+  const indexed = new Set(map.components.map((component) => component.path));
+  if (files.length !== indexed.size || files.some((name) => !indexed.has(`components/${name}`))) {
+    throw new Error("Component map coverage mismatch; run npm run knowledge:refresh");
+  }
+  return {
+    map,
+    list: () => [...entries.values()].map(({ keywords, ...entry }) => entry),
+    search(query, limit = 6) {
+      if (typeof query !== "string" || query.length > 500) throw new Error("Query must be a string of at most 500 characters");
+      if (!Number.isInteger(limit) || limit < 1 || limit > 20) throw new Error("Limit must be from 1 to 20");
+      const words = tokens(query);
+      if (!words.length) return [];
+      const ranked = [...entries.values()].map((entry) => {
+        const names = tokens(`${entry.id} ${entry.title}`);
+        const keywords = tokens(entry.keywords.join(" "));
+        const summary = tokens(entry.summary ?? "");
+        const score = words.reduce((sum, word) => sum + (names.includes(word) ? 12 : keywords.includes(word) ? 6 : summary.includes(word) ? 1 : 0), 0);
+        const { keywords: ignored, ...result } = entry;
+        return { ...result, score };
+      }).filter((entry) => entry.score > 0).sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+      return ranked.slice(0, limit);
+    },
+    async read(id) {
+      const entry = entries.get(id);
+      if (!entry) throw new Error("Unknown document ID; use jsswift_search to find a documented ID");
+      return { id, path: entry.path, text: await readFile(await safePath(entry.path), "utf8") };
+    }
+  };
+}
+
+// src/project.mjs
+import { createRequire } from "node:module";
+import { readFile as readFile2, realpath as realpath2 } from "node:fs/promises";
+import path2 from "node:path";
+async function resolveProject(project = process.cwd()) {
+  const root = await realpath2(path2.resolve(project));
+  const require2 = createRequire(path2.join(root, "package.json"));
+  let mapPath, manifestPath;
+  try {
+    mapPath = require2.resolve("jsswift/knowledge-map.json");
+    manifestPath = require2.resolve("jsswift/package.json");
+  } catch {
+    throw new Error(`No JSswift package with bundled documentation found from ${root}. Install a release containing knowledge-map.json, or use --project /path/to/app.`);
+  }
+  const manifest = JSON.parse(await readFile2(manifestPath, "utf8"));
+  const map = JSON.parse(await readFile2(mapPath, "utf8"));
+  if (manifest.name !== "jsswift" || map.packageVersion !== manifest.version) {
+    throw new Error("JSswift documentation version does not match the installed package");
+  }
+  return { project: root, version: manifest.version, docsRoot: path2.dirname(mapPath) };
+}
+function parseArgs(args) {
+  const options2 = { project: process.cwd() };
+  for (let i = 0; i < args.length; i++) {
+    const key = args[i];
+    if (!["--project", "--docs"].includes(key) || !args[i + 1] || args[i + 1].startsWith("--")) {
+      throw new Error("Usage: jsswift-mcp [--project /path/to/app] [--docs /path/to/development/documentions]");
+    }
+    options2[key.slice(2)] = path2.resolve(args[++i]);
+  }
+  return options2;
+}
+
+// src/server.mjs
+var options = parseArgs(process.argv.slice(2));
+var context = options.docs ? { project: options.project, version: "development", docsRoot: options.docs } : await resolveProject(options.project);
+var knowledge = await loadKnowledge(context.docsRoot);
+var server = new McpServer({ name: "jsswift-knowledge", version: "0.1.0" }, {
+  instructions: `Serving JSswift ${context.version} from project ${context.project}. Prefer _.Button for buttons. Use _.Component and _.signal, _.effect, _.computed, _.untracked, _.batch. Search for the feature and read selected contracts before coding. This server covers application development only.`
+});
+var annotations = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+var jsonResult = (value) => ({ content: [{ type: "text", text: JSON.stringify(value) }], structuredContent: value });
+server.registerTool("jsswift_search", {
+  title: "Find JSswift application documentation",
+  description: "Find focused guides and component contracts by feature, API name, or Italian/English keywords. Returns document IDs and paths. Read matching documents with jsswift_read before using APIs; no results means no indexed match, not permission to invent an API.",
+  inputSchema: z.object({ query: z.string().trim().min(1).max(500), limit: z.number().int().min(1).max(20).default(6) }),
+  annotations
+}, async ({ query, limit }) => jsonResult({ project: context.project, version: context.version, results: knowledge.search(query, limit) }));
+server.registerTool("jsswift_read", {
+  title: "Read a JSswift guide or exact component contract",
+  description: "Read one complete indexed application document using its ID from jsswift_search or the resource list. Does not accept filesystem paths.",
+  inputSchema: z.object({ id: z.string().min(1).max(200) }),
+  annotations
+}, async ({ id }) => {
+  try {
+    return jsonResult({ project: context.project, version: context.version, ...await knowledge.read(id) });
+  } catch {
+    return { isError: true, content: [{ type: "text", text: "Document unavailable or unknown ID. Use jsswift_search to select an indexed document." }] };
+  }
+});
+server.registerResource("knowledge-map", "jsswift://knowledge/map", {
+  title: "JSswift application knowledge map",
+  mimeType: "application/json"
+}, async (uri) => ({ contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(knowledge.map) }] }));
+for (const document of knowledge.list()) {
+  server.registerResource(document.id, `jsswift://docs/${encodeURIComponent(document.id)}`, {
+    title: document.title,
+    description: document.summary ?? document.path,
+    mimeType: "text/markdown"
+  }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: (await knowledge.read(document.id)).text }] }));
+}
+await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@jsswift/knowledge-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Read-only MCP for the installed JSswift version's documentation",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "start": "node dist/server.mjs",
+    "test": "node --test tests/*.test.mjs",
+    "build": "node ../../tools/build-knowledge-mcp.mjs",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.3.1",
+    "zod": "4.6.5"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.3.1"
+  },
+  "license": "MIT",
+  "bin": {
+    "jsswift-mcp": "dist/server.mjs"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/camavi/JSswift.git",
+    "directory": "ai/mcp"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}