gunsnation-mcp 1.0.0

package/README.md

@@ -0,0 +1,115 @@
+# Gunsnation MCP Server
+
+The Gunsnation MCP Server is a lightweight integration layer that exposes the Gunsnation firearms catalog to AI assistants through the Model Context Protocol (MCP). It allows compatible AI clients to search, filter, and retrieve detailed firearm information using structured tool calls instead of manual API integration.
+
+Designed for speed and simplicity, the server connects directly to the Gunsnation API and provides a clean, standardized interface for querying products by brand, model, UPC, or category. Assistants can also fetch full specifications, images, and metadata for individual firearms, making it ideal for retail, comparison, and product discovery workflows.
+
+Built in TypeScript and distributed as an npm package, the server is easy to install and run locally or in hosted environments. With just an API key and an MCP-compatible client, developers can quickly add real-time firearm data access to their AI tools.
+
+Key features
+	•	MCP-compatible firearm search and lookup tools
+	•	Real-time access to the Gunsnation product catalog
+	•	Simple installation via npm or npx
+	•	Lightweight, developer-friendly TypeScript codebase
+	•	Secure API-key authentication
+
+This project is ideal for developers building AI shopping assistants, retail tools, or product discovery experiences that require up-to-date firearm data from Gunsnation.
+
+## Features
+
+- **Search Firearms**: Search the firearms database by name, brand, model, UPC, or category
+- **Get Firearm Details**: Retrieve comprehensive details about a specific firearm including specifications and images
+
+## Installation
+
+```bash
+npm install gunsnation-mcp
+```
+
+Or use directly with npx:
+
+```bash
+npx gunsnation-mcp
+```
+
+## Configuration
+
+### Environment Variables
+
+- `GUNSNATION_API_KEY` (required): Your Gunsnation API key
+- `GUNSNATION_API_URL` (optional): Custom API URL (defaults to https://api.gunsnation.com)
+
+### Claude Desktop Configuration
+
+Add to your Claude Desktop config file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "gunsnation": {
+      "command": "npx",
+      "args": ["gunsnation-mcp"],
+      "env": {
+        "GUNSNATION_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### search_firearms
+
+Search the Gunsnation firearms database.
+
+**Parameters:**
+- `query` (optional): Search query for firearm name, brand, model, or UPC
+- `category` (optional): Category filter (e.g., "Handguns", "Rifles", "Shotguns")
+- `limit` (optional): Maximum number of results (1-100, default: 20)
+- `offset` (optional): Number of results to skip for pagination
+
+**Example:**
+```
+Search for Glock handguns: { "query": "glock", "category": "Handguns", "limit": 10 }
+```
+
+### get_firearm
+
+Get detailed information about a specific firearm.
+
+**Parameters:**
+- `id` (required): The ID of the firearm to retrieve
+
+**Example:**
+```
+Get firearm details: { "id": 12345 }
+```
+
+## Getting an API Key
+
+1. Create an account at [gunsnation.com](https://gunsnation.com)
+2. Go to Settings
+3. Click "Generate API Key" in the API Key section
+4. Copy your API key and keep it secure
+
+## Rate Limits
+
+- 60 requests per minute per API key
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run in development mode
+GUNSNATION_API_KEY=your_key npm run dev
+```
+
+## License
+
+MIT

package/bin/mcp-server-gunsnation.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('../dist/index.js');

package/dist/api/client.d.ts

@@ -0,0 +1,10 @@
+import { SearchFirearmsParams, SearchFirearmsResponse, GetFirearmParams, GetFirearmResponse, ApiResponse } from '../types';
+export declare class GunsnationApiClient {
+    private client;
+    private apiKey;
+    constructor(apiKey: string, baseUrl?: string);
+    private isErrorResponse;
+    searchFirearms(params: SearchFirearmsParams): Promise<ApiResponse<SearchFirearmsResponse>>;
+    getFirearm(params: GetFirearmParams): Promise<ApiResponse<GetFirearmResponse>>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/api/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AACA,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,gBAAgB,EAChB,kBAAkB,EAClB,WAAW,EAEZ,MAAM,UAAU,CAAC;AAElB,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;IAY5C,OAAO,CAAC,eAAe;IASjB,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,WAAW,CAAC,sBAAsB,CAAC,CAAC;IAoC1F,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAC;CAoBrF"}

package/dist/api/client.js

@@ -0,0 +1,79 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GunsnationApiClient = void 0;
+const axios_1 = __importDefault(require("axios"));
+class GunsnationApiClient {
+    client;
+    apiKey;
+    constructor(apiKey, baseUrl) {
+        this.apiKey = apiKey;
+        this.client = axios_1.default.create({
+            baseURL: baseUrl || process.env.GUNSNATION_API_URL || 'https://api.gunsnation.com',
+            headers: {
+                'X-API-Key': apiKey,
+                'Content-Type': 'application/json',
+            },
+            timeout: 30000,
+        });
+    }
+    isErrorResponse(response) {
+        return (typeof response === 'object' &&
+            response !== null &&
+            'success' in response &&
+            response.success === false);
+    }
+    async searchFirearms(params) {
+        try {
+            const queryParams = new URLSearchParams();
+            if (params.query) {
+                queryParams.append('q', params.query);
+            }
+            if (params.category) {
+                queryParams.append('category', params.category);
+            }
+            if (params.limit !== undefined) {
+                queryParams.append('limit', String(params.limit));
+            }
+            if (params.offset !== undefined) {
+                queryParams.append('offset', String(params.offset));
+            }
+            const response = await this.client.get(`/public/firearms/search?${queryParams.toString()}`);
+            return response.data;
+        }
+        catch (error) {
+            if (axios_1.default.isAxiosError(error) && error.response?.data) {
+                return error.response.data;
+            }
+            return {
+                success: false,
+                error: {
+                    message: error instanceof Error ? error.message : 'Unknown error occurred',
+                    code: 'API_ERROR',
+                },
+            };
+        }
+    }
+    async getFirearm(params) {
+        try {
+            const response = await this.client.get(`/public/firearms/${params.id}`);
+            return response.data;
+        }
+        catch (error) {
+            if (axios_1.default.isAxiosError(error) && error.response?.data) {
+                return error.response.data;
+            }
+            return {
+                success: false,
+                error: {
+                    message: error instanceof Error ? error.message : 'Unknown error occurred',
+                    code: 'API_ERROR',
+                },
+            };
+        }
+    }
+}
+exports.GunsnationApiClient = GunsnationApiClient;
+//# sourceMappingURL=client.js.map

package/dist/api/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const server_1 = require("./server");
+async function main() {
+    const apiKey = process.env.GUNSNATION_API_KEY;
+    if (!apiKey) {
+        console.error('Error: GUNSNATION_API_KEY environment variable is required');
+        console.error('');
+        console.error('Usage:');
+        console.error('  GUNSNATION_API_KEY=your_key npx gunsnation-mcp');
+        console.error('');
+        console.error('Or in Claude Desktop config:');
+        console.error(JSON.stringify({
+            mcpServers: {
+                gunsnation: {
+                    command: 'npx',
+                    args: ['gunsnation-mcp'],
+                    env: { GUNSNATION_API_KEY: 'your_key_here' },
+                },
+            },
+        }, null, 2));
+        process.exit(1);
+    }
+    const apiUrl = process.env.GUNSNATION_API_URL;
+    const server = new server_1.GunsnationMcpServer(apiKey, apiUrl);
+    await server.run();
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAEA,qCAA+C;AAE/C,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;IAE9C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,CAAC,KAAK,CAAC,4DAA4D,CAAC,CAAC;QAC5E,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAClB,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACxB,OAAO,CAAC,KAAK,CAAC,kDAAkD,CAAC,CAAC;QAClE,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAClB,OAAO,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAC9C,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC;YAC3B,UAAU,EAAE;gBACV,UAAU,EAAE;oBACV,OAAO,EAAE,KAAK;oBACd,IAAI,EAAE,CAAC,gBAAgB,CAAC;oBACxB,GAAG,EAAE,EAAE,kBAAkB,EAAE,eAAe,EAAE;iBAC7C;aACF;SACF,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QACb,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;IAE9C,MAAM,MAAM,GAAG,IAAI,4BAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvD,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC;AACrB,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,8 @@
+export declare class GunsnationMcpServer {
+    private server;
+    private apiClient;
+    constructor(apiKey: string, apiUrl?: string);
+    private setupHandlers;
+    run(): Promise<void>;
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAYA,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAsB;gBAE3B,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;IAkB3C,OAAO,CAAC,aAAa;IA6Gf,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;CAK3B"}

package/dist/server.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GunsnationMcpServer = void 0;
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const client_1 = require("./api/client");
+const search_firearms_1 = require("./tools/search-firearms");
+const get_firearm_1 = require("./tools/get-firearm");
+class GunsnationMcpServer {
+    server;
+    apiClient;
+    constructor(apiKey, apiUrl) {
+        this.server = new index_js_1.Server({
+            name: 'gunsnation-mcp',
+            version: '1.0.0',
+        }, {
+            capabilities: {
+                tools: {},
+            },
+        });
+        this.apiClient = new client_1.GunsnationApiClient(apiKey, apiUrl);
+        this.setupHandlers();
+    }
+    setupHandlers() {
+        // List available tools
+        this.server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
+            return {
+                tools: [
+                    {
+                        name: 'search_firearms',
+                        description: '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.',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                query: {
+                                    type: 'string',
+                                    description: 'Search query for firearm name, brand, model, or UPC',
+                                },
+                                category: {
+                                    type: 'string',
+                                    description: 'Category filter (e.g., "Handguns", "Rifles", "Shotguns")',
+                                },
+                                limit: {
+                                    type: 'number',
+                                    description: 'Maximum number of results (1-100, default: 20)',
+                                    minimum: 1,
+                                    maximum: 100,
+                                    default: 20,
+                                },
+                                offset: {
+                                    type: 'number',
+                                    description: 'Number of results to skip for pagination',
+                                    minimum: 0,
+                                    default: 0,
+                                },
+                            },
+                        },
+                    },
+                    {
+                        name: 'get_firearm',
+                        description: 'Get detailed information about a specific firearm by its ID. Returns comprehensive details including specifications, description, and images.',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                id: {
+                                    type: ['string', 'number'],
+                                    description: 'The ID of the firearm to retrieve',
+                                },
+                            },
+                            required: ['id'],
+                        },
+                    },
+                ],
+            };
+        });
+        // Handle tool calls
+        this.server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            try {
+                switch (name) {
+                    case 'search_firearms': {
+                        const input = search_firearms_1.searchFirearmsSchema.parse(args);
+                        const result = await (0, search_firearms_1.searchFirearms)(this.apiClient, input);
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: result,
+                                },
+                            ],
+                        };
+                    }
+                    case 'get_firearm': {
+                        const input = get_firearm_1.getFirearmSchema.parse(args);
+                        const result = await (0, get_firearm_1.getFirearm)(this.apiClient, input);
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: result,
+                                },
+                            ],
+                        };
+                    }
+                    default:
+                        throw new types_js_1.McpError(types_js_1.ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+                }
+            }
+            catch (error) {
+                if (error instanceof types_js_1.McpError) {
+                    throw error;
+                }
+                const message = error instanceof Error ? error.message : 'Unknown error occurred';
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: ${message}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        });
+    }
+    async run() {
+        const transport = new stdio_js_1.StdioServerTransport();
+        await this.server.connect(transport);
+        console.error('Gunsnation MCP server running on stdio');
+    }
+}
+exports.GunsnationMcpServer = GunsnationMcpServer;
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/tools/get-firearm.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import { GunsnationApiClient } from '../api/client';
+export declare const getFirearmSchema: z.ZodObject<{
+    id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+}, "strip", z.ZodTypeAny, {
+    id: string | number;
+}, {
+    id: string | number;
+}>;
+export type GetFirearmInput = z.infer<typeof getFirearmSchema>;
+export declare function getFirearm(client: GunsnationApiClient, input: GetFirearmInput): Promise<string>;
+//# sourceMappingURL=get-firearm.d.ts.map

package/dist/tools/get-firearm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-firearm.d.ts","sourceRoot":"","sources":["../../src/tools/get-firearm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAGpD,eAAO,MAAM,gBAAgB;;;;;;EAE3B,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AA0D/D,wBAAsB,UAAU,CAC9B,MAAM,EAAE,mBAAmB,EAC3B,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,MAAM,CAAC,CAUjB"}

package/dist/tools/get-firearm.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFirearmSchema = void 0;
+exports.getFirearm = getFirearm;
+const zod_1 = require("zod");
+exports.getFirearmSchema = zod_1.z.object({
+    id: zod_1.z.union([zod_1.z.string(), zod_1.z.number()]).describe('The ID of the firearm to retrieve'),
+});
+function formatDetailedFirearm(firearm) {
+    const lines = [];
+    lines.push(`# ${firearm.name}`);
+    lines.push('');
+    // Basic Info
+    lines.push('## Basic Information');
+    lines.push(`- **ID**: ${firearm.id}`);
+    if (firearm.brand)
+        lines.push(`- **Brand**: ${firearm.brand}`);
+    if (firearm.caliber)
+        lines.push(`- **Caliber**: ${firearm.caliber}`);
+    if (firearm.action)
+        lines.push(`- **Action**: ${firearm.action}`);
+    if (firearm.category)
+        lines.push(`- **Category**: ${firearm.category}`);
+    if (firearm.upc)
+        lines.push(`- **UPC**: ${firearm.upc}`);
+    if (firearm.price !== null)
+        lines.push(`- **Price**: $${firearm.price.toFixed(2)}`);
+    lines.push('');
+    // Specifications
+    const specs = firearm.specifications;
+    const hasSpecs = Object.values(specs).some(v => v !== null && v !== undefined);
+    if (hasSpecs) {
+        lines.push('## Specifications');
+        if (specs.barrelLength)
+            lines.push(`- **Barrel Length**: ${specs.barrelLength}"`);
+        if (specs.overallLength)
+            lines.push(`- **Overall Length**: ${specs.overallLength}"`);
+        if (specs.weight)
+            lines.push(`- **Weight**: ${specs.weight} oz`);
+        if (specs.capacity)
+            lines.push(`- **Capacity**: ${specs.capacity}`);
+        if (specs.material)
+            lines.push(`- **Material**: ${specs.material}`);
+        if (specs.finish)
+            lines.push(`- **Finish**: ${specs.finish}`);
+        if (specs.sightType)
+            lines.push(`- **Sight Type**: ${specs.sightType}`);
+        if (specs.safetyFeatures)
+            lines.push(`- **Safety Features**: ${specs.safetyFeatures}`);
+        if (specs.frameSize)
+            lines.push(`- **Frame Size**: ${specs.frameSize}`);
+        if (specs.stockMaterial)
+            lines.push(`- **Stock Material**: ${specs.stockMaterial}`);
+        if (specs.stockType)
+            lines.push(`- **Stock Type**: ${specs.stockType}`);
+        if (specs.magazinesIncluded)
+            lines.push(`- **Magazines Included**: ${specs.magazinesIncluded}`);
+        lines.push('');
+    }
+    // Description
+    if (firearm.description) {
+        lines.push('## Description');
+        lines.push(firearm.description);
+        lines.push('');
+    }
+    // Images
+    if (firearm.images.length > 0) {
+        lines.push('## Images');
+        firearm.images.forEach((img, index) => {
+            lines.push(`- Image ${index + 1}: ${img.original}`);
+        });
+    }
+    return lines.join('\n');
+}
+async function getFirearm(client, input) {
+    const response = await client.getFirearm({
+        id: input.id,
+    });
+    if (!response.success) {
+        return `Error: ${response.error.message} (${response.error.code})`;
+    }
+    return formatDetailedFirearm(response.data);
+}
+//# sourceMappingURL=get-firearm.js.map

package/dist/tools/get-firearm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-firearm.js","sourceRoot":"","sources":["../../src/tools/get-firearm.ts"],"names":[],"mappings":"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"}

package/dist/tools/search-firearms.d.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+import { GunsnationApiClient } from '../api/client';
+export declare const searchFirearmsSchema: z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    offset: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    offset: number;
+    category?: string | undefined;
+    query?: string | undefined;
+}, {
+    category?: string | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    query?: string | undefined;
+}>;
+export type SearchFirearmsInput = z.infer<typeof searchFirearmsSchema>;
+export declare function searchFirearms(client: GunsnationApiClient, input: SearchFirearmsInput): Promise<string>;
+//# sourceMappingURL=search-firearms.d.ts.map

package/dist/tools/search-firearms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-firearms.d.ts","sourceRoot":"","sources":["../../src/tools/search-firearms.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAGpD,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;EAK/B,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAiCvE,wBAAsB,cAAc,CAClC,MAAM,EAAE,mBAAmB,EAC3B,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,MAAM,CAAC,CA6BjB"}

package/dist/tools/search-firearms.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchFirearmsSchema = void 0;
+exports.searchFirearms = searchFirearms;
+const zod_1 = require("zod");
+exports.searchFirearmsSchema = zod_1.z.object({
+    query: zod_1.z.string().optional().describe('Search query for firearm name, brand, model, or UPC'),
+    category: zod_1.z.string().optional().describe('Category filter (e.g., "Handguns", "Rifles", "Shotguns")'),
+    limit: zod_1.z.number().min(1).max(100).optional().default(20).describe('Maximum number of results (1-100, default: 20)'),
+    offset: zod_1.z.number().min(0).optional().default(0).describe('Number of results to skip for pagination'),
+});
+function formatFirearmForDisplay(firearm) {
+    const lines = [];
+    lines.push(`**${firearm.name}**`);
+    lines.push(`- ID: ${firearm.id}`);
+    if (firearm.brand) {
+        lines.push(`- Brand: ${firearm.brand}`);
+    }
+    if (firearm.caliber) {
+        lines.push(`- Caliber: ${firearm.caliber}`);
+    }
+    if (firearm.action) {
+        lines.push(`- Action: ${firearm.action}`);
+    }
+    if (firearm.price !== null) {
+        lines.push(`- Price: $${firearm.price.toFixed(2)}`);
+    }
+    if (firearm.specifications.barrelLength) {
+        lines.push(`- Barrel Length: ${firearm.specifications.barrelLength}"`);
+    }
+    if (firearm.specifications.weight) {
+        lines.push(`- Weight: ${firearm.specifications.weight} oz`);
+    }
+    if (firearm.images.length > 0) {
+        lines.push(`- Image: ${firearm.images[0].original}`);
+    }
+    return lines.join('\n');
+}
+async function searchFirearms(client, input) {
+    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 = [];
+    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');
+}
+//# sourceMappingURL=search-firearms.js.map

package/dist/tools/search-firearms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-firearms.js","sourceRoot":"","sources":["../../src/tools/search-firearms.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -0,0 +1,64 @@
+export interface FirearmImage {
+    original: string;
+    thumbnail?: string;
+    medium?: string;
+}
+export interface FirearmSpecifications {
+    weight: string | null;
+    barrelLength: string | null;
+    overallLength?: string | null;
+    material?: string | null;
+    finish?: string | null;
+    sightType?: string | null;
+    safetyFeatures?: string | null;
+    frameSize?: string | null;
+    stockMaterial?: string | null;
+    stockType?: string | null;
+    magazinesIncluded?: number | null;
+    capacity?: string | null;
+}
+export interface Firearm {
+    id: number;
+    name: string;
+    brand: string | null;
+    caliber: string | null;
+    action: string | null;
+    price: number | null;
+    images: FirearmImage[];
+    specifications: FirearmSpecifications;
+    upc?: string;
+    productHash?: string;
+    category?: string;
+    description?: string;
+}
+export interface SearchFirearmsResponse {
+    success: true;
+    data: Firearm[];
+    meta: {
+        total: number;
+        limit: number;
+        offset: number;
+    };
+}
+export interface GetFirearmResponse {
+    success: true;
+    data: Firearm;
+}
+export interface ApiErrorResponse {
+    success: false;
+    error: {
+        message: string;
+        code: string;
+    };
+}
+export type ApiResponse<T> = T | ApiErrorResponse;
+export interface SearchFirearmsParams {
+    query?: string;
+    category?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface GetFirearmParams {
+    id: string | number;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,cAAc,EAAE,qBAAqB,CAAC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,IAAI,EAAE;QACJ,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE;QACL,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC;AAElD,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;CACrB"}

package/dist/types/index.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "gunsnation-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Gunsnation firearms database API",
+  "main": "dist/index.js",
+  "bin": {
+    "gunsnation-mcp": "./bin/mcp-server-gunsnation.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "ts-node src/index.ts",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "gunsnation",
+    "firearms",
+    "api"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "axios": "^1.7.2",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/debug": "^4.1.13",
+    "@types/ms": "^2.1.0",
+    "@types/node": "^20.14.10",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.5.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "mcpName": "io.github.DynamicDeals/gunsnation"
+}

package/src/api/client.ts

@@ -0,0 +1,92 @@
+import axios, { AxiosInstance } from 'axios';
+import {
+  SearchFirearmsParams,
+  SearchFirearmsResponse,
+  GetFirearmParams,
+  GetFirearmResponse,
+  ApiResponse,
+  ApiErrorResponse,
+} from '../types';
+
+export class GunsnationApiClient {
+  private client: AxiosInstance;
+  private apiKey: string;
+
+  constructor(apiKey: string, baseUrl?: string) {
+    this.apiKey = apiKey;
+    this.client = axios.create({
+      baseURL: baseUrl || process.env.GUNSNATION_API_URL || 'https://api.gunsnation.com',
+      headers: {
+        'X-API-Key': apiKey,
+        'Content-Type': 'application/json',
+      },
+      timeout: 30000,
+    });
+  }
+
+  private isErrorResponse(response: unknown): response is ApiErrorResponse {
+    return (
+      typeof response === 'object' &&
+      response !== null &&
+      'success' in response &&
+      (response as ApiErrorResponse).success === false
+    );
+  }
+
+  async searchFirearms(params: SearchFirearmsParams): Promise<ApiResponse<SearchFirearmsResponse>> {
+    try {
+      const queryParams = new URLSearchParams();
+
+      if (params.query) {
+        queryParams.append('q', params.query);
+      }
+      if (params.category) {
+        queryParams.append('category', params.category);
+      }
+      if (params.limit !== undefined) {
+        queryParams.append('limit', String(params.limit));
+      }
+      if (params.offset !== undefined) {
+        queryParams.append('offset', String(params.offset));
+      }
+
+      const response = await this.client.get<SearchFirearmsResponse>(
+        `/public/firearms/search?${queryParams.toString()}`
+      );
+
+      return response.data;
+    } catch (error) {
+      if (axios.isAxiosError(error) && error.response?.data) {
+        return error.response.data as ApiErrorResponse;
+      }
+      return {
+        success: false,
+        error: {
+          message: error instanceof Error ? error.message : 'Unknown error occurred',
+          code: 'API_ERROR',
+        },
+      };
+    }
+  }
+
+  async getFirearm(params: GetFirearmParams): Promise<ApiResponse<GetFirearmResponse>> {
+    try {
+      const response = await this.client.get<GetFirearmResponse>(
+        `/public/firearms/${params.id}`
+      );
+
+      return response.data;
+    } catch (error) {
+      if (axios.isAxiosError(error) && error.response?.data) {
+        return error.response.data as ApiErrorResponse;
+      }
+      return {
+        success: false,
+        error: {
+          message: error instanceof Error ? error.message : 'Unknown error occurred',
+          code: 'API_ERROR',
+        },
+      };
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+import { GunsnationMcpServer } from './server';
+
+async function main() {
+  const apiKey = process.env.GUNSNATION_API_KEY;
+
+  if (!apiKey) {
+    console.error('Error: GUNSNATION_API_KEY environment variable is required');
+    console.error('');
+    console.error('Usage:');
+    console.error('  GUNSNATION_API_KEY=your_key npx gunsnation-mcp');
+    console.error('');
+    console.error('Or in Claude Desktop config:');
+    console.error(JSON.stringify({
+      mcpServers: {
+        gunsnation: {
+          command: 'npx',
+          args: ['gunsnation-mcp'],
+          env: { GUNSNATION_API_KEY: 'your_key_here' },
+        },
+      },
+    }, null, 2));
+    process.exit(1);
+  }
+
+  const apiUrl = process.env.GUNSNATION_API_URL;
+
+  const server = new GunsnationMcpServer(apiKey, apiUrl);
+  await server.run();
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/src/server.ts

@@ -0,0 +1,149 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ErrorCode,
+  McpError,
+} from '@modelcontextprotocol/sdk/types.js';
+import { GunsnationApiClient } from './api/client';
+import { searchFirearms, searchFirearmsSchema } from './tools/search-firearms';
+import { getFirearm, getFirearmSchema } from './tools/get-firearm';
+
+export class GunsnationMcpServer {
+  private server: Server;
+  private apiClient: GunsnationApiClient;
+
+  constructor(apiKey: string, apiUrl?: string) {
+    this.server = new Server(
+      {
+        name: 'gunsnation-mcp',
+        version: '1.0.0',
+      },
+      {
+        capabilities: {
+          tools: {},
+        },
+      }
+    );
+
+    this.apiClient = new GunsnationApiClient(apiKey, apiUrl);
+
+    this.setupHandlers();
+  }
+
+  private setupHandlers(): void {
+    // List available tools
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      return {
+        tools: [
+          {
+            name: 'search_firearms',
+            description:
+              '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.',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                query: {
+                  type: 'string',
+                  description: 'Search query for firearm name, brand, model, or UPC',
+                },
+                category: {
+                  type: 'string',
+                  description: 'Category filter (e.g., "Handguns", "Rifles", "Shotguns")',
+                },
+                limit: {
+                  type: 'number',
+                  description: 'Maximum number of results (1-100, default: 20)',
+                  minimum: 1,
+                  maximum: 100,
+                  default: 20,
+                },
+                offset: {
+                  type: 'number',
+                  description: 'Number of results to skip for pagination',
+                  minimum: 0,
+                  default: 0,
+                },
+              },
+            },
+          },
+          {
+            name: 'get_firearm',
+            description:
+              'Get detailed information about a specific firearm by its ID. Returns comprehensive details including specifications, description, and images.',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                id: {
+                  type: ['string', 'number'],
+                  description: 'The ID of the firearm to retrieve',
+                },
+              },
+              required: ['id'],
+            },
+          },
+        ],
+      };
+    });
+
+    // Handle tool calls
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+
+      try {
+        switch (name) {
+          case 'search_firearms': {
+            const input = searchFirearmsSchema.parse(args);
+            const result = await searchFirearms(this.apiClient, input);
+            return {
+              content: [
+                {
+                  type: 'text',
+                  text: result,
+                },
+              ],
+            };
+          }
+
+          case 'get_firearm': {
+            const input = getFirearmSchema.parse(args);
+            const result = await getFirearm(this.apiClient, input);
+            return {
+              content: [
+                {
+                  type: 'text',
+                  text: result,
+                },
+              ],
+            };
+          }
+
+          default:
+            throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+        }
+      } catch (error) {
+        if (error instanceof McpError) {
+          throw error;
+        }
+
+        const message = error instanceof Error ? error.message : 'Unknown error occurred';
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error: ${message}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    });
+  }
+
+  async run(): Promise<void> {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    console.error('Gunsnation MCP server running on stdio');
+  }
+}

package/src/tools/get-firearm.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+import { GunsnationApiClient } from '../api/client';
+import { Firearm } from '../types';
+
+export const getFirearmSchema = z.object({
+  id: z.union([z.string(), z.number()]).describe('The ID of the firearm to retrieve'),
+});
+
+export type GetFirearmInput = z.infer<typeof getFirearmSchema>;
+
+function formatDetailedFirearm(firearm: Firearm): string {
+  const lines: string[] = [];
+
+  lines.push(`# ${firearm.name}`);
+  lines.push('');
+
+  // Basic Info
+  lines.push('## Basic Information');
+  lines.push(`- **ID**: ${firearm.id}`);
+  if (firearm.brand) lines.push(`- **Brand**: ${firearm.brand}`);
+  if (firearm.caliber) lines.push(`- **Caliber**: ${firearm.caliber}`);
+  if (firearm.action) lines.push(`- **Action**: ${firearm.action}`);
+  if (firearm.category) lines.push(`- **Category**: ${firearm.category}`);
+  if (firearm.upc) lines.push(`- **UPC**: ${firearm.upc}`);
+  if (firearm.price !== null) lines.push(`- **Price**: $${firearm.price.toFixed(2)}`);
+  lines.push('');
+
+  // Specifications
+  const specs = firearm.specifications;
+  const hasSpecs = Object.values(specs).some(v => v !== null && v !== undefined);
+
+  if (hasSpecs) {
+    lines.push('## Specifications');
+    if (specs.barrelLength) lines.push(`- **Barrel Length**: ${specs.barrelLength}"`);
+    if (specs.overallLength) lines.push(`- **Overall Length**: ${specs.overallLength}"`);
+    if (specs.weight) lines.push(`- **Weight**: ${specs.weight} oz`);
+    if (specs.capacity) lines.push(`- **Capacity**: ${specs.capacity}`);
+    if (specs.material) lines.push(`- **Material**: ${specs.material}`);
+    if (specs.finish) lines.push(`- **Finish**: ${specs.finish}`);
+    if (specs.sightType) lines.push(`- **Sight Type**: ${specs.sightType}`);
+    if (specs.safetyFeatures) lines.push(`- **Safety Features**: ${specs.safetyFeatures}`);
+    if (specs.frameSize) lines.push(`- **Frame Size**: ${specs.frameSize}`);
+    if (specs.stockMaterial) lines.push(`- **Stock Material**: ${specs.stockMaterial}`);
+    if (specs.stockType) lines.push(`- **Stock Type**: ${specs.stockType}`);
+    if (specs.magazinesIncluded) lines.push(`- **Magazines Included**: ${specs.magazinesIncluded}`);
+    lines.push('');
+  }
+
+  // Description
+  if (firearm.description) {
+    lines.push('## Description');
+    lines.push(firearm.description);
+    lines.push('');
+  }
+
+  // Images
+  if (firearm.images.length > 0) {
+    lines.push('## Images');
+    firearm.images.forEach((img, index) => {
+      lines.push(`- Image ${index + 1}: ${img.original}`);
+    });
+  }
+
+  return lines.join('\n');
+}
+
+export async function getFirearm(
+  client: GunsnationApiClient,
+  input: GetFirearmInput
+): Promise<string> {
+  const response = await client.getFirearm({
+    id: input.id,
+  });
+
+  if (!response.success) {
+    return `Error: ${response.error.message} (${response.error.code})`;
+  }
+
+  return formatDetailedFirearm(response.data);
+}

package/src/tools/search-firearms.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+import { GunsnationApiClient } from '../api/client';
+import { Firearm } from '../types';
+
+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'),
+});
+
+export type SearchFirearmsInput = z.infer<typeof searchFirearmsSchema>;
+
+function formatFirearmForDisplay(firearm: Firearm): string {
+  const lines: string[] = [];
+
+  lines.push(`**${firearm.name}**`);
+  lines.push(`- ID: ${firearm.id}`);
+
+  if (firearm.brand) {
+    lines.push(`- Brand: ${firearm.brand}`);
+  }
+  if (firearm.caliber) {
+    lines.push(`- Caliber: ${firearm.caliber}`);
+  }
+  if (firearm.action) {
+    lines.push(`- Action: ${firearm.action}`);
+  }
+  if (firearm.price !== null) {
+    lines.push(`- Price: $${firearm.price.toFixed(2)}`);
+  }
+  if (firearm.specifications.barrelLength) {
+    lines.push(`- Barrel Length: ${firearm.specifications.barrelLength}"`);
+  }
+  if (firearm.specifications.weight) {
+    lines.push(`- Weight: ${firearm.specifications.weight} oz`);
+  }
+  if (firearm.images.length > 0) {
+    lines.push(`- Image: ${firearm.images[0].original}`);
+  }
+
+  return lines.join('\n');
+}
+
+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');
+}

package/src/types/index.ts

@@ -0,0 +1,71 @@
+export interface FirearmImage {
+  original: string;
+  thumbnail?: string;
+  medium?: string;
+}
+
+export interface FirearmSpecifications {
+  weight: string | null;
+  barrelLength: string | null;
+  overallLength?: string | null;
+  material?: string | null;
+  finish?: string | null;
+  sightType?: string | null;
+  safetyFeatures?: string | null;
+  frameSize?: string | null;
+  stockMaterial?: string | null;
+  stockType?: string | null;
+  magazinesIncluded?: number | null;
+  capacity?: string | null;
+}
+
+export interface Firearm {
+  id: number;
+  name: string;
+  brand: string | null;
+  caliber: string | null;
+  action: string | null;
+  price: number | null;
+  images: FirearmImage[];
+  specifications: FirearmSpecifications;
+  upc?: string;
+  productHash?: string;
+  category?: string;
+  description?: string;
+}
+
+export interface SearchFirearmsResponse {
+  success: true;
+  data: Firearm[];
+  meta: {
+    total: number;
+    limit: number;
+    offset: number;
+  };
+}
+
+export interface GetFirearmResponse {
+  success: true;
+  data: Firearm;
+}
+
+export interface ApiErrorResponse {
+  success: false;
+  error: {
+    message: string;
+    code: string;
+  };
+}
+
+export type ApiResponse<T> = T | ApiErrorResponse;
+
+export interface SearchFirearmsParams {
+  query?: string;
+  category?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface GetFirearmParams {
+  id: string | number;
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}