GunStore-POS Admin MCP

GunStore-POS Admin MCP

A local MCP server that wraps the GunStore-POSFrappe REST API, so you can read and change a store's settings and content fromClaude or Codex — toggle integration config, edit item pricing/listing, fixrecords, trigger RSR/FastBound/ATF operations, run the Firearms-In-Stock report.

How it works

• A small generic backbone (frappe_* tools) covers every doctype and everywhitelisted method — present and future. A curated layer makes the frequentsettings/sync/report ops one call.
• Talks to Frappe over HTTPS with token auth (Authorization: token key:secret).
• Safety: delete/cancel/submit and destructive methods — including thisdomain's own high-consequence verbs (dispose / push / charge / consolidate /ship / return / receive / sold / settle / onboard) —require confirm=true;password/credential fields are never transmitted (set those in Desk);schema/permission doctypes are read-only.

Setup

1. Generate a Frappe API key

In Desk as the user you want to act as (Administrator): top-right avatar →My Settings → API Access → Generate Keys. Copy the API Key andAPI Secret (the secret is shown only once).

2. Configure credentials

cp .env.example .env
# edit .env: FRAPPE_BASE_URL, FRAPPE_API_KEY, FRAPPE_API_SECRET

.env is git-ignored. Point at a dev site first (http://dev.localhost:8000) to test,then switch to your live POS URL (e.g. https://pos.example.com).

3. Install

uv sync          # creates .venv and installs deps

4. Register with your agent

/path/to/gunstore-pos-mcp below is wherever you cloned this repo (the package isat the repo root). The server loads .env by its own file path, so credentialsnever go in the agent config.

Claude Code — add to .mcp.json (project) or run claude mcp add:

{
  "mcpServers": {
    "gunstore-pos": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/gunstore-pos-mcp", "gunstore-mcp"]
    }
  }
}

Claude Desktop — the same block in claude_desktop_config.json.

Codex — add to ~/.codex/config.toml, then restart Codex (it reads MCPservers at startup):

[mcp_servers.gunstore-pos]
command = "uv"            # or an absolute path to uv if it isn't on Codex's PATH
args = ["run", "--directory", "/path/to/gunstore-pos-mcp", "gunstore-mcp"]
startup_timeout_sec = 120

Verify with a quick stdio handshake (initialize + tools/list) or just listtools from within Codex.

Secrets stay in .env (loaded by the server), not in the agent config.

Tools

Tool reference, organised by task (safety notes and alternatives included): TOOLS.md

115 tools total: 10 generic + 56 curated + 12 distributor + 7 CPA reports + 30 shop-floor; 108 register by default. Two opt-in sets are held back: the 4 distributor queue actions (GUNSTORE_MCP_DISTRIBUTOR_ACTIONS=1) and the 3 GunBroker write actions (GUNSTORE_MCP_GUNBROKER_ACTIONS=1). Neither is registered otherwise — an absent tool cannot be talked into firing.

Modes: GUNSTORE_MCP_MODE=cpa starts a read-only accountant surface —exactly 26 tools (the write surface is never registered), a per-name read-onlymethod allowlist at the client layer, and the 7 integration Settings doctypesblocked from reads. Default (full) is the whole surface. Register a secondserver entry (e.g. gunstore-pos-cpa) with the same command plus"env": {"GUNSTORE_MCP_MODE": "cpa"} to run both side by side.

Standalone CPA install

To install only the read-only accountant surface (no full server) — e.g. ona second machine or for an analyst agent:

git clone [email protected]:Old-Steel-Arsenal/gunstore-pos-mcp.git ~/gunstore-pos-mcp
claude mcp add gunstore-pos-cpa --scope user \
  --env GUNSTORE_MCP_MODE=cpa \
  --env FRAPPE_BASE_URL=https://pos.example.com \
  --env FRAPPE_API_KEY=<key> \
  --env FRAPPE_API_SECRET=<secret> \
  -- uv run --directory ~/gunstore-pos-mcp gunstore-mcp

• Process env beats .env: the server loads .env with override=False,so env vars set in the registration win. A standalone install needs no.env file at all — and the same checkout can serve several entries withdifferent FRAPPE_BASE_URL / mode combinations (e.g. a dev-site instance).
• Verify: after connecting, tools/list must show exactly 26 tools andthe server name gunstore-pos-cpa. A misspelled/unknown mode value refusesto start (fail-closed) rather than silently degrading to the writable surface.
• Security boundary — read before handing this to a third party: thethree-layer gate restricts the MCP call layer only. The API key/secret inthe registration is whatever that Frappe user can do — with a System Managerkey, anyone who extracts it can write via plain REST, MCP gate or not. For athird-party (e.g. an outside accountant's machine), create a dedicatedFrappe API user with read-only roles and register with that key pair.

Generic backbone

Curated

Shop floor: stocktake, cash drawer, storage locations (POS 1.5.0-beta.15)

Every write needs confirm=true; there is no registration gate (they are the same counter actions the POS pages offer, role-checked per call and audited on the remote connector). Firearms are never adjusted by a stocktake and storage moves touch no stock or books.

CPA reports (read-only; registered in both modes)

Remote connector (OAuth, no API key)

The same server runs as a remote MCP endpoint with GUNSTORE_MCP_TRANSPORT=http.It is an OAuth resource server; the POS itself is the authorization server(Frappe v16's built-in OAuth: dynamic client registration + PKCE). A user adds theconnector URL in claude.ai (Settings → Connectors) or Claude Code(claude mcp add --transport http <name> <url>), signs in to the POS in the browserand approves. No key is typed anywhere, and the server holds none.

• Every request carries that user's bearer token. The server checks it against thePOS (ffl_core.api.connector.connector_identity, cached 60 s; the token is neverlogged or cached in the clear) and forwards it on every call, so each call runswith the signed-in user's own POS roles.
• Works with any MCP client that supports OAuth — Claude (claude.aiConnectors, Claude Code claude mcp add --transport http) and ChatGPT (customconnectors / developer mode, or the Responses API mcp tool with the user'stoken). Each client registers itself with the POS (dynamic clientregistration), and the audit shows which one made each call.
• Switched in the POS: Desk → MCP Settings turns the read-only and fullservers on or off separately (and owns the OAuth settings they sign inthrough); a switched-off server tells the user so on every call.
• Only connector tokens are accepted: a token the POS issued to a client createdby dynamic registration. Tokens of OAuth apps made in Desk are refused.
• Every call is audited in the POS (Desk → Connector Audit Log, permanent, rowscannot be deleted; reads included): who, through which connector, which tool,which arguments (secrets masked by key, in filters and inside JSON strings),Started → Success / Failed. The row is written before the tool runs — if itcannot be, the tool does not run. Needs a gunstore-pos release carryingffl_core/api/connector.py and the Connector Audit Log doctype.
• A user with Restrict IP set cannot use the connector: calls reach the POS fromthe connector (and ultimately from Claude's servers), never from the user's IP.
• cpa mode keeps all three read-only layers. The full surface is 107 toolsremotely: upload_attachment reads a path on the server and is never registeredthere. The distributor actions never open remotely (the server refuses to start);the 3 GunBroker writes open on the full connector only, where the POS deploysets GUNSTORE_MCP_GUNBROKER_ACTIONS from that store's own GunBroker switch — astore that lists on GunBroker must be able to end a listing.
• Env: GUNSTORE_MCP_TRANSPORT=http, FRAPPE_BASE_URL (the store's public POS URL,also the OAuth issuer), GUNSTORE_MCP_PUBLIC_URL(https://pos.<domain>/connector/<mode>/mcp, the URL users are given),GUNSTORE_MCP_PORT, GUNSTORE_MCP_MODE; optional GUNSTORE_MCP_HOST (listenaddress, default 127.0.0.1) and FRAPPE_INTERNAL_URL (loopback URL of the localPOS frontend — calls then go there directly with the site's Host header). It runson the POS host behind that host's reverse proxy, which maps the public path to/mcp and forwards /.well-known/oauth-protected-resource/<public path> unchanged.
• Deployment: a container per surface on each store's POS host, behind that host'sCaddy — image ghcr.io/old-steel-arsenal/gunstore-pos-mcp (built on every push to main),deployed by each POS release (gunstore-pos deploy/prod/mcp, pinnedMCP_TAG) — see deploy/README.md.
• POS side, once per site (OAuth Settings): Show Auth Server Metadata andEnable Dynamic Client Registration on; Skip Authorization off (every userapproves). Revoke a user's access in Desk under OAuth Bearer Token.

Security notes

• Local (stdio) server: uses the key's user (Administrator) = full access. Run itlocally only; keep .env out of git (it is, by default). The remote connectorholds no key — see "Remote connector" above.
• Credentials never transit the MCP: password-type and credential-named fields arestripped from every write. Set secrets in Desk directly.
• All writes are logged by Frappe under the key's user (audit trail).
• To revoke access, regenerate that user's keys in Desk.