convez.ai
MCP ServerIntegração & APIsAvançado
xuanji86

FastBound MCP Server

xuanji86/fastbound-mcp

Integração MCP com FastBound A&D para gerenciamento de inventário regulado de armas

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP para integração com a API FastBound de Aquisição & Disposição de armas de fogo (A&D), utilizada por licenciados federais (FFLs) nos EUA. Fornece 51 ferramentas para buscar inventário, registrar aquisições/disposições, gerenciar contatos e gerar relatórios através de linguagem natural, com modelo de segurança de gravação protegida e dry-run.

Instalação

$npx convez-ai xuanji86/fastbound-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 semana
Versão
v0.2.2
Issues abertas
0
Contribuidores
1

Casos de uso

  • Busca e consulta de inventário de armas e munições via linguagem natural
  • Registro seguro de aquisições e disposições com validação prévia (dry-run)
  • Geração de relatórios e consultas sobre transações de armas para FFLs
  • Gerenciamento de contatos e webhooks integrados ao FastBound

Veredito

Integração robusta e bem-arquitetada para o ecossistema FastBound com forte ênfase em segurança regulatória (desabilitação padrão de gravações, dry-run obrigatório, conformidade ATF). Essencial para FFLs que utilizam Claude, mas restrito a nicho específico de usuários com conta FastBound.

README

A tradução para o português deste README ainda está na fila.

FastBound MCP

An MCP server for the FastBound firearms Acquisition & Disposition (A&D) API — the electronic bound book used by US Federal Firearms Licensees (FFLs). It lets an MCP client (Claude Desktop, Claude Code, Codex CLI, Codex Desktop, etc.) search inventory, record acquisitions and dispositions, manage contacts, and pull reports through natural language.

⚠️ Compliance disclaimer. This tool writes to ATF-regulated records (27 CFR Part 478). You — the FFL/operator — are solely responsible for the accuracy and legality of every record. Test against a FastBound TEST account before touching production data. Writes are disabled by default (see Write safety).

Unofficial. A community-built integration — not affiliated with, endorsed by, or sponsored by FastBound. "FastBound" is a trademark of its respective owner, used here nominatively to describe API compatibility. See NOTICE.

Features

  • 51 tools covering account/reference, items, acquisitions, dispositions, contacts, reports, webhooks, and inventory — comprehensive coverage of the FastBound v1 Account API.
  • Guarded writes with dry-run preview. Writes are off unless you opt in; committing/destructive operations preview exactly what they will send and require an explicit confirm:true.
  • Rate-limit aware (60 req/min token bucket + 429 backoff) and surfaces FastBound's side-effect headers (multiple-sale reports, auto-acquisitions on FFL transfers, contact dedupe).

Install

The server runs over stdio and is configured entirely through environment variables.

Claude Code

claude mcp add fastbound \
  -e FASTBOUND_ACCOUNT_NUMBER=12345 \
  -e FASTBOUND_API_KEY=your-api-key \
  -e FASTBOUND_AUDIT_USER=you@ffl.com \
  -e FASTBOUND_ALLOW_WRITES=false \
  -- npx -y fastbound-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "fastbound": {
      "command": "npx",
      "args": ["-y", "fastbound-mcp"],
      "env": {
        "FASTBOUND_ACCOUNT_NUMBER": "12345",
        "FASTBOUND_API_KEY": "your-api-key",
        "FASTBOUND_AUDIT_USER": "you@ffl.com",
        "FASTBOUND_ALLOW_WRITES": "false"
      }
    }
  }
}

Codex (CLI & Desktop)

Codex loads MCP servers over stdio, and both the Codex CLI and the Codex desktop / IDE app read the same config file: ~/.codex/config.toml. This is a standard stdio MCP server, so a single entry works for both:

[mcp_servers.fastbound]
command = "node"
args = ["/absolute/path/to/fastbound-mcp/dist/index.js"]
env = { FASTBOUND_ACCOUNT_NUMBER = "12345", FASTBOUND_API_KEY = "your-api-key", FASTBOUND_AUDIT_USER = "you@ffl.com", FASTBOUND_ALLOW_WRITES = "false" }
  • Codex CLI — run npm run build first so dist/ exists, then start codex; the /mcp command lists the connected fastbound server and its tools.
  • Codex Desktop / IDE extension — shares the same ~/.codex/config.toml. Add the block above (or use the app's MCP settings panel), then restart the app to load it.

If you npm i -g . (or publish the package), replace the node + absolute-path form with command = "fastbound-mcp".

Compatibility is verified end-to-end: all 51 tool schemas are standard JSON Schema (draft-07, additionalProperties: false, no $ref/anyOf); tool names stay within OpenAI's function-name limits; the server emits only clean newline-delimited JSON-RPC on stdout (no log pollution) and negotiates MCP protocol 2025-06-18. Codex's client accepts the tools without modification.

Configuration

VariableRequiredDefaultPurpose
FASTBOUND_ACCOUNT_NUMBERyes—Account number (the numeric id in your cloud.fastbound.com URL). Used as the Basic-auth username.
FASTBOUND_API_KEYyes—API key from Settings → Account. Basic-auth password.
FASTBOUND_AUDIT_USERrecommended—Email recorded as X-AuditUser on writes (ATF audit trail). Must be an active account user. Per-call auditUser overrides it.
FASTBOUND_ALLOW_WRITESnofalseMaster write switch. When false, every write tool refuses and sends nothing.
FASTBOUND_BASE_URLnohttps://cloud.fastbound.comAPI root override.
FASTBOUND_API_VERSIONno—Optional x-api-version header.

Get a free TEST account at fastbound.com to build and validate integrations without affecting real records. Generate the API key in Settings → Account, and find the account number in your dashboard URL.

Write safety

This server treats writes as dangerous by default:

  1. Off by default. With FASTBOUND_ALLOW_WRITES unset/false, every write tool returns BLOCKED and sends nothing.
  2. Audit user required. Writes need a valid X-AuditUser email (from FASTBOUND_AUDIT_USER or a per-call auditUser).
  3. Dry-run by default for the dangerous ones. Committing or destructive tools (acquire, dispose, commit_*, delete_item, undispose_item, merge_contacts, update_*, theft-loss/destroyed/NFA, …) return a DRY RUN preview showing the exact method, path, and request body. Re-call with confirm:true to execute. The preview is built from the same code that sends the live request, so it can't drift.
  4. Staging tools execute directly. Creating pending (uncommitted) records or adding items to them carries no ATF effect, so those run without a confirm step (but still require the write switch + audit user).

Tool results are tagged OK / DRY RUN / BLOCKED / ERROR on the first line.

Tools

  • Reference: get_account, list_smartlists, list_users
  • Items: search_items, get_item, update_item, set_item_external_id, set_item_acquisition_contact, delete_item, undispose_item
  • Acquisitions: search_acquisitions, get_acquisition, get_acquisition_item, acquire, create_pending_acquisition, add_acquisition_items, update_acquisition, update_acquisition_item, attach_acquisition_contact, commit_acquisition, delete_acquisition, delete_acquisition_item
  • Dispositions: search_dispositions, get_disposition, list_disposition_items, list_4473_dispositions, dispose, create_pending_disposition, add_disposition_items, update_disposition, edit_disposition_item_price, attach_disposition_contact, remove_disposition_items, commit_disposition, lock_disposition, dispose_theft_loss, dispose_destroyed, dispose_nfa, delete_disposition
  • Contacts: search_contacts, get_contact, create_contact, update_contact, manage_contact_licenses, merge_contacts
  • Reports: download_bound_book, download_4473, download_attachment, download_multiple_sale_report
  • Webhooks / Inventory: manage_webhooks, bulk_verify_inventory

Firearm classification fields (caliber, manufacturer, type, condition, location) are account-configurable — use list_smartlists to discover valid values before writing.

Development

npm install
npm run build        # tsc → dist/
npm test             # vitest (offline unit tests)
npm run typecheck

The unit tests are fully mocked and offline. An opt-in live smoke test (test/smoke.account.test.ts) runs read-only get_account against a real account when FASTBOUND_ACCOUNT_NUMBER/FASTBOUND_API_KEY are set, and skips otherwise:

FASTBOUND_ACCOUNT_NUMBER=... FASTBOUND_API_KEY=... npx vitest run test/smoke.account.test.ts

License

MIT

Ver o original no GitHub

Bom para

Relacionados