Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/prerelease-preview-pins-16.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@adcp/sdk': patch
---

Keep stable AdCP pins on stable releases when a server's `adcpVersion` is a prerelease preview registered with `registerExternalSchemaRoot`. A release pin such as `3.3` or `3.4` no longer resolves onto the preview, and a prerelease pin must match an advertised prerelease exactly or get `VERSION_UNSUPPORTED`. MCP tool discovery reports the selected release in each framework tool's `_meta.adcp_version`, and still lists the default release for an unsupported pin rather than failing, without listing a preview for a pin that did not name it. Backport of #3707.
65 changes: 55 additions & 10 deletions src/lib/server/create-adcp-server.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import { isPre31AdcpVersion } from '../utils/adcp-version-config';
import { parseAdcpRelease as parseFullAdcpRelease } from '../adapters/version/negotiate';
import { assertWebBotAuthSigningKey, getWebBotAuthLegacyOriginGate } from '../signing/web-bot-auth';
import {
downgradeResponse,
Expand Down Expand Up @@ -82,6 +83,7 @@ import { IdentityAuthorizationError, TrustRecordUnavailableError } from '../iden

import { z } from 'zod';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
import {
COMPATIBLE_ADCP_VERSIONS,
parseAdcpMajorVersion,
Expand Down Expand Up @@ -5186,7 +5188,16 @@ function selectServedAdcpRelease(
});
}
selected = supported
.filter(candidate => candidate.major === requested.major && compareAdcpRelease(candidate, requested) <= 0)
.filter(candidate =>
requested.prerelease !== undefined
? candidate.major === requested.major &&
candidate.minor === requested.minor &&
parseFullAdcpRelease(candidate.exactValue)?.patch === parseFullAdcpRelease(requested.exactValue)?.patch &&
candidate.prerelease === requested.prerelease
: candidate.major === requested.major &&
candidate.prerelease === undefined &&
compareAdcpRelease(candidate, requested) <= 0
)
.sort((left, right) => compareAdcpRelease(right, left))[0];
} else if (requestedMajor !== undefined && Number.isFinite(requestedMajor)) {
// A major-only request may be a 3.0 buyer that cannot send
Expand Down Expand Up @@ -9824,6 +9835,21 @@ export function createAdcpServer<TAccount = unknown>(config: AdcpServerConfig<TA
? 'media-buy'
: 'all';
const mediaBuyProfileTools = new Set<string>(MEDIA_BUY_MCP_TOOL_PROFILE);
// SDK 16 discovery stays lenient for every unsupported pin, as it was before
// prerelease-aware selection: list the default release. When the default is
// a preview, list the newest stable release instead, so discovery never
// moves a caller onto a preview it did not pin.
const discoveryFallback = (): ServedAdcpRelease | undefined => {
if (!parseAdcpRelease(selectedDefault.validationVersion)?.prerelease) return selectedDefault;
const ceiling = parseAdcpRelease(adcpVersion)!;
const stable = selectServedAdcpRelease(
{ adcp_version: `${ceiling.major}.${ceiling.minor}` },
capConfig,
adcpVersion,
defaultAdcpVersion
);
return isMcpToolResponse(stable) ? undefined : stable;
};
const wrappedToolsList = wrapSdkRequestHandler(server, 'tools/list', async (original, request, extra) => {
const response = await original(request, extra);
if (response == null || typeof response !== 'object') return response;
Expand All @@ -9846,9 +9872,14 @@ export function createAdcpServer<TAccount = unknown>(config: AdcpServerConfig<TA
adcpVersion,
defaultAdcpVersion
);
const listRelease: ServedAdcpRelease = isMcpToolResponse(selectedListRelease)
? { validationVersion: selectedDefault.validationVersion }
: selectedListRelease;
const listRelease = isMcpToolResponse(selectedListRelease) ? discoveryFallback() : selectedListRelease;
if (!listRelease) {
throw new McpError(
ErrorCode.InvalidParams,
'VERSION_UNSUPPORTED',
(selectedListRelease as McpToolResponse).structuredContent
);
}
const parsedListRelease = parseAdcpRelease(listRelease.validationVersion);
const listServes32OrNewer =
parsedListRelease !== undefined &&
Expand All @@ -9868,11 +9899,22 @@ export function createAdcpServer<TAccount = unknown>(config: AdcpServerConfig<TA
return listMcpToolProfile === 'all' || mediaBuyProfileTools.has(toolName);
});
const projectedTools = visibleTools.map(tool => {
if (listMcpToolProfile !== 'media-buy') return tool;
const toolName = (tool as { name?: unknown } | null)?.name;
if (typeof toolName !== 'string') return tool;
const inputSchema = getMcpProfileInputSchema(toolName, 'media-buy', listRelease.validationVersion);
return inputSchema ? { ...(tool as Record<string, unknown>), inputSchema } : tool;
const toolRecord = tool as Record<string, unknown>;
const meta = isPlainObject(toolRecord._meta) ? toolRecord._meta : undefined;
const frameworkAdcpTool = meta?.adcp_version === adcpVersion;
const inputSchema =
listMcpToolProfile === 'media-buy'
? getMcpProfileInputSchema(toolName, 'media-buy', listRelease.validationVersion)
: undefined;
return {
...toolRecord,
...(frameworkAdcpTool && {
_meta: { ...meta, adcp_version: listRelease.advertisedVersion ?? listRelease.validationVersion },
}),
...(inputSchema && { inputSchema }),
};
});

return {
Expand Down Expand Up @@ -10003,9 +10045,12 @@ export function createAdcpServer<TAccount = unknown>(config: AdcpServerConfig<TA
adcpVersion,
defaultAdcpVersion
);
return isMcpToolResponse(selected)
? defaultAdcpVersion
: (selected.advertisedVersion ?? selected.validationVersion);
if (isMcpToolResponse(selected)) {
const fallback = discoveryFallback();
if (fallback) return fallback.advertisedVersion ?? fallback.validationVersion;
throw new McpError(ErrorCode.InvalidParams, 'VERSION_UNSUPPORTED', selected.structuredContent);
}
return selected.advertisedVersion ?? selected.validationVersion;
});
setMcpToolProfile(wrapped, activeMcpToolProfile);
setMcpAppResources(wrapped, mcpAppResources);
Expand Down
4 changes: 3 additions & 1 deletion src/lib/server/mcp-modern-server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -328,7 +328,9 @@ export function createModernMcpServerAdapter(agentServer: AdcpServer): ModernMcp
}) as unknown as ModernTool['inputSchema'],
...(registered.outputSchemaJson !== undefined && { outputSchema: registered.outputSchemaJson }),
...(tool.annotations !== undefined && { annotations: tool.annotations as ToolAnnotations }),
...(tool._meta !== undefined && { _meta: tool._meta }),
...(tool._meta !== undefined && {
_meta: frameworkAdcpTool ? { ...tool._meta, adcp_version: discoveryVersion } : tool._meta,
}),
};
}),
_meta: {
Expand Down
42 changes: 42 additions & 0 deletions test/helpers/external-preview-root.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
'use strict';

// SDK 16 packages no AdCP prerelease. A seller enables a preview by
// registering that preview's schema root, so the negotiation tests register a
// minimal one. These schemas are open objects: they exercise release
// selection, not the preview's real shapes.
const fs = require('node:fs');
const os = require('node:os');
const path = require('node:path');
const { registerExternalSchemaRoot, unregisterExternalSchemaRoot } = require('../../dist/lib/validation/schema-loader');

const EXTERNAL_PREVIEW = '3.3.0-rc.0';
const TOOLS = { get_products: 'media-buy', create_media_buy: 'media-buy' };

async function withExternalPreviewRoot(fn, version = EXTERNAL_PREVIEW) {
const root = fs.mkdtempSync(path.join(os.tmpdir(), 'adcp-external-preview-'));
fs.writeFileSync(path.join(root, 'index.json'), JSON.stringify({ adcp_version: version }));
fs.writeFileSync(
path.join(root, 'manifest.json'),
JSON.stringify({ tools: Object.fromEntries(Object.keys(TOOLS).map(tool => [tool, {}])) })
);
for (const [tool, domain] of Object.entries(TOOLS)) {
const dir = path.join(root, 'bundled', domain);
fs.mkdirSync(dir, { recursive: true });
for (const kind of ['request', 'response']) {
const file = `${tool.replace(/_/g, '-')}-${kind}.json`;
fs.writeFileSync(
path.join(dir, file),
JSON.stringify({ $id: `https://adcontextprotocol.org/schemas/${version}/${domain}/${file}`, type: 'object' })
);
}
}
registerExternalSchemaRoot(version, root);
try {
return await fn(version);
} finally {
unregisterExternalSchemaRoot(version);
fs.rmSync(root, { recursive: true, force: true });
}
}

module.exports = { EXTERNAL_PREVIEW, withExternalPreviewRoot };
1 change: 1 addition & 0 deletions test/lib/mcp-modern-negotiation.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -862,6 +862,7 @@ test('modern discovery and direct calls apply the requested per-tool version ava
assert.ok(names30.includes('get_products'));
assert.ok(!names30.includes('get_signals'));
assert.equal(listed30._meta.adcp_version, '3.0.25');
assert.equal(listed30.tools.find(tool => tool.name === 'get_products')._meta.adcp_version, '3.0.25');

const rejected = await client.callTool({ name: 'get_signals', arguments: { adcp_version: '3.0.25' } });
assert.equal(rejected.isError, true);
Expand Down
33 changes: 33 additions & 0 deletions test/server-a2a-adapter.test.js
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
const { describe, it } = require('node:test');
const { toReleasePrecisionVersion } = require('../dist/lib/version.js');
const { withExternalPreviewRoot } = require('./helpers/external-preview-root');
const assert = require('node:assert');
const express = require('express');
const { Role, SendMessageRequest, TaskState } = require('@a2a-js/sdk');
Expand Down Expand Up @@ -619,6 +621,37 @@ describe('createA2AAdapter', () => {
});

describe('message/send routing', () => {
it('negotiates stable and exact preview pins through the executor', () =>
withExternalPreviewRoot(async previewVersion => {
const adcp = createAdcpServer({
name: 'Preview',
version: '1.0.0',
adcpVersion: previewVersion,
defaultAdcpVersion: '3.2.1',
capabilities: { supported_versions: ['3.2.1', previewVersion] },
mediaBuy: { getProducts: async () => ({ products: [], cache_scope: 'public' }) },
});
const app = mountAdapter(createA2AAdapter({ server: adcp, agentCard: baseCard() }));
for (const [pin, expected] of [
['3.4', '3.2'],
[previewVersion, toReleasePrecisionVersion(previewVersion)],
]) {
const res = await postJsonRpc(app, messageSend(dataPartMessage('get_products', { adcp_version: pin })));
assert.strictEqual(res.body.result.status.state, 'completed', JSON.stringify(res.body));
const data = res.body.result.artifacts[0].parts.find(part => part.kind === 'data').data;
assert.strictEqual(data.adcp_version, expected);
}
const refused = await postJsonRpc(
app,
messageSend(
dataPartMessage('get_products', {
adcp_version: previewVersion.replace(/(\d+)$/, (_, n) => String(Number(n) + 1)),
})
)
);
assert.match(JSON.stringify(refused.body), /VERSION_UNSUPPORTED/);
}));

it('Success arm → Task.state=completed + DataPart artifact', async () => {
const adcp = createAdcpServer({
mediaBuy: { getProducts: async () => ({ products: [{ product_id: 'p1' }] }) },
Expand Down
85 changes: 85 additions & 0 deletions test/server-create-adcp-server.test.js
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
const { describe, it, mock } = require('node:test');
const { toReleasePrecisionVersion } = require('../dist/lib/version.js');
const { withExternalPreviewRoot } = require('./helpers/external-preview-root');
const assert = require('node:assert');
const {
createAdcpServer: _createAdcpServer,
Expand Down Expand Up @@ -208,6 +210,89 @@ describe('createAdcpServer', () => {
assert.ok(enhancedContexts.every(Object.isFrozen));
});

it('selects only exact prereleases and never downshifts a stable pin to a preview', () =>
withExternalPreviewRoot(async preview => {
const previewWire = toReleasePrecisionVersion(preview);
const otherPreview = preview.replace(/(\d+)$/, (_, n) => String(Number(n) + 1));
const otherPatch = preview.replace(/\.0-/, '.1-');
const seen = [];
const server = createAdcpServer({
name: 'Preview seller',
version: '1.0.0',
adcpVersion: preview,
defaultAdcpVersion: '3.2.1',
capabilities: { supported_versions: ['3.1.18', '3.2.1', preview] },
mediaBuy: {
getProducts: async (_params, ctx) => {
seen.push(ctx.servedAdcpVersion);
return { products: [], cache_scope: 'public' };
},
},
});
for (const [pin, expected] of [
[preview, previewWire],
['3.3', '3.2'],
['3.4', '3.2'],
[undefined, '3.2'],
]) {
const args = pin ? { adcp_version: pin } : {};
for (const result of [
await callToolRaw(server, 'get_products', args),
await server.invoke({ toolName: 'get_products', args }),
]) {
assert.notEqual(result.isError, true, JSON.stringify(result));
assert.equal(result.structuredContent.adcp_version, expected);
assert.deepEqual(result.structuredContent.products, []);
}
for (const params of [{ adcp_version: pin }, { _meta: { adcp_version: pin } }]) {
const listed = await server.dispatchTestRequest({ method: 'tools/list', params });
const advertised = expected === '3.2' ? '3.2.1' : preview;
assert.equal(listed._meta.adcp_version, advertised);
assert.equal(listed.tools.find(tool => tool.name === 'get_products')._meta.adcp_version, advertised);
}
}
assert.deepEqual(seen, [previewWire, previewWire, '3.2', '3.2', '3.2', '3.2', '3.2', '3.2']);
for (const pin of [otherPreview, otherPatch]) {
const result = await callToolRaw(server, 'get_products', { adcp_version: pin });
assert.equal(result.structuredContent.adcp_error.code, 'VERSION_UNSUPPORTED');
const listed = await server.dispatchTestRequest({
method: 'tools/list',
params: { _meta: { adcp_version: pin } },
});
assert.equal(listed._meta.adcp_version, '3.2.1');
}
const previewOnly = createAdcpServer({
name: 'Preview only',
version: '1.0.0',
adcpVersion: preview,
capabilities: { supported_versions: [preview] },
mediaBuy: { getProducts: async () => ({ products: [] }) },
});
const unavailable = await callToolRaw(previewOnly, 'get_products', { adcp_version: '3.4' });
assert.equal(unavailable.structuredContent.adcp_error.code, 'VERSION_UNSUPPORTED');
await assert.rejects(
previewOnly.dispatchTestRequest({ method: 'tools/list', params: { _meta: { adcp_version: '3.4' } } }),
/VERSION_UNSUPPORTED/
);
}));

it('keeps tools/list lenient for an unsupported stable pin', async () => {
const stableOnly = createAdcpServer({
name: 'Stable seller',
version: '1.0.0',
adcpVersion: '3.2.1',
capabilities: { supported_versions: ['3.1.18', '3.2.1'] },
mediaBuy: { getProducts: async () => ({ products: [] }) },
});
const call = await callToolRaw(stableOnly, 'get_products', { adcp_version: '3.0' });
assert.equal(call.structuredContent.adcp_error.code, 'VERSION_UNSUPPORTED');
for (const params of [{ adcp_version: '3.0' }, { _meta: { adcp_version: '3.0' } }]) {
const listed = await stableOnly.dispatchTestRequest({ method: 'tools/list', params });
assert.equal(listed._meta.adcp_version, '3.2.1');
assert.equal(listed.tools.find(tool => tool.name === 'get_products')._meta.adcp_version, '3.2.1');
}
});

it('rejects an unadvertised or newer defaultAdcpVersion at construction', () => {
assert.throws(
() =>
Expand Down
33 changes: 33 additions & 0 deletions test/server-idempotency.test.js
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
const { describe, it, before, after } = require('node:test');
const { withExternalPreviewRoot } = require('./helpers/external-preview-root');
const assert = require('node:assert/strict');

const { createAdcpServer: _createAdcpServer } = require('../dist/lib/server/create-adcp-server');
Expand Down Expand Up @@ -129,6 +130,38 @@ describe('createAdcpServer with idempotency', () => {
assert.notEqual(result.replayed, true, 'fresh execution must not set replayed:true');
});

it('preserves the request hash when a preview ceiling serves a stable pin', () =>
withExternalPreviewRoot(async previewVersion => {
const idempotency = createIdempotencyStore({ backend: memoryBackend({ sweepIntervalMs: 0 }), ttlSeconds: 86400 });
let calls = 0;
const makeVersioned = (ceiling, supported) =>
createAdcpServer({
name: 'Versioned',
version: '1.0.0',
adcpVersion: ceiling,
defaultAdcpVersion: '3.2.1',
capabilities: { supported_versions: supported },
idempotency,
resolveSessionKey: () => 'tenant_a',
mediaBuy: {
createMediaBuy: async () => {
calls++;
return { media_buy_id: 'mb_1', packages: [] };
},
},
});
const stable = makeVersioned('3.2.1', ['3.2.1']);
const preview = makeVersioned(previewVersion, ['3.2.1', previewVersion]);
const request = { ...basePayload, adcp_version: '3.4', idempotency_key: 'version_hash_key_12345' };
const first = await callTool(stable, 'create_media_buy', request);
const retry = await callTool(preview, 'create_media_buy', request);
assert.equal(first.media_buy_id, 'mb_1');
assert.equal(retry.media_buy_id, 'mb_1');
assert.equal(retry.replayed, true);
assert.equal(calls, 1);
assert.equal(request.adcp_version, '3.4');
}));

it('replay with same key + equivalent payload returns cached response with replayed:true', async () => {
const { server, calls } = makeServer();
const key = 'replay_key_abcdefghij';
Expand Down
Loading