@mistereman22/osrs-wiki-mcp-server 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mistereman22
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,123 @@
-# Temporary Holding Version
+# @mistereman22/osrs-wiki-mcp-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MCP server for the Old School RuneScape Wiki (`https://oldschool.runescape.wiki`). Serves the full tool surface of [`@professional-wiki/mediawiki-mcp-server`](https://github.com/ProfessionalWiki/MediaWiki-MCP-Server) against a pinned, read-only wiki definition.
+
+| Capability | Details |
+| --- | --- |
+| MediaWiki tools | Full upstream tool surface (page reads, search, watchlists, siteinfo, ...) with wiki fixed to `oldschool.runescape.wiki`. **Read-only** - write and wiki-management tools are gated off. |
+| `context://bucket-index` | On-demand hint list of known Bucket buckets for `bucket-query`; read fresh per request with runtime discovery as fallback. |
+
+## Quick start (users)
+
+**Requirement:** Node.js >= 22.19.0
+
+### OpenCode
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "servers": {
+      "osrs-wiki": {
+        "type": "local",
+        "command": ["npx", "@mistereman22/osrs-wiki-mcp-server@1.0.0"],
+        "environment": { "MCP_CONTACT": "you@example.com" }
+      }
+    }
+  }
+}
+```
+
+### Cursor
+```json
+{
+  "mcpServers": {
+    "osrs-wiki": {
+      "command": "npx",
+      "args": ["@mistereman22/osrs-wiki-mcp-server@1.0.0"],
+      "env": { "MCP_CONTACT": "you@example.com" }
+    }
+  }
+}
+```
+
+### Claude Code
+```sh
+/plugin marketplace add mistereman22/osrs-wiki-mcp-server
+/plugin install osrs-wiki-mcp-server@osrs-wiki-mcp-server
+```
+
+### Run directly
+```sh
+MCP_CONTACT="you@example.com" npx @mistereman22/osrs-wiki-mcp-server@1.0.0
+```
+
+## Configuration
+
+| Variable | Required | Meaning |
+| --- | --- | --- |
+| `MCP_CONTACT` | **Yes** | Your contact (email or name + URL), appended to the server's base User-Agent on every OSRS wiki request. Example: `you@example.com`. Server fails fast at startup if missing. |
+
+## Composed User-Agent
+```
+osrs-wiki-mcp-server/1.0.0 (https://github.com/mistereman22/osrs-wiki-mcp-server) you@example.com
+```
+
+## Rate limits
+
+Two independent sliding-window budgets (tuned in `src/server.ts`):
+
+| Surface | Budget | Counted per |
+| --- | --- | --- |
+| MediaWiki API | 30 requests / 60 s | each upstream tool call |
+| External APIs | 30 requests / 60 s | each HTTP request by external API tool |
+
+Over budget: waits up to 10s for a slot, then returns rate-limit error with retry hint.
+
+## Development
+
+### Requirements
+- Node.js >= 22.19.0
+- `npm install` in this directory
+
+### Commands
+```sh
+npm run build   # TypeScript -> dist/
+npm start       # Run built server (requires MCP_CONTACT)
+npm run dev     # Build + run
+```
+
+### Repository layout
+```
+.
++-- src/
+|   +-- index.ts          # Entry point: env gate, stdio transport, lifecycle
+|   +-- env.ts            # MCP_CONTACT fail-fast gate + User-Agent composition
+|   +-- server.ts         # McpServer assembly + tool gating + wiki config + rate limiting
+|   +-- resources.ts      # Generic resource loader (bucket-index)
+|   +-- external.ts       # HTTP utilities (callHttp) for future external APIs
+|   +-- declarations.d.ts # Type declarations for upstream JS-only package
++-- resources/
+|   +-- bucket-index.md   # Bucket hint list for context://bucket-index
++-- .claude-plugin/
+|   +-- marketplace.json  # Claude Code marketplace manifest
++-- dist/                 # Compiled output (generated by build)
++-- package.json
++-- tsconfig.json
++-- README.md
++-- LICENSE
+```
+
+### Rate limit constants
+Tuned in `src/server.ts`:
+- `WINDOW_MS = 60_000` (60s window)
+- `MAX_WAIT_MS = 10_000` (max 10s wait)
+- `WIKI_MAX_REQUESTS = 30`
+- `EXTERNAL_MAX_REQUESTS = 30`
+
+## Contact
+- Maintainer: [github.com/mistereman22](https://github.com/mistereman22)
+- Issues: [github.com/mistereman22/osrs-wiki-mcp-server/issues](https://github.com/mistereman22/osrs-wiki-mcp-server/issues)
+
+## License
+
+[MIT](LICENSE)

package/dist/env.d.ts

@@ -0,0 +1,3 @@
+export declare const CONTACT: string | undefined;
+export declare const USER_AGENT: string;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAsBA,eAAO,MAAM,OAAO,oBAAkC,CAAC;AAcvD,eAAO,MAAM,UAAU,QAAkC,CAAC"}

package/dist/env.js

@@ -0,0 +1,28 @@
+/**
+ * MCP_CONTACT gate + User-Agent composition.
+ * Must be imported first - upstream reads MCP_USER_AGENT at module evaluation time.
+ */
+import process from 'node:process';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+const pkg = createRequire(import.meta.url)(fileURLToPath(new URL('../package.json', import.meta.url)));
+const SERVER_NAME = 'osrs-wiki-mcp-server';
+const SERVER_VERSION = pkg.version ?? '1.0.0';
+const SERVER_REPO = typeof pkg.repository?.url === 'string'
+    ? pkg.repository.url.replace(/^git\+/, '').replace(/\.git$/, '')
+    : 'https://github.com/mistereman22/osrs-wiki-mcp-server';
+const BASE_USER_AGENT = `${SERVER_NAME}/${SERVER_VERSION} (${SERVER_REPO})`;
+export const CONTACT = process.env.MCP_CONTACT?.trim();
+if (!CONTACT) {
+    console.error('[osrs-wiki-mcp-server] MCP_CONTACT is required but not set.\n' +
+        'Your contact is appended to the server User-Agent so anyone\n' +
+        'seeing our requests can reach you, e.g.\n' +
+        '  MCP_CONTACT="you@example.com"\n' +
+        `Base User-Agent: ${BASE_USER_AGENT}\n` +
+        `Repository: ${SERVER_REPO}`);
+    process.exit(1);
+}
+export const USER_AGENT = `${BASE_USER_AGENT} ${CONTACT}`;
+// Upstream reads MCP_USER_AGENT at import time - set it before other imports load.
+process.env.MCP_USER_AGENT = USER_AGENT;
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,OAAO,MAAM,cAAc,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,GAAG,GAAG,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,aAAa,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAIpG,CAAC;AAEF,MAAM,WAAW,GAAG,sBAAsB,CAAC;AAC3C,MAAM,cAAc,GAAG,GAAG,CAAC,OAAO,IAAI,OAAO,CAAC;AAC9C,MAAM,WAAW,GAChB,OAAO,GAAG,CAAC,UAAU,EAAE,GAAG,KAAK,QAAQ;IACtC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;IAChE,CAAC,CAAC,sDAAsD,CAAC;AAC3D,MAAM,eAAe,GAAG,GAAG,WAAW,IAAI,cAAc,KAAK,WAAW,GAAG,CAAC;AAE5E,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC;AAEvD,IAAI,CAAC,OAAO,EAAE,CAAC;IACd,OAAO,CAAC,KAAK,CACZ,+DAA+D;QAC9D,+DAA+D;QAC/D,2CAA2C;QAC3C,mCAAmC;QACnC,oBAAoB,eAAe,IAAI;QACvC,eAAe,WAAW,EAAE,CAC7B,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,MAAM,UAAU,GAAG,GAAG,eAAe,IAAI,OAAO,EAAE,CAAC;AAE1D,mFAAmF;AACnF,OAAO,CAAC,GAAG,CAAC,cAAc,GAAG,UAAU,CAAC"}

package/dist/external.d.ts

@@ -0,0 +1,49 @@
+export declare class HttpToolError extends Error {
+}
+interface CallHttpResult {
+    status: number;
+    statusText: string;
+    finalUrl: string;
+    elapsedMs: number;
+    headerLines: string[];
+    body: string;
+    truncated: boolean;
+    shownBody: string;
+}
+interface CallHttpRequest {
+    url: unknown;
+    method?: string;
+    headers?: Record<string, string>;
+    params?: Record<string, unknown>;
+    data?: unknown;
+    timeout_ms?: number;
+}
+export declare function errorMessage(error: unknown): string;
+export declare function textResult(text: string, isError?: boolean): {
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+    isError: boolean;
+};
+export declare function callHttp(request: CallHttpRequest): Promise<CallHttpResult>;
+export declare function formatHttpResponse(result: CallHttpResult): string;
+interface ApiTool {
+    name: string;
+    title?: string;
+    description: string;
+    inputSchema: any;
+    annotations?: Record<string, unknown>;
+    call: (args: unknown) => Promise<{
+        content: {
+            type: 'text';
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+}
+export declare const API_TOOLS: ApiTool[];
+import type { McpServer } from '@modelcontextprotocol/server';
+export declare function registerExternalApiTools(server: McpServer): void;
+export {};
+//# sourceMappingURL=external.d.ts.map

package/dist/external.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external.d.ts","sourceRoot":"","sources":["../src/external.ts"],"names":[],"mappings":"AAeA,qBAAa,aAAc,SAAQ,KAAK;CAAG;AAE3C,UAAU,cAAc;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,eAAe;IACxB,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAGnD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,UAAQ,GAAG;IAAE,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAEzH;AAqCD,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CA4EhF;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAWjE;AAED,UAAU,OAAO;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,GAAG,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;QAAE,OAAO,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAClG;AAED,eAAO,MAAM,SAAS,EAAE,OAAO,EAE9B,CAAC;AAEF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAE9D,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAahE"}

package/dist/external.js

@@ -0,0 +1,154 @@
+/**
+ * HTTP utilities for external API tools (rate-limited, fixed User-Agent, https-only).
+ * Add tools to API_TOOLS array below; each uses callHttp internally.
+ */
+import axios from 'axios';
+import { externalLimiter, RateLimitError } from './server.js';
+import { USER_AGENT } from './env.js';
+const HTTP_TIMEOUT_MS = 30_000;
+const HTTP_MIN_TIMEOUT_MS = 1_000;
+const HTTP_MAX_TIMEOUT_MS = 300_000;
+const HTTP_MAX_BODY_BYTES = 5 * 1024 * 1024;
+const HTTP_MAX_BODY_CHARS = 100_000;
+export class HttpToolError extends Error {
+}
+export function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+export function textResult(text, isError = false) {
+    return { content: [{ type: 'text', text }], isError };
+}
+function normalizeTimeout(raw) {
+    if (raw === undefined || raw === null)
+        return HTTP_TIMEOUT_MS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed))
+        return HTTP_TIMEOUT_MS;
+    return Math.min(Math.max(parsed, HTTP_MIN_TIMEOUT_MS), HTTP_MAX_TIMEOUT_MS);
+}
+function normalizeBody(raw) {
+    if (raw === undefined || raw === null)
+        return { jsonBody: false };
+    if (typeof raw === 'object')
+        return { data: JSON.stringify(raw), jsonBody: true };
+    if (typeof raw === 'string')
+        return { data: raw, jsonBody: false };
+    return { data: String(raw), jsonBody: true };
+}
+function parseHttpUrl(rawUrl) {
+    const trimmed = typeof rawUrl === 'string' ? rawUrl.trim() : '';
+    if (trimmed === '')
+        throw new HttpToolError('Missing required argument: "url".');
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        throw new HttpToolError(`Invalid URL: ${trimmed}`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new HttpToolError(`Unsupported protocol "${parsed.protocol}" in ${trimmed}. Only http: and https: allowed.`);
+    }
+    return trimmed;
+}
+function hasHeader(headers, name) {
+    return Object.keys(headers).some((key) => key.toLowerCase() === name);
+}
+export async function callHttp(request) {
+    const url = parseHttpUrl(request.url);
+    try {
+        await externalLimiter.acquire();
+    }
+    catch (error) {
+        if (error instanceof RateLimitError) {
+            throw new HttpToolError(error.message);
+        }
+        throw error;
+    }
+    const method = request.method ?? 'GET';
+    const headers = { ...(request.headers ?? {}) };
+    if (!hasHeader(headers, 'user-agent')) {
+        headers['user-agent'] = USER_AGENT;
+    }
+    const params = { ...(request.params ?? {}) };
+    const { data, jsonBody } = normalizeBody(request.data);
+    if (jsonBody && !hasHeader(headers, 'content-type')) {
+        headers['content-type'] = 'application/json';
+    }
+    const timeout = normalizeTimeout(request.timeout_ms);
+    const startedAt = Date.now();
+    let response;
+    try {
+        response = await axios.request({
+            url,
+            method,
+            headers,
+            params,
+            data,
+            timeout,
+            maxRedirects: 5,
+            maxContentLength: HTTP_MAX_BODY_BYTES,
+            responseType: 'text',
+            validateStatus: () => true,
+            transformResponse: [(body) => body],
+        });
+    }
+    catch (error) {
+        const axiosError = error;
+        const code = typeof axiosError.code === 'string' ? `${axiosError.code}: ` : '';
+        throw new HttpToolError(`Request to ${url} failed - ${code}${errorMessage(error)}`);
+    }
+    const elapsedMs = Date.now() - startedAt;
+    const body = typeof response.data === 'string'
+        ? response.data
+        : response.data === undefined || response.data === null
+            ? ''
+            : String(response.data);
+    const truncated = body.length > HTTP_MAX_BODY_CHARS;
+    const shownBody = truncated ? body.slice(0, HTTP_MAX_BODY_CHARS) : body;
+    const headerLines = [];
+    for (const [key, value] of Object.entries(response.headers ?? {})) {
+        headerLines.push(`  ${key}: ${Array.isArray(value) ? value.join(', ') : String(value)}`);
+    }
+    const finalUrl = response.request?.res?.responseUrl ??
+        response.request?.responseURL ??
+        url;
+    return {
+        status: response.status,
+        statusText: response.statusText ?? '',
+        finalUrl,
+        elapsedMs,
+        headerLines,
+        body,
+        truncated,
+        shownBody,
+    };
+}
+export function formatHttpResponse(result) {
+    const sections = [
+        `Status: ${result.status} ${result.statusText}`.trimEnd(),
+        `Final URL: ${result.finalUrl}`,
+        `Elapsed: ${result.elapsedMs}ms`,
+        `Response headers:\n${result.headerLines.length > 0 ? result.headerLines.join('\n') : '  (none)'}`,
+        result.truncated
+            ? `Body (${result.body.length} characters, truncated to ${HTTP_MAX_BODY_CHARS}):\n${result.shownBody}`
+            : `Body:\n${result.shownBody === '' ? '(empty)' : result.shownBody}`,
+    ];
+    return sections.join('\n\n');
+}
+export const API_TOOLS = [
+// ▸▸▸ EXTERNAL API TOOL DEFINITIONS GO HERE ◂◂◂
+];
+export function registerExternalApiTools(server) {
+    for (const tool of API_TOOLS) {
+        server.registerTool(tool.name, {
+            title: tool.title ?? tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            ...(tool.annotations ? { annotations: tool.annotations } : {}),
+        }, tool.call);
+    }
+}
+//# sourceMappingURL=external.js.map

package/dist/external.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * MCP server for the Old School RuneScape Wiki.
+ * Serves the full MediaWiki tool surface against a pinned, read-only wiki.
+ * Transport: stdio (newline-delimited JSON-RPC).
+ */
+import './env.js';
+declare function main(): Promise<void>;
+export { main };
+//# 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":";AACA;;;;GAIG;AAIH,OAAO,UAAU,CAAC;AAUlB,iBAAe,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAqBnC;AAWD,OAAO,EAAE,IAAI,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * MCP server for the Old School RuneScape Wiki.
+ * Serves the full MediaWiki tool surface against a pinned, read-only wiki.
+ * Transport: stdio (newline-delimited JSON-RPC).
+ */
+// Must be first: composes User-Agent from MCP_CONTACT before upstream modules
+// evaluate it at import time.
+import './env.js';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import { logger } from '@professional-wiki/mediawiki-mcp-server/dist/runtime/logger.js';
+import { registerShutdownHandlers } from '@professional-wiki/mediawiki-mcp-server/dist/runtime/shutdown.js';
+import { SERVER_NAME, SERVER_VERSION } from './server.js';
+import { errorMessage } from './external.js';
+import { buildServer } from './server.js';
+async function main() {
+    process.on('uncaughtException', (error) => {
+        const stack = error instanceof Error ? error.stack : undefined;
+        logger.error(`Uncaught exception: ${stack ?? errorMessage(error)}`);
+        process.exit(1);
+    });
+    process.on('unhandledRejection', (reason) => {
+        logger.error(`Unhandled rejection: ${errorMessage(reason)}`);
+    });
+    const server = await buildServer();
+    logger.info(`${SERVER_NAME} ${SERVER_VERSION} serving over stdio`);
+    const handle = serveStdio(() => server, {
+        onerror: (error) => logger.error(`stdio serving error: ${error.message}`),
+    });
+    registerShutdownHandlers({
+        transport: 'stdio',
+        graceMs: 0,
+        stdioTransport: handle,
+    });
+}
+main().catch((error) => {
+    const stack = error instanceof Error ? error.stack : undefined;
+    console.error(`[${SERVER_NAME}] fatal error:`, stack ?? errorMessage(error));
+    process.exit(1);
+});
+export { main };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;GAIG;AAEH,8EAA8E;AAC9E,8BAA8B;AAC9B,OAAO,UAAU,CAAC;AAElB,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAChE,OAAO,EAAE,MAAM,EAAE,MAAM,gEAAgE,CAAC;AACxF,OAAO,EAAE,wBAAwB,EAAE,MAAM,kEAAkE,CAAC;AAE5G,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,KAAK,UAAU,IAAI;IAClB,OAAO,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,KAAc,EAAE,EAAE;QAClD,MAAM,KAAK,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QAC/D,MAAM,CAAC,KAAK,CAAC,uBAAuB,KAAK,IAAI,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACpE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjB,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,MAAe,EAAE,EAAE;QACpD,MAAM,CAAC,KAAK,CAAC,wBAAwB,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC9D,CAAC,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,MAAM,WAAW,EAAE,CAAC;IACnC,MAAM,CAAC,IAAI,CAAC,GAAG,WAAW,IAAI,cAAc,qBAAqB,CAAC,CAAC;IAEnE,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE;QACvC,OAAO,EAAE,CAAC,KAAY,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,wBAAwB,KAAK,CAAC,OAAO,EAAE,CAAC;KAChF,CAAC,CAAC;IACH,wBAAwB,CAAC;QACxB,SAAS,EAAE,OAAO;QAClB,OAAO,EAAE,CAAC;QACV,cAAc,EAAE,MAAM;KACtB,CAAC,CAAC;AACJ,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC/B,MAAM,KAAK,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IAC/D,OAAO,CAAC,KAAK,CACZ,IAAI,WAAW,gBAAgB,EAC/B,KAAK,IAAI,YAAY,CAAC,KAAK,CAAC,CAC5B,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACjB,CAAC,CAAC,CAAC;AAEH,OAAO,EAAE,IAAI,EAAE,CAAC"}

package/dist/resources.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/server';
+export declare function registerResources(server: McpServer): void;
+//# sourceMappingURL=resources.d.ts.map

package/dist/resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAE9D,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAmBzD"}

package/dist/resources.js

@@ -0,0 +1,41 @@
+/**
+ * Generic resource loader - registers all static file resources.
+ * Add new resources to the RESOURCES array below.
+ */
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+const RESOURCES = [
+    {
+        name: 'bucket-index',
+        uri: 'context://bucket-index',
+        file: fileURLToPath(new URL('../../resources/bucket-index.md', import.meta.url)),
+        title: 'Bucket Index',
+        description: 'Curated hint list of known Bucket buckets on the OSRS wiki (names, query forms, purposes). Not authoritative - if nothing matches, fall back to discovery via search-page-by-prefix in the Bucket: namespace.',
+        mimeType: 'text/markdown',
+    },
+    // Add more resources here:
+    // {
+    // 	name: 'my-resource',
+    // 	uri: 'context://my-resource',
+    // 	file: fileURLToPath(new URL('../../resources/my-file.txt', import.meta.url)),
+    // 	title: 'My Resource',
+    // 	description: 'Description for the model',
+    // 	mimeType: 'text/plain',
+    // },
+];
+export function registerResources(server) {
+    for (const resource of RESOURCES) {
+        server.registerResource(resource.name, resource.uri, {
+            title: resource.title,
+            description: resource.description,
+            mimeType: resource.mimeType,
+        }, async (uri) => {
+            const text = await readFile(resource.file, 'utf8');
+            const href = typeof uri === 'string' ? uri : uri.href;
+            return {
+                contents: [{ uri: href, mimeType: resource.mimeType, text }],
+            };
+        });
+    }
+}
+//# sourceMappingURL=resources.js.map

package/dist/resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAWzC,MAAM,SAAS,GAAqB;IACnC;QACC,IAAI,EAAE,cAAc;QACpB,GAAG,EAAE,wBAAwB;QAC7B,IAAI,EAAE,aAAa,CAAC,IAAI,GAAG,CAAC,iCAAiC,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;QAChF,KAAK,EAAE,cAAc;QACrB,WAAW,EACV,+MAA+M;QAChN,QAAQ,EAAE,eAAe;KACzB;IACD,2BAA2B;IAC3B,IAAI;IACJ,wBAAwB;IACxB,iCAAiC;IACjC,iFAAiF;IACjF,yBAAyB;IACzB,6CAA6C;IAC7C,2BAA2B;IAC3B,KAAK;CACL,CAAC;AAIF,MAAM,UAAU,iBAAiB,CAAC,MAAiB;IAClD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QAClC,MAAM,CAAC,gBAAgB,CACtB,QAAQ,CAAC,IAAI,EACb,QAAQ,CAAC,GAAG,EACZ;YACC,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,WAAW,EAAE,QAAQ,CAAC,WAAW;YACjC,QAAQ,EAAE,QAAQ,CAAC,QAAQ;SAC3B,EACD,KAAK,EAAE,GAAiB,EAAE,EAAE;YAC3B,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACnD,MAAM,IAAI,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;YACtD,OAAO;gBACN,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC;aAC5D,CAAC;QACH,CAAC,CACD,CAAC;IACH,CAAC;AACF,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,23 @@
+export declare class RateLimitError extends Error {
+}
+declare class SlidingWindowLimiter {
+    #private;
+    private readonly maxRequests;
+    private readonly windowMs;
+    private readonly maxWaitMs;
+    private readonly label;
+    private readonly stamps;
+    constructor(maxRequests: number, windowMs: number, maxWaitMs: number, label: string);
+    acquire(): Promise<void>;
+}
+export declare const externalLimiter: SlidingWindowLimiter;
+export declare const SERVER_NAME = "osrs-wiki-mcp-server";
+export declare const SERVER_VERSION = "1.0.0";
+/**
+ * Assembles the MCP server: upstream MediaWiki tools wired to pinned OSRS wiki.
+ */
+import './env.js';
+import { McpServer } from '@modelcontextprotocol/server';
+export declare function buildServer(): Promise<McpServer>;
+export {};
+//# 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":"AA2BA,qBAAa,cAAe,SAAQ,KAAK;CAAG;AAM5C,cAAM,oBAAoB;;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IAEvC,YAAY,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAKlF;IAQK,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAkB7B;CACD;AASD,eAAO,MAAM,eAAe,sBAK3B,CAAC;AAyDF,eAAO,MAAM,WAAW,yBAAyB,CAAC;AAClD,eAAO,MAAM,cAAc,UAAU,CAAC;AA4CtC;;GAEG;AACH,OAAO,UAAU,CAAC;AAElB,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAWzD,wBAAsB,WAAW,IAAI,OAAO,CAAC,SAAS,CAAC,CAgDtD"}

package/dist/server.js

@@ -0,0 +1,193 @@
+import { reconcileTools } from '@professional-wiki/mediawiki-mcp-server/dist/runtime/reconcile.js';
+import { allTools, registerAllTools, } from '@professional-wiki/mediawiki-mcp-server/dist/tools/index.js';
+import { extensionPacks } from '@professional-wiki/mediawiki-mcp-server/dist/tools/extensions/index.js';
+import { textResult } from './external.js';
+/**
+ * Two independent sliding-window rate limiters (package-owned constants).
+ * wikiLimiter: per MediaWiki tool call at registration seam.
+ * externalLimiter: per HTTP request via callHttp.
+ * Over budget: waits up to 10s, then fails with RateLimitError.
+ */
+const WINDOW_MS = 60_000;
+const MAX_WAIT_MS = 10_000;
+const WIKI_MAX_REQUESTS = 30;
+const EXTERNAL_MAX_REQUESTS = 30;
+export class RateLimitError extends Error {
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+class SlidingWindowLimiter {
+    maxRequests;
+    windowMs;
+    maxWaitMs;
+    label;
+    stamps = [];
+    constructor(maxRequests, windowMs, maxWaitMs, label) {
+        this.maxRequests = maxRequests;
+        this.windowMs = windowMs;
+        this.maxWaitMs = maxWaitMs;
+        this.label = label;
+    }
+    #prune(now) {
+        while (this.stamps.length > 0 && this.stamps[0] + this.windowMs <= now) {
+            this.stamps.shift();
+        }
+    }
+    async acquire() {
+        for (;;) {
+            const now = Date.now();
+            this.#prune(now);
+            if (this.stamps.length < this.maxRequests) {
+                this.stamps.push(now);
+                return;
+            }
+            const waitMs = this.stamps[0] + this.windowMs - now + 1;
+            if (waitMs > this.maxWaitMs) {
+                throw new RateLimitError(`${this.label} rate limit reached ` +
+                    `(${this.maxRequests} requests per ${Math.round(this.windowMs / 1000)}s). ` +
+                    `Retry in ~${Math.ceil(waitMs / 1000)}s.`);
+            }
+            await sleep(waitMs);
+        }
+    }
+}
+const wikiLimiter = new SlidingWindowLimiter(WIKI_MAX_REQUESTS, WINDOW_MS, MAX_WAIT_MS, 'MediaWiki API');
+export const externalLimiter = new SlidingWindowLimiter(EXTERNAL_MAX_REQUESTS, WINDOW_MS, MAX_WAIT_MS, 'External API');
+function createToolRegistry(server, ctx) {
+    const tools = new Map();
+    const applyGates = () => reconcileTools(tools, {
+        wikiRegistry: ctx.wikis,
+        transport: ctx.auth.transport,
+        wikiProbe: ctx.wikiProbe,
+        extensionPacks,
+        descriptors: allTools,
+    });
+    // Extension probes can flip tools after initial gate; re-gate and notify.
+    const reconcile = () => {
+        const promise = (async () => {
+            await applyGates();
+            await server.sendResourceListChanged?.();
+        })();
+        return promise;
+    };
+    // Rate-limit each upstream MediaWiki tool call at registration seam.
+    // Must wrap before upstream's register() collects RegisteredTool objects.
+    const baseRegisterTool = server.registerTool.bind(server);
+    server.registerTool = (name, config, callback) => {
+        if (typeof callback !== 'function') {
+            return baseRegisterTool(name, config);
+        }
+        return baseRegisterTool(name, config, async (...callbackArgs) => {
+            try {
+                await wikiLimiter.acquire();
+            }
+            catch (error) {
+                if (error instanceof RateLimitError) {
+                    return textResult(error.message, true);
+                }
+                throw error;
+            }
+            return callback(...callbackArgs);
+        });
+    };
+    const registered = registerAllTools(server, reconcile, ctx);
+    server.registerTool = baseRegisterTool;
+    for (const [name, tool] of registered) {
+        tools.set(name, tool);
+    }
+    return { tools, applyGates, reconcile };
+}
+import { USER_AGENT } from './env.js';
+export const SERVER_NAME = 'osrs-wiki-mcp-server';
+export const SERVER_VERSION = '1.0.0';
+const SERVER_TITLE = 'OSRS Wiki MCP Server';
+const SERVER_DESCRIPTION = 'MCP server for the Old School RuneScape Wiki: the full MediaWiki MCP tool surface against a pinned read-only wiki.';
+const BASE_USER_AGENT = `osrs-wiki-mcp-server/1.0.0 (https://github.com/mistereman22/osrs-wiki-mcp-server)`;
+const OSRS_WIKI = Object.freeze({
+    key: 'oldschool.runescape.wiki',
+    sitename: 'Old School RuneScape Wiki',
+    server: 'https://oldschool.runescape.wiki',
+    articlepath: '/wiki',
+    scriptpath: '',
+});
+// Cache hint: lists change only when wiki probe flips; don't share across deployments.
+const CACHE_HINT = { ttlMs: 60_000, cacheScope: 'private' };
+const SERVER_INSTRUCTIONS = [
+    `Tools and resources for the Old School RuneScape Wiki at ${OSRS_WIKI.server}, served by ${SERVER_NAME}.`,
+    'The wiki target is fixed by the package: no tool can add, remove, or switch wikis.',
+    `Deployment is read-only and anonymous. Outbound calls use User-Agent \`${BASE_USER_AGENT} <MCP_CONTACT>\`.`,
+    'MediaWiki tools follow upstream behavior from @professional-wiki/mediawiki-mcp-server.',
+    'For structured data prefer `bucket-query`; use `context://bucket-index` to discover buckets, fall back to runtime discovery.',
+    'Outbound traffic is rate-limited; calls over budget wait or return rate-limit error.',
+].join(' ');
+function buildWikiConfig() {
+    return {
+        defaultWiki: OSRS_WIKI.key,
+        allowWikiManagement: false,
+        uploadDirs: [],
+        wikis: {
+            [OSRS_WIKI.key]: {
+                sitename: OSRS_WIKI.sitename,
+                server: OSRS_WIKI.server,
+                articlepath: OSRS_WIKI.articlepath,
+                scriptpath: OSRS_WIKI.scriptpath,
+                readOnly: true,
+                token: null,
+                private: false,
+            },
+        },
+    };
+}
+/**
+ * Assembles the MCP server: upstream MediaWiki tools wired to pinned OSRS wiki.
+ */
+import './env.js';
+import { McpServer } from '@modelcontextprotocol/server';
+import { createAppState } from '@professional-wiki/mediawiki-mcp-server/dist/wikis/state.js';
+import { createSharedContext } from '@professional-wiki/mediawiki-mcp-server/dist/runtime/createContext.js';
+import { logger } from '@professional-wiki/mediawiki-mcp-server/dist/runtime/logger.js';
+import { readAuthPolicy } from '@professional-wiki/mediawiki-mcp-server/dist/runtime/authShape.js';
+import { StdioSignIn } from '@professional-wiki/mediawiki-mcp-server/dist/auth/stdioSignIn.js';
+import { readMetrics } from '@professional-wiki/mediawiki-mcp-server/dist/runtime/metrics.js';
+import { registerResources } from './resources.js';
+import { registerExternalApiTools } from './external.js';
+export async function buildServer() {
+    logger.info(`${SERVER_NAME} ${SERVER_VERSION} starting - wiki ${OSRS_WIKI.server}, ` +
+        `read-only, user agent ${JSON.stringify(USER_AGENT)}`);
+    const state = createAppState(buildWikiConfig());
+    const auth = readAuthPolicy(process.env, 'stdio', null, new StdioSignIn());
+    const ctx = createSharedContext({
+        logger,
+        state,
+        auth,
+        metrics: readMetrics(process.env, 'stdio'),
+    });
+    const server = new McpServer({
+        name: SERVER_NAME,
+        title: SERVER_TITLE,
+        version: SERVER_VERSION,
+        description: SERVER_DESCRIPTION,
+    }, {
+        capabilities: {
+            resources: { listChanged: true },
+            tools: { listChanged: true },
+        },
+        instructions: SERVER_INSTRUCTIONS,
+        cacheHints: {
+            'tools/list': CACHE_HINT,
+            'resources/list': CACHE_HINT,
+            'resources/templates/list': CACHE_HINT,
+            'resources/read': CACHE_HINT,
+            'server/discover': CACHE_HINT,
+        },
+    });
+    const { applyGates } = createToolRegistry(server, ctx);
+    registerResources(server);
+    // Package tools registered outside upstream tool map; never gated.
+    registerExternalApiTools(server);
+    // Extension-gated tools enabled after initial reconcile once wiki probe completes.
+    await applyGates();
+    return server;
+}
+//# 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/package.json

@@ -1,6 +1,53 @@
 {
-  "name": "@mistereman22/osrs-wiki-mcp-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@mistereman22/osrs-wiki-mcp-server",
+	"version": "1.0.0",
+	"description": "MCP server for the Old School RuneScape Wiki: the full MediaWiki MCP tool surface against a pinned read-only wiki.",
+	"type": "module",
+	"main": "./dist/index.js",
+	"bin": {
+		"osrs-wiki-mcp-server": "./dist/index.js"
+	},
+	"files": [
+		"dist/**/*",
+		"resources/**/*"
+	],
+	"scripts": {
+		"build": "tsc",
+		"start": "node dist/index.js",
+		"dev": "tsc && node dist/index.js"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/mistereman22/osrs-wiki-mcp-server.git"
+	},
+	"keywords": [
+		"mcp",
+		"model-context-protocol",
+		"mediawiki",
+		"osrs",
+		"runescape",
+		"wiki"
+	],
+	"author": "mistereman22",
+	"license": "MIT",
+	"bugs": {
+		"url": "https://github.com/mistereman22/osrs-wiki-mcp-server/issues"
+	},
+	"homepage": "https://github.com/mistereman22/osrs-wiki-mcp-server#readme",
+	"dependencies": {
+		"@modelcontextprotocol/server": "^2.4.0",
+		"@professional-wiki/mediawiki-mcp-server": "^0.21.0",
+		"axios": "^1.21.0",
+		"zod": "^4.6.7"
+	},
+	"devDependencies": {
+		"@types/node": "^26.6.6",
+		"typescript": "^7.0.2"
+	}
+}

package/resources/bucket-index.md

@@ -0,0 +1,77 @@
+# Bucket Index (hint list)
+
+> On-demand hints for `bucket-query` on the Old School RuneScape Wiki.
+> **This index is not authoritative.** Purpose descriptions are best-effort
+> summaries; fields always come from the schema page. If nothing here fits
+> your need, or a name fails at runtime, fall back to discovery:
+> `search-page-by-prefix` in the `Bucket:` namespace (id 9592), then
+> `get-page` on `Bucket:<Name>` to see exact fields and a data preview.
+>
+> Naming rule: pass the page title lowercased with spaces as underscores
+> (`Bucket:Clue equipment` -> `bucket("clue_equipment")`). All bucket and
+> field names are lowercase; fields are verified on the schema page, never
+> guessed from this file.
+
+## Known buckets
+
+| Query as | Page | Holds |
+| --- | --- | --- |
+| `bucket("bountytaskline")` | Bucket:Bountytaskline | Bounty Hunter task line entries |
+| `bucket("clue_equipment")` | Bucket:Clue equipment | Equipment associated with clue scroll steps |
+| `bucket("clue_info")` | Bucket:Clue info | Clue scroll metadata/step info |
+| `bucket("collection_log_source")` | Bucket:Collection log source | Sources for collection log slots |
+| `bucket("combat_achievement")` | Bucket:Combat achievement | Combat achievement tasks, tiers, requirements |
+| `bucket("couriertaskline")` | Bucket:Couriertaskline | Courier activity task line entries |
+| `bucket("demonicpactleaguetask")` | Bucket:Demonicpactleaguetask | Demonic Pact league task entries |
+| `bucket("dependency_list")` | Bucket:Dependency list | Item/object dependency relations |
+| `bucket("drop_table_sources")` | Bucket:Drop table sources | Which activities/NPCs use which drop tables |
+| `bucket("dropsline")` | Bucket:Dropsline | Drop table line entries per source |
+| `bucket("exchange")` | Bucket:Exchange | Grand Exchange prices (name, value, high/low, volumes) |
+| `bucket("feedback")` | Bucket:Feedback | Wiki feedback entries (site-internal) |
+| `bucket("ge_index_header")` | Bucket:Ge index header | Grand Exchange index header/snapshot metadata |
+| `bucket("infobox_activity")` | Bucket:Infobox activity | Skilling/activity infobox data |
+| `bucket("infobox_bonuses")` | Bucket:Infobox bonuses | Equipment combat stats and bonuses |
+| `bucket("infobox_construction")` | Bucket:Infobox construction | Construction object/buildable data |
+| `bucket("infobox_grid_master_unlock")` | Bucket:Infobox grid master unlock | Grid Master unlock data |
+| `bucket("infobox_item")` | Bucket:Infobox item | Core item data: id, name, examine, flags, stats |
+| `bucket("infobox_location")` | Bucket:Infobox location | Location/area data |
+| `bucket("infobox_monster")` | Bucket:Infobox monster | Monster combat stats: level, hitpoints, max hit |
+| `bucket("infobox_npc")` | Bucket:Infobox npc | NPC data: id, combat level, examine |
+| `bucket("infobox_pure")` | Bucket:Infobox pure | Pure-entity infobox data (verify schema) |
+| `bucket("infobox_scenery")` | Bucket:Infobox scenery | Scenery/object entity data |
+| `bucket("infobox_ship_part")` | Bucket:Infobox ship part | Ship part data |
+| `bucket("infobox_shop")` | Bucket:Infobox shop | Shop stock and prices |
+| `bucket("infobox_spell")` | Bucket:Infobox spell | Spell data: requirements, effects, costs |
+| `bucket("interface")` | Bucket:Interface | Game interface definitions |
+| `bucket("item_id")` | Bucket:Item id | Item name to id mappings |
+| `bucket("locline")` | Bucket:Locline | Location line entries |
+| `bucket("logs")` | Bucket:Logs | Woodcutting log/tree data |
+| `bucket("map")` | Bucket:Map | Map marker/region data |
+| `bucket("mine")` | Bucket:Mine | Mining node/rock data |
+| `bucket("mmg_output")` | Bucket:Mmg output | Money making guide output calculations |
+| `bucket("money_making_guide")` | Bucket:Money making guide | Money making methods: profit, requirements |
+| `bucket("music")` | Bucket:Music | Music track unlock data |
+| `bucket("music_file")` | Bucket:Music file | Music file metadata |
+| `bucket("music_map")` | Bucket:Music map | Music tracks by region/map area |
+| `bucket("music_versions")` | Bucket:Music versions | Music version/history entries |
+| `bucket("npc_id")` | Bucket:Npc id | NPC name to id mappings |
+| `bucket("object_id")` | Bucket:Object id | Object/scenery id mappings |
+| `bucket("quest")` | Bucket:Quest | Quest data: requirements, rewards, difficulty |
+| `bucket("recipe")` | Bucket:Recipe | Creation/processing recipes: inputs, outputs, skills |
+| `bucket("recommended_equipment")` | Bucket:Recommended equipment | Recommended gear setups by activity/slot |
+| `bucket("seachart")` | Bucket:Seachart | Sea chart/naval data |
+| `bucket("sound_effect")` | Bucket:Sound effect | Sound effect metadata |
+| `bucket("soundtrack")` | Bucket:Soundtrack | Soundtrack track data |
+| `bucket("storeline")` | Bucket:Storeline | Store line entries |
+| `bucket("testing_bucket")` | Bucket:Testing bucket | Wiki-internal testing data (not real content) |
+| `bucket("transcript")` | Bucket:Transcript | NPC/dialogue transcripts |
+| `bucket("update")` | Bucket:Update | Game update records: dates, summaries |
+| `bucket("varbit")` | Bucket:Varbit | Varbit id to meaning mappings |
+
+## Query reminders
+
+- Query must end in `.run()`; `limit` max 500, paginate with `continueFrom`.
+- Equality: `where("field","value")`; operators: `where({"field",">",value})`
+  with `=`, `!=`, `>`, `<`, `>=`, `<=`; compose with `Bucket.And/Or/Not`.
+- Example: `bucket("infobox_item").select("item_id","examine").where("item_name","Raw lobster").run()`
+- Full Lua reference: https://meta.weirdgloop.org/w/Extension:Bucket/Usage