docs: import agentic-commerce doc files (allow to keep agentic-commer…

docs/agentic-commerce/README.md

@@ -0,0 +1,70 @@
+# @bosonprotocol/agentic-commerce
+
+![tests](https://img.shields.io/badge/tests-995%2F1011%20passing-orange)
+![coverage](https://img.shields.io/badge/coverage-58.9%25-orange)
+![ESLint](https://img.shields.io/badge/ESLint-0%20warnings-brightgreen)
+![TypeScript](https://img.shields.io/badge/TypeScript-passing-brightgreen)
+
+MCP server, MCP client, and GOAT SDK plugin for [Boson Protocol](https://bosonprotocol.io) — the decentralized Agentic Commerce Protocol (dACP) that enables agents to securely buy and sell anything — digital or physical — with game-theoretic guarantees.
+
+## 🤖 For AI Agents
+
+**See [AGENTS.md](https://github.com/bosonprotocol/agent-builder/blob/HEAD/docs/agentic-commerce/AGENTS.md) for a comprehensive AI agent guide** covering end-to-end selling and buying flows, exchange lifecycle, configuration, and integration options. Claude Code auto-loads it via the `CLAUDE.md` → `@AGENTS.md` import.
+
+**Hosted MCP servers (no setup required):**
+- Staging: `https://mcp-staging.bosonprotocol.io/mcp`
+- Production: `https://mcp.bosonprotocol.io/mcp`
+
+## 📚 Documentation
+
+- [AI Agent Guide](https://github.com/bosonprotocol/agent-builder/blob/HEAD/docs/agentic-commerce/AGENTS.md) — End-to-end flows, exchange & dispute lifecycles, enums, integration options
+- [MCP Server README](https://github.com/bosonprotocol/agent-builder/blob/HEAD/docs/agentic-commerce/src/boson/mcp-server/README.md) — All 56 tools, 2 prompts, 10 resources with full parameter reference
+- [MCP Client README](https://github.com/bosonprotocol/agent-builder/blob/HEAD/docs/agentic-commerce/src/boson/mcp-client/README.md) — TypeScript client usage
+- [GOAT SDK Plugin README](https://github.com/bosonprotocol/agent-builder/blob/HEAD/docs/agentic-commerce/src/boson/goat-sdk-plugin/README.md) — Agent framework integration (Anthropic, Vercel AI)
+- [High Value Asset Module README](https://github.com/bosonprotocol/agent-builder/blob/HEAD/docs/agentic-commerce/src/fermion/README.md) — High-value/luxury asset marketplace (formerly Fermion Protocol, integrated into Boson in 2025)
+- [E2E Test Suite](https://github.com/bosonprotocol/agent-builder/blob/HEAD/docs/agentic-commerce/e2e/boson/tests/complete-marketplace-journeys.test.ts) — Runnable reference for every seller/buyer/dispute flow
+- [Boson Protocol Docs](https://docs.bosonprotocol.io) — Protocol concepts and architecture
+- [Agent Integration Docs](https://docs.bosonprotocol.io/using-the-protocol/agent-integration) — MCP + GOAT SDK guide on the protocol site
+
+---
+
+## 🧪 Development
+
+```bash
+# Install dependencies
+pnpm i --frozen-lockfile
+
+# Watch mode for development
+pnpm watch
+
+# Run each in a terminal:
+pnpm dev:boson:http
+pnpm dev:boson:http:inspector
+
+# Run all tests
+pnpm test
+
+# Run with coverage
+pnpm test:coverage
+
+# Linting and type checking
+pnpm lint
+pnpm typecheck
+```
+
+## 📋 Environment Setup
+
+1. Copy `mcpServer.example.json` to `mcpServer.json` if not automatically done
+2. Update the args array to match the real path to the file to be run
+
+## 📋 Requirements
+
+- Node.js 23+
+- Infura project ID and secret (check `.env.example`)
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request

docs/agentic-commerce/README.npm.md

@@ -0,0 +1,70 @@
+# @bosonprotocol/agentic-commerce
+
+![tests](https://img.shields.io/badge/tests-995%2F1011%20passing-orange)
+![coverage](https://img.shields.io/badge/coverage-58.9%25-orange)
+![ESLint](https://img.shields.io/badge/ESLint-0%20warnings-brightgreen)
+![TypeScript](https://img.shields.io/badge/TypeScript-passing-brightgreen)
+
+MCP server, MCP client, and GOAT SDK plugin for [Boson Protocol](https://bosonprotocol.io) — the decentralized Agentic Commerce Protocol (dACP) that enables agents to securely buy and sell anything — digital or physical — with game-theoretic guarantees.
+
+## 🤖 For AI Agents
+
+**See [AGENTS.md](https://github.com/bosonprotocol/agent-builder/blob/HEAD/docs/agentic-commerce/AGENTS.md) for a comprehensive AI agent guide** covering end-to-end selling and buying flows, exchange lifecycle, configuration, and integration options. Claude Code auto-loads it via the `CLAUDE.md` → `@AGENTS.md` import.
+
+**Hosted MCP servers (no setup required):**
+- Staging: `https://mcp-staging.bosonprotocol.io/mcp`
+- Production: `https://mcp.bosonprotocol.io/mcp`
+
+## 📚 Documentation
+
+- [AI Agent Guide](https://github.com/bosonprotocol/agent-builder/blob/HEAD/docs/agentic-commerce/AGENTS.md) — End-to-end flows, exchange & dispute lifecycles, enums, integration options
+- [MCP Server README](https://github.com/bosonprotocol/agent-builder/blob/HEAD/docs/agentic-commerce/src/boson/mcp-server/README.md) — All 56 tools, 2 prompts, 10 resources with full parameter reference
+- [MCP Client README](https://github.com/bosonprotocol/agent-builder/blob/HEAD/docs/agentic-commerce/src/boson/mcp-client/README.md) — TypeScript client usage
+- [GOAT SDK Plugin README](https://github.com/bosonprotocol/agent-builder/blob/HEAD/docs/agentic-commerce/src/boson/goat-sdk-plugin/README.md) — Agent framework integration (Anthropic, Vercel AI)
+- [High Value Asset Module README](https://github.com/bosonprotocol/agent-builder/blob/HEAD/docs/agentic-commerce/src/fermion/README.md) — High-value/luxury asset marketplace (formerly Fermion Protocol, integrated into Boson in 2025)
+- [E2E Test Suite](https://github.com/bosonprotocol/agent-builder/blob/HEAD/docs/agentic-commerce/e2e/boson/tests/complete-marketplace-journeys.test.ts) — Runnable reference for every seller/buyer/dispute flow
+- [Boson Protocol Docs](https://docs.bosonprotocol.io) — Protocol concepts and architecture
+- [Agent Integration Docs](https://docs.bosonprotocol.io/using-the-protocol/agent-integration) — MCP + GOAT SDK guide on the protocol site
+
+---
+
+## 🧪 Development
+
+```bash
+# Install dependencies
+pnpm i --frozen-lockfile
+
+# Watch mode for development
+pnpm watch
+
+# Run each in a terminal:
+pnpm dev:boson:http
+pnpm dev:boson:http:inspector
+
+# Run all tests
+pnpm test
+
+# Run with coverage
+pnpm test:coverage
+
+# Linting and type checking
+pnpm lint
+pnpm typecheck
+```
+
+## 📋 Environment Setup
+
+1. Copy `mcpServer.example.json` to `mcpServer.json` if not automatically done
+2. Update the args array to match the real path to the file to be run
+
+## 📋 Requirements
+
+- Node.js 23+
+- Infura project ID and secret (check `.env.example`)
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request

docs/agentic-commerce/docs/fermion/create-mcp-client.md

@@ -0,0 +1,22 @@
+# Create a High Value Asset Module MCP-Client
+
+> **Note:** "Fermion" is no longer used as a brand. The former Fermion Protocol was integrated into the Boson codebase in 2025 and is now the **High Value Asset Module** of Boson Protocol. The directory name `fermion/`, service names, and SDK package names are retained for code-level compatibility.
+
+The following documentation describes how to create an MCP client to connect an AI Agent to the High Value Asset Module's MCP server.
+
+In this example, the AI Agent using the MCP client will be able to use the module's MCP server to act as a Seller on the High Value Asset Module, create an offer, mint and list tokens (FNFTs), and so on (see the module's Seller flow).
+
+## Prerequisite
+
+Make sure:
+- you have a functional Local Environment running (see [setup-local-env](./setup-local-env.md))
+
+## Create an mcp-client
+
+Creating an MCP client is straightforward using the typescript_sdk and the example given in their GitHub repo (See [MCP typescript_sdk](https://github.com/modelcontextprotocol/typescript-sdk?tab=readme-ov-file#writing-mcp-clients)).
+
+The Client needs to connect using Streamable HTTP (as it's the transport type activated on the MCP-Server container), via the URL "http://localhost:3000/mcp".
+
+Other SDKs are also available in different languages (Python, Java, Kotlin, C#). See [modelcontextprotocol](https://github.com/modelcontextprotocol).
+
+An example is given in [./example/create-mcp-client.ts](./example/create-mcp-client.ts)

docs/agentic-commerce/docs/fermion/example/create-mcp-client.ts

@@ -0,0 +1,35 @@
+/**
+ * Create an mcp-client and connect it to the mcp-server running in the Local Environment
+ * 
+ * This script can be run using ts-node: 
+ * > npx ts-node runit.ts -- createMcpClient
+ */
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+const mcpServerUrl = "http://localhost:3000/mcp";
+
+export async function createMcpClient(listTools = true) {
+  const transport = new StreamableHTTPClientTransport(new URL(mcpServerUrl));
+  const client = new Client(
+    {
+      name: "fermion-mcp-client",
+      version: "1.0.0"
+    }
+  );
+  await client.connect(transport);
+
+  if (listTools) {
+    // List tools
+    const { tools } = await client.listTools();
+    console.log(tools.map((tool) => {
+      return {
+        name: tool.name,
+        description: tool.description,
+        input_schema: JSON.stringify(tool.inputSchema),
+      };
+    }));
+  }
+  return client;
+}

docs/agentic-commerce/docs/fermion/example/create-offer.ts

@@ -0,0 +1,184 @@
+/**
+ * Create an offer for a given entity identified with a given wallet.
+ *
+ * This script can be run using ts-node:
+ * > npx ts-node runit.ts -- createOffer
+ */
+
+import { Interface } from "@ethersproject/abi";
+import { Wallet } from "ethers";
+import {
+  EnvironmentType,
+  ConfigId,
+  TransactionRequest,
+  Log,
+  abis,
+} from "@fermionprotocol/common";
+import { createMcpClient } from "./create-mcp-client";
+import { checkSellerEntity } from "./seller-entity-creation";
+import { ReturnTypeMcp } from "../../../src/common/mcp-server/mcpTypes";
+import { signTransaction } from "./sign-transaction";
+
+const context = {
+  // EnvironmentType of the Local Environment
+  envName: "local" as EnvironmentType,
+  // ConfigId of the Local Environment
+  configId: "local-31337-0" as ConfigId,
+  // One of the pre-funded accounts in the Local Environment (https://github.com/fermionprotocol/contracts/blob/main/e2e/accounts.ts)
+  privateKey:
+    "0xa2e78cd4c87191e50d6a8f1610b1cf160b17216e9090dde7a92960a34c310482",
+  // Local Environment RPC Node
+  rpcNode: "http://localhost:8545",
+  // ERC20 token deployed on Local Environment
+  exchangeToken: "0x82e01223d51Eb87e16A03E24687EDF0F294da6f1",
+};
+
+const offerMetadata = {
+  schemaUrl: "https://json-schema.org",
+  type: "FERMION_OFFER",
+  uuid: "ecf2a6dc-555b-41b5-aca8-b7e29eebbb30",
+  name: "Boson X MetaFactory Hoodie",
+  description:
+    "The future is here and it starts with a limited edition MetaFactory X Boson Protocol Hoodie... This unisex hoodie, in a metablack coloureway with reflective stripes, is made from a heavyweight French terry cotton. It has an adjustable hood and full colour interior, elasticated trims, reflective lining, and reflective back panels... Nothing says open metaverse more than this collab between MetaFactory and Boson Protocol. Limited Edition: Only 75 ever made.",
+  externalUrl:
+    "https://app.bosonportal.io/#/offer-uuid/ecf2a6dc-555b-41b5-aca8-b7e29eebbb30",
+  licenseUrl:
+    "https://app.bosonportal.io/#/license/ecf2a6dc-555b-41b5-aca8-b7e29eebbb30",
+  image:
+    "https://bsn-portal-production-image-upload-storage.s3.amazonaws.com/fc11acc4-e27b-4ede-b7d3-f16735fab406",
+  attributes: [] as unknown[],
+  product: {
+    uuid: "77593bb2-f797-11ec-b939-0242ac120002",
+    version: 1,
+    title: "Boson X MetaFactory Hoodie",
+    description:
+      "The future is here and it starts with a limited edition MetaFactory X Boson Protocol Hoodie... This unisex hoodie, in a metablack coloureway with reflective stripes, is made from a heavyweight French terry cotton. It has an adjustable hood and full colour interior, elasticated trims, reflective lining, and reflective back panels... Nothing says open metaverse more than this collab between MetaFactory and Boson Protocol. Limited Edition: Only 75 ever made.",
+    productionInformation_brandName: "Boson X MetaFactory",
+    details_offerCategory: "PHYSICAL",
+    condition: {
+      value: "new",
+    },
+    category: {
+      value: "fashion",
+    },
+    visuals_images: [
+      {
+        url: "https://bsn-portal-production-image-upload-storage.s3.amazonaws.com/5ba6461b-e4b4-444d-90bf-0c9de1835c35",
+      },
+    ],
+  },
+  shipping: {
+    returnPolicy: {
+      url: "https://example.com/return-policy",
+    },
+    methods: [
+      {
+        value: "pickup",
+      },
+    ],
+  },
+};
+
+const offerParams = {
+  exchangeToken: context.exchangeToken,
+  sellerDeposit: "0",
+  verifierFee: "0",
+  custodianFee: {
+    amount: 0,
+    period: 3600 * 24 * 30,
+  },
+  facilitatorFeePercent: 0,
+  ...offerMetadata,
+};
+
+export async function createOffer() {
+  // Create the wallet (using ether.js v5*)
+  const wallet = new Wallet(context.privateKey);
+  // Check the seller Entity exists
+  const { entityId: sellerId } = await checkSellerEntity(wallet);
+  // Create the MCP Client
+  const mcpClient = await createMcpClient(false);
+  // Call the "initialize_sdk" tool first
+  await mcpClient.callTool({
+    name: "initialize_sdk",
+    arguments: {
+      configId: context.configId,
+      signerAddress: wallet.address,
+    },
+  });
+  // Call the "create_offer" tool
+  const createOfferResult = await mcpClient.callTool({
+    name: "create_offer",
+    arguments: {
+      sellerId,
+      facilitatorId: sellerId,
+      verifierId: sellerId,
+      custodianId: sellerId,
+      ...offerParams,
+    },
+  });
+  // Extract the TransactionData from the tool result
+  const { transactionData } = getContent<{
+    transactionData: Pick<TransactionRequest, "to" | "data">;
+  }>(createOfferResult as ReturnTypeMcp);
+  // Build and sign the blockchain transaction
+  const signedTransaction = await signTransaction(
+    transactionData,
+    context.privateKey,
+    context.rpcNode,
+  );
+  // Send the signed transaction calling the "send_signed_transaction" tool
+  const sendSignedTransactionResult = await mcpClient.callTool({
+    name: "send_signed_transaction",
+    arguments: {
+      signedTransaction,
+    },
+  });
+  // Extract the TransactionReceipt from the tool result
+  const { logs, hash } = getContent<{
+    hash: string;
+    logs: Log[];
+    blockNumber: number;
+  }>(sendSignedTransactionResult as ReturnTypeMcp);
+  // Find the offerId from the transaction Logs
+  const abi = new Interface(abis.IOfferEventsABI);
+  const [offerId] = logs
+    .map((log) => {
+      try {
+        return abi.parseLog(log);
+      } catch (error) {
+        // assume that failing to parse is irrelevant log
+        return null;
+      }
+    })
+    .filter((log) => log !== null)
+    .filter((log) => log.name === "OfferCreated")
+    .map((log) => log.args["bosonOfferId"]);
+  if (!offerId) {
+    throw new Error(
+      `Unable to retrieve the offerId from transation logs (hash: ${hash})`,
+    );
+  }
+  console.log(`Offer ${offerId} has been successfully created`);
+}
+
+function getContent<T>(toolResult: ReturnTypeMcp): T {
+  const contentText = toolResult?.content?.[0]?.text;
+  if (!contentText) {
+    throw new Error(
+      `Invalid return content from tool: ${JSON.stringify(toolResult)}`,
+    );
+  }
+  let contentJson;
+  try {
+    contentJson = JSON.parse(contentText);
+  } catch (e) {
+    console.error(
+      `Unable to parse JSON from ${contentText}. Error: ${e.toString()}`,
+    );
+  }
+  if (!contentJson.success) {
+    throw new Error(`Unsuccessful return from tool: ${contentText}`);
+  }
+  return contentJson as T;
+}