northcinder README

The project's README from github.com/cinderline/northcinder. As one markdown file: README.md.

NorthCinder

Your shopping agent should work for you.

AI agents are starting to do more than answer shopping questions. Soon they will decide which products people see and, in some cases, buy on their behalf.

Big marketplaces are building the easiest version of this: an agent that searches one catalog and steers the buyer toward that platform's checkout. That may be convenient, but it is not independent advice. The marketplace still decides what can be seen and makes money when the agent closes the sale.

NorthCinder takes a different approach. It compares products from the sources you choose and shows where its facts came from. Before it buys anything, it asks for your approval. NorthCinder is software you run alongside your AI app.

The repository owner does not operate a NorthCinder service. There is no NorthCinder account or cloud service.

Get started

You need Node.js 20 or later and an MCP-capable AI app.

npx northcinder init

The command saves your configuration on your computer and prints the MCP entry for your AI app. Local mode is keyless. It runs the MCP server and search engine together in one process, using a temporary loopback port.

Once connected, try a real shopping brief:

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.

What a result looks like

NorthCinder does not pretend there is one universal "best" product. It normally shows no more than three useful choices: the strongest fit, a lower-risk option, and a cheaper or meaningfully different option when one exists.

Each result explains why it ranked where it did. You can also inspect the other finalists, rejected offers, and facts that could not be verified.

Research before recommendation

Product research gets messy quickly. Model names overlap, sellers copy one another, and a polished product page can hide the one detail that makes an item wrong for the buyer.

NorthCinder includes separate research guides for products and sellers. Before doing the research, the MCP host should:

  1. Read northcinder://research/product or northcinder://research/seller.
  2. Call create_research_plan with the actual request and exact subject.
  3. Follow the returned checklist with the research tools it already controls.

If the sources disagree or do not identify the exact product or seller, the result stays provisional. Research can decide whether an offer is ready to compare, but it cannot add ranking points.

No host and model combination is currently qualified for routine research use. Treat every research result as provisional until the buyer checks its identity, sources, conflicts, and unknowns.

Buying stays a separate decision

A recommendation is not permission to buy. Every checkout needs a fresh approval for one exact offer and one unit. The signed approval includes the merchant, variant, price, known total, and spending cap. It can be used once.

NorthCinder rejects raw card details. A supported automated checkout can use an opaque payment token, or NorthCinder can hand the buyer a cart link to finish in their own browser.

Order outcomes stay local and only attach to the purchase they belong to. NorthCinder does not silently rewrite the buyer's profile, and its reminders only send notifications.

Rules you can inspect

Seller payment never improves ranking. Sponsored offers stay labeled and below organic results. Missing store coverage stays visible, and unknown seller history remains unknown instead of being guessed safe or unsafe.

NorthCinder reruns the ranking locally and writes recommendations, approvals, and checkout attempts to a local audit log. The ranking specification, trust specification, neutrality audit, and checkout package contain the details.

These checks cover the offers NorthCinder received, not the completeness or truth of a store's catalog.

How NorthCinder works

Your AI app talks to NorthCinder over MCP. NorthCinder runs the search engine locally, checks the ranking before returning it, and keeps the audit log and purchase approvals on your computer. You choose the store connections. The repository owner is not part of this path.

Store coverage

Store access varies, and NorthCinder says when a store was unavailable or not configured. It does not present a partial search as though it covered the whole market.

Built-in adapters cover Shopify, WooCommerce, eBay, Etsy, and read-only Amazon comparison.

If a native connection is missing, the AI app can keep researching with its own browser or search tools. NorthCinder accepts product facts, not cookies, raw pages, passwords, or page instructions. A native connection must confirm the exact offer before checkout or an unattended watch.

Self-hosted engine

Most people should use local mode. If you choose to run the engine separately, set NORTHCINDER_API_KEYS on the service and configure the client with NORTHCINDER_SERVICE_URL and the matching NORTHCINDER_CLIENT_KEY bearer credential. Non-loopback bearer connections must use HTTPS.

Privacy

Read privacy and software ownership and the security policy for the full boundary.

Build from source

This is a pnpm workspace. Product packages need Node.js 20 or later. The private site workspace needs Node.js 22.12 or later.

corepack pnpm install --frozen-lockfile
corepack pnpm build
node northcinder/bin/northcinder.js init

The full release checks are documented in CONTRIBUTING.md.

Contributing and support

NorthCinder is open source under the MIT License.

northcinder (cinderline/northcinder)

Searching Database…

1.2K ·GitHub
Northcinder
What is this?NorthCinder is an open-source MCP server that lets your AI agent compare products from the sources you choose, show where its facts came from, and ask for your approval before buying anything.
Is this a cloud shopping service or software I run myself?It's self-hosted software you run alongside your AI app over MCP. There is no NorthCinder account or cloud service, and the repository owner does not operate one on your behalf.
How do I get it running?Install Node.js 20 or later and connect an MCP-capable AI app, then run the setup command, which saves your configuration locally and prints the MCP entry to paste into your AI app. Local mode is keyless and runs the server and search engine together over a temporary loopback port.
Do I need an AI provider API key to use it?No. NorthCinder never needs your AI provider key, since that stays inside your AI app; you just need Node.js 20+ and an MCP-capable AI app.
How reliable is the product research it does?Research results stay provisional until a human checks identity, sources, conflicts, and unknowns, and no host/model combination is currently qualified for routine research use. Store coverage also varies, and NorthCinder says explicitly when a store was unavailable or not configured.
Does my shopping data get sent to the project owner?No. NorthCinder does not send your searches, settings, or local history to the repository owner, store credentials stay with you and the store, and raw card details are rejected rather than stored or forwarded.
How is this different from a marketplace's own shopping agent?Marketplace agents typically search one catalog and steer you toward their own checkout, profiting when you buy there. NorthCinder compares offers across the stores you configure and never lets sponsored or seller-paid placement improve ranking.
Which stores can it actually search?Built-in adapters cover Shopify, WooCommerce, eBay, Etsy, and read-only Amazon comparison. For anything else, your AI app can fall back to its own browser or search tools.
Can it actually complete the purchase for me?Checkout always needs a fresh, one-time approval tied to the exact merchant, variant, price, and spending cap. It uses an opaque payment token for supported automated checkouts or hands you a cart link to finish in your own browser, and raw card numbers are never accepted.
Can I run the engine as a shared service instead of locally?Yes, set NORTHCINDERAPIKEYS on the service and configure the client with NORTHCINDERSERVICEURL and a NORTHCINDERCLIENTKEY bearer credential; non-loopback connections must use HTTPS.
What are similar projects?wigolo, leviathan, seo-monster, epiq, graphicle, qmd, headroom, xerj
Which topics is it in?payments, human-in-the-loop, search-engine, ecommerce, privacy-first, model-context-protocol, local-first, mcp-server, privacy, mcp, ai-agents, tool
Creator
cinderline
Size
1.4 MB
Stars
1.2K
Updated
CommitAug 22Releasev0.2.1Aug 22
Age
2mo
Commits · 90 Days