feishu-user-plugin 1.3.6 → 1.3.8

package/src/prompts/_registry.js

@@ -0,0 +1,69 @@
+// src/prompts/_registry.js — Load the 9 sub-skill markdown files as MCP prompt definitions.
+//
+// Reads from skills/feishu-user-plugin/references/ (whitelisted set).
+// For each file:
+//   - name: filename without .md
+//   - description: first non-empty line
+//   - arguments: [{name:'arguments', description, required:false}] if body contains $ARGUMENTS
+//   - body: full file content (used for substitution in getPrompt)
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const WHITELIST = new Set(['send', 'reply', 'digest', 'search', 'doc', 'table', 'wiki', 'drive', 'status']);
+const REFS_DIR = path.join(__dirname, '..', '..', 'skills', 'feishu-user-plugin', 'references');
+
+/**
+ * Parse $ARGUMENTS description from the ## 参数 section.
+ * Looks for a line matching "- $ARGUMENTS：<desc>" or "- $ARGUMENTS: <desc>".
+ * Returns the description text, or a generic fallback.
+ */
+function parseArgumentsDescription(body) {
+  const match = body.match(/\$ARGUMENTS[：:]\s*(.+)/);
+  if (match) {
+    return match[1].trim();
+  }
+  return 'Skill arguments';
+}
+
+/**
+ * Load all whitelisted sub-skill files and return prompt definitions.
+ * @returns {Array<{name: string, description: string, arguments?: Array, body: string}>}
+ */
+function loadAllSkills() {
+  const prompts = [];
+  for (const name of WHITELIST) {
+    const filePath = path.join(REFS_DIR, `${name}.md`);
+    let content;
+    try {
+      content = fs.readFileSync(filePath, 'utf8');
+    } catch (e) {
+      console.error(`[feishu-user-plugin] prompts: could not read ${filePath}: ${e.message}`);
+      continue;
+    }
+
+    // description = first non-empty line
+    const lines = content.split('\n');
+    const firstNonEmpty = lines.find((l) => l.trim() !== '');
+    const description = firstNonEmpty ? firstNonEmpty.trim() : name;
+
+    const hasArguments = content.includes('$ARGUMENTS');
+    const prompt = {
+      name,
+      description,
+      body: content,
+    };
+    if (hasArguments) {
+      const argDesc = parseArgumentsDescription(content);
+      prompt.arguments = [{ name: 'arguments', description: argDesc, required: false }];
+    }
+    prompts.push(prompt);
+  }
+  // Sort deterministically by name
+  prompts.sort((a, b) => a.name.localeCompare(b.name));
+  return prompts;
+}
+
+module.exports = { loadAllSkills };

package/src/prompts/index.js

@@ -0,0 +1,54 @@
+// src/prompts/index.js — MCP prompt registry: listPrompts + getPrompt.
+//
+// Loaded once at module load; cached for the lifetime of the server process.
+// listPrompts() → MCP prompts/list shaped array (no body exposed in listing).
+// getPrompt(name, args) → MCP prompts/get shaped result with $ARGUMENTS substituted.
+
+'use strict';
+
+const { loadAllSkills } = require('./_registry');
+
+// Cache all skills once at module load.
+const _skills = loadAllSkills();
+const _byName = new Map(_skills.map((s) => [s.name, s]));
+
+/**
+ * Returns the spec-shaped prompts array for prompts/list.
+ * Omits the body field; omits arguments if empty.
+ */
+function listPrompts() {
+  return _skills.map((s) => {
+    const p = { name: s.name, description: s.description };
+    if (s.arguments && s.arguments.length > 0) {
+      p.arguments = s.arguments;
+    }
+    return p;
+  });
+}
+
+/**
+ * Returns the prompts/get result for a given prompt name.
+ * Substitutes $ARGUMENTS in the body with args.arguments (or empty string).
+ * @param {string} name
+ * @param {object} args - e.g. { arguments: "Alice: hi" }
+ * @returns {{ description: string, messages: [{role: 'user', content: {type: 'text', text: string}}] }}
+ */
+function getPrompt(name, args = {}) {
+  const skill = _byName.get(name);
+  if (!skill) {
+    throw new Error(`Unknown prompt: ${name}`);
+  }
+  const argValue = args.arguments != null ? String(args.arguments) : '';
+  const text = skill.body.replace(/\$ARGUMENTS/g, argValue);
+  return {
+    description: skill.description,
+    messages: [
+      {
+        role: 'user',
+        content: { type: 'text', text },
+      },
+    ],
+  };
+}
+
+module.exports = { listPrompts, getPrompt };

package/src/server.js

@@ -0,0 +1,305 @@
+// src/server.js — MCP bootstrap, tool registration, request dispatch.
+//
+// What this owns:
+//   - Loading every src/tools/<domain>.js module and flattening its schemas.
+//   - Building the ctx object that handlers receive (factory closures + profile state).
+//   - The MCP Server instance and its ListTools / CallTool request handlers.
+//   - Startup diagnostics (auth status, APP_ID validation).
+//
+// What it does NOT own:
+//   - Tool definitions: those live in src/tools/<domain>.js.
+//   - Feishu API calls: those live in src/clients/{user,official}.
+//   - Auth lifecycle (cookie heartbeat, UAT refresh, file lock): src/auth/*.
+//   - Config discovery / persistence: src/config/*.
+
+const path = require('path');
+const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema } = require('@modelcontextprotocol/sdk/types.js');
+
+// Local dev fallback: MCP clients inject env vars from config's env block at
+// spawn time. This dotenv line only matters when running locally with a .env.
+require('dotenv').config({ path: path.join(__dirname, '..', '.env') });
+
+const { LarkUserClient } = require('./clients/user');
+const { LarkOfficialClient } = require('./clients/official');
+const { resolveToken } = require('./resolver');
+const { listPrompts, getPrompt } = require('./prompts');
+const credentials = require('./auth/credentials');
+const profileRouter = require('./auth/profile-router');
+
+// --- Tool modules ---
+// Adding a new domain: create src/tools/<x>.js exporting { schemas, handlers }
+// and append it here. The schemas are concatenated into the MCP tools/list
+// response; the handlers are looked up by name when tools/call comes in.
+const TOOL_MODULES = [
+  require('./tools/bitable'),
+  require('./tools/calendar'),
+  require('./tools/contacts'),
+  require('./tools/diagnostics'),
+  require('./tools/docs'),
+  require('./tools/drive'),
+  require('./tools/events'),
+  require('./tools/groups'),
+  require('./tools/im-read'),
+  require('./tools/messaging-bot'),
+  require('./tools/messaging-user'),
+  require('./tools/okr'),
+  require('./tools/profile'),
+  require('./tools/tasks'),
+  require('./tools/uploads'),
+  require('./tools/wiki'),
+];
+
+const TOOLS = TOOL_MODULES.flatMap((m) => m.schemas);
+const HANDLERS = Object.fromEntries(TOOL_MODULES.flatMap((m) => Object.entries(m.handlers)));
+
+// --- Profile system + client singletons ---
+// Profile resolution order (see src/auth/credentials.js):
+//   1. ~/.feishu-user-plugin/credentials.json — single source of truth (v1.3.7+)
+//   2. process.env.LARK_* — legacy default profile (v1.3.6 behaviour)
+//   3. process.env.LARK_PROFILES_JSON — legacy named profiles
+//
+// switch_profile (handler in tools/profile.js) calls ctx.setActiveProfile(n)
+// which resets the cached client singletons; the next tool call rebuilds them.
+// When credentials.json exists, switching also persists the active field so
+// cross-process MCP servers see the same active profile after restart.
+
+let userClient = null;
+let officialClient = null;
+let wsServer = null;
+function getEventBuffer() {
+  return wsServer ? wsServer.buffer : null;
+}
+// The "current" profile this in-memory MCP server is pinned to. Initialised
+// from the persisted active profile (credentials.json) at boot, but in-process
+// switches may diverge from the persisted active until the next server restart.
+//
+// Profile selection precedence (v1.3.8 E.1):
+//   1. process.env.FEISHU_PLUGIN_PROFILE — harness pointer
+//   2. credentials.json::active — single-file persisted active
+//   3. 'default' — legacy zero-config path
+let currentProfile = process.env.FEISHU_PLUGIN_PROFILE
+  || credentials.getActiveProfileName();
+
+function profileEnv(name) {
+  return credentials.getActiveProfileEnv(name);
+}
+
+async function getUserClient() {
+  if (userClient) return userClient;
+  const env = profileEnv(currentProfile);
+  const cookie = env.LARK_COOKIE;
+  if (!cookie) throw new Error(
+    `LARK_COOKIE not set for profile "${currentProfile}". To fix:\n` +
+    '1. Open https://www.feishu.cn/messenger/ and log in\n' +
+    '2. DevTools → Network tab → Disable cache → Reload → Click first request → Request Headers → Cookie → Copy value\n' +
+    '   (Do NOT use document.cookie or Application→Cookies — they miss HttpOnly cookies like session/sl_session)\n' +
+    '3. Paste the cookie string into your .mcp.json env LARK_COOKIE field, then restart Claude Code\n' +
+    'If Playwright MCP is available: navigate to feishu.cn/messenger/, let user log in, then use context.cookies() to get the full cookie string including HttpOnly cookies.'
+  );
+  userClient = new LarkUserClient(cookie);
+  await userClient.init();
+  return userClient;
+}
+
+function getOfficialClient() {
+  if (officialClient) return officialClient;
+  const env = profileEnv(currentProfile);
+  const appId = env.LARK_APP_ID;
+  const appSecret = env.LARK_APP_SECRET;
+  if (!appId || !appSecret) throw new Error(
+    `LARK_APP_ID and LARK_APP_SECRET not set for profile "${currentProfile}".\n` +
+    'For team members: these should be pre-filled in your .mcp.json. Check that the config was copied correctly from the team-skills README.\n' +
+    'For external users: create a Custom App at https://open.feishu.cn/app, get the App ID and App Secret, add them to your .mcp.json env.'
+  );
+  officialClient = new LarkOfficialClient(appId, appSecret);
+  // Load UAT directly from the active profile env. With credentials.json the
+  // env may differ from process.env (whose LARK_USER_* may be missing if the
+  // user moved creds out of harness configs); using profileEnv() here keeps
+  // the source of truth consistent with what get*Client() reads above.
+  loadUATFromEnv(officialClient, env);
+  return officialClient;
+}
+
+// Mirror of LarkOfficialClient.loadUAT() but sourced from a specific env block
+// instead of process.env, so credentials.json profiles work uniformly.
+function loadUATFromEnv(client, env) {
+  const token = env.LARK_USER_ACCESS_TOKEN;
+  const refresh = env.LARK_USER_REFRESH_TOKEN;
+  const expires = parseInt(env.LARK_UAT_EXPIRES || '0');
+  if (!token) return;
+  client._uat = token;
+  client._uatRefresh = refresh || null;
+  client._uatExpires = expires || client._decodeTokenExpiry(token);
+}
+
+// Resolver helper: turn document_id / app_token / wiki node / Feishu URL into
+// a native token. No-op for already-native inputs. See src/resolver.js.
+async function resolveDocId(input) {
+  if (!input) return input;
+  return resolveToken(input, getOfficialClient());
+}
+
+// --- ctx ---
+// What handlers receive in their second argument. Kept stable so tools/* don't
+// reach back into server.js for state. Adding a new ctx field: also document
+// it in src/tools/_registry.js docstring.
+function buildCtx() {
+  return {
+    getUserClient,
+    getOfficialClient,
+    getEventBuffer,
+    listProfiles: () => credentials.listProfileNames(),
+    getActiveProfile: () => currentProfile,
+    setActiveProfile: (n) => {
+      // Validate the profile exists (throws if unknown) before nuking client cache.
+      credentials.getActiveProfileEnv(n);
+      currentProfile = n;
+      userClient = null;
+      officialClient = null;
+      // Persist the active-field flip when credentials.json exists so peer MCP
+      // servers see the new active profile on next read. Tolerated when no file.
+      try { credentials.setActiveProfile(n); } catch (_) {}
+    },
+    resolveDocId,
+  };
+}
+
+// --- MCP server ---
+
+const server = new Server(
+  { name: 'feishu-user-plugin', version: require('../package.json').version },
+  { capabilities: { tools: {}, prompts: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  const handler = HANDLERS[name];
+  if (!handler) {
+    return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
+  }
+  // Strip via_profile from args before passing to the handler — it's a
+  // routing-layer concern, not a tool argument. Keep a copy for routing.
+  const cleanArgs = (args && typeof args === 'object') ? { ...args } : {};
+  delete cleanArgs.via_profile;
+
+  try {
+    return await profileRouter.withProfileRouting(buildCtx(), name, args || {}, async () => {
+      return handler(cleanArgs, buildCtx());
+    });
+  } catch (err) {
+    return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+  }
+});
+
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: listPrompts() }));
+
+server.setRequestHandler(GetPromptRequestSchema, async (req) => {
+  const { name, arguments: args } = req.params;
+  return getPrompt(name, args || {});
+});
+
+// --- Process-level error handlers ---
+// Prevent stray promise rejections or uncaught exceptions from killing the MCP server.
+process.on('uncaughtException', (err) => {
+  console.error('[feishu-user-plugin] Uncaught exception:', err.message);
+  console.error(err.stack);
+});
+process.on('unhandledRejection', (reason) => {
+  console.error('[feishu-user-plugin] Unhandled rejection:', reason);
+});
+process.on('SIGTERM', () => { try { wsServer?.stop(); } catch {} process.exit(0); });
+process.on('SIGINT',  () => { try { wsServer?.stop(); } catch {} process.exit(0); });
+
+// --- main ---
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  // Startup diagnostics — use the resolved active-profile env so users on
+  // credentials.json (where process.env may not have LARK_*) get accurate flags.
+  // If FEISHU_PLUGIN_PROFILE was set, validate the name exists. If not, fail
+  // loud — silently falling back to "default" would mask a typo'd harness env.
+  if (process.env.FEISHU_PLUGIN_PROFILE) {
+    const known = credentials.listProfileNames();
+    if (!known.includes(currentProfile)) {
+      console.error(`[feishu-user-plugin] FATAL: FEISHU_PLUGIN_PROFILE="${currentProfile}" not found. Known: ${known.join(', ')}.`);
+      console.error('[feishu-user-plugin] Fix: edit harness env block, or add the profile to ~/.feishu-user-plugin/credentials.json.');
+      process.exit(2);
+    }
+  }
+  let activeEnv = {};
+  try { activeEnv = profileEnv(currentProfile); } catch (_) { /* unknown profile is reported below */ }
+  const hasCanonical = !!credentials.readCanonical();
+  const hasCookie = !!activeEnv.LARK_COOKIE;
+  const hasApp = !!(activeEnv.LARK_APP_ID && activeEnv.LARK_APP_SECRET);
+  const hasUAT = !!activeEnv.LARK_USER_ACCESS_TOKEN;
+  const source = hasCanonical ? `credentials.json profile=${currentProfile}` : 'env vars (legacy)';
+  console.error(`[feishu-user-plugin] MCP Server v${require('../package.json').version} — ${TOOLS.length} tools, ${listPrompts().length} prompts`);
+  console.error(`[feishu-user-plugin] Auth: Cookie=${hasCookie ? 'YES' : 'NO'} App=${hasApp ? 'YES' : 'NO'} UAT=${hasUAT ? 'YES' : 'NO'} (source: ${source})`);
+  if (!hasCookie) console.error('[feishu-user-plugin] WARNING: LARK_COOKIE not set — user identity tools (send_to_user, etc.) will fail');
+  if (!hasApp) console.error('[feishu-user-plugin] WARNING: LARK_APP_ID/SECRET not set — official API tools (read_messages, docs, etc.) will fail');
+  if (!hasUAT) console.error('[feishu-user-plugin] WARNING: LARK_USER_ACCESS_TOKEN not set — P2P chat reading (read_p2p_messages) will fail');
+  // Warn when both credentials.json AND legacy env vars exist — they may
+  // diverge silently after a UAT refresh (we always write credentials.json).
+  if (hasCanonical && (process.env.LARK_COOKIE || process.env.LARK_APP_ID || process.env.LARK_USER_ACCESS_TOKEN)) {
+    console.error('[feishu-user-plugin] NOTE: credentials.json AND legacy LARK_* env vars are both set. Plugin reads credentials.json; the env vars are ignored. To clean up: remove the LARK_* keys from your harness config, leaving FEISHU_PLUGIN_PROFILE only.');
+  }
+  // Nudge legacy env-only users to migrate.
+  if (!hasCanonical && (hasCookie || hasApp || hasUAT)) {
+    console.error('[feishu-user-plugin] TIP: run `npx feishu-user-plugin migrate --confirm` to consolidate credentials into ~/.feishu-user-plugin/credentials.json (single source of truth, removes UAT-refresh drift across harnesses).');
+  }
+
+  // Validate APP_ID/SECRET against Feishu before serving any tool calls.
+  // Catches the "Claude filled in a wrong/stale APP_ID during install" failure
+  // mode that otherwise surfaces as cryptic 401s on every Official API call
+  // (looks like "MCP 掉线" to the user). Non-blocking — we warn but still serve,
+  // because the user may only need user-identity (cookie) tools.
+  if (hasApp) {
+    try {
+      const probe = await getOfficialClient().verifyApp();
+      if (probe.valid) {
+        const nameBit = probe.appName ? ` "${probe.appName}"` : '';
+        console.error(`[feishu-user-plugin] App verified: ${probe.appId}${nameBit}`);
+      } else {
+        console.error(`[feishu-user-plugin] ERROR: LARK_APP_ID=${probe.appId} was REJECTED by Feishu (${probe.error}).`);
+        console.error('[feishu-user-plugin] → Every Official API tool call will fail. Likely wrong/stale APP_ID.');
+        console.error('[feishu-user-plugin] → Re-run the install prompt from team-skills/plugins/feishu-user-plugin/README.md to get the correct credentials.');
+      }
+    } catch (e) {
+      console.error(`[feishu-user-plugin] WARNING: Could not verify APP_ID (${e.message}); network issue or cold start. Proceeding anyway.`);
+    }
+  }
+
+  // --- Real-time events (v1.3.8 C.3) ---
+  // Boot WS only when APP_ID/SECRET are valid. WS uses app credentials
+  // (not UAT), so cookie-only setups don't get realtime.
+  if (hasApp) {
+    try {
+      const { createWSServer } = require('./events');
+      wsServer = createWSServer({
+        appId: activeEnv.LARK_APP_ID,
+        appSecret: activeEnv.LARK_APP_SECRET,
+        registrations: ['im.message.receive_v1'],
+      });
+      // Start asynchronously — don't block MCP serving on WS handshake.
+      wsServer.start().catch((e) => {
+        console.error(`[feishu-user-plugin] WS deferred start error: ${e.message}`);
+      });
+    } catch (e) {
+      console.error(`[feishu-user-plugin] WS init failed: ${e.message}. Continuing without realtime.`);
+    }
+  } else {
+    console.error('[feishu-user-plugin] WS not started — APP_ID/SECRET missing. Realtime events (get_new_events) will return empty.');
+  }
+}
+
+module.exports = { main, TOOLS, HANDLERS };
+
+if (require.main === module) {
+  main().catch((err) => { console.error('Fatal:', err); process.exit(1); });
+}

package/src/setup.js

@@ -21,6 +21,7 @@ function parseArgs() {
     else if (argv[i] === '--app-secret' && argv[i + 1]) args.appSecret = argv[++i];
     else if (argv[i] === '--cookie' && argv[i + 1]) args.cookie = argv[++i];
     else if (argv[i] === '--client' && argv[i + 1]) args.client = argv[++i];
+    else if (argv[i] === '--pointer-only') args.pointerOnly = true;
   }
   return args;
 }
@@ -150,6 +151,19 @@ async function main() {
   }
   if (!client) client = 'claude';
 
+  // If credentials.json exists, recommend pointer-only — the env block in
+  // harness configs becomes redundant (and divergent on UAT refresh).
+  const { readCanonical } = require('./auth/credentials');
+  const hasCanonical = !!readCanonical();
+  let pointerOnly = !!cliArgs.pointerOnly;
+  if (hasCanonical && !pointerOnly && !nonInteractive) {
+    console.log('\n--- Pointer-only mode ---');
+    console.log('Detected ~/.feishu-user-plugin/credentials.json. You can write only');
+    console.log('FEISHU_PLUGIN_PROFILE=default to the harness env (recommended for clean configs).');
+    const ans = (await ask('Use pointer-only mode? (y/N): ')).trim().toLowerCase();
+    pointerOnly = (ans === 'y' || ans === 'yes');
+  }
+
   // Write config
   console.log('\n--- Writing Config ---');
 
@@ -161,9 +175,10 @@ async function main() {
     LARK_USER_REFRESH_TOKEN: hasUAT ? (existingRT || '') : '',
   };
 
-  const result = writeNewConfig(env, undefined, undefined, client);
+  const result = writeNewConfig(env, undefined, undefined, client, { pointerOnly });
   if (result.configPath) console.log(`Written to ${result.configPath} (Claude Code)`);
   if (result.codexConfigPath) console.log(`Written to ${result.codexConfigPath} (Codex)`);
+  if (pointerOnly) console.log('Mode: pointer-only (env block contains only FEISHU_PLUGIN_PROFILE)');
 
   // Summary
   console.log('\n' + '='.repeat(60));

package/src/test-all.js

@@ -4,8 +4,8 @@
  * Sends test messages to "飞书plugin测试群".
  */
 require('dotenv').config({ path: require('path').join(__dirname, '..', '.env') });
-const { LarkUserClient } = require('./client');
-const { LarkOfficialClient } = require('./official');
+const { LarkUserClient } = require('./clients/user');
+const { LarkOfficialClient } = require('./clients/official');
 
 const TEST_GROUP = '飞书plugin测试群';
 const results = [];

package/src/test-comprehensive.js

@@ -6,8 +6,8 @@
 const path = require('path');
 require('dotenv').config({ path: path.join(__dirname, '..', '.env') });
 
-const { LarkUserClient } = require('./client');
-const { LarkOfficialClient } = require('./official');
+const { LarkUserClient } = require('./clients/user');
+const { LarkOfficialClient } = require('./clients/official');
 
 const results = [];
 
@@ -247,7 +247,7 @@ async function testUAT() {
 
   // 3. End-to-end P2P flow: search → create_p2p → read_p2p_messages
   try {
-    const { LarkUserClient } = require('./client');
+    const { LarkUserClient } = require('./clients/user');
     const userClient = new LarkUserClient(process.env.LARK_COOKIE);
     await userClient.init();
     const results = await userClient.search('杨一可');

package/src/test-send.js

@@ -9,7 +9,7 @@
  *   node src/test-send.js info <chatId>    # Get chat info
  */
 require('dotenv').config({ path: require('path').join(__dirname, '..', '.env') });
-const { LarkUserClient } = require('./client');
+const { LarkUserClient } = require('./clients/user');
 
 async function main() {
   const cookie = process.env.LARK_COOKIE;

package/src/tools/_registry.js

@@ -0,0 +1,31 @@
+// src/tools/_registry.js — shared infrastructure for tool modules.
+//
+// Every src/tools/<domain>.js exports:
+//   { schemas: [<MCP tool schema objects>], handlers: { [name]: async (args, ctx) => MCPResponse } }
+//
+// The ctx object that handlers receive is built in src/server.js (or, during
+// the v1.3.7 phase A migration, temporarily in src/index.js) and provides:
+//   - getUserClient():   Promise<LarkUserClient>
+//   - getOfficialClient(): LarkOfficialClient
+//   - getEventBuffer():  EventBuffer | null  — null when WS isn't running
+//   - resolveDocId(x):   Promise<string>  — wiki-node / URL → native token
+//   - listProfiles():    string[]         — names from LARK_PROFILES_JSON + 'default'
+//   - getActiveProfile():string
+//   - setActiveProfile(name): void        — invalidates cached clients
+//
+// Response builders below are imported directly by each tool module — they're
+// not on ctx because they're pure functions with no state.
+
+const text = (s) => ({ content: [{ type: 'text', text: s }] });
+
+// `json` will lift any `fallbackWarning` field to the top of the rendered
+// response so users see the warning before the structured payload. Preserved
+// from index.js v1.3.5 behaviour.
+const json = (o) => {
+  const warn = o && typeof o === 'object' && o.fallbackWarning ? `${o.fallbackWarning}\n\n` : '';
+  return text(warn + JSON.stringify(o, null, 2));
+};
+
+const sendResult = (r, desc) => text(r.success ? desc : `Send failed (status: ${r.status})`);
+
+module.exports = { text, json, sendResult };