@table-bro/mcp 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Table, Bro
+
+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,90 @@
-# Temporary Holding Version
+# @table-bro/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.
+The MCP server of [Table, Bro](https://table-bro.com): pixel-perfect Material data tables for Angular, and more. A Web
+Components table engine on top of existing UI components. The server gives an AI coding agent the reference of the table,
+the check of a table spec and the code generator of a table for Angular and Vanilla JS, with the skins `mat` (Angular
+Material), `bs` (Bootstrap 5) and `nv` (native HTML). The agent writes the files; the server only reads.
+
+| Tool | What it gives |
+| --- | --- |
+| `get_started` | How Table, Bro works, the order of the tools and a minimal table for your target and skin, once a session |
+| `get_docs` | A topic of the reference or a page of Docs with its code, the topics of a query, or the list of the topics |
+| `inspect_project` | The packages, the skins, the CSS, the elements and the tables of the project, and the problems of its setup with their fixes |
+| `validate_spec` | Every error and warning of a table spec, with its path and its fix |
+| `generate_code` | The files of a new table from a spec or a built-in spec, the setup of the project and what to finish by hand |
+| `scaffold_component` | One custom cell, the row details or the filters of the Filter Drawer for an existing table, with how to connect it |
+
+## Setup
+
+The server describes one version of Table, Bro: run the version of `@table-bro/core` that the project has, as `1.1.0` below.
+After an update of Table, Bro, change the version in the setup of the agent too; `inspect_project` compares the
+versions and gives the line to change.
+
+`npx` downloads the package and starts it: the project does not install `@table-bro/mcp`. Node.js 22.12 or newer.
+
+**Claude Code**, `.mcp.json` in the root of the project:
+
+```json
+{"mcpServers": {"table-bro": {"command": "npx", "args": ["-y", "@table-bro/mcp@1.1.0"]}}}
+```
+
+or `claude mcp add --scope project table-bro -- npx -y @table-bro/mcp@1.1.0`.
+
+**Codex**, `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.table-bro]
+command = "npx"
+args = ["-y", "@table-bro/mcp@1.1.0"]
+```
+
+Codex calls the tools of the server when `AGENTS.md` of the project says so:
+
+```markdown
+The tables of this project are Table, Bro. Its MCP server table-bro has the reference, the check of a table and the code generator: call its tool get_started before you write or change a table.
+```
+
+**Cursor**, `.cursor/mcp.json` in the project:
+
+```json
+{"mcpServers": {"table-bro": {"command": "npx", "args": ["-y", "@table-bro/mcp@1.1.0"]}}}
+```
+
+**VS Code**, `.vscode/mcp.json` in the project:
+
+```json
+{"servers": {"table-bro": {"type": "stdio", "command": "npx", "args": ["-y", "@table-bro/mcp@1.1.0"]}}}
+```
+
+**Claude Desktop**, `claude_desktop_config.json`:
+
+```json
+{"mcpServers": {"table-bro": {"command": "npx", "args": ["-y", "@table-bro/mcp@1.1.0"]}}}
+```
+
+## The folder of the project
+
+`inspect_project` reads the project as text. It takes the folder in its argument `path`; without it, the first root of
+the workspace that the client gives, else the folder where the client started the server. A client that starts the
+server outside the project and gives no roots, as a desktop application may, needs `path`: the agent passes the root
+of the project. The profile names the folder it describes.
+
+## Paid modules
+
+A paid module of Table, Bro adds its fields of the config, its topics and its setup to the server when the server is
+started with its name, and the module is installed in the project:
+
+```json
+{"mcpServers": {"table-bro": {"command": "npx", "args": ["-y", "@table-bro/mcp@1.1.0", "--extension", "<the package of the module>"]}}}
+```
+
+The server runs the code of no other package.
+
+## In code
+
+The tools are pure functions, and the package exports them for Node.js and the browser: `validateSpec`,
+`generateCode`, `getDocs`, the built-in specs, `builtinSpecs`, and the JSON Schema of a spec, `specSchema`.
+
+## License
+
+MIT

package/dist/docs/docs.d.ts

@@ -0,0 +1,21 @@
+import type { BroMcpExtension } from '../extension.js';
+import { type BroTarget } from '../generate/setup.js';
+import type { BroSpecSkin } from '../spec/spec.js';
+import { type BroDocTopic } from './topics.js';
+/** The short text the MCP server gives a client when it connects. */
+export declare const serverInstructions: string;
+/**
+ * The one text an agent always reads: how the table works, a minimal working example for the target and the skin
+ * of the project, and the topics of the reference.
+ */
+export declare function getStarted(options?: {
+    target?: BroTarget;
+    skin?: BroSpecSkin;
+}, extensions?: BroMcpExtension[]): string;
+/** One topic of the reference, the topics that match a query, or the list of the topics. */
+export declare function getDocs(request?: {
+    topic?: string;
+    query?: string;
+}, extensions?: BroMcpExtension[]): string;
+/** The topics of the reference with the topics of the paid modules that the server loads. */
+export declare function allTopics(extensions: BroMcpExtension[]): BroDocTopic[];

package/dist/docs/docs.js

@@ -0,0 +1,103 @@
+import { generateCode } from '../generate/generate-code.js';
+import { setupText } from '../generate/setup.js';
+import { builtinSpecs } from '../spec/builtin-specs.js';
+import { tableBroVersion } from '../version.js';
+import { topics } from './topics.js';
+/** The short text the MCP server gives a client when it connects. */
+export const serverInstructions = `Table, Bro ${tableBroVersion}: pixel-perfect Material data tables for Angular, and more. A Web Components table engine on top of existing UI components: `
+    + 'the Custom Element <table-bro> with the skins mat (Angular Material), bs (Bootstrap 5) and nv (native HTML). '
+    + 'Call get_started first: it explains how the table works and which tool to use when. Describe a table as a BroTableSpec '
+    + '(with row details by default), check it with validate_spec, and get its code from generate_code. The server writes no files.';
+/**
+ * The one text an agent always reads: how the table works, a minimal working example for the target and the skin
+ * of the project, and the topics of the reference.
+ */
+export function getStarted(options = {}, extensions = []) {
+    const target = options.target ?? 'angular';
+    const skin = options.skin ?? (target === 'angular' ? 'mat' : 'bs');
+    const products = builtinSpecs.find(builtin => builtin.name === 'products');
+    const code = generateCode(products.spec, { target, skin });
+    // The page holds the cols, the rows and the config: the second file, after the type of the row
+    const page = code.files[1];
+    return [
+        header(extensions).trim(),
+        '## How Table, Bro works',
+        find('basics').text().trim(),
+        '## The order of the tools',
+        find('workflow').text().trim(),
+        `## A minimal table: ${target}, skin ${skin}`,
+        `Setup, once per project:\n\n${setupText(code.setup)}`,
+        `${page.path}:\n\n\`\`\`ts\n${page.content}\`\`\``,
+        '## Topics of get_docs',
+        topicList(extensions)
+    ].join('\n\n');
+}
+/** One topic of the reference, the topics that match a query, or the list of the topics. */
+export function getDocs(request = {}, extensions = []) {
+    const all = allTopics(extensions);
+    if (request.topic) {
+        const topic = all.find(item => item.name === request.topic);
+        if (!topic) {
+            return `${header(extensions)}No topic ${request.topic}. The topics:\n\n${topicList(extensions)}`;
+        }
+        return `${header(extensions)}# ${topic.title}\n\n${topic.text().trim()}`;
+    }
+    if (request.query) {
+        const found = search(all, request.query).slice(0, 2);
+        if (found.length) {
+            return header(extensions) + found.map(topic => `# ${topic.title}\n\n${topic.text().trim()}`).join('\n\n');
+        }
+        return `${header(extensions)}Nothing found for "${request.query}". The topics:\n\n${topicList(extensions)}`;
+    }
+    return `${header(extensions)}The topics:\n\n${topicList(extensions)}`;
+}
+function find(name) {
+    return topics.find(topic => topic.name === name);
+}
+/** The topics of the reference with the topics of the paid modules that the server loads. */
+export function allTopics(extensions) {
+    return [...topics, ...extensions.flatMap(extension => extension.topics ?? [])];
+}
+function topicList(extensions) {
+    return allTopics(extensions).map(topic => `- \`${topic.name}\`: ${topic.summary}`).join('\n');
+}
+/** Every answer names the version it describes and the paid modules that the server loads. */
+function header(extensions) {
+    const modules = extensions.length ? `, with ${extensions.map(extension => extension.package).join(', ')}` : '';
+    return `_table-bro ${tableBroVersion}${modules}_\n\n`;
+}
+/**
+ * The topics of a query, the best first. A word that most topics have weighs little, as row, and a rare one decides,
+ * as height. A title and a summary weigh more than the text, and every next repeat of a word in the text adds less.
+ */
+function search(all, query) {
+    const words = [...new Set(query.toLowerCase().split(/[^a-z0-9]+/).filter(word => word.length > 2).map(stem))];
+    const docs = all.map(topic => ({ topic, head: tokens(`${topic.name} ${topic.title} ${topic.summary}`), text: tokens(topic.text()) }));
+    const weights = words.map(word => Math.log((docs.length + 1) / (docs.filter(doc => count(doc.head, word) + count(doc.text, word)).length + 0.5)));
+    return docs
+        .map(doc => ({
+        topic: doc.topic,
+        score: words.reduce((sum, word, index) => {
+            const repeats = count(doc.text, word);
+            return sum + weights[index] * ((count(doc.head, word) ? 2 : 0) + 2 * repeats / (repeats + 1));
+        }, 0)
+    }))
+        .filter(item => item.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .map(item => item.topic);
+}
+/** The words of a text in lower case; a name in camelCase gives itself and its parts, as replaceRows, replace and rows. */
+function tokens(text) {
+    return text.split(/[^A-Za-z0-9]+/).flatMap(word => {
+        const parts = word.split(/(?<=[a-z0-9])(?=[A-Z])/);
+        return (parts.length > 1 ? [word, ...parts] : parts).map(part => part.toLowerCase());
+    });
+}
+/** A word of a query without the s of the plural: rows finds row and rows. */
+function stem(word) {
+    return (word.length > 3 && word.endsWith('s') && !word.endsWith('ss')) ? word.slice(0, -1) : word;
+}
+/** A word of the text matches by its start: row finds rows, but not arrow. */
+function count(words, word) {
+    return words.filter(item => item.startsWith(word)).length;
+}

package/dist/docs/pages.d.ts

@@ -0,0 +1,25 @@
+/** A file of code of a page of Docs, which the text of the page shows. */
+export interface BroDocFile {
+    /** The name of the file, unique on its page; the text shows the file by the line {{file}}. */
+    file: string;
+    /** The language of the code, as of a Markdown code block: ts, js, scss, css, html, json, bash or text. */
+    language: string;
+    code: string;
+}
+/**
+ * A page of Docs: the one source of the page of Docs on table-bro.com and of its topic of get_docs. The text is
+ * Markdown of a few forms: paragraphs, headings ###, #### and #####, ordered lists whose items continue with blocks
+ * indented by three spaces, `code`, **strong**, _emphasis_ and [links](url). A line {{file}} shows a file of code, and a line
+ * <!-- name --> starts the part of the page that the site shows at that name, next to its tables.
+ */
+export interface BroDocPage {
+    /** The path of the page under /docs. */
+    path: string;
+    name: string;
+    text: string;
+    files: BroDocFile[];
+}
+/** The pages of Docs, in the order of reading. Island Details have their own pages on the site, apart from this package. */
+export declare const docPages: BroDocPage[];
+/** The text of a page as Markdown: without the marks of its parts, with its files of code in code blocks. */
+export declare function docPageMarkdown(page: BroDocPage): string;