Build a Buyer-Controlled AI Shopping Workflow with NorthCinder

What NorthCinder Does

NorthCinder is an open-source Model Context Protocol server that helps an AI shopping agent compare products against a buyer-defined brief. It produces a ranked shortlist, explains why each offer received its position, identifies rejected options, and reports which stores were or were not searched.

NorthCinder runs on your computer alongside an AI application that supports MCP. The repository owner does not operate a hosted NorthCinder service, account system, control plane, or telemetry service. You run the client and aggregation engine, choose the store connections, and retain the local configuration and audit data.

A central design rule is that buyer criteria determine ranking. Seller payments and affiliate information do not improve an offer's position. Sponsored results remain labeled and rank below organic results.

Key Features

• Buyer-driven ranking: Offers are ordered according to the requirements in your shopping brief.
• Machine-readable explanations: Each recommendation includes a score and structured reasons.
• Visible rejections: Offers that fail required criteria are reported with the requirement they missed.
• Store coverage reporting: Unavailable, blocked, and unconfigured stores remain visible instead of being silently omitted.
• Merchant-trust evidence: Each merchant has explicit supporting evidence or an honest unknown state.
• Persistent labels: Sponsorship and source labels stay attached to each offer.
• Local verification: The client reruns deterministic ranking over the inputs disclosed by the service.
• Controlled checkout: Automated checkout requires a signed, single-use approval mandate tied to an exact offer, quantity, and spending cap.
• Local auditing: Recommendations, approvals, and checkout attempts are written to a local audit trail.

Local reranking verifies the order produced from disclosed inputs. It does not prove that an upstream catalog was complete or that every store-provided fact was accurate.

Prerequisites

For the standard installation, you need Node.js 20 or later and an AI application that supports MCP. Individual store integrations can require additional platform access, credentials, or configuration.

Install and Initialize NorthCinder

Step 1: Run the initializer

Open a terminal and run:

npx northcinder init

The initializer guides you through local setup and prints the MCP configuration required by your AI application.

Step 2: Add the MCP configuration

Copy the configuration printed by the initializer into the MCP configuration area of your AI app. The exact location and connection procedure depend on the application, so follow its MCP documentation.

Step 3: Connect or restart the AI app

Apply the configuration and reconnect or restart the application if required. NorthCinder should then be available to the agent as a local MCP server.

Submit Your First Shopping Brief

NorthCinder works best with a specific brief containing required attributes, a budget, comparison factors, and an explanation request. For example:

Find black wool running shoes under $130. Compare price, delivery, fit, and merchant trust. Tell me why the winner ranked first and which options were ruled out.

This brief establishes required criteria such as color, material, product type, and maximum price. It also tells the agent which factors to compare and asks it to expose both the winning rationale and rejected alternatives.

Inspect the response

Review more than the first result. A NorthCinder response can include:

1. Offers that satisfy the required criteria.
2. The score and machine-readable reasons for each recommendation.
3. Rejected offers and the specific requirement each one missed.
4. Merchant-trust evidence or a clear indication that evidence is missing.
5. A store-by-store coverage report.
6. Source and sponsorship labels attached to every offer.

The coverage report is especially important. If a store was unavailable or blocked, the returned shortlist should not be interpreted as a complete search of the entire market.

Understand the Search and Approval Workflow

Your AI app communicates with the NorthCinder client over MCP. The client communicates with the buyer-run search service, which uses configured store adapters. Results return to the client for local reranking, explanation, and auditing.

Search and price watches do not grant permission to buy. Before automated checkout, NorthCinder requires buyer approval for the specific purchase. The resulting mandate is signed, single use, and bound to the exact offer, quantity, and spending cap. A cross-process nonce ledger protects the mandate against reuse.

Depending on the available integration, the approved purchase can proceed through a checkout rail or a cart handoff. Raw card details are rejected; automated payment rails use opaque delegated payment tokens when available.

Configure Store Coverage

Store access differs by platform. Read the documentation for each adapter before depending on it in a real workflow.

• Shopify: Catalog search is available after additional Shopify setup. The older per-store connection is no longer current.
• WooCommerce: Search works with stores that expose the public WooCommerce Store API.
• eBay: Native search requires approved eBay Buy API access.
• Etsy: Native search requires approved Etsy application access.
• Amazon: Read-only comparison can use a browser profile that you control. It stops at challenges and does not perform checkout.

When native access is unavailable, an agent may compare permitted product pages using browser tools it already controls. NorthCinder accepts normalized product facts from these observations. It does not accept cookies, raw HTML, screenshots, page instructions, passwords, one-time codes, or your AI-provider key.

Agent-observed offers cannot be used for automated checkout or an unattended watch until a native adapter or merchant protocol confirms them.

Build NorthCinder from Source

The repository is a pnpm workspace. Product packages require Node.js 20 or later. The private site workspace requires Node.js 22.12 or later.

Step 1: Install dependencies

corepack pnpm install --frozen-lockfile

Step 2: Build the workspace

corepack pnpm build

Step 3: Run the local initializer

node northcinder/bin/northcinder.js init

The repository also contains offline build, type-checking, testing, dependency, secret, packaging, and public-surface checks. Consult CONTRIBUTING.md for the complete release-verification commands.

Advanced Usage Tips

Write testable requirements

Separate mandatory requirements from preferences. For example, identify a hard spending cap and required product attributes, then list softer comparison factors such as delivery speed, fit, and merchant trust. This makes rejection reasons and ranking explanations easier to audit.

Audit coverage before trusting the winner

Check which adapters succeeded, which were blocked, and which were not configured. NorthCinder intentionally keeps these gaps visible. A top-ranked offer is the winner among the disclosed and successfully evaluated inputs, not necessarily every offer available online.

Distinguish verification from completeness

The client can deterministically rerun the ranking to verify that the disclosed buyer criteria produced the received order. This does not verify catalog completeness or guarantee that store-supplied facts are true. Treat missing evidence and unknown trust states as meaningful limitations.

Keep browser observations within their boundary

Browser-assisted comparison can help when a native store adapter is unavailable, but observed offers require native or merchant-protocol confirmation before unattended monitoring or automated checkout. Amazon browser-based comparison is read only, stops at challenges, and does not check out.

Protect credentials and payment data

Keep your AI-provider key in the AI application and store credentials between you and the relevant store. Do not pass passwords, one-time codes, cookies, or raw card details to NorthCinder. Review the repository's privacy and software ownership documentation and security policy for the complete boundary.

Inspect the project contracts

For deeper technical validation, review the repository's ranking specification, neutrality audit, adapter contract, trust specification, checkout package, and client source. These materials document how ranking neutrality, sponsorship placement, coverage reporting, trust evidence, purchase mandates, and local auditing are implemented.

Current Project Status

Version 0.1.2 is the initial public release. Fixture and harness coverage does not prove that third-party credentials are currently valid, that every store is accessible in production, or that a real purchase has been completed. Verify the relevant adapter documentation before relying on an integration.

The package is not yet listed in the official MCP Registry, and the marketing site included in the repository has not been published at a canonical production origin.

Conclusion

NorthCinder provides a local, inspectable foundation for AI-assisted shopping. It combines buyer-defined ranking, explicit rejection reasons, visible store coverage, merchant-trust evidence, local auditing, and purchase-specific approval. Start with the initializer, connect the generated MCP configuration, submit a precise brief, and inspect both the ranking rationale and coverage gaps before approving any purchase.