@sellable/mcp 0.1.754 → 0.1.755

package/dist/server.js

@@ -8,6 +8,7 @@ import { compileAgentToolPolicy, createAgentMcpAuthorizationHandlers, } from "./
 import { getConfig, getConfiguredCredentialIntent } from "./auth.js";
 import { MCP_RUNTIME_IDENTITY } from "./runtime-identity.js";
 import { getSkillByName, listSkills } from "./skills.js";
+import { toMcpToolResult } from "./tool-result-envelope.js";
 import { getAuthStatus } from "./tools/auth.js";
 import { handleAddColumn, handleCommitBlueprint, } from "./tools/blueprint-commit.js";
 import { bootstrapCreateCampaign } from "./tools/bootstrap.js";
@@ -63,7 +64,6 @@ import { attachRecommendedSequence, attachSequence, createWorkflowTable, } from
 import { setupEvergreenCampaigns } from "./tools/setup-evergreen-campaigns.js";
 import { exportTableCsv, listTables } from "./tools/tables.js";
 import { handleVerifyTableRow } from "./tools/verify-row.js";
-import { sanitizeWatchUrlsForMcpResult } from "./tools/watch-url-security.js";
 import { getCampaignWaterfall, setCampaignWaterfallOrder, } from "./tools/waterfalls.js";
 import { exportWorkspaceCsv } from "./tools/workspace-export.js";
 import { addTeammate, createWorkspace, getActiveWorkspace, getWorkspace, listWorkspaces, setActiveWorkspace, } from "./tools/workspaces.js";
@@ -134,11 +134,6 @@ function formatSubskillPromptText(result) {
         : "";
     return `${header}${result.prompt}${footer}`;
 }
-function isStructuredToolResult(result) {
-    return (!!result &&
-        typeof result === "object" &&
-        Array.isArray(result.content));
-}
 const agentApprovalPort = new HttpAgentApprovalEffectPort();
 const agentMcpAuthorization = createAgentMcpAuthorizationHandlers({
     allTools,
@@ -901,18 +896,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
-        const safeResult = sanitizeWatchUrlsForMcpResult(result);
-        if (isStructuredToolResult(safeResult)) {
-            return safeResult;
-        }
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify(safeResult),
-                },
-            ],
-        };
+        // A tool that DECLARES an `outputSchema` must answer with `structuredContent`,
+        // or the client discards the whole response. `toMcpToolResult` owns that,
+        // keyed on the tool's own declaration. See tool-result-envelope.ts.
+        return toMcpToolResult(name, result);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : "Unknown error";

package/dist/tool-result-envelope.d.ts

@@ -0,0 +1,34 @@
+/**
+ * THE MCP WIRE RESULT. One place shapes it, because the CONTRACT that governs it is
+ * declared per tool and enforced by the CLIENT, not by us.
+ *
+ * A tool that declares an `outputSchema` and answers without `structuredContent` has
+ * its ENTIRE response thrown away by the client, whatever the server actually said:
+ *
+ *   - python `mcp/client/session.py`: `if not result.isError:
+ *     _validate_tool_result(...)`, which raises
+ *     `Tool <name> has an output schema but did not return structured content`;
+ *   - typescript `@modelcontextprotocol/sdk` `client/index.js:499-520`: the same
+ *     rule, then ajv validation of the payload against that schema.
+ *
+ * That is not a theoretical hazard. It took the three `integrations_*` tools down on
+ * the live customer runtime for every Slack turn — success and refusal alike, since
+ * neither sets `isError` — and three consecutive failures then tripped Hermes' MCP
+ * circuit breaker, which reported the whole server as "unreachable".
+ *
+ * The declaration and the payload therefore cannot be maintained in two places by
+ * two conventions. `inbox.ts`, `senders.ts`, and `runtime-identity.ts` each hand-built
+ * `{ content, structuredContent }` correctly and `integrations.ts` returned a bare
+ * envelope; keying off the tool's own declaration removes the chance to get it wrong.
+ */
+export type McpToolTextContent = {
+    type: "text";
+    text: string;
+};
+export type McpToolResult = {
+    content: McpToolTextContent[];
+    structuredContent?: unknown;
+    isError?: boolean;
+};
+export declare function isStructuredToolResult(result: unknown): result is McpToolResult;
+export declare function toMcpToolResult(name: string, result: unknown): McpToolResult;

package/dist/tool-result-envelope.js

@@ -0,0 +1,37 @@
+import { allTools } from "./tools/registry.js";
+import { sanitizeWatchUrlsForMcpResult } from "./tools/watch-url-security.js";
+/**
+ * Read off the REAL tool table, so a tool that adds an `outputSchema` is covered the
+ * moment it is registered and cannot be forgotten here.
+ */
+const OUTPUT_SCHEMA_TOOL_NAMES = new Set(allTools
+    .filter((tool) => tool.outputSchema)
+    .map((tool) => tool.name));
+export function isStructuredToolResult(result) {
+    return (!!result &&
+        typeof result === "object" &&
+        Array.isArray(result.content));
+}
+function isPlainObject(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+export function toMcpToolResult(name, result) {
+    const safeResult = sanitizeWatchUrlsForMcpResult(result);
+    if (isStructuredToolResult(safeResult)) {
+        return safeResult;
+    }
+    const content = [
+        { type: "text", text: JSON.stringify(safeResult) },
+    ];
+    if (!OUTPUT_SCHEMA_TOOL_NAMES.has(name)) {
+        return { content };
+    }
+    if (!isPlainObject(safeResult)) {
+        // `structuredContent` must be an OBJECT, so a non-object can never satisfy an
+        // object schema. FAIL CLOSED as an error the client will still deliver, instead
+        // of a well-formed response the client discards wholesale — the operator gets
+        // the payload and a visible error rather than a bare protocol complaint.
+        return { content, isError: true };
+    }
+    return { content, structuredContent: safeResult };
+}

package/dist/tools/integrations.js

@@ -243,11 +243,36 @@ export const integrationsToolDefinitions = [
         },
     },
 ];
+/**
+ * The two CLOSED enums, read off the declared `outputSchema` so there is one source.
+ *
+ * `outcome` and `attribution` are validated by the MCP CLIENT against
+ * `ENVELOPE_OUTPUT_SCHEMA` (`@modelcontextprotocol/sdk` runs ajv over
+ * `structuredContent`; the python SDK does the same via `jsonschema`). An off-enum
+ * value therefore does not degrade the envelope — it makes the client reject the
+ * WHOLE response, so the operator loses the refusal AND its reason.
+ *
+ * `toolError` forwards the route's fields VERBATIM, and off-enum values exist
+ * server-side already (`attribution: "app"` in
+ * `src/lib/sellable-agent/integration-connect-copy.ts`). So an unrecognized value is
+ * normalized FAIL-CLOSED to a refusal by `sellable`, while the route's `error` code —
+ * the field that actually carries the reason — is still forwarded verbatim.
+ */
+const ENVELOPE_OUTCOMES = ENVELOPE_OUTPUT_SCHEMA.properties.outcome.enum;
+const ENVELOPE_ATTRIBUTIONS = ENVELOPE_OUTPUT_SCHEMA.properties.attribution.enum;
 function envelope(value) {
+    const outcome = value.outcome ?? (value.ok ? "ok" : "refused");
+    const attribution = value.attribution ?? (value.ok ? "policy" : "sellable");
     return {
         ok: value.ok,
-        outcome: value.outcome ?? (value.ok ? "ok" : "refused"),
-        attribution: value.attribution ?? (value.ok ? "policy" : "sellable"),
+        outcome: ENVELOPE_OUTCOMES.includes(outcome)
+            ? outcome
+            : value.ok
+                ? "ok"
+                : "refused",
+        attribution: ENVELOPE_ATTRIBUTIONS.includes(attribution)
+            ? attribution
+            : "sellable",
         error: value.error ?? null,
         guidance: value.guidance ?? null,
         result: value.result ?? null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sellable/mcp",
-  "version": "0.1.754",
+  "version": "0.1.755",
   "type": "module",
   "description": "Sellable MCP server for Claude Code, Codex, and Hermes campaign workflows",
   "main": "dist/index.js",