@adcp/client 4.21.0 → 4.22.0

package/dist/lib/utils/response-schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"response-schemas.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/response-schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,qBAAqB,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAgBpE,CAAC"}
+{"version":3,"file":"response-schemas.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/response-schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,qBAAqB,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAuDpE,CAAC"}

package/dist/lib/utils/response-schemas.js

@@ -42,20 +42,51 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TOOL_RESPONSE_SCHEMAS = void 0;
 const schemas = __importStar(require("../types/schemas.generated"));
 exports.TOOL_RESPONSE_SCHEMAS = {
+    // Product discovery & media buy
     get_products: schemas.GetProductsResponseSchema,
-    list_creative_formats: schemas.ListCreativeFormatsResponseSchema,
     create_media_buy: schemas.CreateMediaBuyResponseSchema,
     update_media_buy: schemas.UpdateMediaBuyResponseSchema,
-    sync_creatives: schemas.SyncCreativesResponseSchema,
-    list_creatives: schemas.ListCreativesResponseSchema,
     get_media_buys: schemas.GetMediaBuysResponseSchema,
     get_media_buy_delivery: schemas.GetMediaBuyDeliveryResponseSchema,
     provide_performance_feedback: schemas.ProvidePerformanceFeedbackResponseSchema,
+    // Creative
+    list_creative_formats: schemas.ListCreativeFormatsResponseSchema,
     build_creative: schemas.BuildCreativeResponseSchema,
     preview_creative: schemas.PreviewCreativeResponseSchema,
+    sync_creatives: schemas.SyncCreativesResponseSchema,
+    list_creatives: schemas.ListCreativesResponseSchema,
+    get_creative_delivery: schemas.GetCreativeDeliveryResponseSchema,
+    // Signals
     get_signals: schemas.GetSignalsResponseSchema,
     activate_signal: schemas.ActivateSignalResponseSchema,
+    // Account & audience
+    sync_accounts: schemas.SyncAccountsResponseSchema,
+    list_accounts: schemas.ListAccountsResponseSchema,
+    sync_governance: schemas.SyncGovernanceResponseSchema,
     sync_audiences: schemas.SyncAudiencesResponseSchema,
+    // Governance — property lists & content standards
+    create_property_list: schemas.CreatePropertyListResponseSchema,
+    get_property_list: schemas.GetPropertyListResponseSchema,
+    update_property_list: schemas.UpdatePropertyListResponseSchema,
+    list_property_lists: schemas.ListPropertyListsResponseSchema,
+    delete_property_list: schemas.DeletePropertyListResponseSchema,
+    list_content_standards: schemas.ListContentStandardsResponseSchema,
+    get_content_standards: schemas.GetContentStandardsResponseSchema,
+    calibrate_content: schemas.CalibrateContentResponseSchema,
+    validate_content_delivery: schemas.ValidateContentDeliveryResponseSchema,
+    // Campaign governance
+    sync_plans: schemas.SyncPlansResponseSchema,
+    check_governance: schemas.CheckGovernanceResponseSchema,
+    report_plan_outcome: schemas.ReportPlanOutcomeResponseSchema,
+    get_plan_audit_logs: schemas.GetPlanAuditLogsResponseSchema,
+    // Sponsored Intelligence
+    si_get_offering: schemas.SIGetOfferingResponseSchema,
+    si_initiate_session: schemas.SIInitiateSessionResponseSchema,
+    si_send_message: schemas.SISendMessageResponseSchema,
+    si_terminate_session: schemas.SITerminateSessionResponseSchema,
+    // Capabilities
+    get_adcp_capabilities: schemas.GetAdCPCapabilitiesResponseSchema,
+    // Test controller
     comply_test_controller: schemas.ComplyTestControllerResponseSchema,
 };
 //# sourceMappingURL=response-schemas.js.map

package/dist/lib/utils/response-schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"response-schemas.js","sourceRoot":"","sources":["../../../src/lib/utils/response-schemas.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGH,oEAAsD;AAEzC,QAAA,qBAAqB,GAAuC;IACvE,YAAY,EAAE,OAAO,CAAC,yBAAyB;IAC/C,qBAAqB,EAAE,OAAO,CAAC,iCAAiC;IAChE,gBAAgB,EAAE,OAAO,CAAC,4BAA4B;IACtD,gBAAgB,EAAE,OAAO,CAAC,4BAA4B;IACtD,cAAc,EAAE,OAAO,CAAC,2BAA2B;IACnD,cAAc,EAAE,OAAO,CAAC,2BAA2B;IACnD,cAAc,EAAE,OAAO,CAAC,0BAA0B;IAClD,sBAAsB,EAAE,OAAO,CAAC,iCAAiC;IACjE,4BAA4B,EAAE,OAAO,CAAC,wCAAwC;IAC9E,cAAc,EAAE,OAAO,CAAC,2BAA2B;IACnD,gBAAgB,EAAE,OAAO,CAAC,6BAA6B;IACvD,WAAW,EAAE,OAAO,CAAC,wBAAwB;IAC7C,eAAe,EAAE,OAAO,CAAC,4BAA4B;IACrD,cAAc,EAAE,OAAO,CAAC,2BAA2B;IACnD,sBAAsB,EAAE,OAAO,CAAC,kCAAkC;CACnE,CAAC"}
+{"version":3,"file":"response-schemas.js","sourceRoot":"","sources":["../../../src/lib/utils/response-schemas.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGH,oEAAsD;AAEzC,QAAA,qBAAqB,GAAuC;IACvE,gCAAgC;IAChC,YAAY,EAAE,OAAO,CAAC,yBAAyB;IAC/C,gBAAgB,EAAE,OAAO,CAAC,4BAA4B;IACtD,gBAAgB,EAAE,OAAO,CAAC,4BAA4B;IACtD,cAAc,EAAE,OAAO,CAAC,0BAA0B;IAClD,sBAAsB,EAAE,OAAO,CAAC,iCAAiC;IACjE,4BAA4B,EAAE,OAAO,CAAC,wCAAwC;IAE9E,WAAW;IACX,qBAAqB,EAAE,OAAO,CAAC,iCAAiC;IAChE,cAAc,EAAE,OAAO,CAAC,2BAA2B;IACnD,gBAAgB,EAAE,OAAO,CAAC,6BAA6B;IACvD,cAAc,EAAE,OAAO,CAAC,2BAA2B;IACnD,cAAc,EAAE,OAAO,CAAC,2BAA2B;IACnD,qBAAqB,EAAE,OAAO,CAAC,iCAAiC;IAEhE,UAAU;IACV,WAAW,EAAE,OAAO,CAAC,wBAAwB;IAC7C,eAAe,EAAE,OAAO,CAAC,4BAA4B;IAErD,qBAAqB;IACrB,aAAa,EAAE,OAAO,CAAC,0BAA0B;IACjD,aAAa,EAAE,OAAO,CAAC,0BAA0B;IACjD,eAAe,EAAE,OAAO,CAAC,4BAA4B;IACrD,cAAc,EAAE,OAAO,CAAC,2BAA2B;IAEnD,kDAAkD;IAClD,oBAAoB,EAAE,OAAO,CAAC,gCAAgC;IAC9D,iBAAiB,EAAE,OAAO,CAAC,6BAA6B;IACxD,oBAAoB,EAAE,OAAO,CAAC,gCAAgC;IAC9D,mBAAmB,EAAE,OAAO,CAAC,+BAA+B;IAC5D,oBAAoB,EAAE,OAAO,CAAC,gCAAgC;IAC9D,sBAAsB,EAAE,OAAO,CAAC,kCAAkC;IAClE,qBAAqB,EAAE,OAAO,CAAC,iCAAiC;IAChE,iBAAiB,EAAE,OAAO,CAAC,8BAA8B;IACzD,yBAAyB,EAAE,OAAO,CAAC,qCAAqC;IAExE,sBAAsB;IACtB,UAAU,EAAE,OAAO,CAAC,uBAAuB;IAC3C,gBAAgB,EAAE,OAAO,CAAC,6BAA6B;IACvD,mBAAmB,EAAE,OAAO,CAAC,+BAA+B;IAC5D,mBAAmB,EAAE,OAAO,CAAC,8BAA8B;IAE3D,yBAAyB;IACzB,eAAe,EAAE,OAAO,CAAC,2BAA2B;IACpD,mBAAmB,EAAE,OAAO,CAAC,+BAA+B;IAC5D,eAAe,EAAE,OAAO,CAAC,2BAA2B;IACpD,oBAAoB,EAAE,OAAO,CAAC,gCAAgC;IAE9D,eAAe;IACf,qBAAqB,EAAE,OAAO,CAAC,iCAAiC;IAEhE,kBAAkB;IAClB,sBAAsB,EAAE,OAAO,CAAC,kCAAkC;CACnE,CAAC"}

package/dist/lib/utils/validate-user-agent.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Validate a user-agent string for safe use in HTTP headers.
+ * Rejects newlines (CRLF injection) and null bytes (header truncation).
+ *
+ * @throws {Error} if the value contains forbidden characters
+ */
+export declare function validateUserAgent(value: string): void;
+//# sourceMappingURL=validate-user-agent.d.ts.map

package/dist/lib/utils/validate-user-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-user-agent.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/validate-user-agent.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAIrD"}

package/dist/lib/utils/validate-user-agent.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateUserAgent = validateUserAgent;
+/**
+ * Validate a user-agent string for safe use in HTTP headers.
+ * Rejects newlines (CRLF injection) and null bytes (header truncation).
+ *
+ * @throws {Error} if the value contains forbidden characters
+ */
+function validateUserAgent(value) {
+    if (/[\r\n\x00]/.test(value)) {
+        throw new Error('userAgent must not contain newline or null characters');
+    }
+}
+//# sourceMappingURL=validate-user-agent.js.map

package/dist/lib/utils/validate-user-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-user-agent.js","sourceRoot":"","sources":["../../../src/lib/utils/validate-user-agent.ts"],"names":[],"mappings":";;AAMA,8CAIC;AAVD;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,KAAa;IAC7C,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;AACH,CAAC"}

package/dist/lib/version.d.ts

@@ -6,6 +6,12 @@ export declare const LIBRARY_VERSION = "4.20.0";
  * AdCP specification version this library is built for
  */
 export declare const ADCP_VERSION = "latest";
+/**
+ * AdCP major version sent with every request (adcp_major_version field).
+ * Sellers validate this against their supported versions and return
+ * VERSION_UNSUPPORTED if the version is not in range.
+ */
+export declare const ADCP_MAJOR_VERSION = 3;
 /**
  * AdCP versions this library maintains backward compatibility with
  */

package/dist/lib/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/lib/version.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,eAAO,MAAM,eAAe,WAAW,CAAC;AAExC;;GAEG;AACH,eAAO,MAAM,YAAY,WAAW,CAAC;AAErC;;GAEG;AACH,eAAO,MAAM,wBAAwB,iEAAkE,CAAC;AAExG;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;CAKf,CAAC;AAEX;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,SAAS,MAAM,EAAE,CAEzD"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/lib/version.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,eAAO,MAAM,eAAe,WAAW,CAAC;AAExC;;GAEG;AACH,eAAO,MAAM,YAAY,WAAW,CAAC;AAErC;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;GAEG;AACH,eAAO,MAAM,wBAAwB,iEAAkE,CAAC;AAExG;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;CAKf,CAAC;AAEX;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,SAAS,MAAM,EAAE,CAEzD"}

package/dist/lib/version.js

@@ -2,7 +2,7 @@
 // Generated version information
 // This file is auto-generated by sync-version.ts
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VERSION_INFO = exports.COMPATIBLE_ADCP_VERSIONS = exports.ADCP_VERSION = exports.LIBRARY_VERSION = void 0;
+exports.VERSION_INFO = exports.COMPATIBLE_ADCP_VERSIONS = exports.ADCP_MAJOR_VERSION = exports.ADCP_VERSION = exports.LIBRARY_VERSION = void 0;
 exports.getAdcpVersion = getAdcpVersion;
 exports.getLibraryVersion = getLibraryVersion;
 exports.isCompatibleWith = isCompatibleWith;
@@ -15,6 +15,12 @@ exports.LIBRARY_VERSION = '4.20.0';
  * AdCP specification version this library is built for
  */
 exports.ADCP_VERSION = 'latest';
+/**
+ * AdCP major version sent with every request (adcp_major_version field).
+ * Sellers validate this against their supported versions and return
+ * VERSION_UNSUPPORTED if the version is not in range.
+ */
+exports.ADCP_MAJOR_VERSION = 3;
 /**
  * AdCP versions this library maintains backward compatibility with
  */

package/dist/lib/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/lib/version.ts"],"names":[],"mappings":";AAAA,gCAAgC;AAChC,iDAAiD;;;AA8BjD,wCAEC;AAKD,8CAEC;AAKD,4CAEC;AAKD,sDAEC;AAnDD;;GAEG;AACU,QAAA,eAAe,GAAG,QAAQ,CAAC;AAExC;;GAEG;AACU,QAAA,YAAY,GAAG,QAAQ,CAAC;AAErC;;GAEG;AACU,QAAA,wBAAwB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,cAAc,CAAU,CAAC;AAExG;;GAEG;AACU,QAAA,YAAY,GAAG;IAC1B,OAAO,EAAE,QAAQ;IACjB,IAAI,EAAE,QAAQ;IACd,kBAAkB,EAAE,gCAAwB;IAC5C,WAAW,EAAE,0BAA0B;CAC/B,CAAC;AAEX;;GAEG;AACH,SAAgB,cAAc;IAC5B,OAAO,oBAAY,CAAC;AACtB,CAAC;AAED;;GAEG;AACH,SAAgB,iBAAiB;IAC/B,OAAO,uBAAe,CAAC;AACzB,CAAC;AAED;;GAEG;AACH,SAAgB,gBAAgB,CAAC,WAAmB;IAClD,OAAQ,gCAA8C,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AAC/E,CAAC;AAED;;GAEG;AACH,SAAgB,qBAAqB;IACnC,OAAO,gCAAwB,CAAC;AAClC,CAAC"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/lib/version.ts"],"names":[],"mappings":";AAAA,gCAAgC;AAChC,iDAAiD;;;AAqCjD,wCAEC;AAKD,8CAEC;AAKD,4CAEC;AAKD,sDAEC;AA1DD;;GAEG;AACU,QAAA,eAAe,GAAG,QAAQ,CAAC;AAExC;;GAEG;AACU,QAAA,YAAY,GAAG,QAAQ,CAAC;AAErC;;;;GAIG;AACU,QAAA,kBAAkB,GAAG,CAAC,CAAC;AAEpC;;GAEG;AACU,QAAA,wBAAwB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,cAAc,CAAU,CAAC;AAExG;;GAEG;AACU,QAAA,YAAY,GAAG;IAC1B,OAAO,EAAE,QAAQ;IACjB,IAAI,EAAE,QAAQ;IACd,kBAAkB,EAAE,gCAAwB;IAC5C,WAAW,EAAE,0BAA0B;CAC/B,CAAC;AAEX;;GAEG;AACH,SAAgB,cAAc;IAC5B,OAAO,oBAAY,CAAC;AACtB,CAAC;AAED;;GAEG;AACH,SAAgB,iBAAiB;IAC/B,OAAO,uBAAe,CAAC;AACzB,CAAC;AAED;;GAEG;AACH,SAAgB,gBAAgB,CAAC,WAAmB;IAClD,OAAQ,gCAA8C,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AAC/E,CAAC;AAED;;GAEG;AACH,SAAgB,qBAAqB;IACnC,OAAO,gCAAwB,CAAC;AAClC,CAAC"}

package/docs/README.md

@@ -0,0 +1,42 @@
+# ADCP Client Documentation
+
+Complete documentation for the `@adcp/client` TypeScript library.
+
+## 📚 Getting Started
+
+Start here if you're new to ADCP or this library:
+
+- **[Getting Started Guide](./guides/getting-started.md)** - Comprehensive tutorial from installation to advanced patterns
+- **[MCP Testing Guide](./guides/MCP_TESTING.md)** - Working with Model Context Protocol agents
+
+## 🏗️ Advanced Topics
+
+For developers building production applications:
+
+- **[Production Deployment](./advanced/PRODUCTION-READY.md)** - Production best practices and configurations  
+- **[Deployment Guide](./advanced/DEPLOYMENT.md)** - Deploy testing framework to cloud platforms
+- **[Testing Strategy](./advanced/TESTING-STRATEGY.md)** - Comprehensive testing approaches
+
+## 📖 API Reference
+
+Detailed technical reference:
+
+- **[TypeDoc API Reference](./api/)** - Generated from source code (coming soon)
+- **[Protocol Types](../src/lib/types/)** - TypeScript type definitions
+
+## 🤝 Contributing
+
+Want to contribute to the library?
+
+- **[Contributing Guidelines](../CONTRIBUTING.md)** - How to contribute code, docs, and examples
+- **[Security Policy](../SECURITY.md)** - Security reporting and best practices
+
+## 📋 Reference
+
+- **[Changelog](../CHANGELOG.md)** - Version history and breaking changes
+- **[AdCP Specification](https://adcontextprotocol.org)** - Official protocol documentation
+- **[Examples](../examples/)** - Real-world usage examples
+
+---
+
+> **Quick Start**: If you just want to get up and running quickly, check the main [README.md](../README.md) for a condensed quick start guide.

package/docs/guides/BUILD-AN-AGENT.md

@@ -0,0 +1,292 @@
+# Build an AdCP Agent
+
+## Overview
+
+This guide walks through building an AdCP agent (server) using `@adcp/client`. While most documentation covers the client side — calling existing agents — this guide covers the server side: implementing an agent that other clients can discover and call.
+
+We'll build a **signals agent** that serves audience segments via the `get_signals` tool. The same patterns apply to any AdCP tool (`get_products`, `create_media_buy`, etc.).
+
+## Prerequisites
+
+- Node.js 18+
+- `@adcp/client` installed (`npm install @adcp/client`)
+- `@modelcontextprotocol/sdk` (installed as a dependency of `@adcp/client`)
+
+## Quick Start
+
+A minimal signals agent in ~20 lines:
+
+```typescript
+import {
+  createTaskCapableServer,
+  taskToolResponse,
+  serve,
+  GetSignalsRequestSchema,
+} from '@adcp/client';
+
+function createAgent() {
+  const server = createTaskCapableServer('My Signals Agent', '1.0.0');
+
+  server.tool(
+    'get_signals',
+    'Discover audience segments.',
+    GetSignalsRequestSchema.shape,
+    async (args) => {
+      const signals = [
+        {
+          signal_agent_segment_id: 'demo_segment',
+          signal_id: { source: 'catalog', data_provider_domain: 'example.com', id: 'demo_segment' },
+          name: 'Demo Segment',
+          description: 'A demo audience segment.',
+          value_type: 'binary',
+          signal_type: 'owned',
+          data_provider: 'My Agent',
+          coverage_percentage: 10,
+          deployments: [],
+          pricing_options: [
+            { pricing_option_id: 'po_demo', model: 'cpm', currency: 'USD', cpm: 5 },
+          ],
+        },
+      ];
+
+      return taskToolResponse({ signals, sandbox: true }, `Found ${signals.length} segment(s)`);
+    },
+  );
+
+  return server;
+}
+
+serve(createAgent); // listening on http://localhost:3001/mcp
+```
+
+Start it and test immediately:
+
+```bash
+npx tsx agent.ts
+npx @adcp/client http://localhost:3001/mcp                    # discover tools
+npx @adcp/client http://localhost:3001/mcp get_signals '{}'   # call get_signals
+```
+
+## Key Concepts
+
+### createTaskCapableServer
+
+Creates an MCP server pre-configured with task support (async operations). This is the recommended way to build AdCP agents — it handles task lifecycle plumbing so you can focus on business logic.
+
+```typescript
+import { createTaskCapableServer } from '@adcp/client';
+
+const server = createTaskCapableServer('Agent Name', '1.0.0', {
+  instructions: 'Description of what your agent does.',
+});
+```
+
+For sync-only tools, use `server.tool()` directly. For tools that need async processing, use `registerAdcpTaskTool()` which requires explicit `createTask`/`getTask`/`getTaskResult` handlers.
+
+### Generated Schemas
+
+`@adcp/client` exports Zod schemas for every AdCP tool's input and output. Use these instead of hand-rolling JSON Schema definitions:
+
+```typescript
+import {
+  GetSignalsRequestSchema,    // input validation for get_signals
+  GetSignalsResponseSchema,   // output validation
+  GetProductsRequestSchema,   // input validation for get_products
+  CreateMediaBuyRequestSchema,
+} from '@adcp/client';
+
+// The MCP SDK expects a plain object of Zod fields, not a Zod schema — .shape unwraps it.
+server.tool('get_signals', 'Discover audience segments.', GetSignalsRequestSchema.shape, async (args) => {
+  // args is fully typed from the schema
+});
+```
+
+### taskToolResponse
+
+Builds a properly formatted MCP `CallToolResult` from your response data:
+
+```typescript
+import { taskToolResponse } from '@adcp/client';
+
+// Returns { content: [{ type: 'text', text: '...' }] }
+return taskToolResponse(
+  { signals: [...], sandbox: true },
+  'Found 3 audience segment(s)',  // summary text
+);
+```
+
+For media buy and product tools, dedicated response builders are also available:
+
+```typescript
+import { productsResponse, mediaBuyResponse, deliveryResponse, adcpError } from '@adcp/client';
+```
+
+### Task Statuses (Server-Side Contract)
+
+When your agent receives a tool call, it returns one of these statuses. The buyer client handles each differently:
+
+| Status | When to use | What the buyer client does |
+|--------|------------|---------------------------|
+| `completed` | Request fulfilled synchronously | Reads `result.data` and proceeds |
+| `working` | Processing started, not done yet | Polls `tasks/get` until status changes |
+| `submitted` | Will notify via webhook when done | Waits for webhook delivery at `push_notification_config.url` |
+| `input_required` | Need clarification from buyer | Fires buyer's `InputHandler` callback with the question |
+| `deferred` | Requires human decision | Returns a token; human resumes later via `result.deferred.resume()` |
+
+For synchronous tools, use `taskToolResponse()` — it sets `completed` automatically:
+
+```typescript
+return taskToolResponse({ signals: [...], sandbox: true }, 'Found 3 segments');
+```
+
+For async tools that need background processing, use `registerAdcpTaskTool()`:
+
+```typescript
+import { registerAdcpTaskTool, InMemoryTaskStore } from '@adcp/client';
+
+const taskStore = new InMemoryTaskStore();
+
+registerAdcpTaskTool(server, taskStore, {
+  name: 'create_media_buy',
+  description: 'Create a media buy.',
+  schema: CreateMediaBuyRequestSchema.shape,
+  createTask: async (args) => {
+    // Start processing, return a task ID
+    const taskId = crypto.randomUUID();
+    processInBackground(taskId, args); // your async logic
+    return { taskId, status: 'submitted' };
+  },
+  getTask: async (taskId) => taskStore.get(taskId),
+  getTaskResult: async (taskId) => taskStore.getResult(taskId),
+});
+```
+
+**Error responses**: Use `adcpError()` with standard error codes. The buyer agent uses the `recovery` classification to decide retry behavior:
+
+```typescript
+import { adcpError } from '@adcp/client';
+
+// correctable — buyer should fix params and retry
+return adcpError('BUDGET_TOO_LOW', 'Minimum budget is $1,000');
+
+// transient — buyer should retry after delay
+return adcpError('SERVICE_UNAVAILABLE', 'Try again in 30 seconds');
+
+// terminal — buyer should stop
+return adcpError('ACCOUNT_SUSPENDED', 'Contact support');
+```
+
+See `docs/llms.txt` for the full error code table with recovery classifications.
+
+### Storyboards
+
+The `storyboards/` directory contains YAML files that define exactly what tool call sequences a buyer agent will make against your server. Each storyboard includes phases, steps, sample requests/responses, and validation rules.
+
+Key storyboards for server-side builders:
+- `media_buy_non_guaranteed.yaml` — auction-based buying flow
+- `media_buy_guaranteed_approval.yaml` — guaranteed buying with IO approval
+- `media_buy_proposal_mode.yaml` — proposal-based buying
+- `creative_sales_agent.yaml` — push creative assets to your platform
+- `signal_marketplace.yaml` / `signal_owned.yaml` — signals agent flows
+- `si_session.yaml` — sponsored intelligence sessions
+- `media_buy_governance_escalation.yaml` — governance with human escalation
+
+### HTTP Transport
+
+The `serve()` helper handles HTTP transport setup. Pass it a factory function that returns a configured `McpServer`:
+
+```typescript
+import { serve } from '@adcp/client';
+
+serve(createMyAgent);                          // defaults: port 3001, path /mcp
+serve(createMyAgent, { port: 8080 });          // custom port
+serve(createMyAgent, { path: '/v1/mcp' });     // custom path
+```
+
+`serve()` returns the underlying `http.Server` for lifecycle control (e.g., graceful shutdown).
+
+For custom routing or middleware, you can wire the transport manually:
+
+```typescript
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createServer } from 'http';
+
+const httpServer = createServer(async (req, res) => {
+  if (req.url === '/mcp' || req.url === '/mcp/') {
+    const agentServer = createMyAgent();
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+    try {
+      await agentServer.connect(transport);
+      await transport.handleRequest(req, res);
+    } catch (err) {
+      console.error('Server error:', err);
+      if (!res.headersSent) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Internal server error' }));
+      }
+    } finally {
+      await agentServer.close();
+    }
+  } else {
+    res.writeHead(404);
+    res.end('Not found');
+  }
+});
+```
+
+## Testing Your Agent
+
+### Tool Discovery
+
+```bash
+npx @adcp/client http://localhost:3001/mcp
+```
+
+This lists all tools your agent exposes, their descriptions, and parameters. If `get_signals` appears with the correct schema, your agent is wired up correctly.
+
+### Calling Tools
+
+```bash
+# All segments
+npx @adcp/client http://localhost:3001/mcp get_signals '{"signal_spec":"audience segments"}'
+
+# Filtered by text
+npx @adcp/client http://localhost:3001/mcp get_signals '{"signal_spec":"shoppers"}'
+
+# Filtered by catalog type
+npx @adcp/client http://localhost:3001/mcp get_signals '{"filters":{"catalog_types":["marketplace"]}}'
+
+# JSON output for scripting
+npx @adcp/client http://localhost:3001/mcp get_signals '{}' --json
+```
+
+### Compliance Check
+
+```bash
+npx @adcp/client comply http://localhost:3001/mcp
+```
+
+This runs a standard validation suite against your agent to check AdCP compliance.
+
+## Complete Example
+
+See [`examples/signals-agent.ts`](../../examples/signals-agent.ts) for a complete, runnable signals agent with:
+
+- Three audience segments (owned, custom, marketplace)
+- Text search via `signal_spec`
+- Filtering by `signal_ids` and `catalog_types`
+- Result limiting via `max_results`
+- Proper HTTP transport setup
+
+See [`examples/error-compliant-server.ts`](../../examples/error-compliant-server.ts) for a media buy agent demonstrating:
+
+- Multiple tools (`get_products`, `create_media_buy`, `get_media_buy_delivery`)
+- Structured error handling with `adcpError()`
+- Rate limiting
+- Business logic validation
+
+## Related
+
+- [`registerAdcpTaskTool()`](../../src/lib/server/tasks.ts) — for async tools that need background processing
+- [`examples/error-compliant-server.ts`](../../examples/error-compliant-server.ts) — media buy agent with multiple tools and error handling
+- [AdCP specification](https://adcontextprotocol.org) — full protocol reference