@xoong/mcp 0.0.0-stage → 0.0.34

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Duong Tran Xuan
+
+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/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# @xoong/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.
+An MCP server for xoong: gives AI assistants the spec (`llms.txt`), the operations of your API, `xoong check` and explanations of errors, over stdio.
+
+## Install
+
+```bash
+npm install @xoong/mcp
+```
+
+## Use
+
+```bash
+npx xoong-mcp
+```
+Add it to your assistant's MCP configuration as a stdio server running `xoong-mcp`.
+
+## More
+
+* Documentation and demos: https://github.com/fpt-duongtx/xoong#readme
+* Source: https://github.com/fpt-duongtx/xoong/tree/main/packages/mcp
+* All packages share one version number and are released together: https://github.com/fpt-duongtx/xoong/releases
+* xoong is a working prototype (0.0.x): the HTML syntax is still Draft.
+
+MIT licence.

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@xoong/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.34",
+  "description": "MCP server for xoong: gives AI assistants the spec (llms.txt), the API's operations, `xoong check` and error explanations over stdio.",
+  "type": "module",
+  "bin": {
+    "xoong-mcp": "src/cli.js"
+  },
+  "exports": {
+    ".": "./src/server.js"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@xoong/cli": "0.0.34"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "xoong",
+    "web-framework",
+    "openapi",
+    "custom-elements"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "author": "Duong Tran Xuan <duongtx1505@icloud.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fpt-duongtx/xoong.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/fpt-duongtx/xoong/issues"
+  },
+  "homepage": "https://github.com/fpt-duongtx/xoong#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cli.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// @ts-check
+// xoong-mcp [--operations .xoong/operations.json] [--llms llms.txt] [--docs docs]
+import { readFile, access } from 'node:fs/promises';
+import { createInterface } from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import { createServer } from './server.js';
+
+const args = process.argv.slice(2);
+const flag = (name, fallback) => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : fallback; };
+const opsFile = flag('--operations', '.xoong/operations.json');
+const exists = (p) => access(p).then(() => true, () => false);
+
+const server = createServer({
+  async llms() {
+    // the project's own file first, then the copy that sits at the repository root of this package
+    for (const p of [flag('--llms'), 'llms.txt', fileURLToPath(new URL('../../../llms.txt', import.meta.url))].filter(Boolean)) if (await exists(p)) return readFile(p, 'utf8');
+    throw new Error('llms.txt not found: pass --llms <file>');
+  },
+  async operations() {
+    try { return JSON.parse(await readFile(opsFile, 'utf8')); } catch { throw new Error(`cannot read ${opsFile}: run \`xoong sync <openapi>\` first or pass --operations <file>`); }
+  },
+  docsDir: flag('--docs') ?? ((await exists('docs')) ? 'docs' : undefined),
+});
+
+const lines = createInterface({ input: process.stdin });
+for await (const line of lines) {
+  if (!line.trim()) continue;
+  let msg;
+  try { msg = JSON.parse(line); } catch { process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }) + '\n'); continue; }
+  const out = await server.handle(msg);
+  if (out) process.stdout.write(JSON.stringify(out) + '\n'); // stdout carries protocol messages only
+}

package/src/server.js

@@ -0,0 +1,116 @@
+// @ts-check
+/**
+ * A small Model Context Protocol server (JSON-RPC 2.0, newline-delimited over stdio).
+ * No SDK: the protocol surface xoong needs is `initialize`, `tools/list` and `tools/call`.
+ *
+ * Tools (the loop an assistant follows: read the spec, write code, check, fix from the message):
+ *   get_spec          the whole llms.txt
+ *   list_operations   operations of the synced API (id, method, path, query, body fields)
+ *   check             run `xoong check` on HTML source text; returns structured findings
+ *   explain_error     what an XO code means and how to fix it
+ *   search_docs       find a term in the docs folder (when one is configured)
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { checkHtml, checkScript } from '@xoong/cli/check';
+
+export const PROTOCOL_VERSION = '2024-11-05';
+
+/** Meaning and fix for every code `xoong check` and `xoong doctor` can print. Kept in step with check.js by a test. */
+export const EXPLANATIONS = {
+  XO201: 'An operation name in xo-click, xo-submit, <xo-view get> or <xo-form op> does not exist in the synced API. Use the closest name the message gives, or run `xoong sync` if the API changed.',
+  XO202: 'xo-click calls a GET operation. Reads are declared with <xo-view get="...">; xo-click is for mutations.',
+  XO203: '<xo-view get> uses an operation that is not GET. Use a GET operation for reading and xo-click/xo-submit for writes.',
+  XO210: 'The view\'s operation has a path parameter such as {id}, but the view has no p-id attribute. Add p-id="..." or set view.params in JavaScript.',
+  XO222: '<form xo-submit> must be inside an <xo-view>, otherwise it never binds. Wrap it in <xo-view> (without get is fine).',
+  XO220: 'xo-submit is only valid on a <form>. Move the attribute to the form element.',
+  XO221: 'xo-each, xo-if or xo-body has no path. Give it one, for example xo-each="items".',
+  XO230: 'An xo-* element or attribute that xoong does not define, usually a typo. The message names the closest valid one.',
+  XO240: 'A button or link triggered by xo-click has no accessible name. Add visible text or aria-label.',
+  XO241: 'xo-click is on an element that keyboards cannot reach. Use a <button>, or add role="button" and tabindex="0".',
+  XO250: '<xo-table sortable> needs a `sort` query parameter on the view\'s operation, and page-size needs `limit` and `offset`. Add them to the API or remove the attribute.',
+  XO253: 'A filter box of <xo-table filters="..."> sets a query parameter of the same name, and the view\'s operation does not declare it. Add the parameter to the API or remove the filter.',
+  XO204: 'client.load()/query() were given a write operation, or client.mutate()/stream() a GET. Reads: load/query. Writes: mutate.',
+  XO254: 'xo-selected only makes sense on an xo-click button, and xo-select on a checkbox. Move the attribute.',
+  XO260: 'A route path must start with "/" (or be "*" for not found) and each path may be declared once per router. Write xo-route="/users/:id".',
+  XO261: 'layout="x" on a route (or layout) names a layout that is not declared in the same <xo-router>. Declare <template xo-layout="x">, or use the closest name the message gives.',
+  XO262: 'A layout template needs one element with xo-outlet where the route content is shown, for example <main xo-outlet>.',
+  XO263: 'p-x=":name" reads a route parameter: it only works inside a <template xo-route="..."> whose path contains :name. Fix the name, or use a fixed value or p-x="?query".',
+  XO255: 'This operation has no request schema (for example a multipart body), so <xo-form> can only draw simple fields, and the operation requires nested objects, arrays or unions: the generated form can never satisfy the server. Write the <form xo-submit> by hand.',
+  XO251: '<xo-table> must be inside an <xo-view get="...">, which supplies its data.',
+  XO252: '<xo-form op> found no simple request fields to generate. Write the <form xo-submit> by hand.',
+};
+
+const TOOLS = [
+  { name: 'get_spec', description: 'Return xoong\'s whole public API as one short document (llms.txt). Read it before writing xoong code.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'list_operations', description: 'List the operations of the synced API: id, method, path, query parameters and request body fields. Use these exact names in xo-click, xo-submit and <xo-view get>.', inputSchema: { type: 'object', properties: { filter: { type: 'string', description: 'Only operations whose id or path contains this text.' } } } },
+  { name: 'check', description: 'Run `xoong check` on HTML source text and return findings with line, column, message and fix. Fix every error before showing code to the user.', inputSchema: { type: 'object', properties: { html: { type: 'string', description: 'The HTML source of a screen.' }, script: { type: 'string', description: 'JavaScript or TypeScript source instead of html: checks html`...` templates and client.load/query/mutate/stream calls.' } } } },
+  { name: 'explain_error', description: 'Explain an XO error code (for example XO201) and how to fix it.', inputSchema: { type: 'object', properties: { code: { type: 'string' } }, required: ['code'] } },
+  { name: 'search_docs', description: 'Search the xoong documentation for a term and return matching lines with file names.', inputSchema: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] } },
+];
+
+/**
+ * @param {{ llms: () => Promise<string>, operations: () => Promise<{ operations: Record<string, any> }>, docsDir?: string }} ctx
+ */
+export function createServer(ctx) {
+  const text = (t, isError = false) => ({ content: [{ type: 'text', text: t }], ...(isError ? { isError: true } : {}) });
+
+  /** @param {string} name @param {any} args */
+  async function callTool(name, args = {}) {
+    switch (name) {
+      case 'get_spec': return text(await ctx.llms());
+      case 'list_operations': {
+        const table = await ctx.operations();
+        const f = String(args.filter ?? '').toLowerCase();
+        const rows = Object.values(table.operations).filter((o) => !f || o.id.toLowerCase().includes(f) || o.path.toLowerCase().includes(f))
+          .map((o) => ({ id: o.id, call: `${o.method} ${o.path}`, ...(o.query ? { query: o.query } : {}), ...(o.bodyFields ? { bodyFields: o.bodyFields.map((b) => b.name + (b.required ? '*' : '')) } : {}), ...(o.stream ? { stream: true } : {}), ...(o.multipart ? { multipart: true } : {}) }));
+        return text(JSON.stringify(rows, null, 2));
+      }
+      case 'check': {
+        if (typeof args.html !== 'string' && typeof args.script !== 'string') return text('check needs an "html" or a "script" string', true);
+        const table = await ctx.operations();
+        const findings = typeof args.script === 'string' ? checkScript(args.script, table, 'screen.ts') : checkHtml(args.html, table, 'screen.html');
+        return text(findings.length ? JSON.stringify(findings, null, 2) : 'No findings.');
+      }
+      case 'explain_error': {
+        const code = String(args.code ?? '').toUpperCase();
+        return EXPLANATIONS[code] ? text(`${code}: ${EXPLANATIONS[code]}`) : text(`Unknown code "${args.code}". Known: ${Object.keys(EXPLANATIONS).join(', ')}. API audit codes (XO1xx) are explained by \`xoong doctor\`.`, true);
+      }
+      case 'search_docs': {
+        if (!ctx.docsDir) return text('No docs folder is configured (start the server with --docs <folder>).', true);
+        const q = String(args.query ?? '').toLowerCase();
+        if (!q) return text('search_docs needs a query', true);
+        const hits = [];
+        for (const file of (await readdir(ctx.docsDir)).filter((f) => f.endsWith('.md')).sort()) {
+          (await readFile(join(ctx.docsDir, file), 'utf8')).split('\n').forEach((line, i) => { if (line.toLowerCase().includes(q) && hits.length < 40) hits.push(`${file}:${i + 1}: ${line.trim()}`); });
+        }
+        return text(hits.length ? hits.join('\n') : `No match for "${args.query}".`);
+      }
+      default: return text(`Unknown tool "${name}"`, true);
+    }
+  }
+
+  /**
+   * Handle one JSON-RPC message. Returns the response object, or null for notifications.
+   * @param {any} msg
+   */
+  async function handle(msg) {
+    if (!msg || typeof msg !== 'object' || typeof msg.method !== 'string') return { jsonrpc: '2.0', id: msg?.id ?? null, error: { code: -32600, message: 'Invalid request' } };
+    if (msg.id === undefined) return null; // notification (initialized, cancelled, ...)
+    const reply = (result) => ({ jsonrpc: '2.0', id: msg.id, result });
+    const fail = (code, message) => ({ jsonrpc: '2.0', id: msg.id, error: { code, message } });
+    try {
+      switch (msg.method) {
+        case 'initialize': return reply({ protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: { name: 'xoong', version: '0.0.1' }, instructions: 'Call get_spec first. Write xoong screens, then call check on the HTML and fix every error from its message.' });
+        case 'ping': return reply({});
+        case 'tools/list': return reply({ tools: TOOLS });
+        case 'tools/call': return reply(await callTool(msg.params?.name, msg.params?.arguments));
+        default: return fail(-32601, `Method not found: ${msg.method}`);
+      }
+    } catch (e) {
+      return msg.method === 'tools/call' ? reply(text(`${e instanceof Error ? e.message : e}`, true)) : fail(-32603, String(e instanceof Error ? e.message : e));
+    }
+  }
+
+  return { handle, tools: TOOLS };
+}