sbox-api-mcp 1.1.0 → 1.2.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sbox-api",
-  "description": "S&box game engine API documentation lookup for Claude Code. Search types, methods, properties, and documentation across the entire S&box API.",
+  "description": "S&box game engine MCP for Claude Code. Search API types, methods, and properties. Browse wiki documentation (guides, tutorials, concepts). Find Workshop community assets (models, sounds, maps, and more).",
   "author": {
     "name": "sofianebel"
   }

package/README.md

@@ -1,6 +1,6 @@
 # sbox-api-mcp
 
-MCP server for [S&box](https://sbox.game) game engine API documentation lookup. Indexes **1800+ types**, **15,000+ members**, and **8,000+ documentation entries** from the S&box API, providing fast fuzzy search directly from Claude Code.
+MCP server for [S&box](https://sbox.game) game engine — API reference, wiki documentation, and Workshop assets. Indexes **1800+ types**, **15,000+ members**, and **8,000+ documentation entries** from the S&box API, plus **200+ wiki pages** (guides, tutorials, concepts) and community Workshop assets, all searchable directly from Claude Code.
 
 ## Installation
 
@@ -26,12 +26,19 @@ npx sbox-api-mcp
 
 | Tool | Description | Example |
 |------|-------------|---------|
+| **API Reference** | | |
 | `search_types` | Fuzzy search types (classes, structs, enums, interfaces) | `search_types({ query: "GameObject" })` |
 | `get_type` | Full details of a specific type (methods, properties, fields) | `get_type({ name: "Sandbox.GameObject" })` |
 | `search_members` | Search methods/properties across all types | `search_members({ query: "Position", kind: "property" })` |
 | `list_namespaces` | List all API namespaces with type counts | `list_namespaces({ filter: "Audio" })` |
 | `search_docs` | Full-text search in documentation summaries | `search_docs({ query: "play sound" })` |
 | `update_api_source` | Update API data URL when S&box releases a new version | `update_api_source({ url: "https://cdn.sbox.game/releases/..." })` |
+| **Wiki Documentation** | | |
+| `search_wiki` | Search s&box wiki pages (guides, tutorials, concepts) | `search_wiki({ query: "networking" })` |
+| `get_wiki_page` | Get the full content of a wiki page as markdown | `get_wiki_page({ path: "scene/components" })` |
+| **Workshop (UGC)** | | |
+| `search_packages` | Search community Workshop assets (models, sounds, maps, etc.) | `search_packages({ query: "zombie" })` |
+| `get_package` | Get details of a specific Workshop package | `get_package({ ident: "facepunch.zombiemale" })` |
 
 ## Configuration
 
@@ -53,9 +60,11 @@ The URL format is: `https://cdn.sbox.game/releases/YYYY-MM-DD-HH-MM-SS.zip.json`
 
 ## How It Works
 
-On first startup, the server downloads the S&box API JSON (~9 MB) and caches it locally in `~/.sbox-api-mcp/`. Subsequent startups use an ETag check to skip re-downloading if the data hasn't changed.
+**API Reference:** On first startup, the server downloads the S&box API JSON (~9 MB) and caches it locally in `~/.sbox-api-mcp/`. Subsequent startups use an ETag check to skip re-downloading if the data hasn't changed. The API data is indexed in-memory using [Fuse.js](https://www.fusejs.io/) for fast fuzzy search across type names, member names, and documentation summaries.
 
-The API data is indexed in-memory using [Fuse.js](https://www.fusejs.io/) for fast fuzzy search across type names, member names, and documentation summaries.
+**Wiki Documentation:** Leverages S&box's LLM-optimized endpoints (`llms.txt` index + `.md` raw markdown pages). The wiki index is fetched on first use and cached in-memory for 1 hour. Individual pages are fetched live from `sbox.game/dev/doc/` as raw markdown.
+
+**Workshop (UGC):** Queries the Facepunch services API live for community-made assets.
 
 ## License
 

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

@@ -0,0 +1,11 @@
+export interface WikiEntry {
+    title: string;
+    path: string;
+    section: string;
+}
+export declare function searchWikiIndex(query: string, section?: string, limit?: number): Promise<WikiEntry[]>;
+export declare function getWikiSections(): Promise<Map<string, number>>;
+export declare function fetchWikiPage(path: string): Promise<{
+    content: string;
+    url: string;
+}>;

package/dist/data/wiki-client.js

@@ -0,0 +1,111 @@
+import Fuse from 'fuse.js';
+const LLMS_TXT_URL = 'https://sbox.game/llms.txt';
+const WIKI_BASE_URL = 'https://sbox.game';
+const CACHE_TTL = 60 * 60 * 1000; // 1 hour
+const SECTION_LABELS = {
+    'getting-started': 'Getting Started',
+    'scene': 'Scene',
+    'code': 'Code',
+    'editor': 'Editor',
+    'assets': 'Assets',
+    'graphics': 'Graphics',
+    'ui': 'UI',
+    'gameplay': 'Gameplay',
+    'networking': 'Networking',
+    'services': 'Services',
+};
+let cache = null;
+function parseLlmsTxt(raw) {
+    const entries = [];
+    const linkPattern = /^-\s+\[(.+?)]\((.+?)\)/;
+    for (const line of raw.split('\n')) {
+        const match = line.match(linkPattern);
+        if (!match)
+            continue;
+        const [, title, path] = match;
+        if (!path.startsWith('/dev/doc/'))
+            continue;
+        // Extract section from first path segment after /dev/doc/
+        const segments = path.replace('/dev/doc/', '').replace(/\.md$/, '').split('/');
+        const sectionSlug = segments[0];
+        const section = SECTION_LABELS[sectionSlug] ?? sectionSlug;
+        entries.push({ title, path, section });
+    }
+    return entries;
+}
+function buildWikiFuse(entries) {
+    return new Fuse(entries, {
+        keys: [
+            { name: 'title', weight: 3 },
+            { name: 'path', weight: 1 },
+            { name: 'section', weight: 0.5 },
+        ],
+        threshold: 0.4,
+        includeScore: true,
+        minMatchCharLength: 2,
+    });
+}
+function buildSectionCounts(entries) {
+    const sections = new Map();
+    for (const entry of entries) {
+        sections.set(entry.section, (sections.get(entry.section) ?? 0) + 1);
+    }
+    return sections;
+}
+async function fetchLlmsTxt() {
+    const res = await fetch(LLMS_TXT_URL);
+    if (!res.ok) {
+        throw new Error(`Failed to fetch llms.txt: ${res.status} ${res.statusText}`);
+    }
+    return res.text();
+}
+async function getOrBuildIndex() {
+    if (cache && Date.now() < cache.expiry) {
+        return cache;
+    }
+    console.error('[sbox-api] Fetching wiki index from llms.txt...');
+    const raw = await fetchLlmsTxt();
+    const entries = parseLlmsTxt(raw);
+    const fuse = buildWikiFuse(entries);
+    const sections = buildSectionCounts(entries);
+    console.error(`[sbox-api] Wiki index: ${entries.length} pages, ${sections.size} sections`);
+    cache = { entries, fuse, sections, expiry: Date.now() + CACHE_TTL };
+    return cache;
+}
+export async function searchWikiIndex(query, section, limit = 10) {
+    const index = await getOrBuildIndex();
+    if (!query) {
+        let entries = index.entries;
+        if (section) {
+            entries = entries.filter(e => e.section.toLowerCase() === section.toLowerCase());
+        }
+        return entries.slice(0, limit);
+    }
+    const results = index.fuse.search(query, { limit: limit * 2 });
+    let entries = results.map(r => r.item);
+    if (section) {
+        entries = entries.filter(e => e.section.toLowerCase() === section.toLowerCase());
+    }
+    return entries.slice(0, limit);
+}
+export async function getWikiSections() {
+    const index = await getOrBuildIndex();
+    return index.sections;
+}
+export async function fetchWikiPage(path) {
+    // Normalize path: accept various formats
+    let normalized = path.trim();
+    // Strip leading /dev/doc/ if present
+    normalized = normalized.replace(/^\/dev\/doc\//, '');
+    // Strip leading slash
+    normalized = normalized.replace(/^\//, '');
+    // Strip trailing .md
+    normalized = normalized.replace(/\.md$/, '');
+    const url = `${WIKI_BASE_URL}/dev/doc/${normalized}.md`;
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`Wiki page not found: ${res.status} ${res.statusText} (${url})`);
+    }
+    const content = await res.text();
+    return { content, url };
+}

package/dist/index.js

@@ -11,6 +11,8 @@ 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';
+import { registerSearchWiki } from './tools/search-wiki.js';
+import { registerGetWikiPage } from './tools/get-wiki-page.js';
 async function main() {
     console.error('[sbox-api] Starting S&box API MCP Server...');
     // Load API data
@@ -31,6 +33,9 @@ async function main() {
     // UGC Workshop tools (no indexes needed - live API)
     registerSearchPackages(server);
     registerGetPackage(server);
+    // Wiki documentation tools (live API, in-memory cached index)
+    registerSearchWiki(server);
+    registerGetWikiPage(server);
     // Connect via stdio
     const transport = new StdioServerTransport();
     await server.connect(transport);

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

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

package/dist/tools/get-wiki-page.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { fetchWikiPage } from '../data/wiki-client.js';
+export function registerGetWikiPage(server) {
+    server.registerTool('get_wiki_page', {
+        title: 'Get S&box Wiki Page',
+        description: 'Fetch a specific s&box wiki documentation page as raw markdown. Use search_wiki to find page paths, or provide a known path directly.',
+        inputSchema: {
+            path: z
+                .string()
+                .describe("Wiki page path (e.g., 'scene/components', 'networking/rpc-messages', 'getting-started/first-project')"),
+        },
+    }, async ({ path }) => {
+        try {
+            const { content, url } = await fetchWikiPage(path);
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Source: ${url}\n\n---\n\n${content}`,
+                    }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Error fetching wiki page: ${message}\n\nTip: Use search_wiki to find valid page paths.`,
+                    }],
+            };
+        }
+    });
+}

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

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

package/dist/tools/search-wiki.js

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import { searchWikiIndex, getWikiSections } from '../data/wiki-client.js';
+function formatEntry(entry, index) {
+    const slug = entry.path.replace('/dev/doc/', '').replace(/\.md$/, '');
+    return `${index + 1}. **${entry.title}** [${entry.section}]\n   Path: ${slug}`;
+}
+export function registerSearchWiki(server) {
+    server.registerTool('search_wiki', {
+        title: 'Search S&box Wiki Documentation',
+        description: 'Search the s&box wiki documentation for guides, tutorials, and conceptual docs. Returns matching page titles with paths. Use get_wiki_page with a path to read a specific page.',
+        inputSchema: {
+            query: z
+                .string()
+                .default('')
+                .describe("Topic to search for (e.g., 'networking', 'components', 'shader graph'). Leave empty to list sections or browse."),
+            section: z
+                .string()
+                .optional()
+                .describe("Filter by documentation section (e.g., 'Scene', 'Networking', 'Graphics', 'UI', 'Editor', 'Gameplay', 'Getting Started')"),
+            limit: z.number().min(1).max(50).default(10).describe('Max results (1-50, default 10)'),
+        },
+    }, async ({ query, section, limit }) => {
+        try {
+            // No query and no section: show sections overview
+            if (!query && !section) {
+                const sections = await getWikiSections();
+                const lines = Array.from(sections.entries())
+                    .sort(([, a], [, b]) => b - a)
+                    .map(([name, count]) => `- **${name}** (${count} pages)`);
+                const total = Array.from(sections.values()).reduce((a, b) => a + b, 0);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `S&box Wiki Documentation — ${total} pages in ${sections.size} sections:\n\n${lines.join('\n')}\n\nTip: Use search_wiki with a query or section to find specific pages.`,
+                        }],
+                };
+            }
+            const results = await searchWikiIndex(query, section, limit);
+            if (results.length === 0) {
+                const hint = section ? ` in section "${section}"` : '';
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `No wiki pages found matching "${query}"${hint}. Try broadening your search or removing the section filter.`,
+                        }],
+                };
+            }
+            const formatted = results.map((entry, i) => formatEntry(entry, i));
+            const sectionLabel = section ? ` in "${section}"` : '';
+            const queryLabel = query ? `matching "${query}"` : '';
+            const header = `Found ${results.length} wiki pages ${queryLabel}${sectionLabel}:\n`;
+            return {
+                content: [{
+                        type: 'text',
+                        text: `${header}\n${formatted.join('\n\n')}\n\nTip: Use get_wiki_page with the path to read a page.`,
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Error searching wiki: ${err instanceof Error ? err.message : String(err)}`,
+                    }],
+            };
+        }
+    });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sbox-api-mcp",
-  "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.",
+  "version": "1.2.0",
+  "description": "MCP server for S&box game engine — API reference, wiki documentation, and Workshop (UGC) asset search. Search types, methods, properties, wiki guides/tutorials, and community-made models, sounds, maps, and more.",
   "type": "module",
   "bin": {
     "sbox-api-mcp": "dist/index.js"
@@ -26,6 +26,7 @@
     "documentation",
     "claude",
     "claude-code",
+    "wiki",
     "ugc",
     "workshop",
     "assets",