world-building-framework 0.2.0 → 0.2.2

package/dist/mcp/server.js

@@ -0,0 +1,140 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { readVaultFile } from "../core/vault/index.js";
+import { runSchema } from "../cli/commands/schema.js";
+import { runSearch } from "../cli/commands/search.js";
+import { runValidate } from "../cli/commands/validate.js";
+import { runCreate } from "../cli/commands/create.js";
+import { runUpdate } from "../cli/commands/update.js";
+import { loadWorldConfig } from "../core/config/index.js";
+import { findVaultDir, resolveVaultDir } from "../cli/vault-path.js";
+/**
+ * What every agent connecting to the server is told up front: the
+ * world-vault skill's rules (skills/world-vault/SKILL.md), in terms of this
+ * server's tools instead of CLI commands.
+ */
+export const MCP_INSTRUCTIONS = `This server reads and writes a world built with the World Building Framework: a vault of entity and event files, named by UUID. Use only these tools to read or change it; they validate everything before it's written.
+
+1. Call \`schema\` before writing anything. It lists every field, its shape, and an example input.
+2. Call \`search\` before creating something, to avoid duplicates and to get the UUIDs you link with.
+3. Links are always "[[<uuid>|<current title>]]", in frontmatter and in body text. Never a bare [[Name]].
+4. Before \`create\` or \`update\`, show the user the frontmatter and body you're about to write, and wait for their go-ahead.
+5. \`update\` is for corrections only (a typo, a wrong tag, a missing link). Call \`read\` first and send the file's complete new content: any field you leave out is removed. Changing a title rewrites links showing the old title in other files.
+6. A change in the story is never an update. Create a new entity file with \`supersedes\` (a link to the entity's latest version) and \`causedBy\` (a link to the event that caused the change). Other files keep linking to the entity's first file.
+7. Each published wiki (see \`list_variants\`) includes or leaves out whole files by their tags, and shows an included file in full. Keep secrets in their own files with narrower tags, never in the text of a file a wider audience sees.
+
+Errors in a result block a write; warnings don't, but mention them to the user.`;
+function toolResult({ result, failed }) {
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], ...(failed ? { isError: true } : {}) };
+}
+/** Runs a tool body, turning a thrown error into an error result the agent can read, like the CLI's `{"error": ...}`. */
+async function run(body) {
+    try {
+        return toolResult(await body());
+    }
+    catch (err) {
+        return toolResult({ result: { error: err.message }, failed: true });
+    }
+}
+/** A note when the world pins a different framework version than the one running this server, else undefined. */
+async function versionMismatch(vaultDir, running) {
+    if (!vaultDir)
+        return undefined;
+    try {
+        const pkg = JSON.parse(await readFile(path.join(vaultDir, "package.json"), "utf8"));
+        const pinned = pkg.dependencies?.["world-building-framework"];
+        if (!pinned || pinned === running)
+            return undefined;
+        return `This server runs world-building-framework ${running}, but the world pins ${pinned}. The published wiki is built with ${pinned}, so validation can differ slightly. Update the world (npm install world-building-framework@${running}, then wbf refresh), or start the server at the pinned version.`;
+    }
+    catch {
+        return undefined;
+    }
+}
+const fileInput = {
+    frontmatter: z.record(z.string(), z.unknown()).describe("The file's frontmatter fields. See the schema tool."),
+    body: z.string().optional().describe("Markdown body text. Links inside it use the same [[<uuid>|Title]] form."),
+};
+/**
+ * The `wbf mcp` server (claude-dev/DISTRIBUTION_PLAN.md, component 6): the
+ * CLI's vault commands as MCP tools, for agents without a terminal. Each tool
+ * calls the same function as its CLI command; only `read` is extra, since an
+ * agent without a shell can't open a file to prepare an `update`.
+ */
+export function createMcpServer(options) {
+    const server = new McpServer({ name: "world-building-framework", version: options.version }, { instructions: MCP_INSTRUCTIONS });
+    const vault = options.vault;
+    const readOnly = { readOnlyHint: true, openWorldHint: false };
+    server.registerTool("schema", {
+        title: "Show the file schema",
+        description: "Every frontmatter field with its shape and whether it's required, this world's entityType list, and example inputs for create. Call it before writing anything.",
+        annotations: readOnly,
+    }, () => run(async () => {
+        const text = await runSchema(vault);
+        const note = await versionMismatch(findVaultDir(vault), options.version);
+        return { result: note ? `${text}\n\nNote: ${note}` : text };
+    }));
+    server.registerTool("search", {
+        title: "Search the world",
+        description: "Keyword search over titles, aliases and text. Each result has the file's id (the UUID you link with), title and score, and for entities entityType and tags.",
+        inputSchema: {
+            query: z.string().min(1).describe("Search terms"),
+            tags: z.array(z.string()).optional().describe("Only files carrying all of these tags"),
+            limit: z.number().int().positive().optional().describe("Maximum number of results"),
+        },
+        annotations: readOnly,
+    }, ({ query, tags, limit }) => run(async () => ({ result: await runSearch(vault, query, { tags, limit }) })));
+    server.registerTool("read", {
+        title: "Read a file",
+        description: "One file's id, frontmatter and body. Call it before update, which needs the file's complete new content.",
+        inputSchema: { id: z.string().describe("The file's UUID") },
+        annotations: readOnly,
+    }, ({ id }) => run(async () => {
+        const file = await readVaultFile(resolveVaultDir(vault), id);
+        return { result: { id: file.id, frontmatter: file.frontmatter, body: file.body } };
+    }));
+    server.registerTool("validate", {
+        title: "Validate",
+        description: "Checks without writing anything. With frontmatter (and body): a candidate file, exactly as create would check it. With id: one existing file. With neither: the whole world.",
+        inputSchema: {
+            id: z.string().optional().describe("Check one existing file"),
+            frontmatter: fileInput.frontmatter.optional(),
+            body: fileInput.body,
+        },
+        annotations: readOnly,
+    }, ({ id, frontmatter, body }) => run(async () => {
+        const candidate = frontmatter ? { frontmatter, body } : undefined;
+        const outcome = await runValidate(vault, { id: candidate ? undefined : id, candidate });
+        const valid = Array.isArray(outcome) ? outcome.every((o) => o.valid) : outcome.valid;
+        return { result: outcome, failed: !valid };
+    }));
+    server.registerTool("create", {
+        title: "Create a file",
+        description: "Creates a new entity or event file under a new UUID, after the same checks as validate; on any error nothing is written. Returns the new id. Show the user the content and get their go-ahead first.",
+        inputSchema: fileInput,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, ({ frontmatter, body }) => run(async () => {
+        const outcome = await runCreate(vault, { frontmatter, body });
+        return { result: outcome, failed: !outcome.written };
+    }));
+    server.registerTool("update", {
+        title: "Correct a file",
+        description: "Replaces an existing file's whole content, for corrections only; a change in the story is a new version (create with supersedes and causedBy). Call read first and send the complete content: fields you leave out are removed. type can't change. A changed title is also rewritten in other files' links. Show the user the change and get their go-ahead first.",
+        inputSchema: { id: z.string().describe("The file's UUID"), ...fileInput },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    }, ({ id, frontmatter, body }) => run(async () => {
+        const outcome = await runUpdate(vault, id, { frontmatter, body });
+        return { result: outcome, failed: !outcome.written };
+    }));
+    server.registerTool("list_variants", {
+        title: "List the wikis",
+        description: "The build variants in world.config.json, by name: one published wiki each, e.g. a player wiki and a GM wiki. A file is in a wiki if it carries all of the variant's tags (and, for events, its date is inside the dateRange); {} includes everything. Use it to see which audiences a file's tags reach.",
+        annotations: readOnly,
+    }, () => run(async () => {
+        const config = await loadWorldConfig(resolveVaultDir(vault));
+        return { result: config.buildVariants ?? {} };
+    }));
+    return server;
+}

package/dist/render-pipeline/build.d.ts

@@ -4,6 +4,9 @@ import type { BuildVariantQuery, RenderedPage } from "./types.js";
  * Stage 1: vault -> derived, Quartz-ready page set (RENDER_PIPELINE.md). Filters
  * by the build variant's query, merges each included entity's version history
  * into one page, and rewrites every link to a slug (or strips it if the target
- * isn't included).
+ * isn't included). Adds a start page listing everything included, titled
+ * `options.title` (the world's title).
  */
-export declare function buildDerivedTree(files: VaultFile[], query: BuildVariantQuery): RenderedPage[];
+export declare function buildDerivedTree(files: VaultFile[], query: BuildVariantQuery, options?: {
+    title?: string;
+}): RenderedPage[];

package/dist/render-pipeline/build.js

@@ -1,9 +1,10 @@
-import { buildGraph } from "../core/graph/index.js";
+import { buildGraph, topologicalOrder } from "../core/graph/index.js";
 import { filterEvents, filterEntityAnchors } from "./filter.js";
 import { mergeEntityBody } from "./merge.js";
 import { assignSlugs } from "./slugs.js";
 import { rewriteLinks, rewriteFrontmatterLinks } from "./rewrite.js";
 import { renameQuartzReservedFields } from "./quartz-compat.js";
+import { buildStartPage, START_PAGE_SLUG } from "./start-page.js";
 function titleOf(file) {
     return typeof file.frontmatter.title === "string" ? file.frontmatter.title : file.id;
 }
@@ -11,20 +12,22 @@ function titleOf(file) {
  * Stage 1: vault -> derived, Quartz-ready page set (RENDER_PIPELINE.md). Filters
  * by the build variant's query, merges each included entity's version history
  * into one page, and rewrites every link to a slug (or strips it if the target
- * isn't included).
+ * isn't included). Adds a start page listing everything included, titled
+ * `options.title` (the world's title).
  */
-export function buildDerivedTree(files, query) {
+export function buildDerivedTree(files, query, options = {}) {
     const graph = buildGraph(files);
     const includedEventIds = filterEvents(graph, files, query);
     const includedAnchorIds = filterEntityAnchors(graph, files, query);
     // Sorted for a deterministic slug assignment, independent of vault read order.
     const includedIds = [...includedEventIds, ...includedAnchorIds].sort();
     const titles = new Map(includedIds.map((id) => [id, titleOf(graph.nodes.get(id))]));
-    const slugsById = assignSlugs(titles);
-    const pages = [];
-    for (const id of includedEventIds) {
+    const slugsById = assignSlugs(titles, [START_PAGE_SLUG]);
+    const eventPages = [];
+    const entityPages = [];
+    for (const id of topologicalOrder(graph).filter((eventId) => includedEventIds.has(eventId))) {
         const file = graph.nodes.get(id);
-        pages.push({
+        eventPages.push({
             id,
             slug: slugsById.get(id),
             frontmatter: renameQuartzReservedFields(rewriteFrontmatterLinks(file.frontmatter, slugsById)),
@@ -34,12 +37,13 @@ export function buildDerivedTree(files, query) {
     for (const anchorId of includedAnchorIds) {
         const anchor = graph.nodes.get(anchorId);
         const mergedBody = mergeEntityBody(graph, anchorId, includedEventIds);
-        pages.push({
+        entityPages.push({
             id: anchorId,
             slug: slugsById.get(anchorId),
             frontmatter: renameQuartzReservedFields(rewriteFrontmatterLinks(anchor.frontmatter, slugsById)),
             body: rewriteLinks(mergedBody, slugsById),
         });
     }
-    return pages;
+    const startPage = buildStartPage(options.title ?? "World Wiki", entityPages, eventPages);
+    return [...eventPages, ...entityPages, startPage];
 }

package/dist/render-pipeline/index.d.ts

@@ -5,6 +5,7 @@ export * from "./merge.js";
 export * from "./slugs.js";
 export * from "./rewrite.js";
 export * from "./quartz-compat.js";
+export * from "./start-page.js";
 export * from "./build.js";
 export * from "./write.js";
 export * from "./sync.js";

package/dist/render-pipeline/index.js

@@ -5,6 +5,7 @@ export * from "./merge.js";
 export * from "./slugs.js";
 export * from "./rewrite.js";
 export * from "./quartz-compat.js";
+export * from "./start-page.js";
 export * from "./build.js";
 export * from "./write.js";
 export * from "./sync.js";

package/dist/render-pipeline/slugs.d.ts

@@ -2,6 +2,7 @@
  * Assigns a unique, readable slug per id — vault files are UUID-named (SCHEMA.md),
  * meaningless as a published URL; this is what Stage 1 uses instead for the
  * derived tree. Iterates `titles` in whatever order the caller provides, so pass
- * ids in a deterministic order for reproducible builds.
+ * ids in a deterministic order for reproducible builds. No page gets a slug
+ * in `reserved` (e.g. the start page's "index").
  */
-export declare function assignSlugs(titles: Map<string, string>): Map<string, string>;
+export declare function assignSlugs(titles: Map<string, string>, reserved?: string[]): Map<string, string>;

package/dist/render-pipeline/slugs.js

@@ -10,10 +10,11 @@ function slugify(title) {
  * Assigns a unique, readable slug per id — vault files are UUID-named (SCHEMA.md),
  * meaningless as a published URL; this is what Stage 1 uses instead for the
  * derived tree. Iterates `titles` in whatever order the caller provides, so pass
- * ids in a deterministic order for reproducible builds.
+ * ids in a deterministic order for reproducible builds. No page gets a slug
+ * in `reserved` (e.g. the start page's "index").
  */
-export function assignSlugs(titles) {
-    const used = new Set();
+export function assignSlugs(titles, reserved = []) {
+    const used = new Set(reserved);
     const slugs = new Map();
     for (const [id, title] of titles) {
         const base = slugify(title);

package/dist/render-pipeline/start-page.d.ts

@@ -0,0 +1,9 @@
+import type { RenderedPage } from "./types.js";
+/** Quartz builds a site's root page from `content/index.md`; without it, the wiki's own address is a 404. */
+export declare const START_PAGE_SLUG = "index";
+/**
+ * The wiki's start page: every included entity, grouped by entityType and sorted
+ * by title, then every included event in causal order. `events` must already be
+ * in that order; only pages of this build go in, so nothing filtered out shows up.
+ */
+export declare function buildStartPage(title: string, entities: RenderedPage[], events: RenderedPage[]): RenderedPage;

package/dist/render-pipeline/start-page.js

@@ -0,0 +1,44 @@
+/** Quartz builds a site's root page from `content/index.md`; without it, the wiki's own address is a 404. */
+export const START_PAGE_SLUG = "index";
+function titleOf(page) {
+    return typeof page.frontmatter.title === "string" ? page.frontmatter.title : page.slug;
+}
+function linkTo(page) {
+    return `[[${page.slug}|${titleOf(page)}]]`;
+}
+function describeDate(page) {
+    const date = page.frontmatter.worldDate;
+    if (typeof date?.year !== "number")
+        return "";
+    return typeof date.day === "number" ? ` (year ${date.year}, day ${date.day})` : ` (year ${date.year})`;
+}
+function heading(entityType) {
+    return entityType.charAt(0).toUpperCase() + entityType.slice(1);
+}
+/**
+ * The wiki's start page: every included entity, grouped by entityType and sorted
+ * by title, then every included event in causal order. `events` must already be
+ * in that order; only pages of this build go in, so nothing filtered out shows up.
+ */
+export function buildStartPage(title, entities, events) {
+    const groups = new Map();
+    for (const page of entities) {
+        const entityType = typeof page.frontmatter.entityType === "string" ? page.frontmatter.entityType : "";
+        groups.set(entityType, [...(groups.get(entityType) ?? []), page]);
+    }
+    // Typed groups alphabetically, untyped entities last.
+    const groupKeys = [...groups.keys()].sort((a, b) => (a === "" ? 1 : b === "" ? -1 : a.localeCompare(b)));
+    const sections = groupKeys.map((key) => {
+        const pages = groups.get(key).sort((a, b) => titleOf(a).localeCompare(titleOf(b)));
+        return `## ${key === "" ? "Other" : heading(key)}\n\n${pages.map((page) => `- ${linkTo(page)}`).join("\n")}`;
+    });
+    if (events.length > 0) {
+        sections.push(`## Events\n\n${events.map((page) => `- ${linkTo(page)}${describeDate(page)}`).join("\n")}`);
+    }
+    return {
+        id: START_PAGE_SLUG,
+        slug: START_PAGE_SLUG,
+        frontmatter: { title },
+        body: sections.length > 0 ? `${sections.join("\n\n")}\n` : "Nothing here yet.\n",
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "world-building-framework",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Build, search and publish fictional worlds from a vault of Markdown files: the wbf CLI and its core engine.",
   "license": "UNLICENSED",
   "type": "module",
@@ -32,11 +32,12 @@
     "prepublishOnly": "npm run typecheck && npm test"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
     "better-sqlite3": "^13.0.3",
     "commander": "^15.0.0",
     "gray-matter": "^4.0.3",
     "uuid": "^14.0.2",
-    "zod": "^3.23.8"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^9.6.0",

package/skills/world-vault/SKILL.md

@@ -98,3 +98,11 @@ When an event changes something about an entity (it looks different, its status
 Both fields are required together. The vault keeps every version, and the published wiki shows the whole history. Never overwrite an entity file's body to reflect an in-world change; that erases history the vault is designed to keep.
 
 Other files always link to an entity's **original, first-ever** file (its anchor), never to a later version. If you're not sure which id is the anchor, follow the file's `supersedes` chain back. Or reuse whatever id you already have for that entity: that's always the anchor once created.
+
+## 9. Secrets: each wiki shows whole files
+
+A world can publish several wikis (build variants in `world.config.json`, e.g. a player wiki and a GM wiki). They filter by **file**, using its `tags` and, for events, its date. Everything inside a file that's included is shown, body text and all.
+
+- Before writing, check which wikis the file will appear in: compare its `tags` with each variant's `tags` in `world.config.json`.
+- Keep anything meant for fewer readers (a GM secret, a later plot twist) out of files the wider audience sees. Put it in its own file with narrower tags, and link to it from there.
+- A link to a file a wiki leaves out turns into plain text, so its title still shows. Give secret files titles that don't give the secret away.

package/templates/AGENTS.md

@@ -6,6 +6,14 @@ This repo is a world built with the World Building Framework (version __WBF_VERS
 - Run `npx wbf schema` before writing anything, `npx wbf search <terms>` before creating something, and `npx wbf --help` for every command.
 - Never hand-write or hand-edit a vault `.md` file. Only `wbf create` and `wbf update` validate content, and only `create` generates the required UUID filename.
 - Show the user what you're about to write, and wait for their go-ahead, before `create` or `update`.
-- If skills were installed for your agent (`npx wbf init --agent <name>`), the `world-vault` skill has the full workflow.
+
+## Skills
+
+The `world-vault` skill (open Agent Skills format, `SKILL.md`) has the full workflow. If your project skills folder doesn't have it yet, install it for yourself, then tell the user to commit the new files:
+
+- Claude Code: `npx wbf init --agent claude`
+- Any other agent that reads `SKILL.md` skills: `npx wbf init --skills-dir <your project skills folder>`, relative to this repo. Only use a folder you know your agent reads.
+
+`init` only adds what's missing here and never overwrites a file.
 
 Generated by `wbf init`. `npx wbf refresh` keeps it current while it's unedited.