Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@commerce-evidence-toolkit Compare these product dimensions against our source rules and return match or hold."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Three local, read-only checks for agents working with product data. The package wraps the same versioned comparison rules published in the Agentic Commerce Field Guide.
Version 0.1.0 · MIT licensed. Download the versioned release, or run the source as described below. Registry availability is separate from a GitHub release; consult the live registry for its current state.
Tool | Inputs | Result |
| One product object, optional supplied evidence, | Selected-field review: |
| Explicit source and feed snapshots, item IDs, evidence references, timestamps and age policy |
|
| Same item and measurement basis, named length/width/height, units and tolerance |
|
The checks do not fetch references, authenticate evidence, contact a merchant, change a feed, place orders or send telemetry. A match is not provider acceptance, live product truth, physical fit or compatibility. This is a selected local review contract, not a complete provider schema validator. Hold results are evidence decisions, not protocol failures.
Related MCP server: trading-swarm-mcp
Download commerce-evidence-toolkit-0.1.0.mcpb and SHA256SUMS from the v0.1.0 release. Check the archive against its published SHA-256 checksum. The bundle contains the server and production dependencies; Node.js 22 or later is required.
Use your compatible client's MCPB import flow, or extract the archive to a directory and configure the absolute path to its server/index.mjs using the JSON example below. MCPB support varies by client. Protocol tests do not establish certification by any desktop app.
A Node package archive is also included in the release. Installing that archive requires npm to install its dependencies. It has not been published to npm.
Requires Node.js 22 or later and npm. Dependency installation uses the network; the three comparison operations run locally after installation.
npm ci --ignore-scripts
npm test
node server/index.mjsThe final command starts an MCP server over standard input/output. It waits for a compatible client; it is not a browser URL. Do not print debug messages to stdout, which carries the protocol.
For a compatible client that accepts an MCP JSON configuration, replace the path below with the absolute location of your checkout:
{
"mcpServers": {
"commerce-evidence": {
"command": "node",
"args": ["/absolute/path/agentic-commerce-field-guide/server/index.mjs"]
}
}
}Client configuration locations differ. This example declares the transport and executable; it does not claim every assistant automatically installs or invokes the server.
The files in examples/ are complete tool arguments, not bare internal records. The three starter examples below are fictional and use frozen times where relevant.
Tool | Arguments file | Expected example result |
|
| |
|
| |
|
|
Ask your client to call the named tool with that file's JSON object. Every successful response includes structured content with toolVersion, a canonical documentation URL and the full result. Each core result retains its own ruleset version and evidence limitations. Incomplete accepted inputs return holds; malformed envelopes and excessive requests return protocol tool errors. The wrapper caps serialized requests at 200,000 UTF-8 bytes and nesting at 25 levels; individual checks impose narrower limits.
Dimension values are positive decimal strings and explicit units (in, cm, mm, m); tolerance is a nonnegative decimal string in millimetres. Do not silently rename depth to length, treat diameter as two axes, or substitute package measurements. Product-record review covers selected positive USD fields; feed freshness is a selected current USD snapshot contract. References are caller assertions and are never fetched.
examples/observed-dimensions.json contains the HOLMERUD 40541421 dimensions observed on public US and GB product pages for the September 24 study. It returns match at the declared 2 mm display threshold and mismatch at zero. Fractional inch displays are represented exactly as decimals. The tool does not fetch or authenticate the linked sources. This threshold is not a manufacturing or installation tolerance. The study retains eight complete comparisons and 22 unresolved listings; it is not an industry error-rate estimate.
npm run verify:artifacts
npm test
node scripts/test-clean-install.mjs
npm run bundlenpm run bundle creates a local .mcpb archive with the production dependencies and a SHA-256 file under dist/. The Node package can be built with npm pack. A local package build is not an npm or MCP Registry publication.
The test suite compares all 40 fixture/method cases against their source rules (10 dimensions, 6 freshness, and 12 product records under 2 methods), checks error bounds and input immutability, and invokes all 40 over stdio with the TypeScript SDK client. The clean-install test installs the archive into a temporary directory and calls all three tools. A separate Python SDK client test calls all three examples and an incomplete-input hold. These are protocol tests with synthetic inputs, not independent users or desktop-app certification.
provenance.json records the source site commit, actual production download verification time, and SHA-256 for every file in artifacts/. The September 24 snapshot adds dimensions to the existing product-feed and measurement artifacts. Verification recomputes hashes and the earlier portability/freshness cases. Synthetic cases show rule behavior, not merchant error rates or model accuracy.
Primary tool documentation:
Please cite the relevant guide and this version or commit. CITATION.cff provides author metadata. To report a correction, open an issue with the tool version, a minimal non-sensitive input, expected result, actual result and supporting reference. Never post customer data or credentials.
Original software, documentation, tests and fictional fixtures are available under the MIT License; see license scope. Third-party dependencies retain their own license notices in the packaged dependency directories. Linked specifications, source pages, images and trademarks are not relicensed by this repository.
Compare supplied length, width and height using exact decimal unit conversion. Input requires schemaVersion 1.0, source and candidate with itemId, basis product/package, evidenceRef, and each axis as {value: decimal string, unit: mm/cm/m/in}; toleranceMm is an explicit decimal string. Same item, basis and named axes required. Unknowns yield hold. Does not establish physical fit or source truth. See examples/dimensions.json.
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavior beyond those: 'Unknowns yield hold' and 'Does not establish physical fit or source truth,' plus the requirement for exact decimal conversion. This does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two dense sentences with no filler. The main verb and object are front-loaded, followed by a compact list of required fields and constraints, and it ends with a pointer to examples. Every phrase contributes information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema defines no output schema, and the description only hints at result behavior with 'Unknowns yield hold,' without stating the full set of outcomes (e.g., match/no-match) or the response shape. It does not explain how toleranceMm affects the comparison or what evidenceRef is for. The 'See examples/dimensions.json' pointer helps, but the description itself leaves an agent with incomplete expectations for the tool's result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description is the only semantic source for parameters. It compensates by defining the axis shape as {value: decimal string, unit: mm/cm/m/in}, requiring toleranceMm as an explicit decimal string, and naming schemaVersion, source/candidate fields. It leaves some semantics implicit (e.g., what basis product/package means, how toleranceMm is applied) but covers the critical format constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource: 'Compare supplied length, width and height using exact decimal unit conversion.' It also names unique input requirements (schemaVersion, source/candidate, itemId, basis, evidenceRef) that differentiate it from siblings like compare_feed_snapshots and review_product_record. This makes the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear input prerequisites ('Input requires schemaVersion 1.0, source and candidate...') and constraints ('Same item, basis and named axes required'), which tell an agent when the tool is applicable. It also gives negative guidance: 'Does not establish physical fit or source truth,' preventing misuse. However, it never explicitly contrasts with sibling tools, so an agent must infer the alternative from the purpose statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare supplied source and feed snapshots for exact item IDs, current USD prices, sale state and availability. Requires schemaVersion 1.0, profile openai-native-stable, explicit asOf, maxAgeHours, capturedAt and evidenceRef. Unresolved evidence yields hold with no proposed changes. No fetches or feed writes. See examples/feed-snapshots.json.
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-destructive operation. The description adds context by stating 'No fetches or feed writes', which reinforces the read-only nature and explicitly indicates no side effects. It also mentions the behavioral outcome of unresolved evidence (hold with no proposed changes), which is beyond the annotations. The bar is lowered due to annotations, and the description adds meaningful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with three sentences that pack essential information: what it does, required parameters, and outcome. It front-loads the core purpose and then adds constraints and side-effect disclosures. The reference to an example file is a minor addition but not wasteful. It could be considered slightly dense but well-structured for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (single parameter that is a complex object with nested structures), the description covers the essential aspects: inputs, required fields, behavior on unresolved evidence, and side effects. The output schema is absent, but the description doesn't need to explain return values if the agent can infer expected changes from the context. The description is sufficient for an agent to call the tool correctly, though it could benefit from mentioning the exact format of the asOf timestamp or maxAgeHours constraints, but that's not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero description coverage for parameters, so the description carries the burden of explaining parameter meaning. The description mentions several required parameters (schemaVersion, profile, asOf, maxAgeHours, capturedAt, evidenceRef) and clarifies that they are explicit requirements, but it does not provide definitions or formats for each parameter beyond their names. For nested objects like 'feed' and 'source', the schema already defines their structure, and the description implies they contain items with price, item_id, etc. The description adds minimal value over the schema since it only lists parameter names, not their semantic meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: comparing source and feed snapshots for specific attributes (item IDs, USD prices, sale state, availability). It specifies the action (compare) and the resource (snapshots), which helps distinguish it from siblings like 'compare_dimensions' which likely compares dimensions, not prices. However, it does not explicitly name the siblings or contrast with them directly in the description, so it misses full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool by specifying the data it compares (exact item IDs, prices, sale state, availability) and the required parameters (schemaVersion, profile, asOf, maxAgeHours, capturedAt, evidenceRef). It also states the consequence of unresolved evidence (hold with no changes), which guides the agent on expected outcomes. However, it does not explicitly say when not to use it or suggest alternatives, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Review one supplied product record using a selected canonical-field subset and positive USD prices. Optional mapping transforms only explicit supplied fields. Missing or conflicting facts remain on hold. Does not fetch URLs, verify GTIN assignment, or validate a complete provider upload.
| Name | Required | Description | Default |
|---|---|---|---|
| method | No | copy | |
| record | Yes | ||
| evidence | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds genuine value beyond that: 'Missing or conflicting facts remain on hold' and the negative scope ('Does not fetch URLs, verify GTIN assignment...') disclose limits an agent could not infer from the schema or annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences with no redundancy; the core purpose leads, and the negative-scope sentence packs useful constraints into a compact closing list. Nothing feels wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a nested record object, an evidence parameter, no output schema, and no sibling guidance, the description covers the processing constraints and safety profile but omits what a review returns, what evidence is for, and when to prefer this tool over compare_* siblings. Adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only hints at method via 'Optional mapping transforms only explicit supplied fields' and never explains the 'evidence' parameter, the 'record' shape, or the copy/mapped enum values. Significant parameter meaning is left undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
'Review one supplied product record' gives a specific verb and resource, and the constraints (canonical-field subset, positive USD prices) sharpen the scope. It is distinguishable from the sibling compare tools, though the single-record focus is implied rather than explicitly stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states what the tool does not do (fetch URLs, verify GTIN, validate uploads) but never tells an agent when to use review_product_record versus compare_dimensions or compare_feed_snapshots. No alternative selection logic is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0compare_dimensionscompare_feed_snapshotsreview_product_recordScored across 3 tools
Each tool targets a clearly distinct evidence operation: single-record review, dimensional comparison, and feed snapshot comparison. Any apparent overlap around USD prices is resolved by the object of comparison (one record vs. source/feed snapshots).
All tools follow a consistent lowercase snake_case verb_noun pattern: review_*, compare_*. The repeated compare_ prefix is justified because the objects differ, and there are no mixed conventions or vague action names.
Three tools is a tight but appropriate scope for a specialized evidence-validation toolkit. Each tool handles a distinct evidence type and earns its place, with no redundant or filler tools present.
Core evidence workflows are covered: canonical product-record review, dimensional comparison, and feed snapshot comparison. However, the toolkit explicitly omits external evidence operations such as URL fetching, GTIN verification, and provider upload validation, which would be minor gaps for some commerce evidence tasks.
Read-only checks for proposed orders against evidence and policy; no trading or payment authority.
Read-only EU e-invoice checks: VAT format, VIES, Peppol lookup. Returns evidence, no filing.
Product identity, pack sizes and feed/page checks. Free small trials; paid calls from $0.0003.
Preview-first feed optimization for retailers and agencies: audit, fix and serve product feeds.
