GunStore POS Admin

A local MCP server that wraps the GunStore-POS Frappe REST API, so you can read and change production settings/content from Claude or Codex — toggle integration config, edit item pricing/listing, fix records, trigger RSR/FastBound/ATF operations, run the Firearms-In-Stock report.

Companion repo: firearm-listing-import — a Claude Code / Codex skill that uses this MCP (per-gun photos + descriptions → Serial No → WooCommerce). Extracted from the gunstore-pos app as a standalone, separately distributable package.

How it works

• A small generic backbone (frappe_* tools) covers every doctype and every whitelisted method — present and future. A curated layer makes the frequent settings/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 this domain's own high-consequence verbs (dispose / push / charge / consolidate) — 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 and API 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 dev first (http://dev.localhost:8000) to test, then switch to prod (https://pos.oldsteelarsenal.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 is at the repo root). The server loads .env by its own file path, so credentials never 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 MCP servers 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 list tools from within Codex.

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

Tools

中文速查手册（按"你想干什么"组织，含安全须知与替代路径）：TOOLS.md

Generic backbone

Curated

Security notes

• Uses the key's user (Administrator) = full access. Run locally only; keep .env out of git (it is, by default).
• Credentials never transit the MCP: password-type and credential-named fields are stripped 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.