logomarks 0.0.0-stage → 1.0.0

package/src/mcp/inputs.js

@@ -0,0 +1,122 @@
+/**
+ * @module logomarks/mcp/inputs
+ *
+ * The inputs the tools share: their schemas (zod, which the server turns
+ * into JSON Schema for the caller), and reading them: a mark, a colour, the
+ * marks to check, the mark an edit starts from, and where to write. Relative paths resolve against the
+ * server's working folder (the project the agent is in).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { fitMark } from '@logomarks/core/fit';
+import { PLATFORMS, STYLE_IDS } from '@logomarks/brand-kit';
+import { loadMark } from '../brand/mark.js';
+import { parseColor } from '../util/color.js';
+import { FONTS } from '../brand/fonts.js';
+import { expandSvgs, slugOf } from '../util/files.js';
+
+/** The schemas the tools share. */
+export const schema = {
+	mark: z.string().min(1).describe('The mark: a live slug ("hex-gem") or name ("Hex Gem") from find_marks, or the path to your own .svg file (fitted to the 512 grid first).'),
+	color: z.string().optional().describe('The brand colour as hex, e.g. "#ff5c3a". Default "#d4ff3a" (the Logomarks lime).'),
+	font: z.enum(/** @type {[string, ...string[]]} */ (Object.keys(FONTS))).optional().describe('The typeface for the brand name (all SIL OFL). Defaults to inter.'),
+	name: z.string().optional().describe("The brand's name, set beside the mark. Defaults to the mark's name."),
+	svg: z.string().optional().describe('One mark as SVG text. Use this or paths.'),
+	svgName: z.string().optional().describe('A name for the svg (its slug), shown in the results. Defaults to "mark".'),
+	paths: z.array(z.string()).optional().describe('.svg files or folders of them (not recursive). Use this or svg.'),
+	ignore: z.array(z.string()).optional().describe('Finding ids to leave out, e.g. ["uneven-gaps"].'),
+	strict: z.boolean().optional().describe('Count warnings as failures too. Default false.'),
+	seed: z.string().optional().describe('Drives every random choice; the same seed gives the same image. Defaults to the mark\'s slug.'),
+	source: z.string().optional().describe('The mark: a live slug or name, or the path to an .svg file. Use this or svg.'),
+	sourceSvg: z.string().optional().describe('The mark as SVG text (fitted to the 512 grid first). Use this or mark.'),
+	out: z.string().optional().describe('Also write the result here (.svg); the result then gives the path instead of the SVG text. Relative to the working folder; an existing file is replaced.'),
+	tagline: z.string().optional().describe('A short line under the name on social images and the brand sheet.'),
+	url: z.string().optional().describe("The brand's website, for the brand sheet and the email signature."),
+	handle: z.string().optional().describe('The social handle, e.g. "@hexalabs". Defaults to @ and the name.'),
+	platforms: z.array(z.string()).optional().describe(`Social images by id or platform name (default every one): ${Object.keys(PLATFORMS).join(', ')}; or ${[...new Set(Object.values(PLATFORMS).map((p) => p.platform))].join(', ')}.`),
+	styles: z.array(z.enum(/** @type {[import('@logomarks/brand-kit').StyleId, ...import('@logomarks/brand-kit').StyleId[]]} */ ([...STYLE_IDS]))).optional().describe('minimal (the logo on paper), bold (the brand colour edge to edge, the mark cropped large), pattern (the mark repeated), gradient (a grainy gradient of the brand colour; only when asked for). Default the first three.'),
+	animated: z.boolean().optional().describe('Also write animated SVGs for avatars, stories and banners. Default false.'),
+};
+
+/**
+ * A path, resolved against the working folder.
+ *
+ * @param {string} cwd The working folder.
+ * @param {string} p The path.
+ * @returns {string} The absolute path.
+ */
+export const resolvePath = (cwd, p) => path.resolve(cwd, p);
+
+/**
+ * A mark by slug, name or file (a relative file resolved against the working folder).
+ *
+ * @param {string} ref The reference.
+ * @param {string} cwd The working folder.
+ * @returns {import('../brand/mark.js').Mark} The mark.
+ * @throws {import('../brand/mark.js').MarkNotFound} When it is neither.
+ */
+export function readMark(ref, cwd) {
+	const file = resolvePath(cwd, ref);
+	return loadMark(fs.existsSync(file) ? file : ref);
+}
+
+/**
+ * A colour input.
+ *
+ * @param {string | undefined} value The value.
+ * @returns {string | undefined} `#RRGGBB`, or undefined when it wasn't given.
+ * @throws {Error} When it isn't a colour.
+ */
+export function readColor(value) {
+	if (value === undefined) return undefined;
+	const hex = parseColor(value);
+	if (!hex) throw new Error(`color takes a hex colour such as "#ff5c3a", not "${value}"`);
+	return hex;
+}
+
+/**
+ * The marks a check names: one as SVG text, or files and folders.
+ *
+ * @param {{ svg?: string, svgName?: string, paths?: string[] }} input The inputs.
+ * @param {string} cwd The working folder.
+ * @returns {import('./inputs.js').SvgInput[]} Each mark's name, file (absolute; none for text) and SVG.
+ * @throws {Error} When neither or both are given, a path is missing, or a folder has no SVGs.
+ */
+export function readSvgs({ svg, svgName, paths }, cwd) {
+	if (svg !== undefined && paths?.length) throw new Error('pass svg or paths, not both');
+	if (svg !== undefined) return [{ name: svgName?.trim() || 'mark', svg }];
+	if (!paths?.length) throw new Error('pass svg (the SVG text) or paths (.svg files or folders)');
+	const files = expandSvgs(paths.map((p) => resolvePath(cwd, p)));
+	if (!files.length) throw new Error(`no .svg files in ${paths.join(', ')}`);
+	return files.map((file) => ({ name: slugOf(file), file, svg: fs.readFileSync(file, 'utf8') }));
+}
+
+/**
+ * A mark as SVG from a live slug or name, an .svg path, or SVG text (fitted to the grid).
+ *
+ * @param {string} ref The reference, or the SVG itself.
+ * @param {string} cwd The working folder.
+ * @returns {{ name: string, svg: string }} Its name and SVG.
+ * @throws {import('../brand/mark.js').MarkNotFound} When it is none of them.
+ */
+export function readAnyMark(ref, cwd) {
+	if (ref.trimStart().startsWith('<')) return { name: 'mark', svg: fitMark(ref).svg };
+	const m = readMark(ref, cwd);
+	return { name: m.slug, svg: m.svg };
+}
+
+/**
+ * The mark an edit starts from: a live mark or file (`mark`), or SVG text (`svg`).
+ *
+ * @param {{ mark?: string, svg?: string }} input The inputs.
+ * @param {string} cwd The working folder.
+ * @returns {{ name: string, svg: string }} Its name and SVG, fitted.
+ * @throws {Error} When neither or both are given.
+ */
+export function readSource({ mark, svg }, cwd) {
+	if (mark !== undefined && svg !== undefined) throw new Error('pass mark or svg, not both');
+	if (mark === undefined && svg === undefined) throw new Error('pass mark (a live slug or name, or an .svg path) or svg (the SVG text)');
+	return mark !== undefined ? readAnyMark(mark, cwd) : { name: 'mark', svg: fitMark(/** @type {string} */ (svg)).svg };
+}

package/src/mcp/preview.d.ts

@@ -0,0 +1,4 @@
+/** The longest side of an image handed back, in pixels: 800. */
+export const PREVIEW: number;
+/** The PNG itself when its longest side is within `PREVIEW`, else the SVG drawn again to it. */
+export function preview(img: { png: Uint8Array; svg: string; width: number; height: number }): Promise<Uint8Array>;

package/src/mcp/preview.js

@@ -0,0 +1,24 @@
+/**
+ * @module logomarks/mcp/preview
+ *
+ * The image a tool hands back to look at: no larger than it needs to be.
+ * Mockups and covers carry textures and gradients, so a full-size PNG runs
+ * to megabytes; the agent gets a preview, and the file gets the full size.
+ */
+
+import { render } from '../raster/render.js';
+
+/** The longest side of an image handed back, in pixels. */
+export const PREVIEW = 800;
+
+/**
+ * An image to hand back: the PNG itself when it is small enough, else the SVG drawn again with its longest side at `PREVIEW`.
+ *
+ * @param {{ png: Uint8Array, svg: string, width: number, height: number }} img The image and its SVG.
+ * @returns {Promise<Uint8Array>} The PNG to return.
+ */
+export async function preview({ png, svg, width, height }) {
+	const longest = Math.max(width, height);
+	if (longest <= PREVIEW) return png;
+	return /** @type {Uint8Array} */ ((await render(svg, { width: Math.round((width * PREVIEW) / longest), text: true, png: true })).png);
+}

package/src/mcp/tools/check.d.ts

@@ -0,0 +1,15 @@
+import type { Tool } from '../index.js';
+
+/** `check_mark`'s arguments: `svg` text or `paths`. */
+export interface CheckInput {
+	svg?: string;
+	svgName?: string;
+	paths?: string[];
+	/** Refit to the grid (files in place; text returned). */
+	fix?: boolean;
+	strict?: boolean;
+	ignore?: string[];
+}
+
+/** `check_mark`: every house rule, findings as JSON. */
+export const tool: Tool<CheckInput>;

package/src/mcp/tools/check.js

@@ -0,0 +1,47 @@
+/**
+ * @module logomarks/mcp/tools/check
+ *
+ * `check_mark`: every house rule on one SVG or a folder of them, with
+ * finding ids, messages and boxes; and the safe refit, when asked.
+ */
+
+import fs from 'node:fs';
+import { z } from 'zod';
+import { check, fix } from '../../checks/index.js';
+import { schema, readSvgs } from '../inputs.js';
+import { result, text } from '../content.js';
+
+/** @type {import('../index.js').Tool<import('./check.js').CheckInput>} */
+export const tool = {
+	name: 'check_mark',
+	title: 'Check a mark against the house rules',
+	description: [
+		'Check SVG logomarks against the house rules; use it on every mark you draw or edit, because reading SVG code can\'t show these.',
+		'Errors: viewbox, size, centre, clipped (fit to the 512 canvas, longest side 448, centred: fix=true refits), markup (filled paths only), empty, speck, sliver, pinhole (stray pieces and holes under 60 / 30 sq units, each with its box).',
+		'Warnings: fill (currentColor), precision (one decimal), thin and narrow-gap (under 10 units: lost at 32 px), uneven-gaps (keep one gap, 22, or a clear 1:2).',
+		'Returns { ok, passed, failed, marks: [{ name, ok, errors, warnings, size, findings: [{ id, severity, message, box }] }] }.',
+		'Fix every error, read every warning, then run similar_marks and review_sheet. Re-check until ok.',
+	].join(' '),
+	inputSchema: {
+		svg: schema.svg,
+		svgName: schema.svgName,
+		paths: schema.paths,
+		fix: z.boolean().optional().describe('Refit to the grid (the only automatic fix): files in paths are rewritten in place; for svg text the refitted SVG is returned. Default false.'),
+		strict: schema.strict,
+		ignore: schema.ignore,
+	},
+	annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+	async run({ svg, svgName, paths, fix: refit = false, strict = false, ignore = [] }, { cwd }) {
+		const marks = readSvgs({ svg, svgName, paths }, cwd).map(({ name, file, svg: source }) => {
+			let report = check(source, { name, ignore, strict });
+			const fitted = refit ? fix(source, report) : null;
+			if (fitted) {
+				if (file) fs.writeFileSync(file, fitted);
+				report = check(fitted, { name, ignore, strict });
+			}
+			return { name, ...(file && { file }), fixed: Boolean(fitted), ...report, ...(fitted && !file && { svg: fitted }) };
+		});
+		const failed = marks.filter((m) => !m.ok).length;
+		return result(text({ ok: !failed, passed: marks.length - failed, failed, marks }));
+	},
+};

package/src/mcp/tools/combine.d.ts

@@ -0,0 +1,15 @@
+import type { Tool } from '../index.js';
+import type { CombineOp, Placement } from '../../edit/combine.js';
+
+/** `combine_marks`'s arguments. */
+export interface CombineInput {
+	/** A live slug or name, an .svg path, or SVG text. */
+	a: string;
+	b: string;
+	op: CombineOp;
+	transform?: Placement;
+	out?: string;
+}
+
+/** `combine_marks`: two marks made one, fitted, checked and shown. */
+export const tool: Tool<CombineInput>;

package/src/mcp/tools/combine.js

@@ -0,0 +1,42 @@
+/**
+ * @module logomarks/mcp/tools/combine
+ *
+ * `combine_marks`: two marks made one, fitted and checked.
+ */
+
+import { z } from 'zod';
+import { combineMarks, COMBINE_OPS } from '../../edit/combine.js';
+import { readAnyMark, schema } from '../inputs.js';
+import { edited } from '../edited.js';
+
+/** A mark, by any means. */
+const markRef = z.string().min(1);
+
+/** @type {import('../index.js').Tool<import('./combine.js').CombineInput>} */
+export const tool = {
+	name: 'combine_marks',
+	title: 'Combine two marks',
+	description: [
+		'Combine two marks into one with the vector editor’s booleans (curves kept): union, subtract (b cut out of a), intersect, exclude (where exactly one covers), or place (both, as they are).',
+		'b is placed on a’s 512 canvas first: transform scales and turns it about its own centre, flips it, then moves it by x, y units. Both are fitted to the grid first, so scale 0.5 makes b half a’s size.',
+		'Returns { ok, svg (512 canvas, longest side 448, centred; the file path instead with out), checks } and the result as an image.',
+	].join(' '),
+	inputSchema: {
+		a: markRef.describe('The first mark: a live slug or name, an .svg path, or SVG text.'),
+		b: markRef.describe('The second, the same ways.'),
+		op: z.enum(/** @type {[import('../../edit/combine.js').CombineOp, ...import('../../edit/combine.js').CombineOp[]]} */ ([...COMBINE_OPS])).describe(`How to combine them: ${COMBINE_OPS.join(', ')}.`),
+		transform: z.object({
+			scale: z.number().positive().optional().describe('Scale b about its own centre. Default 1.'),
+			rotate: z.number().optional().describe('Turn b clockwise about its own centre, in degrees. Default 0.'),
+			flip: z.enum(['horizontal', 'vertical']).optional().describe('Flip b. Default: no flip.'),
+			x: z.number().optional().describe('Move b across, in units. Default 0.'),
+			y: z.number().optional().describe('Move b down, in units. Default 0.'),
+		}).optional().describe('Where b goes over a. Default: centred, as it is.'),
+		out: schema.out,
+	},
+	annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+	async run({ a, b, op, transform, out }, { cwd }) {
+		const [first, second] = [readAnyMark(a, cwd), readAnyMark(b, cwd)];
+		return edited(combineMarks(first.svg, second.svg, { op, transform, name: `${first.name}-${op}-${second.name}` }), { out, cwd });
+	},
+};

package/src/mcp/tools/cover.d.ts

@@ -0,0 +1,20 @@
+import type { Tool } from '../index.js';
+
+/** `render_cover`'s arguments. */
+export interface CoverInput {
+	mark: string;
+	/** One of `RECIPES`. */
+	recipe?: string;
+	title?: string;
+	label?: string;
+	color?: string;
+	/** `og`, `w:h` or a number. */
+	aspect?: string;
+	width?: number;
+	seed?: string;
+	/** Also write it here (.png or .svg). */
+	out?: string;
+}
+
+/** `render_cover`: a cover with the mark on it, as an image. */
+export const tool: Tool<CoverInput>;

package/src/mcp/tools/cover.js

@@ -0,0 +1,46 @@
+/**
+ * @module logomarks/mcp/tools/cover
+ *
+ * `render_cover`: a cover or social image with the mark on it, as an image;
+ * written to a file when asked.
+ */
+
+import { z } from 'zod';
+import { cover, RECIPES } from '../../cover/index.js';
+import { writeFile } from '../../util/files.js';
+import { schema, readMark, readColor, resolvePath } from '../inputs.js';
+import { result, text, image } from '../content.js';
+import { preview, PREVIEW } from '../preview.js';
+
+/** Each recipe and what it looks like, for the description. */
+const recipes = Object.entries(RECIPES).map(([k, r]) => `${k} (${r.about.replace(/\.$/, '')})`).join('; ');
+
+/** @type {import('../index.js').Tool<import('./cover.js').CoverInput>} */
+export const tool = {
+	name: 'render_cover',
+	title: 'Render a cover image',
+	description: [
+		'Draw a cover with the mark on it and return the image; use it for an Open Graph image, a blog or launch header, or a square post.',
+		`Recipes: ${recipes}.`,
+		`Returns a preview up to ${PREVIEW} px; pass out to write the full-size file (.png, or .svg with the text as outlines).`,
+	].join(' '),
+	inputSchema: {
+		mark: schema.mark,
+		recipe: z.enum(/** @type {[string, ...string[]]} */ (Object.keys(RECIPES))).optional().describe(`The look: ${Object.keys(RECIPES).join(', ')}. Default mark.`),
+		title: z.string().optional().describe('A headline; the mark moves out of its way.'),
+		label: z.string().optional().describe('A small line over the title.'),
+		color: schema.color,
+		aspect: z.string().regex(/^(og|\d+(\.\d+)?(:\d+(\.\d+)?)?)$/, 'og, w:h (16:9) or a number').optional().describe('og (1200×630, the default), 1:1, 16:9, 4:5, 9:16, any w:h, or a number.'),
+		width: z.number().int().min(200).max(6000).optional().describe("The written file's width in pixels. Default 1200."),
+		seed: schema.seed,
+		out: z.string().optional().describe('Also write the full-size file here: .png, or .svg (text as outlines). Relative to the working folder; an existing file is replaced.'),
+	},
+	annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+	async run({ mark: ref, recipe, title, label, color, aspect, width, seed, out }, { cwd }) {
+		const mark = readMark(ref, cwd);
+		const file = out && resolvePath(cwd, out);
+		const c = await cover({ mark, recipe, title, label, seed, color: readColor(color), aspect: aspect && /^[\d.]+$/.test(aspect) ? Number(aspect) : aspect, width: file ? width : Math.min(width ?? PREVIEW, PREVIEW) });
+		if (file) writeFile(file, file.toLowerCase().endsWith('.svg') ? c.svg : c.png);
+		return result(text({ recipe: recipe ?? 'mark', ...(file && { file, width: c.width, height: c.height }) }), image(await preview(c)));
+	},
+};

package/src/mcp/tools/edit.d.ts

@@ -0,0 +1,21 @@
+import type { Tool } from '../index.js';
+import type { EditOp } from '../../edit/ops.js';
+
+/** `edit_mark`'s arguments. */
+export interface EditInput {
+	mark?: string;
+	svg?: string;
+	ops: EditOp[];
+	out?: string;
+}
+
+/** `list_parts`'s arguments. */
+export interface PartsInput {
+	mark?: string;
+	svg?: string;
+}
+
+/** `edit_mark`: ops by part, run in order, the result fitted, checked and shown. */
+export const tool: Tool<EditInput>;
+/** `list_parts`: the parts by index, and an image of them numbered. */
+export const parts: Tool<PartsInput>;

package/src/mcp/tools/edit.js

@@ -0,0 +1,73 @@
+/**
+ * @module logomarks/mcp/tools/edit
+ *
+ * `edit_mark`: a list of edits by part, run in order, the result fitted and
+ * checked; and `list_parts`, the parts by index, to name them.
+ */
+
+import { z } from 'zod';
+import { editMark, markParts, OPS } from '../../edit/ops.js';
+import { partsPreview } from '../../edit/preview.js';
+import { schema, readSource } from '../inputs.js';
+import { edited } from '../edited.js';
+import { result, text, image } from '../content.js';
+
+/** A point on the 512 canvas. */
+const point = z.tuple([z.number(), z.number()]);
+
+/** One op. */
+const op = z.object({
+	op: z.enum(/** @type {[import('../../edit/ops.js').OpName, ...import('../../edit/ops.js').OpName[]]} */ (Object.keys(OPS))),
+	parts: z.array(z.number().int().min(0)).optional().describe('Part indices from list_parts, as they stand when this op runs (a delete renumbers what follows). Default every part.'),
+	dx: z.number().optional().describe('move: units across.'),
+	dy: z.number().optional().describe('move: units down.'),
+	angle: z.number().optional().describe('rotate: degrees, clockwise.'),
+	by: z.union([z.number().positive(), z.tuple([z.number().positive(), z.number().positive()])]).optional().describe('scale: a factor, or [sx, sy].'),
+	about: point.optional().describe('rotate, scale, flip: the point to turn about, on the 512 canvas. Default the parts’ centre.'),
+	axis: z.enum(['horizontal', 'vertical', 'both']).optional().describe('flip: horizontal (left to right) or vertical. mirror: vertical (left matches right; the default), horizontal or both.'),
+	radius: z.number().min(0).optional().describe('round: the corner radius in units.'),
+	distance: z.number().optional().describe('offset: units to grow (positive) or shrink (negative).'),
+	join: z.enum(['miter', 'round']).optional().describe('offset: sharp corners (miter, the default) or round.'),
+	count: z.number().int().min(2).max(24).optional().describe('radial: copies about the centre (4).'),
+	color: z.string().optional().describe('color, tone: hex.'),
+});
+
+/** @type {import('../index.js').Tool<import('./edit.js').EditInput>} */
+export const tool = {
+	name: 'edit_mark',
+	title: 'Edit a mark',
+	description: [
+		'Edit a mark by part with a list of ops, run in order (the vector editor’s own operations: curves kept, booleans exact). Use it to change a live mark or fix one you drew.',
+		`Ops: ${Object.entries(OPS).map(([k, v]) => `${k} (${v.about})`).join('; ')}.`,
+		'Call list_parts first to see each part’s index, box and area. Example: [{"op":"delete","parts":[3]},{"op":"round","radius":12},{"op":"mirror","axis":"vertical"}].',
+		'Returns { ok, parts (after), svg (512 canvas, longest side 448, centred; the file path instead with out), checks } and the result as an image. Fix any speck, sliver or gap the checks report.',
+	].join(' '),
+	inputSchema: {
+		mark: schema.source,
+		svg: schema.sourceSvg,
+		ops: z.array(op).min(1).describe('The edits, in order.'),
+		out: schema.out,
+	},
+	annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+	async run({ mark, svg, ops, out }, { cwd }) {
+		const source = readSource({ mark, svg }, cwd);
+		return edited(editMark(source.svg, ops, { name: source.name }), { out, cwd });
+	},
+};
+
+/** @type {import('../index.js').Tool<import('./edit.js').PartsInput>} */
+export const parts = {
+	name: 'list_parts',
+	title: 'List a mark’s parts',
+	description: [
+		'List a mark’s parts by index in drawing order; call it before edit_mark, whose ops name parts by these indices. Each part has its box [x0, y0, x1, y1] and centre on the 512 canvas, its area (holes taken out), its holes and its tone.',
+		'Returns { count, parts } and an image of the mark with every part boxed and numbered.',
+	].join(' '),
+	inputSchema: { mark: schema.source, svg: schema.sourceSvg },
+	annotations: { readOnlyHint: true, openWorldHint: false },
+	async run({ mark, svg }, { cwd }) {
+		const source = readSource({ mark, svg }, cwd);
+		const list = markParts(source.svg);
+		return result(text({ count: list.length, parts: list }), image(await partsPreview(source.svg, list)));
+	},
+};

package/src/mcp/tools/find.d.ts

@@ -0,0 +1,14 @@
+import type { Tool } from '../index.js';
+
+/** `find_marks`'s arguments. */
+export interface FindInput {
+	query?: string;
+	style?: string;
+	tags?: string[];
+	industry?: string;
+	letter?: string;
+	limit?: number;
+}
+
+/** `find_marks`: search the live set by words and filters (no arguments: the filters' values). */
+export const tool: Tool<FindInput>;

package/src/mcp/tools/find.js

@@ -0,0 +1,36 @@
+/**
+ * @module logomarks/mcp/tools/find
+ *
+ * `find_marks`: search the bundled live set by words and filters.
+ */
+
+import { z } from 'zod';
+import { findMarks, facets, DEFAULT_LIMIT } from '../../find/index.js';
+import { result, text } from '../content.js';
+
+/** @type {import('../index.js').Tool<import('./find.js').FindInput>} */
+export const tool = {
+	name: 'find_marks',
+	title: 'Find live Logomarks',
+	description: [
+		'Search the free Logomarks set (geometric logomarks, CC0, bundled offline): use it first when someone needs a logo, icon or brand mark, or a mark to build on.',
+		'Search works as on logomarks.ai: every word must be found in a mark (its name, search words, industries, style, tags, mood, letter or description), trades by their UK and US names too ("solicitor" finds the lawyers\' marks); the best fits come first. Filler words (a, for, logo) are ignored.',
+		'Filters narrow it exactly. Call with no arguments to list every style, tag, mood and industry with its count.',
+		'Returns { total, marks: [{ slug, name, style, description, url … }] }: pass a slug to get_mark, build_brand_kit, render_mockup or render_cover.',
+	].join(' '),
+	inputSchema: {
+		query: z.string().optional().describe('Free words: what it should look like or be for, e.g. "fox", "calm hexagon", "coffee", "letter k".'),
+		style: z.string().optional().describe('One style, e.g. letter, badge, monogram, iso, line, grid, glitch, animal, bold, modular, woven, inflated. Call with no arguments for every style.'),
+		tags: z.array(z.string()).optional().describe('Tags a mark must all have: round, square, symmetric, radial, solid, light, wide, tall, letter, number, new.'),
+		industry: z.string().optional().describe('An industry it suits, e.g. coffee, fintech, ai, law-firm, real-estate, fitness, music.'),
+		letter: z.string().max(2).optional().describe('The letter or number a letter mark shows, e.g. "K" or "7".'),
+		limit: z.number().int().min(1).max(100).optional().describe(`How many marks to return. Default ${DEFAULT_LIMIT}.`),
+	},
+	annotations: { readOnlyHint: true, openWorldHint: false },
+	async run({ query, style, tags, industry, letter, limit }) {
+		if (!query && !style && !tags?.length && !industry && !letter) return result(text({ facets: facets() }));
+		const found = findMarks(query, { style, tags, industry, letter, limit });
+		if (!found.total) return result(text({ ...found, hint: 'Nothing matched: try fewer or broader words, or call find_marks with no arguments to see the styles, tags and industries.' }));
+		return result(text(found));
+	},
+};

package/src/mcp/tools/get.d.ts

@@ -0,0 +1,15 @@
+import type { Tool } from '../index.js';
+
+/** `get_mark`'s arguments. */
+export interface GetInput {
+	/** A live slug or name, or an .svg path. */
+	mark: string;
+	color?: string;
+	/** Also return a PNG this many pixels square. */
+	size?: number;
+	/** Write the mark here (.svg or .png). */
+	out?: string;
+}
+
+/** `get_mark`: a mark's SVG, and a PNG to look at when asked. */
+export const tool: Tool<GetInput>;

package/src/mcp/tools/get.js

@@ -0,0 +1,44 @@
+/**
+ * @module logomarks/mcp/tools/get
+ *
+ * `get_mark`: a mark's SVG, painted in a colour, or a PNG to look at; and
+ * written to a file when asked.
+ */
+
+import { z } from 'zod';
+import { paint, markPng, MARK_URL } from '../../brand/mark.js';
+import { writeFile } from '../../util/files.js';
+import { schema, readMark, readColor, resolvePath } from '../inputs.js';
+import { result, text, image } from '../content.js';
+
+/** A PNG's side when a .png is written without one. */
+const PNG_SIZE = 512;
+
+/** @type {import('../index.js').Tool<import('./get.js').GetInput>} */
+export const tool = {
+	name: 'get_mark',
+	title: 'Get a mark',
+	description: [
+		'Get a mark to use: a live Logomark by slug or name (CC0, free to use), or your own .svg fitted to the 512 grid.',
+		'The SVG is 512×512, longest side 448, centred, filled paths in currentColor (or in color, when given).',
+		'Pass size to also get a PNG image to look at. Pass out to write the file (.svg, or .png at size, default 512); the result then gives its path instead of the SVG text.',
+		'Returns { slug, name, url, licence, color, svg | file }.',
+	].join(' '),
+	inputSchema: {
+		mark: schema.mark,
+		color: z.string().optional().describe('Paint it in this hex colour, e.g. "#ff5c3a". Default: currentColor (the SVG) or black (a PNG).'),
+		size: z.number().int().min(16).max(4096).optional().describe('Also return a PNG this many pixels square (16–4096), to look at. Default: none.'),
+		out: z.string().optional().describe('Write the mark here: .svg, or .png (at size, default 512). Relative to the working folder; an existing file is replaced.'),
+	},
+	annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+	async run({ mark: ref, color: c, size, out }, { cwd }) {
+		const mark = readMark(ref, cwd);
+		const color = readColor(c);
+		const svg = paint(mark.svg, color);
+		const png = size || out?.toLowerCase().endsWith('.png') ? await markPng(mark.svg, { size: size ?? PNG_SIZE, color: color ?? '#000000' }) : null;
+		const file = out && resolvePath(cwd, out);
+		if (file) writeFile(file, file.toLowerCase().endsWith('.png') ? /** @type {Uint8Array} */ (png) : svg);
+		const about = { slug: mark.slug, name: mark.name, ...(mark.live ? { url: MARK_URL + mark.slug, licence: 'CC0-1.0' } : { live: false }), color: color ?? 'currentColor', ...(file && { file }) };
+		return result(text(file ? about : { ...about, svg }), ...(png && size ? [image(png)] : []));
+	},
+};

package/src/mcp/tools/glitch.d.ts

@@ -0,0 +1,12 @@
+import type { Tool } from '../index.js';
+import type { GlitchOptions } from '../../edit/glitch.js';
+
+/** `glitch_mark`'s arguments: the mark (`mark` or `svg`), the preset and its settings, and where to write it. */
+export interface GlitchInput extends Omit<GlitchOptions, 'name'> {
+	mark?: string;
+	svg?: string;
+	out?: string;
+}
+
+/** `glitch_mark`: a glitch edition, fitted and checked, and its image. */
+export const tool: Tool<GlitchInput>;

package/src/mcp/tools/glitch.js

@@ -0,0 +1,39 @@
+/**
+ * @module logomarks/mcp/tools/glitch
+ *
+ * `glitch_mark`: a glitch edition of a mark, fitted and checked.
+ */
+
+import { z } from 'zod';
+import { glitchMark, PRESETS, PRESET_ABOUT } from '../../edit/glitch.js';
+import { schema, readSource } from '../inputs.js';
+import { edited } from '../edited.js';
+
+/** @type {import('../index.js').Tool<import('./glitch.js').GlitchInput>} */
+export const tool = {
+	name: 'glitch_mark',
+	title: 'Glitch a mark',
+	description: [
+		'Make a glitch edition of a mark: cut with the house gap (22) and the pieces slid, as the Logomarks glitch editions are. Use it to make a live mark more your own.',
+		`Presets: ${Object.entries(PRESET_ABOUT).map(([k, v]) => `${k} (${v})`).join('; ')}.`,
+		'A seed places the cuts: the same seed gives the same SVG, byte for byte; another seed is a shuffle. A placement that would leave a speck or a sliver is nudged, then reseeded; when none is clean the call fails, so try another seed.',
+		'Returns { ok, glitch, svg (512 canvas, longest side 448, centred; the file path instead with out), checks } and the result as an image: look at it.',
+	].join(' '),
+	inputSchema: {
+		mark: schema.source,
+		svg: schema.sourceSvg,
+		preset: z.enum(/** @type {[import('../../edit/glitch.js').GlitchPreset, ...import('../../edit/glitch.js').GlitchPreset[]]} */ (Object.keys(PRESETS))).describe(`The kind of glitch: ${Object.keys(PRESETS).join(', ')}.`),
+		angle: z.number().min(-180).max(180).optional().describe('The cut direction in degrees, clockwise from across. Default: the mark’s own slope (shear), across the lanes (lane), else 0.'),
+		place: z.number().min(0).max(1).optional().describe('Where the first cut crosses, 0–1 across the mark. Default: seeded.'),
+		slide: z.number().min(0).max(200).optional().describe('How far the sides slide apart along the cut, in units; a band’s largest nudge. Default 44 (twice the gap).'),
+		gap: z.number().min(4).max(80).optional().describe('The gap at each cut, in units. Default 22 (the house gap).'),
+		cuts: z.number().int().min(1).max(5).optional().describe('Cuts for slice (1–3), bands for bands (3–5). Default: seeded.'),
+		seed: z.number().int().min(0).optional().describe('Places the cuts: the same seed gives the same SVG, another is a shuffle. Default 1.'),
+		out: schema.out,
+	},
+	annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+	async run({ mark, svg, out, ...o }, { cwd }) {
+		const source = readSource({ mark, svg }, cwd);
+		return edited(glitchMark(source.svg, { ...o, name: source.name }), { out, cwd });
+	},
+};

package/src/mcp/tools/index.d.ts

@@ -0,0 +1,4 @@
+import type { Tool } from '../index.js';
+
+/** The tools, in order: find, get, check, similar, sheet; list_parts, glitch, edit, combine; build_brand_kit, build_social_pack, render_mockup, render_cover. */
+export const TOOLS: Tool<never>[];

package/src/mcp/tools/index.js

@@ -0,0 +1,23 @@
+/**
+ * @module logomarks/mcp/tools
+ *
+ * Every tool the MCP server offers, in the order an agent uses them: find
+ * and get a mark; check, compare and look at one it drew; edit it (glitch,
+ * edit by part, combine); build on it.
+ */
+
+import { tool as find } from './find.js';
+import { tool as get } from './get.js';
+import { tool as check } from './check.js';
+import { tool as similar } from './similar.js';
+import { tool as sheet } from './sheet.js';
+import { tool as glitch } from './glitch.js';
+import { tool as edit, parts } from './edit.js';
+import { tool as combine } from './combine.js';
+import { tool as kit } from './kit.js';
+import { tool as social } from './social.js';
+import { tool as mockup } from './mockup.js';
+import { tool as cover } from './cover.js';
+
+/** The tools, in order. */
+export const TOOLS = [find, get, check, similar, sheet, parts, glitch, edit, combine, kit, social, mockup, cover];