GunSpec
KI & Agenten

KI & LLMs

Wie man die API einem Modell übergibt: fertige Pakete für die Coding-Agenten, der Ablauf und die Regeln, die sie lehren, eine Tool-Schicht zum Generieren, und die Textdateien, die ein Crawler oder Agent zuerst liest. Alles unten wird aus diesen Paketen und der Spezifikation gelesen: was die Seite sagt, ist das, was ein Agent gesagt bekommt.

  • 5Agenten-Pakete
  • 12Regeln in jedem Paket
  • 6Empfohlene Tools
  • 133Operationen in der Spec

Pakete für Coding-Agenten

Eine Datei pro Agent, abgeleitet aus demselben OpenAPI-Dokument, auf das sie den Agenten für die volle Oberfläche zurückverweist. Hineinkopieren, und der Agent kennt Basis-URL, Header, Hülle, Fehler, Paginierung, Caching, Webhooks und die wichtigen Endpunkte sowie den Ort in dieser Doku, an dem der Rest steht.

  • Claude Code

    18 KB15 Abschnitte67 Pfade zitiertÖffnen

    Query the GunSpec.io firearms REST API. Use when a task involves fetching firearms, ammunition, calibers, manufacturers, countries, or game-balance stats from GunSpec, or building an integration against api.gunspec.io. Covers authentication, the response envelope, pagination, error handling, and the official TypeScript and Python SDKs.

    Ziel.claude/skills/gunspec-api/SKILL.md
    mkdir -p .claude/skills/gunspec-apicurl -s https://assets.gunspec.io/ai/claude-code/skills/gunspec-api/SKILL.md \  -o .claude/skills/gunspec-api/SKILL.md

  • GitHub Copilot

    12 KB13 Abschnitte22 Pfade zitiertÖffnen

    How to consume the GunSpec.io firearms REST API (auth, envelope, errors, pagination, SDKs).

    Ziel.github/instructions/gunspec-api.instructions.md
    mkdir -p .github/instructionscurl -s \  https://assets.gunspec.io/ai/github-copilot/instructions/gunspec-api.instructions.md \  -o .github/instructions/gunspec-api.instructions.md

  • OpenAI Codex

    13 KB14 Abschnitte22 Pfade zitiertÖffnen

    Guidance for consuming the GunSpec.io REST API: a firearms specification database (firearms, ammunition, calibers, manufacturers, countries, and game-balance stats). Merge this section into your project AGENTS.md (repo root) or ~/.codex/AGENTS.md for all projects.

    ZielAGENTS.md
    curl -s https://assets.gunspec.io/ai/codex/AGENTS.md >> AGENTS.md

  • Cursor

    12 KB13 Abschnitte22 Pfade zitiertÖffnen

    How to consume the GunSpec.io firearms REST API (auth, envelope, errors, pagination, SDKs).

    Ziel.cursor/rules/gunspec-api.mdc
    mkdir -p .cursor/rulescurl -s https://assets.gunspec.io/ai/cursor/rules/gunspec-api.mdc \  -o .cursor/rules/gunspec-api.mdc

  • Any agent

    21 KB16 Abschnitte75 Pfade zitiertÖffnen

    Drop-in context that teaches an AI coding agent to consume the GunSpec.io REST API correctly. GunSpec is a firearms specification database: 9,000+ firearms with dimensions, ballistics, materials, and game-balance stats, plus ammunition, calibers, manufacturers, countries, conflicts, and aggregate statistics.

    Zielyour system prompt or rules file
    curl -s https://assets.gunspec.io/ai/gunspec-api.md

Jedes Paket verlinkt 10 Seiten dieser Doku für Details: field-reference, errors, rate-limits, caching, endpoint-access, pagination, versioning, tools, ai, media.

Ordner durchsuchen

Der Ablauf eines Agenten

Die Reihenfolge, die jedes Paket und llms.txt lehren, wie dort geschrieben. Es gibt sie, weil die teuren Fehler jedes Mal dieselben sind: ein geratener Slug, eine stellvertretend gewählte Variante, eine erfundene Spezifikation.

  1. 1

    Resolve the name to an id first.

    GET /v1/firearms/resolve?q={what the user said}. Pass their words through unchanged - it is built for "G19 gen 5 MOS", "AK-47", "H&K MP5". Never guess a slug: glock-19-gen5, glock-g19-gen5 and glock-19 are not interchangeable, and a guess returns 404 or a record for a different variant. This is not search - /v1/firearms/search ranks a page of records about a query and has no notion of certainty; resolve answers which record a query is.

  2. 2

    status: "ambiguous" means ask the user, not pick the first.

    firearmId is null and alternatives holds the tied candidates with their names. "Glock 19" does not name a generation, and the generations differ in exactly the weights and dimensions people ask about. status: "not_found" is a 200, not a 404 - say we hold no such record. Any match: "fuzzy" candidate is a suggestion, always scores 0, and is never an answer. Read unresolvedTokens before replying: those are words the resolver could not place, usually a variant the catalog does not hold. POST /v1/firearms/resolve resolves up to 50 names in one request (Studio).

  3. 3

    GET /v1/firearms/{id} for the full record. GET /v1/firearms/{id}/variants for the rest of the family.

  4. 4

    Never infer a missing specification.

    null means GunSpec does not hold the value. Do not fill it from model knowledge, from a sibling variant, or by computing it. Say it is not in the database.

  5. 5

    Units are in the field names

    weightEmptyG grams, barrelLengthMm and overallLengthMm millimetres, muzzleVelocityMps m/s. Read the suffix and state the unit. /v1/firearms/{id}/dimensions gives metric and imperial.

  6. 6

    dataConfidence is not accuracy.

    It is a 0-1 record-level score set from what was actually sourced and never raised by hand, not a per-field probability that a number is correct: 0.95 does not mean the barrel length is 95% likely to be right. 0.5 with verifiedAt null is seed model knowledge; treat anything below 0.7 as unverified. Use it to rank and triage; follow sources (or the provenance object on a detail record) to verify a specific figure. Bands and source order: https://docs.gunspec.io/en/field-reference#data-confidence

  7. 7

    Specifications legitimately differ by production year, factory, batch and regional variant. Where a record notes disagreement between sources, surface the disagreement rather than presenting one number as settled.

  8. 8

    Cache what you fetch, and refresh conditionally.

    Store the ETag you were given and send it back as If-None-Match; a record that has not changed answers 304 with no body and no charge against your daily allowance. Compare version (stable across plans) rather than ETag when reconciling mirrors held under different keys.

Der erste Schritt hat eigene Endpunkte: GET /v1/firearms/resolve Resolve a name to one firearm · POST /v1/firearms/resolve Resolve many names at once

Regeln für den Agenten

Die 12 Regeln am Ende des Briefings, wörtlich. Ein Paket, das eine davon auslässt, ist keines von uns.

  1. 01Read the key from the environment. Never hardcode or print it.
  2. 02Prefer the official SDK. Fall back to fetch with the X-API-Key header.
  3. 03Check success before reading data. On failure, surface error.code and request_id.
  4. 04Handle 429 with Retry-After backoff.
  5. 05When unsure about a field or endpoint, fetch https://api.gunspec.io/openapi.json. Do not guess.
  6. 06Resolve a name to an id with /firearms/search before fetching a record. Never guess a slug.
  7. 07When search returns several variants, ask the user which one. Do not pick for them.
  8. 08Never invent a missing specification. null means GunSpec does not hold it, so say so.
  9. 09Report units from the field-name suffix (...Mm, ...G, ...Mps). Never assume one.
  10. 10Treat dataConfidence as record completeness and provenance, not per-field accuracy. Cite sources for a specific figure.
  11. 11Cache what you fetch, and refresh with If-None-Match. Re-downloading a record whose version has not changed spends quota to learn nothing.
  12. 12If you keep a mirror, subscribe to webhooks rather than polling for changes, and dedupe on X-Webhook-Id.

Tool-Aufrufe

Gib einem Modell nicht die rohe API und die Doku. Gib ihm ein kleines, benanntes Tool pro Aufgabe und lass den Ablauf oben die Reihenfolge bestimmen. Die von den Paketen empfohlene Schicht, jeweils auf die aufgerufene Operation abgebildet; die Schemas aus dem OpenAPI-Dokument generieren statt von Hand schreiben, damit Parameter und Antworttypen synchron bleiben.

ToolRuft aufHinweis
search_firearms(query)GET /v1/firearms/search-
get_firearm(id)GET /v1/firearms/{id}-
list_variants(id)GET /v1/firearms/{id}/variants-
compare_firearms(ids)GET /v1/firearms/comparemax 5 ids
get_manufacturer(id)GET /v1/manufacturers/{id}-
get_caliber(id)GET /v1/calibers/{id}-

Anthropic-Tool-Aufruf

Anthropic-Tool-Aufruf
typescript
import Anthropic from '@anthropic-ai/sdk' const client = new Anthropic() // One tool the model can call. Generate the rest from the OpenAPI document// rather than writing them by hand, so the parameters stay in step.const tools = [{  name: 'search_firearms',  description: 'Search the GunSpec firearm database by free-text query.',  input_schema: {    type: 'object',    properties: {      q: { type: 'string', description: 'Search terms, e.g. "9mm service pistol"' },    },    required: ['q'],  },}] // The HTTP call you run when the model asks for the tool.async function searchFirearms(q) {  const res = await fetch(    `https://api.gunspec.io/v1/firearms/search?q=${encodeURIComponent(q)}`,    { headers: { 'X-API-Key': process.env.GUNSPEC_API_KEY } },  )  const { data } = await res.json()  return data // hand straight back to the model as the tool result} const message = await client.messages.create({  model: 'claude-sonnet-4-6',  max_tokens: 1024,  tools,  messages: [{ role: 'user', content: 'Compare the recoil of a Glock 17 and a SIG P320.' }],})

Innerhalb eines Tools die SDKs (@buun_group/gunspec-sdk, gunspec) dem rohen fetch vorziehen: sie bringen Auth, Hülle, Auto-Paging und Retries mit, sodass der Tool-Körper ein Aufruf ist.

Maschinenlesbare Dateien

Drei Text-URLs, die ein Agent zur Laufzeit holen oder ein Crawler indexieren kann, alle mit offenem CORS. llms.txt ist der Index; llms-full.txt das ganze Briefing; das OpenAPI-Dokument die Quelle, auf die beide zeigen.

Abschnitte des Index:

  1. 01Quick facts
  2. 02Response shape
  3. 03Pagination
  4. 04Versioning
  5. 05Agent workflow (read this before calling anything)
  6. 06Endpoints
  7. 07SDKs
  8. 08MCP server
  9. 09For AI agents

Warum es leicht zu konsumieren ist

Der Vertrag ist einheitlich, was einen Prompt kurz und einen Parser klein hält. Die Zahlen stammen aus der Spezifikation.

  • Eine Hülle auf jeder JSON-Antwort über 133 Operationen: { success, data }, mit einem pagination-Block auf Listen. Die wenigen Operationen, die Bytes oder eine Weiterleitung liefern, nämlich Geschossdiagramm, Rohdownloads von Medien und Modellen sowie der Händler-Klickzähler, stehen auf der Medienseite.
  • Eine Fehlerform mit stabilem code und einem von 39 konkreten reason-Werten, sodass ein Modell verzweigen kann, ohne Prosa zu lesen. Jeder Code und Grund.
  • Ein Header für Auth (X-API-Key oder Authorization: Bearer); 17 Operationen brauchen keinen. Authentifizierung.
  • Einheiten stecken in den Feldnamen (Mps (m/s), Mm (mm), Rpm (rpm), G (g), J (J), N (N), M (m)), sodass ein Wert nie in der falschen Einheit berichtet werden kann. Feldreferenz.
  • Jeder Katalogeintrag trägt updatedAt, version und ein ETag, sodass ein Agent cachen und bedingt aktualisieren kann, statt erneut zu lesen. Caching.
  • Änderungen werden als signierte Webhooks gepusht, und der Vertrag ist versioniert: Additives landet, Breaking zieht auf ein neues Präfix.

Model Context Protocol

GunSpec betreibt einen gehosteten MCP-Server unter https://mcp.gunspec.io. Richte einen beliebigen MCP-Client mit deinem API-Schlüssel darauf, um einem Assistenten die Tool-Schicht oben unter deinem Plan zu geben.

MCP-Server einrichten