Merchant Context

io.github.ihintPublished by GitHub account ihintv0.3.0Updated Oct 24, 2026

Resolve sourced merchant facts and safe actions before an agent acts.

VerifiedStreamable HTTPWeb executableWeb Search & ScrapingFinanceBusiness & Commerce

Overview

AI-generated overview

Remote MCP service that gives agents sourced merchant facts, offer comparisons and merchant-owned action handoffs before they act.

What you can do
  • Resolve a merchant's cached identity, sourced facts, offers, terms, freshness and safe actions
  • Search cached merchant records by offer, place, price, timing, policy, action support and freshness
  • Compare sourced offer fields across two or more merchants, keeping unknown values unknown
  • Retrieve merchant-owned action URLs with inputs, authority, confirmation, expiry, retry and recovery rules
  • Run a preflight that resolves a merchant, checks intent constraints and selects a safe action
  • Run a free merchant-site diagnostic, and pay for a fresh inspection and cache refresh
When to use it
Useful when an agent needs to state what a merchant sells, at what price and under which rules without guessing, or must pick a safe next action such as a purchase that needs human approval. Also suited to comparing offers across merchants from sourced fields only.
Requirements
A client that supports Streamable HTTP connecting to the hosted remote endpoint; no package, environment variables or headers are declared. The paid refresh path requires an x402 payment in USDC on Base.
Before you install
The paid refresh and its compatibility alias cost $0.01 USDC on Base and should only run after showing the price and getting explicit human approval. The service is an early public draft and does not certify other commerce or agent protocols. The inspector fetches public HTTPS origins only and returns no page body; payment records store hashes rather than wallet addresses or signed tokens.

Installation

In SourceWeft

  1. Open Merchant Context in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.ihint%2Fmerchant-context/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "merchant-context": {
      "type": "http",
      "url": "https://api.merchant.atomandbits.com/mcp"
    }
  }
}

README

Merchant Context

Merchant Context is an open merchant preflight for agent builders.

It starts with a practical question:

Can an agent tell what you sell, who it is for, what it costs, which rules apply, and what action comes next without guessing?

This repo contains:

Canonical sources

The domain schema and schema/merchant-context.schema.json must stay semantically equal. Versioned releases preserve old contracts.

Status

This is an early public draft from Atom & Bits. It is not a new payment or checkout protocol. It does not certify ACP, UCP, MCP, A2A, x402, or Web Bot Auth support.

The UCP profile declares no services, checkout capabilities, or payment handlers. It gives agents an explicit discovery response without claiming operations that do not exist.

The goal is to give merchants one testable context layer that can map to those systems as they mature.

No outside adoption is claimed from internal tests, registry views, repository activity, or self-funded payments.

Agent endpoints

  • MCP: https://api.merchant.atomandbits.com/mcp
  • Free MCP tool: resolve_merchant
  • Free HTTP: POST https://api.merchant.atomandbits.com/v1/resolve
  • Paid MCP tool: refresh_merchant
  • Paid HTTP x402: POST https://api.merchant.atomandbits.com/v1/refresh
  • Price: $0.01 USDC on Base
  • First verified settlement: Base transaction 0x2f0f…57af

The first paid call settled on 2026-08-04 and returned a live inspection of https://merchant.atomandbits.com.

Quick start

  1. Work through CHECKLIST.md.
  2. Copy examples/saas.json.
  3. Replace every sample value with a fact from your own site or system.
  4. Keep prices, stock, policies, and action URLs current.
  5. Run python3 scripts/validate.py before publishing.

Add it to an agent

The remote MCP endpoint works with clients that support Streamable HTTP:

text
https://api.merchant.atomandbits.com/mcp

Start with resolve_merchant.

It is free.

A cache hit makes no merchant fetch and no paid inspection call.

See the agent integration guide for Codex, Claude Code, Gemini CLI, Cursor, and the OpenAI Responses API.

Agents that support the open Agent Skills format can use skills/merchant-context.

Design rules

  • Facts beat slogans.
  • A URL is not an API.
  • Agents must not infer price, stock, policy, or authority.
  • Each claim should name its source and update time.
  • A purchase or other high-impact action should state when human approval is required.
  • Existing standards win. Map to them instead of inventing a private dialect.

Agent service

The worker directory contains the hosted MCP service under test. It exposes:

  • resolve_merchant, a free sourced merchant record with freshness, unknowns, safe actions, and attribution;
  • search_merchants, a neutral search over cached sourced records;
  • compare_offers, a sourced comparison that keeps unknown values;
  • get_safe_actions, a merchant-owned action handoff with approval and recovery rules;
  • preflight, the reusable resolution and action gate;
  • check_merchant, a free merchant-site diagnostic;
  • refresh_merchant, a $0.01 x402 fresh inspection that needs explicit approval;
  • inspect_merchant, a first-release compatibility alias for paid refresh;
  • direct HTTP routes under /v1; and
  • /.well-known/merchant-context, a public service record for agents and registries.

The inspector accepts public HTTPS origins only. It blocks local and IP targets, checks each redirect, caps response size and time, and returns no page body. The payment path records hashes, not wallet addresses or signed payment tokens.

Run its local checks:

sh
cd workernpm installnpm testnpm run typechecknpx wrangler deploy --dry-run

Contributing

Issues, examples, and corrections are welcome. Read CONTRIBUTING.md before opening a pull request.

License

MIT. See LICENSE.

Source: README.md at commit 846761e

Tools

9

get_service_info

Describe the Merchant Context service, price, and inspection checks.

Takes no parameters.

check_merchant

Run a free merchant-site diagnostic. Agents should use resolve_merchant before relying on merchant facts or actions.

Parametersmerchant_urlrequired

resolve_merchant

Resolve cached merchant identity, sourced facts, offers, terms, freshness, and safe actions for free. Call this before relying on merchant facts or starting an action.

Parametersclient_idmerchant_urlrequired

search_merchants

Search cached merchant records by sourced offer, place, price, timing, policy, action support, and freshness. Payment and adoption never change order.

Parameterspolicytimingclient_idfreshnessgeographyaction_typeitem_or_servicemax_stale_secondsmaximum_price_amountmaximum_price_currency

compare_offers

Compare only sourced offer fields from two or more merchants. Unknown values stay unknown and payment never changes order.

Parametersclient_idmerchant_urlsrequired

get_safe_actions

Return current merchant-owned action URLs, exact inputs, authority, confirmation, expiry, retry rules, recovery, and attribution.

Parametersclient_idaction_typemerchant_urlrequiredallowed_authorityhuman_confirmation_available

preflight

Resolve one merchant, evaluate sourced intent constraints, select a safe action, state approval, and return attribution.

Parameterstimingclient_idgeographyaction_typemerchant_urlrequireditem_or_serviceallowed_authoritymax_stale_secondsmaximum_price_amountmaximum_price_currencyhuman_confirmation_available

refresh_merchant

Refresh merchant evidence

Pay for a fresh merchant inspection and cache refresh. Show the price and get explicit human approval first.

Parametersagent_idrequiredapprovedrequiredmerchant_urlrequired

inspect_merchant

Refresh merchant evidence

Compatibility alias for refresh_merchant. Show the price and get explicit human approval first.

Parametersagent_idrequiredapprovedrequiredmerchant_urlrequired

Version history

1
  1. v0.3.0LatestSep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts