@kammcs/buildit-mcp 0.0.0-stage → 0.2.0

package/dist/untrusted.js

@@ -0,0 +1,466 @@
+/**
+ * Marking text that people wrote.
+ *
+ * Titles, descriptions, comments, pages, chat messages and names are written
+ * by people (guests among them) and read by an agent, so they can carry text
+ * aimed at the agent ("ignore previous instructions and ..."). Every tool that
+ * returns such text wraps it:
+ *
+ *   <untrusted_content id="3f9c0a7d21" source="comment" author="Ana">
+ *   ...
+ *   </untrusted_content id="3f9c0a7d21">
+ *
+ * and the server's instructions tell the agent that anything inside is data,
+ * never instructions, and that a block ends only at a closing tag with its
+ * id. The id is random for each tool result (or resource read), so text
+ * written before the call can't know it. This is a best-effort signal, not a
+ * security boundary; the boundaries are the token's scopes and limits, the
+ * API's permission checks, and preview-then-confirm for destructive changes.
+ *
+ * So that the content can't seem to end the block early, or fake a new one,
+ * the block's name is also defused wherever it could form a tag inside,
+ * look-alikes included; text that only mentions the name is left exactly as
+ * written (see neutralize).
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomBytes } from 'node:crypto';
+export const UNTRUSTED_TAG = 'untrusted_content';
+export const DEFAULT_MAX_CHARS = 8000;
+const MAX_ATTRIBUTE_CHARS = 120;
+const DEFAULT_MORE_HINT = 'Ask for the full text (for example with detail="full") to read the rest.';
+const ATTRIBUTE_NAME = /^[a-z][a-z_]{0,30}$/;
+// ---------------------------------------------------------------------------
+// Block ids
+// ---------------------------------------------------------------------------
+const blockIds = new AsyncLocalStorage();
+/** A fresh random block id: 10 hex characters. */
+export function newBlockId() {
+    return randomBytes(5).toString('hex');
+}
+/**
+ * Runs `fn` with one block id for every block it wraps, so one tool result
+ * (or resource read) uses one id. Outside such a run, each block gets its
+ * own random id.
+ */
+export function withBlockId(fn, id = newBlockId()) {
+    return blockIds.run(id, fn);
+}
+function currentBlockId() {
+    return blockIds.getStore() ?? newBlockId();
+}
+// ---------------------------------------------------------------------------
+// Defusing the block's name
+// ---------------------------------------------------------------------------
+/**
+ * Cyrillic, Greek and other letters that look like the Latin letters of
+ * "untrusted" and "content" (lower case; text is lower-cased first).
+ */
+const LOOK_ALIKES = {
+    '\u{3C5}': 'u', // Greek upsilon
+    '\u{57D}': 'u', // Armenian seh
+    '\u{1D1C}': 'u', // small capital U
+    '\u{3BD}': 'n', // Greek nu (from upper-case N)
+    '\u{3B7}': 'n', // Greek eta
+    '\u{43F}': 'n', // Cyrillic pe
+    '\u{274}': 'n', // small capital N
+    '\u{3C4}': 't', // Greek tau
+    '\u{442}': 't', // Cyrillic te
+    '\u{1D1B}': 't', // small capital T
+    '\u{433}': 'r', // Cyrillic ghe
+    '\u{280}': 'r', // small capital R
+    '\u{455}': 's', // Cyrillic dze
+    '\u{A731}': 's', // small capital S
+    '\u{435}': 'e', // Cyrillic ie
+    '\u{3B5}': 'e', // Greek epsilon
+    '\u{1D07}': 'e', // small capital E
+    '\u{501}': 'd', // Cyrillic komi de
+    '\u{1D05}': 'd', // small capital D
+    '\u{441}': 'c', // Cyrillic es
+    '\u{3F2}': 'c', // Greek lunate sigma
+    '\u{1D04}': 'c', // small capital C
+    '\u{43E}': 'o', // Cyrillic o
+    '\u{3BF}': 'o', // Greek omicron
+    '\u{3C3}': 'o', // Greek sigma
+    '\u{1D0F}': 'o', // small capital O
+};
+/**
+ * Characters that render as nothing or only change the one before them,
+ * dropped from the shadow copy: default ignorable code points (invisible
+ * formatting characters, tag characters U+E0000 to U+E007F, and the
+ * variation selectors, including the supplementary U+E0100 to U+E01EF and
+ * the Mongolian U+180B to U+180F) and combining marks.
+ */
+const STRIPPED = /[\p{Default_Ignorable_Code_Point}\p{M}]/u;
+/** The name in the shadow copy: the two words with any punctuation, spaces or controls between. */
+const NAME_IN_SHADOW = /untrusted[\p{P}\p{Z}\p{Cc}\s]*content/gu;
+/** What may sit between a bracket and the name: spaces, controls and the stripped characters. */
+const GAP = /[\s\p{Cc}\p{Default_Ignorable_Code_Point}\p{M}]/u;
+/** Slashes and their look-alikes. */
+const SLASH = /[/\\\u{2044}\u{2215}\u{29F8}\u{2571}\u{FF0F}\u{FF3C}\u{27CB}]/u;
+/**
+ * Opening angle brackets and their look-alikes. Compatibility forms (＜, ﹤,
+ * 〈, ...) are found through their shadow (NFKD, marks dropped).
+ */
+const OPENERS = new Set([
+    '<',
+    '\u{2C2}', // ˂ modifier letter left arrowhead
+    '\u{2039}', // ‹ single left-pointing angle quotation mark
+    '\u{3008}', // 〈 CJK left angle bracket (and U+2329 through NFKD)
+    '\u{27E8}', // ⟨ mathematical left angle bracket
+    '\u{27EA}', // ⟪ mathematical left double angle bracket
+    '\u{276C}', // ❬ medium left-pointing angle bracket ornament
+    '\u{276E}', // ❮ heavy left-pointing angle quotation mark ornament
+    '\u{2770}', // ❰ heavy left-pointing angle bracket ornament
+    '\u{29FC}', // ⧼ left-pointing curved angle bracket
+    '\u{2991}', // ⦑ left angle bracket with dot
+    '\u{2993}', // ⦓ left arc less-than bracket
+    '\u{227A}', // ≺ precedes
+    '\u{1438}', // ᐸ Canadian syllabics pa
+]);
+/** Closing angle brackets and their look-alikes, as OPENERS. */
+const CLOSERS = new Set([
+    '>',
+    '\u{2C3}', // ˃
+    '\u{203A}', // ›
+    '\u{3009}', // 〉 (and U+232A through NFKD)
+    '\u{27E9}', // ⟩
+    '\u{27EB}', // ⟫
+    '\u{276D}', // ❭
+    '\u{276F}', // ❯
+    '\u{2771}', // ❱
+    '\u{29FD}', // ⧽
+    '\u{2992}', // ⦒
+    '\u{2994}', // ⦔
+    '\u{227B}', // ≻ succeeds
+    '\u{1433}', // ᐳ Canadian syllabics po
+]);
+/** `&lt;` as an HTML entity, ending at the end of the string. */
+const OPEN_ENTITY = /&(?:lt|#0*60|#x0*3c);$/i;
+/** `&gt;` as an HTML entity, at the start of the string. */
+const CLOSE_ENTITY = /^&(?:gt|#0*62|#x0*3e);/i;
+/** How far back or ahead an entity can reach, in UTF-16 units. */
+const ENTITY_REACH = 16;
+/** What the name can be glued to as the end of a word, path, URL or anchor (not a tag). */
+const WORDLIKE = /[\p{L}\p{N}#/.\-_~%+=?&@:]/u;
+/** Characters an attribute name or an unquoted value can't contain (besides gaps and brackets). */
+const NOT_IN_ATTRIBUTE = /["'`=<>]/;
+// eslint-disable-next-line no-control-regex -- ASCII is the fast path
+const ASCII_ONLY = /^[\u0000-\u007F]*$/;
+/** What one code point contributes to the shadow copy. */
+function shadowOf(ch, cache) {
+    const cached = cache.get(ch);
+    if (cached !== undefined)
+        return cached;
+    let out = '';
+    if (!STRIPPED.test(ch)) {
+        for (const c of ch.normalize('NFKD').toLowerCase()) {
+            if (STRIPPED.test(c))
+                continue;
+            out += LOOK_ALIKES[c] ?? c;
+        }
+    }
+    cache.set(ch, out);
+    return out;
+}
+/** Where the name appears in `text`, as [start, end) spans of `text`, in order. */
+function nameSpans(text, cache) {
+    const spans = [];
+    if (ASCII_ONLY.test(text)) {
+        // One shadow character per character: the indexes are the same.
+        for (const m of text.toLowerCase().matchAll(NAME_IN_SHADOW)) {
+            spans.push([m.index, m.index + m[0].length]);
+        }
+        return spans;
+    }
+    // The shadow copy: NFKD, lower case, without invisible characters and
+    // marks, look-alikes folded to Latin. Each of its UTF-16 units remembers
+    // the code point of `text` it came from (start and length).
+    let shadow = '';
+    const from = [];
+    const size = [];
+    for (let i = 0; i < text.length;) {
+        const cp = text.codePointAt(i) ?? 0;
+        const len = cp > 0xffff ? 2 : 1;
+        const piece = cp < 0x80 ? text.charAt(i).toLowerCase() : shadowOf(text.slice(i, i + len), cache);
+        shadow += piece;
+        for (let k = 0; k < piece.length; k++) {
+            from.push(i);
+            size.push(len);
+        }
+        i += len;
+    }
+    for (const m of shadow.matchAll(NAME_IN_SHADOW)) {
+        const last = m.index + m[0].length - 1;
+        spans.push([from[m.index] ?? 0, (from[last] ?? 0) + (size[last] ?? 1)]);
+    }
+    return spans;
+}
+/** The code point that ends just before `index`, and its length in UTF-16 units. */
+function before(text, index) {
+    if (index <= 0)
+        return undefined;
+    const low = text.charCodeAt(index - 1);
+    if (index >= 2 && low >= 0xdc00 && low <= 0xdfff) {
+        const high = text.charCodeAt(index - 2);
+        if (high >= 0xd800 && high <= 0xdbff)
+            return { ch: text.slice(index - 2, index), len: 2 };
+    }
+    return { ch: text.charAt(index - 1), len: 1 };
+}
+/** The code point that starts at `index`. */
+function at(text, index) {
+    const cp = text.codePointAt(index);
+    return cp === undefined ? '' : String.fromCodePoint(cp);
+}
+function isBracket(ch, set, cache) {
+    return set.has(ch) || (ch.charCodeAt(0) > 0x7f && set.has(shadowOf(ch, cache)));
+}
+/** Skips gap characters from `index`; the index after them. */
+function skipGap(text, index) {
+    let i = index;
+    while (i < text.length) {
+        const ch = at(text, i);
+        if (!GAP.test(ch))
+            break;
+        i += ch.length;
+    }
+    return i;
+}
+/** Skips a run of characters that may make up an attribute name or an unquoted value. */
+function skipAttributeRun(text, index, cache, slashes) {
+    let i = index;
+    while (i < text.length) {
+        const ch = at(text, i);
+        if (GAP.test(ch) || NOT_IN_ATTRIBUTE.test(ch))
+            break;
+        if (!slashes && SLASH.test(ch))
+            break;
+        if (isBracket(ch, CLOSERS, cache) || isBracket(ch, OPENERS, cache))
+            break;
+        i += ch.length;
+    }
+    return i;
+}
+/**
+ * Whether the name that ends at `end` is followed by the rest of a tag: a
+ * closing bracket (or `&gt;`), right after it or after attributes
+ * (`key="value"`, `key='value'` or `key=value`, each after a space), with an
+ * optional slash before the bracket. A space and a bracket with no attribute
+ * between, as in "Settings > untrusted_content > Ids", is prose. `memo`
+ * keeps the answer for each state the scan passes (a position, and whether
+ * an attribute came before it), so that scans from many names share their
+ * work and the whole is linear.
+ */
+function closesTag(text, end, cache, memo) {
+    const isCloserAt = (i) => i < text.length &&
+        (isBracket(at(text, i), CLOSERS, cache) || CLOSE_ENTITY.test(text.slice(i, i + ENTITY_REACH)));
+    const path = [];
+    let answer = false;
+    let i = end;
+    let attributes = false;
+    for (;;) {
+        const state = 2 * i + (attributes ? 1 : 0);
+        const known = memo.get(state);
+        if (known !== undefined) {
+            answer = known;
+            break;
+        }
+        path.push(state);
+        let k = skipGap(text, i);
+        if (k >= text.length)
+            break;
+        const spaced = /\s/.test(text.slice(i, k));
+        const ch = at(text, k);
+        if (attributes || !spaced) {
+            if (isCloserAt(k)) {
+                answer = true;
+                break;
+            }
+            if (SLASH.test(ch)) {
+                answer = isCloserAt(skipGap(text, k + ch.length));
+                break;
+            }
+        }
+        // An attribute, after at least one space.
+        if (k === i)
+            break;
+        const nameEnd = skipAttributeRun(text, k, cache, false);
+        if (nameEnd === k)
+            break;
+        k = skipGap(text, nameEnd);
+        if (text.charAt(k) !== '=')
+            break;
+        k = skipGap(text, k + 1);
+        const quote = text.charAt(k);
+        if (quote === '"' || quote === "'") {
+            const close = text.indexOf(quote, k + 1);
+            if (close < 0)
+                break;
+            i = close + 1;
+        }
+        else {
+            const valueEnd = skipAttributeRun(text, k, cache, true);
+            if (valueEnd === k)
+                break;
+            i = valueEnd;
+        }
+        attributes = true;
+    }
+    for (const state of path)
+        memo.set(state, answer);
+    return answer;
+}
+/**
+ * Defuses every place in `text` where the block's name could form a tag that
+ * opens or closes an untrusted_content block, and leaves all other text as
+ * it is, so that prose and Markdown that mention the name (in backticks,
+ * bold, headings, links, quotes, paths and so on) come back byte for byte.
+ *
+ * The name is found in any case, with any punctuation or spaces between its
+ * two words, in full-width, mathematical or other compatibility forms, with
+ * Cyrillic or Greek look-alike letters, and with invisible characters,
+ * combining marks or variation selectors anywhere in it: in a shadow copy of
+ * the text (NFKD, lower case, those characters dropped, look-alikes folded
+ * to Latin), mapped back.
+ *
+ * It could form a tag when, after optional spaces, invisible characters and
+ * one optional slash (or look-alike), an opening angle bracket stands before
+ * it: `<`, a look-alike (˂, 〈, ‹, ⟨, ...) or a compatibility form of one
+ * (＜, ﹤, ...). That bracket becomes `[`, so `</untrusted_content>` reads as
+ * `[/untrusted_content>`: still legible, no longer a tag. When `&lt;` stands
+ * there instead, or the name (not glued to a word, path, URL or anchor) is
+ * followed by the rest of a tag (`>`, a look-alike or `&gt;`, right after it
+ * or after attributes; see closesTag), `[` goes just before the name. A
+ * name right after `[` is already
+ * defused and stays as it is, so running this again changes nothing.
+ *
+ * This is a second line of defence: the first is the block id, which text
+ * written before the call can't know. Linear in the length of the text.
+ */
+export function neutralize(text) {
+    if (text.length < 'untrustedcontent'.length)
+        return text;
+    const cache = new Map();
+    const spans = nameSpans(text, cache);
+    if (spans.length === 0)
+        return text;
+    const memo = new Map();
+    // Edits by position: replace the character there (of this width) with "[", or insert "[".
+    const edits = new Map();
+    for (const [start, end] of spans) {
+        let j = start;
+        let slash = false;
+        for (;;) {
+            const prev = before(text, j);
+            if (prev === undefined)
+                break;
+            if (GAP.test(prev.ch)) {
+                j -= prev.len;
+            }
+            else if (!slash && SLASH.test(prev.ch)) {
+                slash = true;
+                j -= prev.len;
+            }
+            else {
+                break;
+            }
+        }
+        const opener = before(text, j);
+        if (opener?.ch === '[')
+            continue;
+        if (opener !== undefined && isBracket(opener.ch, OPENERS, cache)) {
+            edits.set(j - opener.len, opener.len);
+            continue;
+        }
+        if (OPEN_ENTITY.test(text.slice(Math.max(0, j - ENTITY_REACH), j))) {
+            edits.set(start, 0);
+            continue;
+        }
+        // Glued (no space) to the end of a word, path, URL or anchor: not a tag of the name.
+        let glued = before(text, start);
+        if (glued !== undefined && SLASH.test(glued.ch))
+            glued = before(text, start - glued.len);
+        if (glued !== undefined && WORDLIKE.test(glued.ch))
+            continue;
+        if (closesTag(text, end, cache, memo))
+            edits.set(start, 0);
+    }
+    let out = '';
+    let last = 0;
+    for (const pos of [...edits.keys()].sort((a, b) => a - b)) {
+        if (pos < last)
+            continue;
+        out += text.slice(last, pos) + '[';
+        last = pos + (edits.get(pos) ?? 0);
+    }
+    return out + text.slice(last);
+}
+// ---------------------------------------------------------------------------
+// Wrapping
+// ---------------------------------------------------------------------------
+/** Cuts `text` to at most `max` characters without splitting a surrogate pair. */
+function cut(text, max) {
+    let end = Math.max(0, max);
+    const code = text.charCodeAt(end - 1);
+    if (code >= 0xd800 && code <= 0xdbff)
+        end -= 1;
+    return text.slice(0, end);
+}
+function attribute(value) {
+    const flat = neutralize(value)
+        // Control characters and line breaks would let a value spill out of its attribute line.
+        // eslint-disable-next-line no-control-regex -- stripping control characters is the point
+        .replace(/[\u0000-\u001F\u007F-\u009F\u{2028}\u{2029}]+/gu, ' ')
+        .trim();
+    return cut(flat, MAX_ATTRIBUTE_CHARS)
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+/** The opening tag of a block with this id and these attributes. */
+function openTag(id, options) {
+    const attrs = [`id="${id}"`, `source="${attribute(options.source)}"`];
+    if (options.author !== undefined && options.author !== '') {
+        attrs.push(`author="${attribute(options.author)}"`);
+    }
+    for (const [key, value] of Object.entries(options.attributes ?? {})) {
+        if (value === undefined || value === null || value === '')
+            continue;
+        if (!ATTRIBUTE_NAME.test(key) || key === 'id' || key === 'source' || key === 'author') {
+            throw new Error(`Bad untrusted_content attribute name: ${key}`);
+        }
+        attrs.push(`${key}="${attribute(value)}"`);
+    }
+    return `<${UNTRUSTED_TAG} ${attrs.join(' ')}>`;
+}
+/**
+ * Wraps people-written text for an agent. Long text is cut, and a note
+ * outside the block (so it is the server speaking, not the author) says how
+ * much was cut and how to read the rest.
+ */
+export function wrapUntrusted(text, options) {
+    const max = options.maxChars ?? DEFAULT_MAX_CHARS;
+    const truncated = text.length > max;
+    const body = neutralize(truncated ? cut(text, max) : text);
+    const id = currentBlockId();
+    let out = `${openTag(id, options)}\n${body}\n</${UNTRUSTED_TAG} id="${id}">`;
+    if (truncated) {
+        out += `\n[Cut at ${max} of ${text.length} characters. ${options.moreHint ?? DEFAULT_MORE_HINT}]`;
+    }
+    return out;
+}
+/**
+ * Flattens a short people-written label (a person's, project's or org's
+ * name) to one defused line of at most `maxChars` characters. In text
+ * output, labels go inside a block (wrapLines in the tools); free text
+ * (titles, descriptions, comments, pages, messages) uses wrapUntrusted.
+ */
+export function sanitizeLabel(text, maxChars = 200) {
+    const flat = neutralize(text)
+        // eslint-disable-next-line no-control-regex -- stripping control characters is the point
+        .replace(/[\u0000-\u001F\u007F-\u009F\u{2028}\u{2029}]+/gu, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return flat.length > maxChars ? cut(flat, maxChars - 1) + '…' : flat;
+}

package/dist/version.js

@@ -0,0 +1,28 @@
+import { readFileSync } from 'node:fs';
+/** The server's name, as reported to MCP clients and in the User-Agent header. */
+export const SERVER_NAME = 'buildit-mcp';
+function readVersion() {
+    // Both src/ (tests) and dist/ (the built server) sit one level below package.json.
+    const raw = readFileSync(new URL('../package.json', import.meta.url), 'utf8');
+    const parsed = JSON.parse(raw);
+    return typeof parsed.version === 'string' ? parsed.version : '0.0.0';
+}
+/** The server's own version, from package.json. */
+export const SERVER_VERSION = readVersion();
+/** Compares dotted numeric versions ("1.2.10" > "1.2.9"); pre-release tags are ignored. */
+export function compareVersions(a, b) {
+    const parts = (v) => v
+        .replace(/^v/, '')
+        .split(/[-+]/, 1)
+        .join('')
+        .split('.')
+        .map((p) => Number.parseInt(p, 10) || 0);
+    const pa = parts(a);
+    const pb = parts(b);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0)
+            return d < 0 ? -1 : 1;
+    }
+    return 0;
+}

package/package.json

@@ -1,6 +1,77 @@
 {
   "name": "@kammcs/buildit-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "MCP server for buildIt.Social: lets AI agents work with an org's projects, pages and channels through the buildIt.Social agent API, with a personal access token.",
+  "license": "MIT",
+  "author": "Kamm Creative Solutions",
+  "homepage": "https://github.com/kammcs/buildit-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kammcs/buildit-mcp.git"
+  },
+  "bugs": "https://github.com/kammcs/buildit-mcp/issues",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "buildit",
+    "agents"
+  ],
+  "mcpName": "io.github.kammcs/buildit-mcp",
+  "type": "module",
+  "bin": {
+    "buildit-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node scripts/clean.mjs && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "lint": "tsc -p tsconfig.json --noEmit && eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "check": "npm run lint && npm run format:check && npm run build && npm run test && npm run privacy:pack",
+    "inspect": "npm run build && tsx scripts/inspect.ts",
+    "inspect:docker": "npm run build && docker build -t buildit-mcp:inspect . && tsx scripts/inspect.ts --image buildit-mcp:inspect",
+    "image:publish": "tsx scripts/publish-image.ts",
+    "bundle": "npm run build && tsx scripts/bundle.ts",
+    "conformance": "npm run build && tsx scripts/conformance.ts",
+    "generate": "tsx scripts/generate.ts",
+    "privacy": "tsx scripts/privacy.ts",
+    "prepublishOnly": "npm run check",
+    "privacy:pack": "tsx scripts/privacy.ts --pack"
+  },
+  "dependencies": {
+    "@hono/node-server": "2.1.3",
+    "@modelcontextprotocol/hono": "2.0.2",
+    "@modelcontextprotocol/server": "2.3.1",
+    "hono": "4.13.13",
+    "zod": "4.6.5"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@modelcontextprotocol/client": "2.3.1",
+    "@modelcontextprotocol/conformance": "0.2.0-alpha.12",
+    "@modelcontextprotocol/inspector": "2.11.0",
+    "@types/node": "22.20.5",
+    "eslint": "10.12.0",
+    "eslint-config-prettier": "10.1.8",
+    "globals": "17.13.0",
+    "prettier": "3.9.9",
+    "tsx": "4.23.15",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.71.1",
+    "vitest": "5.0.3"
+  }
+}