An MCP server for GoCommerce

What it does

Configuration

Nothing is required. The endpoint is authenticated by the store’s own admin credentials, so these settings decide what an agent may do; they live in Config only, with no panel card and no environment variable.

The module reads its Config struct, not the environment. The variable names are the ones the package’s own example or the reference binary uses; in your own main() you choose where each value comes from. Where a setting has a panel label, the admin’s settings drawer can hold it too, and a value typed there wins over Config.

Setting it up

1. Install the modulePass mcp.New to gocommerce.New in your own main(), as below. The reference binary has no flag for it; examples/store/main.go installs it.
2. Choose a credentialThe endpoint takes what the admin API takes. A static admin token carries every right; a signed-in operator needs agent.dispatch, which only the owner role holds until it is granted.
3. Point the agent at itAn HTTP client posts JSON-RPC to /api/admin/x/mcp with the credential as a bearer token. A desktop agent over stdio needs mcp.ServeStdio(app, m) called in place of ListenAndServe.
4. Read what it didEvery mutating call, including one refused for want of a right, is recorded. GET /api/admin/x/mcp/audit lists them, and the admin’s Agent activity screen shows the same list.

import (
	"github.com/itswadesh/gocommerce/core"
	"github.com/itswadesh/gocommerce/ext/mcp"
)

app, err := gocommerce.New(cfg, mcp.New(mcp.Config{
	ServerName: "example-store",
	// The ten mutating tools stay hidden until you switch this off.
	ReadOnly: true,
}))

How it works

• The same services as REST

  Each tool calls the domain service its REST route calls, so an agent cannot reach a state a person could not, and cannot skip a rule by coming in through a different door.

• Rights, per tool

  One route dispatches every tool, so each tool names the rights its REST equivalent needs — orders.refund for refund_order, catalog.write for set_variant_price — and they are checked against the signed-in operator on every call.

• Errors an agent can use

  A tool that fails returns its error as content with isError set: “that order is already shipped” is an answer. A call refused for want of a right comes back as a JSON-RPC error instead.

• An audit table

  The module owns one table, mcp_audit: the tool, its arguments, ok or error, and when. Every mutating call is written, including a refused one. The right to read it, agent.read, is separate from the right to act.

• Read-only, visibly

  tools/list marks each tool with readOnlyHint, an annotation from a later MCP revision that older clients ignore. Under ReadOnly the mutating tools are not listed at all.

• Stdio for desktop agents

  mcp.ServeStdio reads one JSON-RPC message per line from stdin and answers on stdout. It runs with the bootstrap credential, so every tool the Config allows is available.

What it does not do

Read these before an order depends on it. No store is known to run GoCommerce in production yet, so these come from the code, not from anyone’s experience.

• No flag, no quick startNeither the Docker quick start nor the reference binary installs it. Using it means a main() of your own.
• Tools onlyThe server advertises revision 2024-11-05 and answers initialize, ping, tools/list and tools/call. Resources, prompts and change notifications are not implemented.
• Plain POST, one message at a timeEach request is one POST answered with one JSON body. There is no server-sent event stream, no session id and no batching, so a client that needs any of those will not connect.
• The static token is not narrowedAn agent holding the static admin token has every right, and the per-tool checks do not apply to it. ReadOnly is the one switch that holds such an agent back.
• Reads leave no trailOnly mutating calls reach mcp_audit. What an agent read — customers, orders, sales — is not recorded by the module.
• No tools from other modules yetConfig.Tools takes extra tools, but no other module in the repository ships any today. Each one you want exposed is one you write.