@kammcs/buildit-mcp 0.0.0-stage → 0.2.0

package/dist/tools/shared.js

@@ -0,0 +1,462 @@
+/**
+ * Shapes and helpers shared by the item and comment tools.
+ *
+ * Every tool returns structured content (matching its outputSchema) and a
+ * short markdown summary. People-written text is never passed through as is:
+ *
+ * - short labels (names of people, the org, tokens, projects, channels,
+ *   statuses, types, labels, fields, sprints, releases, and item titles in
+ *   structured content) go through sanitizeLabel: one line, defused, capped
+ *   (PERSON_NAME_CHARS for people, NAME_CHARS for other names);
+ * - free text (descriptions, comments, search snippets, history values) goes
+ *   through wrapUntrusted, in structured content and in the text;
+ * - in the text, every label is inside an <untrusted_content> block too: a
+ *   list is one block (wrapLines), and the names of one thing are a block of
+ *   their own, so the server's own words are all that stands outside.
+ */
+import { z } from 'zod';
+import { OPERATIONS, PLAN_SCOPES, } from '../api/generated/operations.js';
+import { ToolInputError } from '../errors.js';
+import { sanitizeLabel, wrapUntrusted } from '../untrusted.js';
+import { compareVersions } from '../version.js';
+// ---------------------------------------------------------------------------
+// Scopes and annotations from the contract
+// ---------------------------------------------------------------------------
+/**
+ * Every scope the given operations need, from the contract's
+ * x-buildit-required-scopes (or x-buildit-scope where that is absent): a
+ * tool needs all of them. Plan operations (create_plan, apply_plan) take
+ * the scopes of the plan's action: pass the actions to planScopesOf instead.
+ */
+export function scopesOf(...ids) {
+    const out = new Set();
+    for (const id of ids) {
+        if (OPERATIONS[id].scope === 'plan_action') {
+            throw new Error(`${id} takes its plan action's scopes; use planScopesOf`);
+        }
+        for (const scope of OPERATIONS[id].requiredScopes)
+            out.add(scope);
+    }
+    return [...out];
+}
+/**
+ * Whether the API is at least `version`: true or false when /v1/meta has
+ * said (stdio reads it at startup), undefined when it hasn't (the API then
+ * answers for itself).
+ */
+export function apiAtLeast(api, version) {
+    const known = api.served?.apiVersion;
+    return known === undefined ? undefined : compareVersions(known, version) >= 0;
+}
+/** Refuses `what` when the API is known to be older than `version`. */
+export function requireApi(api, version, what) {
+    if (apiAtLeast(api, version) === false) {
+        throw new ToolInputError(`${what} needs buildIt.Social's agent API ${version} or newer, and this server runs ${api.served?.apiVersion ?? 'an older one'}. Leave it out; the person's buildIt.Social server needs an update for it.`);
+    }
+}
+/** Every scope the given plan actions need, from the contract's x-buildit-plan-required-scopes. */
+export function planScopesOf(...actions) {
+    return [...new Set(actions.flatMap((a) => PLAN_SCOPES[a]))];
+}
+// ---------------------------------------------------------------------------
+// Input fields
+// ---------------------------------------------------------------------------
+const ITEM_REF_RE = /^(#?[A-Za-z][A-Za-z0-9]{1,5}-[1-9][0-9]{0,8}|[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12})$/;
+export const ItemRefInput = z
+    .string()
+    .regex(ITEM_REF_RE, 'An item key such as DEMO-12, or an item uuid.')
+    .describe('An item key such as DEMO-12 (any case, a leading # is fine) or the item uuid.');
+export const ProjectKeyInput = z
+    .string()
+    .regex(/^[A-Za-z][A-Za-z0-9]{1,5}$/, 'A project key such as DEMO.')
+    .describe('A project key such as DEMO (any case). whoami and list_projects list them.');
+export const UserRefInput = z
+    .string()
+    .min(1)
+    .max(320)
+    .describe('A person: "me", an email, or an exact display name, among the project\'s members (find_users lists them).');
+/**
+ * How images and their layout are written in descriptions and pages (the
+ * contract's MarkdownDescription and PageBody), for the input fields.
+ */
+export const IMAGE_LAYOUT_NOTE = 'Images: ![alt](file:<id> "40% wrap-left gap-m"); an optional title sets the layout: width 10%-100% in steps of 5, left|center|right|wrap-left|wrap-right, gap-s|gap-m|gap-l.';
+/** The reminder for fields that rewrite Markdown. */
+export const KEEP_IMAGE_TITLES = 'Keep image titles (layouts) as read.';
+export const IdempotencyKeyInput = z
+    .uuid()
+    .describe('A random uuid you choose. Sending the same call again with it returns the first result instead of creating twice. If you leave it out, one is generated and returned, so you can retry safely with it.');
+export const CursorInput = z
+    .string()
+    .min(1)
+    .max(2048)
+    .describe('The next_cursor of the previous page, to read the next one (same other arguments).');
+export const limitInput = (max, def) => z.number().int().min(1).max(max).optional().describe(`Page size, 1 to ${max} (default ${def}).`);
+/** Removes a leading # from an item key, keeps uuids as they are. */
+export function itemRef(ref) {
+    return ref.startsWith('#') ? ref.slice(1) : ref;
+}
+// ---------------------------------------------------------------------------
+// Output shapes
+// ---------------------------------------------------------------------------
+/** The longest a person's display name is shown, in characters. */
+export const PERSON_NAME_CHARS = 64;
+/** The longest any other name is shown: the org, a token, project, channel, sprint, release, status, type, field or option. */
+export const NAME_CHARS = 60;
+const label = (value, max = 200) => sanitizeLabel(value, max);
+const nullableLabel = (value, max = 200) => value === null || value === undefined || value === '' ? null : sanitizeLabel(value, max);
+/** A person-written name other than a person's, flattened and capped (null stays null). */
+export const nameLabel = (value) => nullableLabel(value, NAME_CHARS);
+export const PersonSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    email: z.string().nullable(),
+});
+export function person(u) {
+    return {
+        id: u.id,
+        name: label(u.display_name, PERSON_NAME_CHARS),
+        email: nullableLabel(u.email, 320),
+    };
+}
+export function personText(p) {
+    if (p === null)
+        return 'nobody';
+    return p.email ? `${p.name} <${p.email}>` : p.name;
+}
+export const ItemOutSchema = z.object({
+    key: z.string(),
+    id: z.string(),
+    title: z.string().describe('People-written; flattened to one defused line.'),
+    project: z.string(),
+    type: z.string(),
+    level: z.string().describe('epic, standard or subtask.'),
+    status: z.string(),
+    status_category: z.string().describe('not_started, started, done or canceled.'),
+    priority: z.string(),
+    assignee: PersonSchema.nullable(),
+    parent: z.string().nullable().describe("The parent's key."),
+    labels: z.array(z.string()),
+    estimate: z.number().nullable(),
+    sprint: z.string().nullable(),
+    fix_release: z.string().nullable(),
+    start_date: z.string().nullable(),
+    due_date: z.string().nullable(),
+    updated_at: z.string(),
+    version: z.number().describe('Send as if_version to update_item or transition_item.'),
+    description_version: z.number().describe('Send with description_replace to update_item.'),
+});
+export function itemOut(i) {
+    return {
+        key: i.key,
+        id: i.id,
+        title: label(i.title, 300),
+        project: i.project.key,
+        type: label(i.type.name, 60),
+        level: i.type.level,
+        status: label(i.status.name, 60),
+        status_category: i.status.category,
+        priority: i.priority,
+        assignee: i.assignee ? person(i.assignee) : null,
+        parent: i.parent?.key ?? null,
+        labels: i.labels.map((l) => label(l.name, 40)),
+        estimate: i.estimate,
+        sprint: nameLabel(i.sprint?.name),
+        fix_release: nameLabel(i.fix_release?.name),
+        start_date: i.start_date,
+        due_date: i.due_date,
+        updated_at: i.updated_at,
+        version: i.version,
+        description_version: i.description_version,
+    };
+}
+export const CustomOutSchema = z.object({
+    field: z.string(),
+    kind: z.string(),
+    value: z.unknown().describe('Text and url values are wrapped as untrusted content.'),
+});
+function customValue(c) {
+    const v = c.value;
+    if (typeof v === 'string') {
+        return c.kind === 'text' || c.kind === 'url'
+            ? wrapUntrusted(v, { source: 'field', maxChars: 2000 })
+            : label(v, NAME_CHARS);
+    }
+    if (Array.isArray(v)) {
+        return v.map((x) => (typeof x === 'string' ? label(x, NAME_CHARS) : person(x)));
+    }
+    if (typeof v === 'object')
+        return person(v);
+    return v;
+}
+export function customOut(c) {
+    return { field: label(c.field, NAME_CHARS), kind: c.kind, value: customValue(c) };
+}
+/**
+ * A custom field as one line for the text output, to go inside a block
+ * with the item's other fields: text values flattened and cut (the
+ * structured content has them whole, wrapped).
+ */
+export function customLine(c) {
+    const v = c.value;
+    let value;
+    if (typeof v === 'string') {
+        value = label(v, c.kind === 'text' || c.kind === 'url' ? 500 : NAME_CHARS);
+    }
+    else if (Array.isArray(v)) {
+        value =
+            v
+                .map((x) => typeof x === 'string' ? label(x, NAME_CHARS) : label(x.display_name, PERSON_NAME_CHARS))
+                .join(', ') || 'none';
+    }
+    else if (typeof v === 'object') {
+        value = label(v.display_name, PERSON_NAME_CHARS);
+    }
+    else {
+        value = String(v);
+    }
+    return `- ${label(c.field, NAME_CHARS)} (${c.kind}): ${value}`;
+}
+export const ItemFullSchema = ItemOutSchema.extend({
+    reporter: PersonSchema.nullable(),
+    initiative: z.string().nullable(),
+    rank: z.string(),
+    created_at: z.string(),
+    started_at: z.string().nullable(),
+    completed_at: z.string().nullable(),
+    canceled_at: z.string().nullable(),
+    description: z
+        .string()
+        .describe('Markdown, wrapped as untrusted content; empty when the item has none.'),
+    description_truncated: z
+        .boolean()
+        .describe('True when the description was cut; ask get_item with detail="full".'),
+    custom: z.array(CustomOutSchema),
+});
+/**
+ * An item with its description, cut at `maxDescription` characters. In full
+ * mode the API has sent everything, so a cut can't be read further here.
+ */
+export function itemFull(i, maxDescription, full = false, 
+/** What the note on a cut description says to do, in place of the default. */
+moreHint) {
+    const cut = i.description.length > maxDescription;
+    return {
+        ...itemOut(i),
+        reporter: i.reporter ? person(i.reporter) : null,
+        initiative: i.initiative?.key ?? null,
+        rank: i.rank,
+        created_at: i.created_at,
+        started_at: i.started_at,
+        completed_at: i.completed_at,
+        canceled_at: i.canceled_at,
+        // No description stays empty rather than becoming an empty block.
+        description: i.description.trim() === ''
+            ? ''
+            : wrapUntrusted(i.description, {
+                source: 'description',
+                maxChars: maxDescription,
+                moreHint: moreHint ??
+                    (full
+                        ? 'The rest is too long to show here; the person can read it in buildIt.Social.'
+                        : `Call get_item with item="${i.key}" and detail="full" to read more.`),
+            }),
+        description_truncated: i.description_truncated || cut,
+        custom: i.custom.map(customOut),
+    };
+}
+export const SearchItemOutSchema = ItemOutSchema.extend({
+    match: z
+        .object({
+        score: z.number(),
+        title_highlight: z.string(),
+        snippet: z.string().nullable().describe('Wrapped as untrusted content.'),
+    })
+        .optional()
+        .describe('With a text query only.'),
+    description: z.string().optional().describe('With detail="full" only; wrapped, may be cut.'),
+    custom: z.array(CustomOutSchema).optional().describe('With detail="full" only.'),
+    link_counts: z
+        .object({
+        blocks: z.number(),
+        blocked_by: z.number(),
+        relates: z.number(),
+        duplicates: z.number(),
+        duplicated_by: z.number(),
+        blocked_by_open: z.number(),
+    })
+        .optional(),
+    activity_at: z.string().optional(),
+});
+export function searchItemOut(i, maxDescription) {
+    const out = itemOut(i);
+    if (i.match) {
+        out.match = {
+            score: i.match.score,
+            title_highlight: label(i.match.title_highlight, 400),
+            snippet: i.match.snippet === null
+                ? null
+                : wrapUntrusted(i.match.snippet, { source: 'snippet', maxChars: 500 }),
+        };
+    }
+    if (i.description !== undefined) {
+        out.description = wrapUntrusted(i.description, {
+            source: 'description',
+            maxChars: maxDescription,
+            moreHint: `Call get_item with item="${i.key}" and detail="full" to read all of it.`,
+        });
+    }
+    if (i.custom !== undefined)
+        out.custom = i.custom.map(customOut);
+    if (i.link_counts !== undefined) {
+        const c = i.link_counts;
+        out.link_counts = {
+            blocks: c.blocks,
+            blocked_by: c.blocked_by,
+            relates: c.relates,
+            duplicates: c.duplicates,
+            duplicated_by: c.duplicated_by,
+            blocked_by_open: c.blocked_by_open,
+        };
+    }
+    if (i.activity_at !== undefined)
+        out.activity_at = i.activity_at;
+    return out;
+}
+export const CommentOutSchema = z.object({
+    id: z.string(),
+    author: PersonSchema.nullable(),
+    body: z.string().describe('Plain text, wrapped as untrusted content.'),
+    mentions: z.array(z.string()).describe('Display names of the people mentioned.'),
+    created_at: z.string(),
+    edited_at: z.string().nullable(),
+    via_agent: z.string().nullable().describe('The token name, when an agent wrote it.'),
+});
+export function commentOut(c, maxChars, moreHint) {
+    const author = c.author ? person(c.author) : null;
+    const viaAgent = nameLabel(c.via_agent);
+    return {
+        id: c.id,
+        author,
+        // The author and the agent's token name are people-written too: they
+        // are attributes of the block, not words of the server.
+        body: wrapUntrusted(c.body, {
+            source: 'comment',
+            author: author?.name,
+            attributes: { via_agent: viaAgent },
+            maxChars,
+            ...(moreHint ? { moreHint } : {}),
+        }),
+        mentions: c.mentions.map((m) => label(m.display_name, PERSON_NAME_CHARS)),
+        created_at: c.created_at,
+        edited_at: c.edited_at,
+        via_agent: viaAgent,
+    };
+}
+/**
+ * A comment for the text output: a line of facts, then the wrapped body,
+ * whose tag names the author (and the agent, when one wrote it).
+ */
+export function commentText(c) {
+    const facts = [
+        c.created_at,
+        ...(c.author ? [] : ['unknown author']),
+        ...(c.via_agent ? ['written through an agent'] : []),
+        ...(c.edited_at ? [`edited ${c.edited_at}`] : []),
+        `id ${c.id}`,
+    ];
+    return `- ${facts.join(' · ')}\n${c.body}`;
+}
+export const LinkOutSchema = z.object({
+    id: z.string().describe('The link id (link_items with action="remove" can take it).'),
+    kind: z.string().describe('blocks, blocked_by, relates, duplicates or duplicated_by.'),
+    key: z.string().nullable().describe("The other item's key; null when it can't be seen."),
+    title: z.string().nullable(),
+    status: z.string().nullable(),
+});
+export function linkOut(l) {
+    return {
+        id: l.id,
+        kind: l.kind,
+        key: l.item?.key ?? null,
+        title: l.item ? label(l.item.title, 300) : null,
+        status: l.item ? label(l.item.status.name, NAME_CHARS) : null,
+    };
+}
+export const HistoryOutSchema = z.object({
+    at: z.string(),
+    actor: z.string().nullable(),
+    via_agent: z.string().nullable(),
+    kind: z.string(),
+    field: z.string().nullable(),
+    old: z
+        .string()
+        .nullable()
+        .describe('The old value as recorded (ids), wrapped as untrusted content.'),
+    new: z
+        .string()
+        .nullable()
+        .describe('The new value as recorded (ids), wrapped as untrusted content.'),
+    old_label: z
+        .string()
+        .nullable()
+        .describe('The old value as people read it now (names, keys), flattened to one line.'),
+    new_label: z
+        .string()
+        .nullable()
+        .describe('The new value as people read it now (names, keys), flattened to one line.'),
+});
+function historyValue(v) {
+    if (v === undefined || v === null)
+        return null;
+    const text = typeof v === 'string' ? v : JSON.stringify(v);
+    return wrapUntrusted(text, { source: 'history', maxChars: 500, moreHint: 'Read the item.' });
+}
+export function historyOut(h) {
+    return {
+        at: h.at,
+        actor: h.actor ? label(h.actor.display_name, PERSON_NAME_CHARS) : null,
+        via_agent: nameLabel(h.via_agent),
+        kind: h.kind,
+        field: nameLabel(h.field),
+        old: historyValue(h.old),
+        new: historyValue(h.new),
+        old_label: nullableLabel(h.old_label, 300),
+        new_label: nullableLabel(h.new_label, 300),
+    };
+}
+// ---------------------------------------------------------------------------
+// Text
+// ---------------------------------------------------------------------------
+/** One line about an item, for lists (it carries the title, so lists are wrapped). */
+export function itemLine(i) {
+    const parts = [
+        i.key,
+        i.type,
+        `${i.status} (${i.status_category})`,
+        ...(i.priority !== 'none' ? [i.priority] : []),
+        i.assignee ? `@${i.assignee.name}` : 'unassigned',
+        ...(i.estimate !== null ? [`est ${i.estimate}`] : []),
+        ...(i.parent ? [`parent ${i.parent}`] : []),
+        ...(i.sprint ? [i.sprint] : []),
+        ...(i.due_date ? [`due ${i.due_date}`] : []),
+        ...(i.labels.length > 0 ? [`labels ${i.labels.join(', ')}`] : []),
+    ];
+    return `${parts.join(' · ')} — ${i.title}`;
+}
+/**
+ * Lines inside one untrusted block, for text that carries people-written
+ * titles or names (a list, or the names of one thing). The lines must not
+ * hold blocks themselves: flatten free text into them instead.
+ */
+export function wrapLines(lines, source) {
+    return wrapUntrusted(lines.join('\n'), { source, maxChars: 100_000 });
+}
+/** The line that tells the agent how to read the next page. */
+export function nextPageHint(tool, cursor) {
+    return cursor === null
+        ? 'This is the last page.'
+        : [
+            `More results: call ${tool} again with the same arguments and this cursor:`,
+            sanitizeLabel(cursor, 2048),
+        ].join('\n');
+}

package/dist/tools/whoami.js

@@ -0,0 +1,230 @@
+/**
+ * whoami: who the token acts as, where, and with what reach.
+ */
+import { z } from 'zod';
+import { OPERATIONS } from '../api/generated/operations.js';
+import { defineTool } from '../toolsets/registry.js';
+import { expandScopes } from '../toolsets/toolsets.js';
+import { sanitizeLabel } from '../untrusted.js';
+import { compareVersions, SERVER_NAME, SERVER_VERSION } from '../version.js';
+import { NAME_CHARS, PERSON_NAME_CHARS, wrapLines } from './shared.js';
+const MAX_PROJECTS_IN_TEXT = 50;
+const OutputSchema = z.object({
+    user: z.object({
+        id: z.string(),
+        name: z.string().nullable(),
+        email: z.string().nullable(),
+    }),
+    org: z.object({
+        id: z.string(),
+        name: z.string().nullable(),
+        test: z
+            .boolean()
+            .nullable()
+            .describe('A test org (true); null when the API is older than 1.2.0.'),
+    }),
+    token: z.object({
+        name: z.string().nullable(),
+        expires_at: z.string().nullable(),
+    }),
+    scopes: z.array(z.string()).describe('As granted; a write scope also allows reading.'),
+    limits: z.object({
+        projects: z
+            .array(z.string())
+            .nullable()
+            .describe('Keys of the projects the token is limited to; null means every project.'),
+        channels: z
+            .array(z.string())
+            .nullable()
+            .describe('Names of the channels the token is limited to; null means every channel.'),
+    }),
+    projects: z.array(z.object({
+        key: z.string(),
+        name: z.string().nullable(),
+        id: z.string().nullable(),
+    })),
+    cannot: z.array(z.string()).describe("What the token can't do."),
+    features: z.object({
+        projects: z.boolean().describe('Whether Projects is enabled for the org.'),
+    }),
+    rate_limits: z.object({
+        requests_per_minute: z.number().describe("The token's requests a minute."),
+        user_requests_per_minute: z
+            .number()
+            .describe("The user's requests a minute, across all their tokens."),
+        writes_per_minute: z.number().describe("The token's writes a minute."),
+        writes_per_day: z.number().describe("The token's writes a day (UTC)."),
+        org_requests_per_minute: z
+            .number()
+            .describe("The org's requests a minute, across all its tokens."),
+    }),
+    server: z.object({
+        name: z.string(),
+        version: z.string(),
+        api_version: z.string().nullable(),
+        update_required: z.boolean(),
+        not_served: z
+            .array(z.string())
+            .nullable()
+            .describe("The contract's operations this API doesn't serve yet; null if it doesn't say."),
+    }),
+});
+/**
+ * What a token can't do, in words, from its scopes (with the ones they imply)
+ * and its limits. The API is the authority; this only tells the agent why a
+ * tool isn't listed, so it can tell the person instead of looking for one.
+ */
+export function cannotDo(scopes, limits) {
+    const has = expandScopes(scopes);
+    const out = [];
+    if (!has.has('projects:read'))
+        out.push('read projects or items (needs projects:read)');
+    if (!has.has('projects:write')) {
+        out.push(`change items, comments, sprints or releases (${has.has('projects:read') ? 'it can only read; ' : ''}needs projects:write)`);
+    }
+    if (!has.has('projects:delete'))
+        out.push('delete, move or bulk-edit items (needs projects:delete)');
+    if (!has.has('projects:admin')) {
+        out.push('create channels or projects, or change workflows, work types, fields or labels (needs projects:admin)');
+    }
+    else if ((limits.projects ?? null) !== null || (limits.channels ?? null) !== null) {
+        out.push('create channels or projects (the token is limited to some projects or channels; that needs a token without limits)');
+    }
+    if (!has.has('pages:read'))
+        out.push('read pages (needs pages:read)');
+    else if (!has.has('pages:write'))
+        out.push('create or edit pages (needs pages:write)');
+    if (!has.has('chat:read'))
+        out.push('read channel messages (needs chat:read)');
+    return out;
+}
+const nullableLabel = (v, max) => v === undefined || v === null || v === '' ? null : sanitizeLabel(v, max);
+export const whoamiTool = defineTool({
+    name: 'whoami',
+    toolset: 'items',
+    title: 'Who am I',
+    description: "Who the token acts as: the user, the org, the token's name, expiry, scopes and limits, what it can't do, and the projects in reach. Call it when you don't know the project keys, when no tool fits a task, or after an authorization error.",
+    scopes: [],
+    annotations: {
+        title: 'Who am I',
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    inputSchema: z.object({}),
+    outputSchema: OutputSchema,
+    async run(_args, ctx) {
+        const options = ctx.apiOptions;
+        const [me, meta] = await Promise.all([
+            ctx.api.getMe(options),
+            ctx.api.getMeta(options).catch((err) => {
+                ctx.logger.debug('meta unavailable', { error: err });
+                return undefined;
+            }),
+        ]);
+        const minVersion = meta?.min_mcp_version;
+        const updateRequired = minVersion !== undefined && compareVersions(SERVER_VERSION, minVersion) < 0;
+        const structured = {
+            user: {
+                id: me.user.id,
+                name: nullableLabel(me.user.display_name, PERSON_NAME_CHARS),
+                email: nullableLabel(me.user.email, 320),
+            },
+            org: {
+                id: me.org.id,
+                name: nullableLabel(me.org.name, NAME_CHARS),
+                test: me.org.test ?? null,
+            },
+            token: {
+                name: nullableLabel(me.token.name, NAME_CHARS),
+                expires_at: me.token.expires_at,
+            },
+            scopes: [...me.token.scopes].sort(),
+            limits: {
+                projects: me.token.limits.projects?.map((p) => sanitizeLabel(p.key, 40)) ?? null,
+                channels: me.token.limits.channels?.map((c) => sanitizeLabel(c.name, NAME_CHARS)) ?? null,
+            },
+            cannot: cannotDo(me.token.scopes, me.token.limits),
+            projects: me.projects.map((p) => ({
+                key: sanitizeLabel(p.key, 40),
+                name: nullableLabel(p.name, NAME_CHARS),
+                id: p.id,
+            })),
+            features: { projects: me.features.projects },
+            rate_limits: {
+                requests_per_minute: me.rate_limits.requests_per_minute,
+                user_requests_per_minute: me.rate_limits.user_requests_per_minute,
+                writes_per_minute: me.rate_limits.writes_per_minute,
+                writes_per_day: me.rate_limits.writes_per_day,
+                org_requests_per_minute: me.rate_limits.org_requests_per_minute,
+            },
+            server: {
+                name: SERVER_NAME,
+                version: SERVER_VERSION,
+                api_version: meta?.api_version ?? null,
+                update_required: updateRequired,
+                not_served: meta?.operations
+                    ? Object.keys(OPERATIONS)
+                        .filter((id) => !meta.operations?.includes(id))
+                        .sort()
+                    : null,
+            },
+        };
+        const s = structured;
+        // The names of the user, the org, the token, the projects and the
+        // channels were written by people: one block holds them all.
+        const names = [
+            `User: ${s.user.name ?? s.user.id}${s.user.email ? ` (${s.user.email})` : ''}`,
+            `Org: ${s.org.name ?? s.org.id}`,
+            ...(s.token.name ? [`Token: ${s.token.name}`] : []),
+        ];
+        if (s.projects.length > 0) {
+            const shown = s.projects
+                .slice(0, MAX_PROJECTS_IN_TEXT)
+                .map((p) => (p.name ? `${p.key} (${p.name})` : p.key));
+            names.push(`Projects in reach: ${shown.join(', ')}`);
+        }
+        if (s.limits.channels !== null && s.limits.channels.length > 0) {
+            names.push(`Channels the token is limited to: ${s.limits.channels.join(', ')}`);
+        }
+        const lines = [
+            `Signed in to buildIt.Social with a personal access token${s.token.expires_at ? ` (expires ${s.token.expires_at})` : ''}. Who and where, as people named them:`,
+            wrapLines(names, 'names'),
+            `Scopes: ${s.scopes.length > 0 ? s.scopes.join(', ') : 'none'}.`,
+            `Limits: ${s.limits.projects === null
+                ? 'all projects'
+                : `only the projects ${s.limits.projects.join(', ') || '(none)'}`}; ${s.limits.channels === null
+                ? 'all channels the user can see'
+                : s.limits.channels.length === 0
+                    ? 'no channels'
+                    : `only the ${s.limits.channels.length} channel(s) listed above, among those the user can see`}.`,
+        ];
+        if (s.org.test === true) {
+            lines.push('This org is a test org: its data may be wiped and seeded by test tools.');
+        }
+        if (s.cannot.length > 0) {
+            lines.push(`This token can't: ${s.cannot.join('; ')}.`);
+        }
+        if (!s.features.projects) {
+            lines.push('Projects is not enabled for this org: project and item tools will not work.');
+        }
+        if (s.projects.length === 0) {
+            lines.push('Projects in reach: none.');
+        }
+        else {
+            const more = s.projects.length > MAX_PROJECTS_IN_TEXT
+                ? ` (the first ${MAX_PROJECTS_IN_TEXT} listed above; the rest in the structured result)`
+                : ' (listed above)';
+            lines.push(`Projects in reach: ${s.projects.length}${more}.`);
+        }
+        const r = s.rate_limits;
+        lines.push(`Rate limits for this token: ${r.requests_per_minute} calls and ${r.writes_per_minute} writes a minute, ${r.writes_per_day} writes a day. For your account, across all your tokens: ${r.user_requests_per_minute} calls a minute. For the whole org: ${r.org_requests_per_minute} calls a minute.`);
+        if (s.server.not_served !== null && s.server.not_served.length > 0) {
+            lines.push(`This buildIt.Social server (API ${s.server.api_version ?? 'unknown'}) doesn't serve these operations yet, so calls that need them are refused until it is updated: ${s.server.not_served.join(', ')}.`);
+        }
+        if (updateRequired) {
+            lines.push(`This buildit-mcp (${SERVER_VERSION}) is older than the API supports (${minVersion} or newer). Ask the person to update it.`);
+        }
+        return { structured, text: lines.join('\n') };
+    },
+});