sbox-api-mcp 1.0.0 → 1.1.0

package/dist/data/ugc-client.d.ts

@@ -0,0 +1,53 @@
+export declare const PACKAGE_TYPES: readonly ["model", "sound", "material", "map", "game", "clothing", "library", "vsnd", "prefab", "shader"];
+export type PackageType = (typeof PACKAGE_TYPES)[number];
+export interface PackageOrg {
+    Ident: string;
+    Title: string;
+    Description?: string;
+    Thumb?: string;
+    Twitter?: string;
+    WebUrl?: string;
+    Discord?: string;
+}
+export interface UgcPackage {
+    Org: PackageOrg;
+    Ident: string;
+    FullIdent: string;
+    Title: string;
+    Summary?: string;
+    Thumb?: string;
+    ThumbWide?: string;
+    ThumbTall?: string;
+    VideoThumb?: string;
+    TypeName: string;
+    Updated: string;
+    Created: string;
+    UsageStats?: Record<string, unknown>;
+    Tags?: string[];
+    Favourited?: number;
+    VotesUp?: number;
+    Collections?: number;
+    Referenced?: number;
+    Public?: boolean;
+}
+export interface SearchPackagesResponse {
+    Packages: UgcPackage[];
+    TotalCount: number;
+    Facets: unknown[];
+    Tags?: Record<string, number>;
+    Orders?: Array<{
+        Name: string;
+        Title: string;
+        Icon: string;
+    }>;
+}
+export interface SearchPackagesParams {
+    query: string;
+    type?: PackageType;
+    category?: string;
+    tag?: string;
+    order?: string;
+    take?: number;
+    skip?: number;
+}
+export declare function searchPackages(params: SearchPackagesParams): Promise<SearchPackagesResponse>;

package/dist/data/ugc-client.js

@@ -0,0 +1,26 @@
+const UGC_API_BASE = 'https://services.facepunch.com/sbox/package';
+export const PACKAGE_TYPES = [
+    'model', 'sound', 'material', 'map', 'game',
+    'clothing', 'library', 'vsnd', 'prefab', 'shader',
+];
+export async function searchPackages(params) {
+    const url = new URL(`${UGC_API_BASE}/find`);
+    url.searchParams.set('q', params.query);
+    if (params.type)
+        url.searchParams.set('type', params.type);
+    if (params.category)
+        url.searchParams.set('category', params.category);
+    if (params.tag)
+        url.searchParams.set('tag', params.tag);
+    if (params.order)
+        url.searchParams.set('order', params.order);
+    if (params.take)
+        url.searchParams.set('take', String(params.take));
+    if (params.skip)
+        url.searchParams.set('skip', String(params.skip));
+    const res = await fetch(url.toString());
+    if (!res.ok) {
+        throw new Error(`UGC API error: ${res.status} ${res.statusText}`);
+    }
+    return res.json();
+}

package/dist/index.js

@@ -9,6 +9,8 @@ import { registerSearchMembers } from './tools/search-members.js';
 import { registerListNamespaces } from './tools/list-namespaces.js';
 import { registerSearchDocs } from './tools/search-docs.js';
 import { registerUpdateSource } from './tools/update-source.js';
+import { registerSearchPackages } from './tools/search-packages.js';
+import { registerGetPackage } from './tools/get-package.js';
 async function main() {
     console.error('[sbox-api] Starting S&box API MCP Server...');
     // Load API data
@@ -26,6 +28,9 @@ async function main() {
     registerListNamespaces(server, indexes);
     registerSearchDocs(server, indexes);
     registerUpdateSource(server, indexes);
+    // UGC Workshop tools (no indexes needed - live API)
+    registerSearchPackages(server);
+    registerGetPackage(server);
     // Connect via stdio
     const transport = new StdioServerTransport();
     await server.connect(transport);

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

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerGetPackage(server: McpServer): void;

package/dist/tools/get-package.js

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+import { searchPackages } from '../data/ugc-client.js';
+function formatPackageDetails(pkg) {
+    const sections = [];
+    sections.push(`# ${pkg.Title}`);
+    sections.push(`**Identifier:** \`${pkg.FullIdent}\``);
+    sections.push(`**Type:** ${pkg.TypeName}`);
+    if (pkg.Summary)
+        sections.push(`**Summary:** ${pkg.Summary}`);
+    sections.push(`**Author:** ${pkg.Org.Title} (${pkg.Org.Ident})`);
+    sections.push('');
+    sections.push('## Stats');
+    if (pkg.VotesUp)
+        sections.push(`- Votes: ${pkg.VotesUp}`);
+    if (pkg.Favourited)
+        sections.push(`- Favourited: ${pkg.Favourited}`);
+    if (pkg.Collections)
+        sections.push(`- In collections: ${pkg.Collections}`);
+    if (pkg.Referenced)
+        sections.push(`- Referenced by: ${pkg.Referenced}`);
+    sections.push('');
+    sections.push('## Dates');
+    sections.push(`- Created: ${pkg.Created}`);
+    sections.push(`- Updated: ${pkg.Updated}`);
+    if (pkg.Tags?.length) {
+        sections.push('');
+        sections.push(`## Tags\n${pkg.Tags.join(', ')}`);
+    }
+    if (pkg.Thumb) {
+        sections.push('');
+        sections.push(`## Thumbnail\n${pkg.Thumb}`);
+    }
+    sections.push('');
+    sections.push(`## Usage\nUse \`${pkg.FullIdent}\` in your S&box project to reference this package.`);
+    sections.push(`Workshop page: https://sbox.game/${pkg.Org.Ident}/${pkg.Ident}`);
+    return sections.join('\n');
+}
+export function registerGetPackage(server) {
+    server.registerTool('get_package', {
+        title: 'Get S&box Package Details',
+        description: 'Get detailed information about a specific S&box Workshop package by its identifier (e.g., "facepunch.zombiemale"). Returns full metadata including stats, tags, author info, and usage instructions.',
+        inputSchema: {
+            ident: z
+                .string()
+                .describe("Package identifier in 'org.name' format (e.g., 'facepunch.zombiemale', 'fpopium.chair_01')"),
+        },
+    }, async ({ ident }) => {
+        try {
+            // The API doesn't have a direct get-by-id endpoint,
+            // so we search with the exact ident and filter
+            const parts = ident.split('.');
+            const searchQuery = parts.length > 1 ? parts[1] : ident;
+            const response = await searchPackages({ query: searchQuery, take: 20 });
+            const pkg = response.Packages.find(p => p.FullIdent.toLowerCase() === ident.toLowerCase());
+            if (!pkg) {
+                // Try broader search
+                const broader = await searchPackages({ query: ident, take: 20 });
+                const found = broader.Packages.find(p => p.FullIdent.toLowerCase() === ident.toLowerCase());
+                if (!found) {
+                    const suggestions = response.Packages.slice(0, 5)
+                        .map(p => `  - ${p.FullIdent} ("${p.Title}")`)
+                        .join('\n');
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: `Package "${ident}" not found.\n\nSimilar packages:\n${suggestions}`,
+                            }],
+                    };
+                }
+                return {
+                    content: [{ type: 'text', text: formatPackageDetails(found) }],
+                };
+            }
+            return {
+                content: [{ type: 'text', text: formatPackageDetails(pkg) }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Error fetching package: ${err instanceof Error ? err.message : String(err)}`,
+                    }],
+            };
+        }
+    });
+}

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

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerSearchPackages(server: McpServer): void;

package/dist/tools/search-packages.js

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+import { searchPackages, PACKAGE_TYPES } from '../data/ugc-client.js';
+function formatPackage(pkg, index) {
+    const lines = [];
+    const votes = pkg.VotesUp ? ` | Votes: ${pkg.VotesUp}` : '';
+    const favs = pkg.Favourited ? ` | Favs: ${pkg.Favourited}` : '';
+    const tags = pkg.Tags?.length ? `Tags: ${pkg.Tags.join(', ')}` : '';
+    lines.push(`${index + 1}. **${pkg.FullIdent}** — "${pkg.Title}"`);
+    if (pkg.Summary)
+        lines.push(`   ${pkg.Summary}`);
+    lines.push(`   Type: ${pkg.TypeName}${votes}${favs}`);
+    if (tags)
+        lines.push(`   ${tags}`);
+    lines.push(`   Use in code: \`${pkg.FullIdent}\``);
+    return lines.join('\n');
+}
+export function registerSearchPackages(server) {
+    server.registerTool('search_packages', {
+        title: 'Search S&box Workshop Packages',
+        description: 'Search the S&box Workshop (UGC) for community-made assets: models, sounds, materials, maps, prefabs, shaders, clothing, and more. Returns packages with their identifiers that can be used directly in S&box game code.',
+        inputSchema: {
+            query: z.string().describe("Search query (e.g., 'zombie', 'wooden chair', 'footstep sound')"),
+            type: z
+                .enum(PACKAGE_TYPES)
+                .optional()
+                .describe('Filter by asset type: model, sound, material, map, game, clothing, library, vsnd, prefab, shader'),
+            category: z
+                .string()
+                .optional()
+                .describe('Filter by category (for models: Animal, Architecture, Debris, Development, Fence/Wall, Food, Furniture, Human, Lighting, Nature, Prop, Toy, Vehicle, Weapon)'),
+            tag: z.string().optional().describe("Filter by tag (e.g., 'kenney', 'retro', 'psx', 'realistic')"),
+            order: z
+                .enum(['popular', 'newest', 'updated', 'trending', 'thumbsup', 'favourites'])
+                .optional()
+                .describe('Sort order. Defaults to relevance.'),
+            take: z.number().min(1).max(50).default(10).describe('Max results (1-50, default 10)'),
+        },
+    }, async ({ query, type, category, tag, order, take }) => {
+        try {
+            const response = await searchPackages({ query, type, category, tag, order, take });
+            if (response.Packages.length === 0) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `No packages found matching "${query}"${type ? ` (type: ${type})` : ''}. Try broadening your search or removing filters.`,
+                        }],
+                };
+            }
+            const formatted = response.Packages.map((pkg, i) => formatPackage(pkg, i));
+            const typeLabel = type ? ` (type: ${type})` : '';
+            const header = `Found ${response.TotalCount} packages matching "${query}"${typeLabel} (showing ${response.Packages.length}):\n`;
+            const topTags = response.Tags
+                ? Object.entries(response.Tags)
+                    .sort(([, a], [, b]) => b - a)
+                    .slice(0, 10)
+                    .map(([t, c]) => `${t} (${c})`)
+                    .join(', ')
+                : null;
+            const footer = topTags ? `\n---\nTop tags in results: ${topTags}` : '';
+            return {
+                content: [{
+                        type: 'text',
+                        text: `${header}\n${formatted.join('\n\n')}${footer}`,
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Error searching packages: ${err instanceof Error ? err.message : String(err)}`,
+                    }],
+            };
+        }
+    });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sbox-api-mcp",
-  "version": "1.0.0",
-  "description": "MCP server for S&box game engine API documentation lookup. Search types, methods, properties, and documentation across the entire S&box API.",
+  "version": "1.1.0",
+  "description": "MCP server for S&box game engine API documentation and Workshop (UGC) asset search. Search types, methods, properties, documentation, and community-made models, sounds, maps, and more.",
   "type": "module",
   "bin": {
     "sbox-api-mcp": "dist/index.js"
@@ -25,7 +25,11 @@
     "api",
     "documentation",
     "claude",
-    "claude-code"
+    "claude-code",
+    "ugc",
+    "workshop",
+    "assets",
+    "models"
   ],
   "author": "sofianebel",
   "license": "MIT",