@realmkeep/mcp 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# @realmkeep/mcp
 
-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.
+Lets an AI assistant (Claude, Codex, Cursor) fill in a Realmkeep game listing for you.
+It creates and edits a **draft**, images included. You open the link it gives you, check it
+and press Submit, so the site's spam and review checks still apply.
+
+1. Create an account-wide API key at `/dashboard/api-keys`. Keys scoped to one listing
+   cannot create new listings.
+2. Add the server to your client.
+
+Claude Code:
+
+```
+claude mcp add realmkeep -e REALMKEEP_API_KEY=rk_your_key -- npx -y @realmkeep/mcp
+```
+
+Claude Desktop, Cursor and others, in the client's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "realmkeep": {
+      "command": "npx",
+      "args": ["-y", "@realmkeep/mcp"],
+      "env": { "REALMKEEP_API_KEY": "rk_your_key" }
+    }
+  }
+}
+```
+
+Codex, in `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.realmkeep]
+command = "npx"
+args = ["-y", "@realmkeep/mcp"]
+env = { REALMKEEP_API_KEY = "rk_your_key" }
+```
+
+`REALMKEEP_URL` overrides the site address (default `https://realmkeep.gg`).
+
+## Tools
+
+Every tool writes drafts only. None of them submits a listing: the person does that in the
+dashboard, so the site's checks still apply.
+
+| Tool | Parameters | What it does |
+| --- | --- | --- |
+| `list_taxonomy` | none | Lists the platforms, genres, themes, engines and player modes a listing can carry. |
+| `list_listings` | none | Lists the account's listings with id, name and state. |
+| `create_listing_draft` | `name` | Creates a draft from a game name and returns it with a `missing` list. |
+| `get_listing` | `id` | Reads one listing: every field, its links and terms, and what is still missing. |
+| `upload_listing_image` | `listingId`, `path`, `role` (`banner`, `logo` or `screenshot`), `altText` | Reads an image file from your computer and uploads it to a draft. A banner or logo replaces the existing one, screenshots are added. PNG, JPEG, WebP or AVIF up to 8 MB; `altText` is required. Refused once the listing is submitted. |
+| `update_listing` | `id`, then any of `name`, `tagline`, `descriptionMarkdown`, `playUrl`, `contactEmail`, `launchStatus`, `nsfw`, `links`, `platforms`, `genres`, `themes`, `engines`, `playerModes` and the other listing fields | Fills in a subset of a draft. Send only what changes, `null` clears an optional field. Refused once the listing is submitted. |
+
+The API behind them is documented at `/docs/api`, and described in `/openapi.json`.

package/dist/cli.d.ts

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

package/dist/cli.d.ts.map

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

package/dist/cli.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createClient } from './client.js';
+import { createServer } from './server.js';
+const apiKey = process.env['REALMKEEP_API_KEY'];
+if (apiKey === undefined || apiKey === '') {
+    console.error('Set REALMKEEP_API_KEY to an account-wide key from /dashboard/api-keys.');
+    process.exit(1);
+}
+const client = createClient({
+    apiKey,
+    baseUrl: process.env['REALMKEEP_URL'] ?? 'https://realmkeep.gg',
+});
+await createServer(client).connect(new StdioServerTransport());
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAA;AAChF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAA;AAC/C,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;IAC1C,OAAO,CAAC,KAAK,CAAC,wEAAwE,CAAC,CAAA;IACvF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACjB,CAAC;AAED,MAAM,MAAM,GAAG,YAAY,CAAC;IAC1B,MAAM;IACN,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,sBAAsB;CAChE,CAAC,CAAA;AAEF,MAAM,YAAY,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAA"}

package/dist/client.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A thin client for the Realmkeep listing API. The MCP server holds no listing logic:
+ * every rule (limits, content check, drafts only) lives on the site and comes back as
+ * an error message the model can read.
+ */
+export interface ClientOptions {
+    apiKey: string;
+    baseUrl: string;
+    fetch?: typeof fetch;
+}
+export declare class RealmkeepError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export interface RealmkeepClient {
+    request(method: string, path: string, body?: unknown): Promise<unknown>;
+    /** POST a multipart form, for the one endpoint that takes a file. */
+    upload(path: string, form: FormData): Promise<unknown>;
+}
+export declare function createClient(options: ClientOptions): RealmkeepClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;CACrB;AAED,qBAAa,cAAe,SAAQ,KAAK;IAErC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM;gBADZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM;CAKlB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACvE,qEAAqE;IACrE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACvD;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,eAAe,CA2CpE"}

package/dist/client.js

@@ -0,0 +1,48 @@
+/**
+ * A thin client for the Realmkeep listing API. The MCP server holds no listing logic:
+ * every rule (limits, content check, drafts only) lives on the site and comes back as
+ * an error message the model can read.
+ */
+export class RealmkeepError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'RealmkeepError';
+    }
+}
+export function createClient(options) {
+    const doFetch = options.fetch ?? fetch;
+    const base = options.baseUrl.replace(/\/$/, '');
+    async function send(path, init, headers) {
+        const response = await doFetch(`${base}/api/v1${path}`, {
+            ...init,
+            headers: {
+                authorization: `Bearer ${options.apiKey}`,
+                accept: 'application/json',
+                ...headers,
+            },
+        });
+        const text = await response.text();
+        let json;
+        try {
+            json = text === '' ? null : JSON.parse(text);
+        }
+        catch {
+            json = null;
+        }
+        if (!response.ok) {
+            const error = json?.error;
+            throw new RealmkeepError(response.status, error?.code ?? 'http_error', error?.message ?? `Realmkeep answered ${response.status}`);
+        }
+        return json;
+    }
+    return {
+        request: (method, path, body) => send(path, { method, ...(body === undefined ? {} : { body: JSON.stringify(body) }) }, { 'content-type': 'application/json' }),
+        // No content-type here: fetch sets it, with the boundary, from the FormData.
+        upload: (path, form) => send(path, { method: 'POST', body: form }, {}),
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAE5B;IACA;IAFX,YACW,MAAc,EACd,IAAY,EACrB,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAA;QAJL,WAAM,GAAN,MAAM,CAAQ;QACd,SAAI,GAAJ,IAAI,CAAQ;QAIrB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAA;IAC9B,CAAC;CACF;AAQD,MAAM,UAAU,YAAY,CAAC,OAAsB;IACjD,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAAA;IACtC,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;IAE/C,KAAK,UAAU,IAAI,CAAC,IAAY,EAAE,IAAiB,EAAE,OAA+B;QAClF,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,IAAI,UAAU,IAAI,EAAE,EAAE;YACtD,GAAG,IAAI;YACP,OAAO,EAAE;gBACP,aAAa,EAAE,UAAU,OAAO,CAAC,MAAM,EAAE;gBACzC,MAAM,EAAE,kBAAkB;gBAC1B,GAAG,OAAO;aACX;SACF,CAAC,CAAA;QAEF,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAA;QAClC,IAAI,IAAa,CAAA;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;QAC9C,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,GAAG,IAAI,CAAA;QACb,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,KAAK,GAAI,IAA+D,EAAE,KAAK,CAAA;YACrF,MAAM,IAAI,cAAc,CACtB,QAAQ,CAAC,MAAM,EACf,KAAK,EAAE,IAAI,IAAI,YAAY,EAC3B,KAAK,EAAE,OAAO,IAAI,sBAAsB,QAAQ,CAAC,MAAM,EAAE,CAC1D,CAAA;QACH,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO;QACL,OAAO,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAC9B,IAAI,CACF,IAAI,EACJ,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EACzE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CACvC;QACH,6EAA6E;QAC7E,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;KACvE,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createClient, RealmkeepError } from './client.js';
+export type { RealmkeepClient } from './client.js';
+export { createServer } from './server.js';
+export { tools } from './tools.js';
+//# 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":"AAAA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC1D,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createClient, RealmkeepError } from './client.js';
+export { createServer } from './server.js';
+export { tools } from './tools.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAE1D,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA"}

package/dist/server.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type RealmkeepClient } from './client.js';
+export declare function createServer(client: RealmkeepClient): McpServer;
+//# 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":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AACnE,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,aAAa,CAAA;AAGlE,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAmB/D"}

package/dist/server.js

@@ -0,0 +1,22 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { RealmkeepError } from './client.js';
+import { tools } from './tools.js';
+export function createServer(client) {
+    const server = new McpServer({ name: 'realmkeep', version: '0.2.0' });
+    for (const tool of tools) {
+        server.tool(tool.name, tool.description, tool.shape, async (args) => {
+            try {
+                const result = await tool.run(client, args);
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            catch (error) {
+                // The site's message is written to be read: it names the limit, the field, or
+                // the reason. Returned as a tool error so the model can correct and retry.
+                const message = error instanceof RealmkeepError ? `${error.code}: ${error.message}` : String(error);
+                return { isError: true, content: [{ type: 'text', text: message }] };
+            }
+        });
+    }
+    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":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AACnE,OAAO,EAAE,cAAc,EAAwB,MAAM,aAAa,CAAA;AAClE,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAElC,MAAM,UAAU,YAAY,CAAC,MAAuB;IAClD,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAA;IAErE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YAClE,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,IAA+B,CAAC,CAAA;gBACtE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAA;YACxF,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,8EAA8E;gBAC9E,2EAA2E;gBAC3E,MAAM,OAAO,GACX,KAAK,YAAY,cAAc,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;gBACrF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,CAAA;YAC/E,CAAC;QACH,CAAC,CAAC,CAAA;IACJ,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/tools.d.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import type { RealmkeepClient } from './client.js';
+export declare const listingFields: {
+    readonly name: z.ZodString;
+    readonly tagline: z.ZodString;
+    readonly descriptionMarkdown: z.ZodString;
+    readonly playUrl: z.ZodString;
+    readonly contactEmail: z.ZodString;
+    readonly launchStatus: z.ZodString;
+    readonly nsfw: z.ZodBoolean;
+    readonly developerName: z.ZodNullable<z.ZodString>;
+    readonly publisherName: z.ZodNullable<z.ZodString>;
+    readonly releaseDate: z.ZodNullable<z.ZodString>;
+    readonly serverRegion: z.ZodNullable<z.ZodString>;
+    readonly languages: z.ZodArray<z.ZodString, "many">;
+    readonly monetization: z.ZodNullable<z.ZodString>;
+    readonly hasAds: z.ZodBoolean;
+    readonly hasIap: z.ZodBoolean;
+    readonly payToWin: z.ZodBoolean;
+    readonly keyboardOnly: z.ZodBoolean;
+    readonly remappableControls: z.ZodBoolean;
+    readonly colourblindFriendly: z.ZodBoolean;
+    readonly subtitled: z.ZodBoolean;
+    readonly noFlashing: z.ZodBoolean;
+    readonly ageRatingSystem: z.ZodNullable<z.ZodString>;
+    readonly ageRatingValue: z.ZodNullable<z.ZodString>;
+    readonly trailerUrl: z.ZodNullable<z.ZodString>;
+    readonly serverHost: z.ZodNullable<z.ZodString>;
+    readonly serverPort: z.ZodNullable<z.ZodNumber>;
+    readonly voteRewardText: z.ZodNullable<z.ZodString>;
+    readonly voteCallbackUrl: z.ZodNullable<z.ZodString>;
+    readonly redirectAfterVote: z.ZodBoolean;
+    readonly links: z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>;
+    readonly platforms: z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber]>, "many">;
+    readonly genres: z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber]>, "many">;
+    readonly themes: z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber]>, "many">;
+    readonly engines: z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber]>, "many">;
+    readonly playerModes: z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber]>, "many">;
+};
+export interface Tool {
+    name: string;
+    description: string;
+    shape: z.ZodRawShape;
+    run(client: RealmkeepClient, args: Record<string, unknown>): Promise<unknown>;
+}
+export declare const tools: readonly Tool[];
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAkBlD,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoChB,CAAA;AAEV,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,CAAC,CAAC,WAAW,CAAA;IACpB,GAAG,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAC9E;AAgBD,eAAO,MAAM,KAAK,EAAE,SAAS,IAAI,EAmFhC,CAAA"}

package/dist/tools.js

@@ -0,0 +1,136 @@
+import { readFile, stat } from 'node:fs/promises';
+import { basename, extname } from 'node:path';
+import { z } from 'zod';
+/**
+ * The tools an AI assistant gets. Each is a single API call and returns the site's own
+ * JSON, so what the model sees is what the API says, including the `missing` list and
+ * the `dashboardUrl` it should hand to the person.
+ */
+const SOCIAL = z
+    .record(z.string(), z.string().nullable())
+    .describe('Network to URL, for example { "youtube": "https://youtube.com/@x" }. null removes one.');
+const TERMS = z
+    .array(z.union([z.string(), z.number()]))
+    .describe('Names, slugs or ids from list_taxonomy. A name the site lacks becomes a suggestion.');
+export const listingFields = {
+    name: z.string().describe('Game name'),
+    tagline: z.string().describe('One line, at least 10 characters'),
+    descriptionMarkdown: z.string().describe('Markdown, at least 150 characters of text'),
+    playUrl: z.string().describe('https URL where people play or download the game'),
+    contactEmail: z.string().describe('Email address for the site to reach the owner'),
+    launchStatus: z.string().describe('in_development, alpha, beta, early_access, live or sunset'),
+    nsfw: z.boolean().describe('True for adult content'),
+    developerName: z.string().nullable(),
+    publisherName: z.string().nullable(),
+    releaseDate: z.string().nullable().describe('YYYY-MM-DD'),
+    serverRegion: z.string().nullable(),
+    languages: z.array(z.string()).describe('Language codes'),
+    monetization: z.string().nullable(),
+    hasAds: z.boolean(),
+    hasIap: z.boolean(),
+    payToWin: z.boolean(),
+    keyboardOnly: z.boolean(),
+    remappableControls: z.boolean(),
+    colourblindFriendly: z.boolean(),
+    subtitled: z.boolean(),
+    noFlashing: z.boolean(),
+    ageRatingSystem: z.string().nullable().describe('pegi or esrb'),
+    ageRatingValue: z.string().nullable(),
+    trailerUrl: z.string().nullable().describe('YouTube link or direct .mp4 link'),
+    serverHost: z.string().nullable(),
+    serverPort: z.number().int().nullable(),
+    voteRewardText: z.string().nullable(),
+    voteCallbackUrl: z.string().nullable(),
+    redirectAfterVote: z.boolean(),
+    links: SOCIAL,
+    platforms: TERMS,
+    genres: TERMS,
+    themes: TERMS,
+    engines: TERMS.describe('At most one engine'),
+    playerModes: TERMS,
+};
+const HAND_OVER = 'You cannot submit a listing. When the draft is filled in, give the person the dashboardUrl so they can check it and press Submit.';
+const IMAGE_TYPES = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp',
+    '.avif': 'image/avif',
+};
+/** The size the site accepts, checked here so a huge file is not read into memory first. */
+const MAX_IMAGE_BYTES = 8 * 1024 * 1024;
+export const tools = [
+    {
+        name: 'list_taxonomy',
+        description: 'List the platforms, genres, themes, engines and player modes Realmkeep supports. Call this before choosing terms for a listing.',
+        shape: {},
+        run: (client) => client.request('GET', '/taxonomy'),
+    },
+    {
+        name: 'list_listings',
+        description: "List the account's listings with their id, name and state.",
+        shape: {},
+        run: (client) => client.request('GET', '/listings'),
+    },
+    {
+        name: 'create_listing_draft',
+        description: `Create a new draft listing from a game name. Returns the draft with a missing list. ${HAND_OVER}`,
+        shape: { name: listingFields.name },
+        run: (client, args) => client.request('POST', '/listings', { name: args['name'] }),
+    },
+    {
+        name: 'get_listing',
+        description: 'Read one listing: every field, its links and terms, and what is still missing before it can be submitted.',
+        shape: { id: z.string().describe('Listing id') },
+        run: (client, args) => client.request('GET', `/listings/${encodeURIComponent(String(args['id']))}`),
+    },
+    {
+        name: 'upload_listing_image',
+        description: 'Upload an image from a file on this computer to a draft listing. role is banner (wide, at least 1600 px across), logo (square, at least 512 px) or screenshot (at least 1600 px across). A banner or logo replaces the existing one; screenshots are added. altText is required: describe what the image shows. PNG, JPEG, WebP or AVIF up to 8 MB. Only drafts accept uploads.',
+        shape: {
+            listingId: z.string().describe('Listing id'),
+            path: z.string().describe('Path of the image file on the local machine'),
+            role: z.enum(['banner', 'logo', 'screenshot']),
+            altText: z.string().describe('What the image shows, up to 300 characters'),
+        },
+        run: async (client, args) => {
+            const path = String(args['path']);
+            const type = IMAGE_TYPES[extname(path).toLowerCase()];
+            if (type === undefined) {
+                throw new Error('The file must be a .png, .jpg, .jpeg, .webp or .avif image');
+            }
+            const info = await stat(path);
+            if (!info.isFile()) {
+                throw new Error('The path must be a regular image file');
+            }
+            if (info.size > MAX_IMAGE_BYTES) {
+                throw new Error('The file is larger than 8 MB. Save it at a lower quality and try again.');
+            }
+            const bytes = await readFile(path);
+            if (bytes.byteLength > MAX_IMAGE_BYTES) {
+                throw new Error('The file is larger than 8 MB. Save it at a lower quality and try again.');
+            }
+            const form = new FormData();
+            form.set('file', new File([new Uint8Array(bytes)], basename(path), { type }));
+            form.set('role', String(args['role']));
+            form.set('altText', String(args['altText']));
+            return client.upload(`/listings/${encodeURIComponent(String(args['listingId']))}/media`, form);
+        },
+    },
+    {
+        name: 'update_listing',
+        description: `Fill in any subset of a draft listing. Send only the fields you want to change; null clears an optional field. Only drafts can be changed. ${HAND_OVER}`,
+        shape: {
+            id: z.string().describe('Listing id'),
+            ...Object.fromEntries(Object.entries(listingFields)
+                .filter(([key]) => key !== 'name')
+                .map(([key, schema]) => [key, schema.optional()])),
+            name: listingFields.name.optional(),
+        },
+        run: (client, args) => {
+            const { id, ...fields } = args;
+            return client.request('PATCH', `/listings/${encodeURIComponent(String(id))}`, Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined)));
+        },
+    },
+];
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

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

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@realmkeep/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "mcpName": "io.github.mortek/realmkeep",
+  "version": "0.2.0",
+  "description": "MCP server that lets an AI assistant fill in a Realmkeep game listing as a draft",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "realmkeep-mcp": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "zod": "^3.24.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "directory": "packages/mcp"
+  }
+}