@bevel-software/platform-mcp-core 0.8.0

package/src/results.ts

@@ -0,0 +1,131 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * Extract a human-meaningful failure message from a tool-call error. UTCP's
+ * HTTP protocol surfaces a non-2xx as an axios-style error whose `.response.data`
+ * is the REST endpoint's JSON body (`{ error: "..." }`). Pull that out so the
+ * MCP caller sees the tool's real message instead of a bare "status code 500".
+ */
+export function describeToolFailure(err: unknown): string {
+  const data = (err as { response?: { data?: unknown } })?.response?.data;
+  if (data && typeof data === 'object') {
+    const inner = (data as { error?: unknown }).error;
+    if (typeof inner === 'string' && inner.length > 0) return inner;
+  }
+  if (typeof data === 'string' && data.length > 0) return data;
+  // Total, like `safeJsonText`: a thrown value whose own `toString` throws
+  // (e.g. a null-prototype object) must still come back as a description —
+  // this function runs inside catch paths, where a second throw would turn
+  // a tool failure into a handler failure.
+  try {
+    return err instanceof Error ? err.message : String(err);
+  } catch {
+    return '(indescribable tool failure)';
+  }
+}
+
+/**
+ * Turn a tool's final value into an MCP result:
+ *  - a tool that already returns the MCP agentic shape (`{ content: [...] }`,
+ *    each entry a real content block) is passed through unchanged;
+ *  - a bare string becomes the text content;
+ *  - anything else is JSON-stringified into one text block.
+ *
+ * Note we do NOT collapse a structured object down to its `text` field: doing
+ * so silently dropped the other fields (e.g. `ask`'s `status` / `sessionId`,
+ * the id a caller must echo back to poll or continue a conversation).
+ * Stringifying the whole object keeps every field, so the caller always sees
+ * the id it is responsible for echoing.
+ *
+ * The passthrough guard checks the entries, not just that `content` is an array:
+ * a domain value that merely happens to carry a `content` array of non-blocks
+ * (e.g. `{ content: ['a', 'b'] }`) is data, not an MCP result, so it falls
+ * through to JSON-stringify and survives intact instead of being emitted as a
+ * malformed result the client can't parse.
+ */
+function isMcpContentBlock(entry: unknown): boolean {
+  return typeof entry === 'object' && entry !== null && typeof (entry as { type?: unknown }).type === 'string';
+}
+
+/**
+ * `JSON.stringify`, made total. A tool can legally hand back a value JSON
+ * refuses verbatim — a BigInt or circular object (throws), a bare
+ * function/symbol (stringifies to `undefined`) — and a COMPLETED call must not
+ * turn into a crash at the serialization step. The plain stringify runs first
+ * so well-formed values (shared non-circular references included) come out
+ * exactly as before; only a value it rejects degrades to the replacer pass
+ * (BigInt → decimal string, its own ancestor → '[Circular]'), and a value even
+ * that can't take (e.g. a throwing `toJSON`) falls back to `String(value)`.
+ */
+function safeJsonText(value: unknown): string {
+  try {
+    const text = JSON.stringify(value);
+    if (text !== undefined) return text;
+  } catch {
+    // BigInt / circular / throwing toJSON — degrade below.
+  }
+  try {
+    // Circularity is being one's own ANCESTOR, not being visited twice: a
+    // shared (diamond) reference is legal JSON and stringify visits it once
+    // per parent, so a grown-only "seen" set would mislabel every sibling
+    // share as circular. The stack tracks only the active descent — the
+    // holder (`this`) of the current key is necessarily the innermost live
+    // ancestor, so popping down to it discards branches already unwound.
+    const ancestors: object[] = [];
+    const text = JSON.stringify(value, function (this: unknown, _key, v: unknown) {
+      if (typeof v === 'bigint') return v.toString();
+      if (v && typeof v === 'object') {
+        while (ancestors.length > 0 && ancestors[ancestors.length - 1] !== this) ancestors.pop();
+        if (ancestors.includes(v)) return '[Circular]';
+        ancestors.push(v);
+      }
+      return v;
+    });
+    if (text !== undefined) return text;
+  } catch {
+    // fall through to the value's own toString
+  }
+  try {
+    return String(value);
+  } catch {
+    return '(unserializable tool output)';
+  }
+}
+
+export function toCallToolResult(value: unknown): CallToolResult {
+  // Already in MCP agentic format — pass through untouched, but only when every
+  // `content` entry is a real content block (has a string `type`).
+  const content = (value as { content?: unknown })?.content;
+  if (value && typeof value === 'object' && Array.isArray(content) && content.every(isMcpContentBlock)) {
+    return value as CallToolResult;
+  }
+  const text = typeof value === 'string' ? value : safeJsonText(value ?? null);
+  return { content: [{ type: 'text', text: text || '(tool produced no output)' }] };
+}
+
+export function renderProgress(chunk: unknown): string {
+  const s = typeof chunk === 'string' ? chunk : safeJsonText(chunk);
+  return s.length > 500 ? s.slice(0, 497) + '...' : s;
+}
+
+export function toolError(message: string): CallToolResult {
+  return { isError: true, content: [{ type: 'text', text: message }] };
+}
+
+/**
+ * The result returned when the caller is missing personal credentials a tool
+ * needs. Marked `isError` so the external agent surfaces it to the person rather
+ * than treating it as tool output. Names the tool, lists the missing items, and
+ * gives the absolute setup-page URL so the person can provide them and retry.
+ */
+export function needsAuthorizationResult(
+  toolName: string,
+  missing: string[],
+  connectUrl: string,
+): CallToolResult {
+  const items = missing.join(', ');
+  const text =
+    `The "${toolName}" tool needs credentials you haven't set up yet: ${items}. ` +
+    `Open ${connectUrl} to connect your accounts and enter your keys, then run the tool again.`;
+  return { isError: true, content: [{ type: 'text', text }] };
+}

package/src/skills.ts

@@ -0,0 +1,34 @@
+/**
+ * Skills exposed as MCP prompts (slash commands in an MCP client).
+ *
+ * Both surfaces do this the same way and must keep doing it the same way: a
+ * skill's instructions are the prompt body, and the bundled files are named at
+ * the end with the exact call that fetches them. A person running the same
+ * skill through the hosted endpoint and through the local server should get
+ * identical text, so the formatting lives here rather than in either server.
+ */
+
+/** Minimal skill shapes the prompt bridge needs (no dependency on `modules/skills`). */
+export interface SkillSummary {
+  name: string;
+  description: string;
+}
+
+export interface LoadedSkill extends SkillSummary {
+  body: string;
+  path: string;
+  files: string[];
+}
+
+/** The prompt message text for a loaded skill: its instructions body + a pointer to bundled files. */
+export function skillPromptText(skill: LoadedSkill): string {
+  const rel = skill.files.map((f) =>
+    f.startsWith(`${skill.path}/`) ? f.slice(skill.path.length + 1) : f,
+  );
+  // Each name is quoted: a comma inside a file name must not read as a list
+  // separator, and the quoted form is exactly the `file` value get_skill takes.
+  const footer = rel.length
+    ? `\n\n---\nSkill folder: ${skill.path}\nBundled files (fetch each with the get_skill tool: { name: ${JSON.stringify(skill.name)}, file }): ${rel.map((f) => JSON.stringify(f)).join(', ')}`
+    : '';
+  return `${skill.body}${footer}`;
+}

package/src/utcp-namespace.ts

@@ -0,0 +1,70 @@
+/**
+ * The key UTCP uses to look up a manual's `${VAR}`. `@utcp/sdk` first SANITIZES
+ * the manual name — every non-word char (`-`, `.`, spaces, …) becomes `_`
+ * (`manualCallTemplate.name.replace(/[^\w]/g, "_")` at registration) — and then
+ * namespaces variables under `<namespace>_<VAR>` where every `_` in the
+ * sanitized namespace is DOUBLED (the variable substitutor), so `my_tool` + `KEY`
+ * → `my__tool_KEY` and `my-tool` + `KEY` → the very same `my__tool_KEY`. Our
+ * secret storage AND scope resolution must derive the exact same key. For an
+ * alphanumeric name (no `_`, no punctuation) this reduces to `<name>_<VAR>`,
+ * so plain tool names are unaffected.
+ */
+export function utcpNamespacePrefix(manualName: string): string {
+  return `${manualName.replace(/[^\w]/g, '_').replace(/_/g, '__')}_`;
+}
+
+export function utcpNamespacedKey(manualName: string, varName: string): string {
+  return `${utcpNamespacePrefix(manualName)}${varName}`;
+}
+
+/**
+ * The origin template WE mint for every Bevel-hosted manual's discovery URL
+ * (`${API_URL}/api/…`). `${API_URL}` expands to the loopback origin, so a
+ * Bevel-hosted URL always has this exact string as its scheme+authority.
+ */
+const LOOPBACK_ORIGIN_TEMPLATE = '${API_URL}';
+
+/**
+ * True only when `${API_URL}` is the URL's ORIGIN (scheme+authority) — the shape
+ * we ourselves produce for a Bevel-hosted manual. A third-party `.tool` author
+ * can embed the literal `${API_URL}` anywhere in a path or query
+ * (`http://evil.example/?x=${API_URL}`) but can NOT make it the authority without
+ * pointing the request back at our own loopback, so anchoring the trust decision
+ * to the origin is what a user `.tool`'s URL text cannot forge.
+ */
+function isBevelHostedUrl(url: string): boolean {
+  if (!url.startsWith(LOOPBACK_ORIGIN_TEMPLATE)) return false;
+  // The char right after the origin must delimit the authority; anything else
+  // (`${API_URL}.evil.com`, `${API_URL}evil`) is a different, untrusted host.
+  const next = url.charAt(LOOPBACK_ORIGIN_TEMPLATE.length);
+  return next === '' || next === '/' || next === '?' || next === '#';
+}
+
+/**
+ * Seed the loopback discovery vars (`<ns>_API_URL` + `<ns>_CONNECTION_KEY`) for
+ * every Bevel-HOSTED manual in `manuals` — one whose discovery `url` targets our
+ * own backend with `${API_URL}` as its ORIGIN (the KB manual and inline `.tool`
+ * sub-manuals). A third-party http/mcp `.tool` points at an arbitrary URL, so it
+ * is deliberately NOT seeded: handing it `connectionKey` would leak the bearer to
+ * that endpoint. Keying off the origin (not a bare `includes('${API_URL}')`) is
+ * deliberate — an `http` `.tool`'s URL is author-controlled, so a substring match
+ * would let `http://attacker/?x=${API_URL}` be seeded the bearer and exfiltrate
+ * it. This is the exfiltration-safe seeding rule shared by the external MCP proxy
+ * and the in-process agent factory, so the bearer-leak decision is written ONCE.
+ */
+export function seedBevelHostedManualVars(
+  manuals: readonly { name?: unknown; url?: unknown }[],
+  loopbackBaseUrl: string,
+  connectionKey: string,
+): Record<string, string> {
+  const variables: Record<string, string> = {};
+  for (const m of manuals) {
+    const name = typeof m.name === 'string' ? m.name : '';
+    if (!name) continue;
+    const url = (m as { url?: unknown }).url;
+    if (typeof url !== 'string' || !isBevelHostedUrl(url)) continue;
+    variables[utcpNamespacedKey(name, 'API_URL')] = loopbackBaseUrl;
+    variables[utcpNamespacedKey(name, 'CONNECTION_KEY')] = connectionKey;
+  }
+  return variables;
+}