search_firearms
Search the Gunsnation firearms database to find weapons by name, brand, model, or UPC. Filter results by category and get details like caliber, action type, and price.
Instructions
Search the Gunsnation firearms database. Returns a list of firearms matching the search criteria with basic details including name, brand, caliber, action type, and price.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Search query for firearm name, brand, model, or UPC | |
| category | No | Category filter (e.g., "Handguns", "Rifles", "Shotguns") | |
| limit | No | Maximum number of results (1-100, default: 20) | |
| offset | No | Number of results to skip for pagination |
Implementation Reference
- src/tools/search-firearms.ts:45-77 (handler)The handler function that performs the API call to search firearms and formats the results for the MCP response.
export async function searchFirearms( client: GunsnationApiClient, input: SearchFirearmsInput ): Promise<string> { const response = await client.searchFirearms({ query: input.query, category: input.category, limit: input.limit, offset: input.offset, }); if (!response.success) { return `Error: ${response.error.message} (${response.error.code})`; } if (response.data.length === 0) { return 'No firearms found matching your search criteria.'; } const results: string[] = []; results.push(`Found ${response.meta.total} firearms (showing ${response.data.length}):\n`); for (const firearm of response.data) { results.push(formatFirearmForDisplay(firearm)); results.push(''); // Empty line between results } if (response.meta.offset + response.data.length < response.meta.total) { results.push(`\n---\nShowing ${response.meta.offset + 1}-${response.meta.offset + response.data.length} of ${response.meta.total}. Use offset parameter to see more results.`); } return results.join('\n'); } - src/tools/search-firearms.ts:5-10 (schema)Zod schema for validating the input arguments for the search_firearms tool.
export const searchFirearmsSchema = z.object({ query: z.string().optional().describe('Search query for firearm name, brand, model, or UPC'), category: z.string().optional().describe('Category filter (e.g., "Handguns", "Rifles", "Shotguns")'), limit: z.number().min(1).max(100).optional().default(20).describe('Maximum number of results (1-100, default: 20)'), offset: z.number().min(0).optional().default(0).describe('Number of results to skip for pagination'), }); - src/server.ts:96-107 (registration)Registration of the search_firearms tool within the server request handler switch block.
case 'search_firearms': { const input = searchFirearmsSchema.parse(args); const result = await searchFirearms(this.apiClient, input); return { content: [ { type: 'text', text: result, }, ], }; }