lorehub-mcp 0.1.0__tar.gz

lorehub_mcp-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/

lorehub_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lostwood Games
+
+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.

lorehub_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.5
+Name: lorehub-mcp
+Version: 0.1.0
+Summary: MCP server that lets AI agents read the Meta Areas of a LoreHub dialogue
+Project-URL: Homepage, https://lorehub.app
+Project-URL: Documentation, https://lorehub.app/mcp
+Author: Lostwood Games
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,dialogue,game-development,lorehub,mcp,model-context-protocol,narrative
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.3
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# LoreHub MCP
+
+<!-- mcp-name: io.github.lostwood-games/lorehub-mcp -->
+
+An MCP server that lets AI agents (Claude, Cursor and any other MCP client) read the **Meta Areas** of a [LoreHub](https://lorehub.app) dialogue.
+
+A director draws Meta Areas on the Dialogue Builder canvas: a shot, a location, a mood, with a note, a priority and meta rules such as `shot = close_up`. With this server, your agent reads those areas and the nodes inside them, and turns them into references, shot lists or mood boards. It only reads: it never changes your world.
+
+More on the [LoreHub MCP page](https://lorehub.app/mcp) and in the [Meta Areas guide](https://lorehub.app/meta-areas-guide).
+
+## Install
+
+You need a LoreHub account with at least Viewer access to the world, and [uv](https://docs.astral.sh/uv/getting-started/installation/). Nothing else to install: `uvx` downloads and runs the server.
+
+```bash
+uvx lorehub-mcp
+```
+
+Or with pip: `pip install lorehub-mcp`, then run `lorehub-mcp`.
+
+### Claude Code
+
+```bash
+claude mcp add lorehub --env LOREHUB_LOGIN=you@example.com --env LOREHUB_PASSWORD=your-password -- uvx lorehub-mcp
+```
+
+### Claude Desktop
+
+Settings → Developer → Edit Config, then add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "lorehub": {
+      "command": "uvx",
+      "args": ["lorehub-mcp"],
+      "env": {
+        "LOREHUB_LOGIN": "you@example.com",
+        "LOREHUB_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add the same block to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):
+
+```json
+{
+  "mcpServers": {
+    "lorehub": {
+      "command": "uvx",
+      "args": ["lorehub-mcp"],
+      "env": {
+        "LOREHUB_LOGIN": "you@example.com",
+        "LOREHUB_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+Other MCP clients work the same way: run `uvx lorehub-mcp` over stdio with the two environment variables.
+
+## Find your world and dialogue ids
+
+You don't need to look them up yourself. Ask the agent, for example *"List my LoreHub worlds, then find the dialogue Tom at Grandpa's and give me its Meta Areas"*, and it calls `list_worlds`, `list_dialogues` and `get_dialogue_meta` in turn.
+
+To copy them by hand: open the dialogue in the Dialogue Builder. The address looks like `app.lorehub.app/<owner>/<world>/game/<story id>?dialogue=<dialogue id>`, so the dialogue id is after `?dialogue=`. The world id comes from `list_worlds`.
+
+## Tools
+
+| Tool | What it returns |
+| --- | --- |
+| `list_worlds()` | The worlds your account can open, with their ids and your role. |
+| `list_dialogues(world_id, game_id?, name?)` | Stories and their dialogues with ids. `name` filters by dialogue name. |
+| `get_dialogue_meta(world_id, dialogue_id, area?, include_nodes=true)` | Each Meta Area's title, note, priority and meta rules as `field name: value`, the nodes inside it, and the nodes where areas overlap (higher priority first). `area` filters by title text or area id. |
+
+Example output of `get_dialogue_meta`:
+
+```json
+{
+  "dialogue": "Tom at Grandpa's",
+  "dialogue_id": "…",
+  "areas": [
+    {"title": "Grandpa's house: wide", "priority": 1,
+     "rules": {"shot": "wide", "background": "grandpas_house"},
+     "nodes": ["dlg.n_01", "dlg.n_04"], "id": "…"},
+    {"title": "Close-up: Tom is crying", "note": "Tears, low light", "priority": 2,
+     "rules": {"shot": "close_up", "background": "grandpas_house", "tom_emotion": "crying"},
+     "nodes": ["dlg.n_04"], "id": "…"}
+  ],
+  "overlaps": [{"node": "dlg.n_04", "areas": ["Close-up: Tom is crying (P2)", "Grandpa's house: wide (P1)"]}]
+}
+```
+
+## Configuration
+
+| Variable | Default | |
+| --- | --- | --- |
+| `LOREHUB_LOGIN`, `LOREHUB_PASSWORD` | | Your LoreHub user name or email and password. The server signs in, and signs in again when the token expires. |
+| `LOREHUB_TOKEN` | | A LoreHub JWT instead of a login and password. It lasts 8 hours. |
+| `LOREHUB_API_URL` | `https://api.lorehub.app` | |
+| `LOREHUB_TIMEOUT` | `30` | Seconds per request. |
+| `LOREHUB_LOG_LEVEL` | `INFO` | Logs go to stderr. |
+| `LOREHUB_NODE_WIDTH`, `LOREHUB_NODE_HEADER_HEIGHT` | `200`, `32` | The canvas node card size. Leave them as they are. |
+
+## How it works
+
+The server makes read-only GET calls to the LoreHub API with your account's token: the dialogue's Meta Areas, its name and story, the story's meta schema (to turn rule ids into field names) and the node positions. A node is inside an area when the middle of its header is, the same rule the Dialogue Builder uses.
+
+Not yet: nodes come back as full ids, without their line text or speaker.
+
+## License
+
+MIT

lorehub_mcp-0.1.0/README.md

@@ -0,0 +1,118 @@
+# LoreHub MCP
+
+<!-- mcp-name: io.github.lostwood-games/lorehub-mcp -->
+
+An MCP server that lets AI agents (Claude, Cursor and any other MCP client) read the **Meta Areas** of a [LoreHub](https://lorehub.app) dialogue.
+
+A director draws Meta Areas on the Dialogue Builder canvas: a shot, a location, a mood, with a note, a priority and meta rules such as `shot = close_up`. With this server, your agent reads those areas and the nodes inside them, and turns them into references, shot lists or mood boards. It only reads: it never changes your world.
+
+More on the [LoreHub MCP page](https://lorehub.app/mcp) and in the [Meta Areas guide](https://lorehub.app/meta-areas-guide).
+
+## Install
+
+You need a LoreHub account with at least Viewer access to the world, and [uv](https://docs.astral.sh/uv/getting-started/installation/). Nothing else to install: `uvx` downloads and runs the server.
+
+```bash
+uvx lorehub-mcp
+```
+
+Or with pip: `pip install lorehub-mcp`, then run `lorehub-mcp`.
+
+### Claude Code
+
+```bash
+claude mcp add lorehub --env LOREHUB_LOGIN=you@example.com --env LOREHUB_PASSWORD=your-password -- uvx lorehub-mcp
+```
+
+### Claude Desktop
+
+Settings → Developer → Edit Config, then add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "lorehub": {
+      "command": "uvx",
+      "args": ["lorehub-mcp"],
+      "env": {
+        "LOREHUB_LOGIN": "you@example.com",
+        "LOREHUB_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add the same block to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):
+
+```json
+{
+  "mcpServers": {
+    "lorehub": {
+      "command": "uvx",
+      "args": ["lorehub-mcp"],
+      "env": {
+        "LOREHUB_LOGIN": "you@example.com",
+        "LOREHUB_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+Other MCP clients work the same way: run `uvx lorehub-mcp` over stdio with the two environment variables.
+
+## Find your world and dialogue ids
+
+You don't need to look them up yourself. Ask the agent, for example *"List my LoreHub worlds, then find the dialogue Tom at Grandpa's and give me its Meta Areas"*, and it calls `list_worlds`, `list_dialogues` and `get_dialogue_meta` in turn.
+
+To copy them by hand: open the dialogue in the Dialogue Builder. The address looks like `app.lorehub.app/<owner>/<world>/game/<story id>?dialogue=<dialogue id>`, so the dialogue id is after `?dialogue=`. The world id comes from `list_worlds`.
+
+## Tools
+
+| Tool | What it returns |
+| --- | --- |
+| `list_worlds()` | The worlds your account can open, with their ids and your role. |
+| `list_dialogues(world_id, game_id?, name?)` | Stories and their dialogues with ids. `name` filters by dialogue name. |
+| `get_dialogue_meta(world_id, dialogue_id, area?, include_nodes=true)` | Each Meta Area's title, note, priority and meta rules as `field name: value`, the nodes inside it, and the nodes where areas overlap (higher priority first). `area` filters by title text or area id. |
+
+Example output of `get_dialogue_meta`:
+
+```json
+{
+  "dialogue": "Tom at Grandpa's",
+  "dialogue_id": "…",
+  "areas": [
+    {"title": "Grandpa's house: wide", "priority": 1,
+     "rules": {"shot": "wide", "background": "grandpas_house"},
+     "nodes": ["dlg.n_01", "dlg.n_04"], "id": "…"},
+    {"title": "Close-up: Tom is crying", "note": "Tears, low light", "priority": 2,
+     "rules": {"shot": "close_up", "background": "grandpas_house", "tom_emotion": "crying"},
+     "nodes": ["dlg.n_04"], "id": "…"}
+  ],
+  "overlaps": [{"node": "dlg.n_04", "areas": ["Close-up: Tom is crying (P2)", "Grandpa's house: wide (P1)"]}]
+}
+```
+
+## Configuration
+
+| Variable | Default | |
+| --- | --- | --- |
+| `LOREHUB_LOGIN`, `LOREHUB_PASSWORD` | | Your LoreHub user name or email and password. The server signs in, and signs in again when the token expires. |
+| `LOREHUB_TOKEN` | | A LoreHub JWT instead of a login and password. It lasts 8 hours. |
+| `LOREHUB_API_URL` | `https://api.lorehub.app` | |
+| `LOREHUB_TIMEOUT` | `30` | Seconds per request. |
+| `LOREHUB_LOG_LEVEL` | `INFO` | Logs go to stderr. |
+| `LOREHUB_NODE_WIDTH`, `LOREHUB_NODE_HEADER_HEIGHT` | `200`, `32` | The canvas node card size. Leave them as they are. |
+
+## How it works
+
+The server makes read-only GET calls to the LoreHub API with your account's token: the dialogue's Meta Areas, its name and story, the story's meta schema (to turn rule ids into field names) and the node positions. A node is inside an area when the middle of its header is, the same rule the Dialogue Builder uses.
+
+Not yet: nodes come back as full ids, without their line text or speaker.
+
+## License
+
+MIT

lorehub_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "lorehub-mcp"
+version = "0.1.0"
+description = "MCP server that lets AI agents read the Meta Areas of a LoreHub dialogue"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Lostwood Games" }]
+requires-python = ">=3.10"
+keywords = ["mcp", "model-context-protocol", "lorehub", "dialogue", "game-development", "narrative", "ai-agents"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Games/Entertainment",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "mcp>=2.3,<3",
+    "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://lorehub.app"
+Documentation = "https://lorehub.app/mcp"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[project.scripts]
+lorehub-mcp = "lorehub_mcp.server:main"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lorehub_mcp"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

lorehub_mcp-0.1.0/server.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.lostwood-games/lorehub-mcp",
+  "title": "LoreHub Meta Areas",
+  "description": "Read the Meta Areas a director marks on a LoreHub dialogue: notes, priorities, rules and the nodes inside.",
+  "websiteUrl": "https://lorehub.app/mcp",
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "lorehub-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "LOREHUB_LOGIN",
+          "description": "LoreHub user name or email. The server signs in with it and signs in again when the token expires.",
+          "isSecret": true
+        },
+        {
+          "name": "LOREHUB_PASSWORD",
+          "description": "LoreHub password for LOREHUB_LOGIN.",
+          "isSecret": true
+        },
+        {
+          "name": "LOREHUB_TOKEN",
+          "description": "A LoreHub JWT, instead of a login and password. It lasts 8 hours.",
+          "isSecret": true
+        },
+        {
+          "name": "LOREHUB_API_URL",
+          "description": "LoreHub API address.",
+          "default": "https://api.lorehub.app"
+        }
+      ]
+    }
+  ]
+}

lorehub_mcp-0.1.0/src/lorehub_mcp/__init__.py

@@ -0,0 +1 @@
+"""LoreHub Meta Areas MCP server."""

lorehub_mcp-0.1.0/src/lorehub_mcp/client.py

@@ -0,0 +1,120 @@
+"""A small async client for the parts of the LoreHub REST API this server reads."""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+log = logging.getLogger("lorehub_mcp")
+
+DEFAULT_API_URL = "https://api.lorehub.app"
+
+
+class LoreHubError(Exception):
+    """A LoreHub call failed in a way the caller should see (bad id, no access, API down)."""
+
+
+@dataclass(frozen=True)
+class Settings:
+    api_url: str
+    token: str | None
+    login: str | None
+    password: str | None
+    node_width: int
+    node_header_height: int
+    timeout: float
+
+    @classmethod
+    def from_env(cls) -> "Settings":
+        return cls(
+            api_url=os.environ.get("LOREHUB_API_URL", DEFAULT_API_URL).rstrip("/"),
+            token=os.environ.get("LOREHUB_TOKEN") or None,
+            login=os.environ.get("LOREHUB_LOGIN") or None,
+            password=os.environ.get("LOREHUB_PASSWORD") or None,
+            # The Dialogue Builder's node card: a node is inside an area when the middle of its header is.
+            node_width=int(os.environ.get("LOREHUB_NODE_WIDTH", "200")),
+            node_header_height=int(os.environ.get("LOREHUB_NODE_HEADER_HEIGHT", "32")),
+            timeout=float(os.environ.get("LOREHUB_TIMEOUT", "30")),
+        )
+
+
+class LoreHubClient:
+    """Authenticates with a LoreHub JWT. Tokens last 8 hours, so with a login and password set the client signs in
+    again once when a call comes back 401."""
+
+    def __init__(self, settings: Settings, transport: httpx.AsyncBaseTransport | None = None):
+        if not settings.token and not (settings.login and settings.password):
+            raise LoreHubError("Set LOREHUB_TOKEN, or LOREHUB_LOGIN and LOREHUB_PASSWORD.")
+        self.settings = settings
+        self._token = settings.token
+        self._http = httpx.AsyncClient(base_url=settings.api_url, timeout=settings.timeout, transport=transport)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    # --- endpoints -------------------------------------------------------------------------------------------
+
+    async def get_worlds(self) -> list[dict[str, Any]]:
+        return await self._get("/api/Setting")
+
+    async def get_meta_areas(self, world_id: str, dialogue_id: str) -> dict[str, Any]:
+        return await self._get(f"/api/v3/worlds/{world_id}/dialogues/{dialogue_id}/metaareas")
+
+    async def get_dialogue(self, world_id: str, dialogue_id: str) -> dict[str, Any]:
+        return await self._get(f"/api/v2/Dialogue/{world_id}/{dialogue_id}")
+
+    async def get_dialogues_for_game(self, world_id: str, game_id: str) -> list[dict[str, Any]]:
+        return await self._get(f"/api/v2/Dialogue/GetForGame/{world_id}/{game_id}")
+
+    async def get_games(self, world_id: str) -> list[dict[str, Any]]:
+        return await self._get(f"/api/v3/worlds/{world_id}/games")
+
+    async def get_nodes(self, world_id: str, dialogue_id: str) -> list[dict[str, Any]]:
+        return await self._get(f"/api/DialogNode/{world_id}/{dialogue_id}")
+
+    async def get_meta_schemas(self, world_id: str, game_id: str) -> list[dict[str, Any]]:
+        return await self._get(f"/api/MetaSchemaGame/{world_id}/{game_id}")
+
+    # --- plumbing --------------------------------------------------------------------------------------------
+
+    async def _sign_in(self) -> None:
+        if not (self.settings.login and self.settings.password):
+            raise LoreHubError("LoreHub rejected LOREHUB_TOKEN (it lasts 8 hours). Set a fresh token, or LOREHUB_LOGIN and LOREHUB_PASSWORD.")
+        log.info("Signing in to LoreHub as %s", self.settings.login)
+        r = await self._http.post("/api/Account/Login", json={"UserNameOrMail": self.settings.login, "Password": self.settings.password})
+        if r.status_code != 200:
+            raise LoreHubError(f"LoreHub sign-in failed ({r.status_code}). Check LOREHUB_LOGIN and LOREHUB_PASSWORD.")
+        self._token = r.json().get("token")
+        if not self._token:
+            raise LoreHubError("LoreHub sign-in returned no token.")
+
+    async def _get(self, path: str) -> Any:
+        if not self._token:
+            await self._sign_in()
+        r = await self._send(path)
+        if r.status_code == 401 and self.settings.login and self.settings.password:
+            await self._sign_in()
+            r = await self._send(path)
+        if r.status_code == 401:
+            raise LoreHubError("LoreHub rejected the token (it lasts 8 hours). Set a fresh LOREHUB_TOKEN, or LOREHUB_LOGIN and LOREHUB_PASSWORD.")
+        if r.status_code == 403:
+            raise LoreHubError("No access to this world. The LoreHub account needs at least Viewer access.")
+        if r.status_code == 404:
+            raise LoreHubError(f"Not found in LoreHub: {path}. Check the world and dialogue ids.")
+        if r.status_code >= 400:
+            raise LoreHubError(f"LoreHub returned {r.status_code} for {path}: {r.text[:300]}")
+        return r.json()
+
+    async def _send(self, path: str) -> httpx.Response:
+        log.debug("GET %s", path)
+        try:
+            return await self._http.get(path, headers={"Authorization": f"Bearer {self._token}"})
+        except httpx.TimeoutException as ex:
+            # The test API scales to zero, so the first call after a quiet period can be slow.
+            raise LoreHubError(f"LoreHub did not answer within {self.settings.timeout:g}s ({path}). Try again.") from ex
+        except httpx.HTTPError as ex:
+            raise LoreHubError(f"Could not reach LoreHub at {self.settings.api_url}: {ex}") from ex

lorehub_mcp-0.1.0/src/lorehub_mcp/meta.py

@@ -0,0 +1,62 @@
+"""Turns LoreHub's Meta Area data into the compact shape the tools return. Pure functions, so they are easy to test."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def node_inside(area: dict[str, Any], node: dict[str, Any], node_width: int, header_height: int) -> bool:
+    """LoreHub's rule (NodeRect.ContainsHeaderMiddle): a node is inside when the middle of its header is inside the
+    area's rectangle, left and top edges included."""
+    mx = node["posX"] + node_width // 2
+    my = node["posY"] + header_height // 2
+    return area["x"] <= mx < area["x"] + area["width"] and area["y"] <= my < area["y"] + area["height"]
+
+
+def matches(area: dict[str, Any], query: str) -> bool:
+    q = query.strip().lower()
+    return q == str(area["id"]).lower() or q in (area.get("title") or "").lower()
+
+
+def shape_areas(
+    areas: list[dict[str, Any]],
+    schemas: list[dict[str, Any]],
+    nodes: list[dict[str, Any]] | None,
+    node_width: int,
+    header_height: int,
+) -> list[dict[str, Any]]:
+    """One entry per area, in canvas reading order (top to bottom, then left to right). Rules are keyed by the meta
+    schema field's name. Empty and default values are left out to keep the output small."""
+    names = {str(s["id"]).lower(): s.get("name") or str(s["id"]) for s in schemas}
+    out: list[dict[str, Any]] = []
+    for a in sorted(areas, key=lambda a: (a["y"], a["x"])):
+        item: dict[str, Any] = {"title": a.get("title") or "(untitled)"}
+        if a.get("note"):
+            item["note"] = a["note"]
+        item["priority"] = a.get("priority", 1)
+        rules = {names.get(str(r["definitionId"]).lower(), f"unknown field {r['definitionId']}"): r["value"] for r in a.get("rules") or []}
+        if rules:
+            item["rules"] = rules
+            if not a.get("rulesEnabled", True):
+                item["rules_enabled"] = False
+        if nodes is not None:
+            inside = [n for n in nodes if node_inside(a, n, node_width, header_height)]
+            inside.sort(key=lambda n: (n["posY"], n["posX"]))
+            item["nodes"] = [n.get("fullId") or n.get("osfId") or str(n["id"]) for n in inside]
+        item["id"] = a["id"]
+        out.append(item)
+    return out
+
+
+def overlaps(shaped: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Nodes inside more than one area, with the areas in priority order, so an agent knows which context wins."""
+    by_node: dict[str, list[dict[str, Any]]] = {}
+    for a in shaped:
+        for n in a.get("nodes", []):
+            by_node.setdefault(n, []).append(a)
+    result = []
+    for node, areas in by_node.items():
+        if len(areas) > 1:
+            ordered = sorted(areas, key=lambda a: -a["priority"])
+            result.append({"node": node, "areas": [f"{a['title']} (P{a['priority']})" for a in ordered]})
+    return result

lorehub_mcp-0.1.0/src/lorehub_mcp/server.py

@@ -0,0 +1,128 @@
+"""LoreHub Meta Areas MCP server: hands an agent the Meta Areas a director marked on a dialogue's canvas."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import sys
+from typing import Annotated, Any
+
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+from mcp_types import ToolAnnotations
+from pydantic import Field
+
+from .client import LoreHubClient, LoreHubError, Settings
+from .meta import matches, overlaps, shape_areas
+
+# stdio carries the protocol on stdout, so every log line goes to stderr.
+logging.basicConfig(stream=sys.stderr, level=os.environ.get("LOREHUB_LOG_LEVEL", "INFO"), format="%(asctime)s %(levelname)s %(name)s: %(message)s")
+log = logging.getLogger("lorehub_mcp")
+
+mcp = MCPServer(
+    name="lorehub-meta",
+    instructions=(
+        "Reads the Meta Areas a director drew on a LoreHub dialogue: each area's title, note, priority, meta rules "
+        "(field = value) and the nodes inside it. Use get_dialogue_meta when you have a world id and dialogue id. "
+        "If you only know the world, story or dialogue name, call list_worlds and list_dialogues first. Read-only."
+    ),
+)
+
+READ_ONLY = ToolAnnotations(readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=True)
+
+WorldId = Annotated[str, Field(description="LoreHub world (setting) id, a GUID.")]
+
+_client: LoreHubClient | None = None
+
+
+def client() -> LoreHubClient:
+    global _client
+    if _client is None:
+        try:
+            _client = LoreHubClient(Settings.from_env())
+        except LoreHubError as ex:
+            raise ToolError(str(ex)) from ex
+    return _client
+
+
+@mcp.tool(annotations=READ_ONLY)
+async def get_dialogue_meta(
+    world_id: WorldId,
+    dialogue_id: Annotated[str, Field(description="Dialogue id, a GUID.")],
+    area: Annotated[str | None, Field(description="Only areas whose title contains this text (case-insensitive), or an area id. Omit for all areas.")] = None,
+    include_nodes: Annotated[bool, Field(description="List the nodes inside each area (by full id) and the nodes where areas overlap.")] = True,
+) -> dict[str, Any]:
+    """Get the Meta Areas of one dialogue: what the director marked on the canvas, ready to hand to a reference-
+    generating agent. Each area has its title, note, priority (higher wins where areas overlap), its meta rules as
+    field name -> value, and the nodes inside it. Areas are in canvas reading order."""
+    c = client()
+    try:
+        dialogue, data = await asyncio.gather(c.get_dialogue(world_id, dialogue_id), c.get_meta_areas(world_id, dialogue_id))
+        areas = [a for a in data.get("areas", []) if area is None or matches(a, area)]
+        game_id = dialogue.get("gameId")
+        needs_schema = any(a.get("rules") for a in areas)
+        schemas, nodes = await asyncio.gather(
+            c.get_meta_schemas(world_id, game_id) if needs_schema and game_id else _none([]),
+            c.get_nodes(world_id, dialogue_id) if include_nodes and areas else _none(None),
+        )
+    except LoreHubError as ex:
+        raise ToolError(str(ex)) from ex
+
+    shaped = shape_areas(areas, schemas, nodes, c.settings.node_width, c.settings.node_header_height)
+    result: dict[str, Any] = {"dialogue": dialogue.get("name") or dialogue_id, "dialogue_id": dialogue_id, "areas": shaped}
+    if include_nodes and (o := overlaps(shaped)):
+        result["overlaps"] = o
+    if not shaped:
+        result["message"] = f"No Meta Areas match '{area}'." if area and data.get("areas") else "This dialogue has no Meta Areas."
+    log.info("get_dialogue_meta %s: %d of %d areas", dialogue_id, len(shaped), len(data.get("areas", [])))
+    return result
+
+
+@mcp.tool(annotations=READ_ONLY)
+async def list_worlds() -> dict[str, Any]:
+    """List the LoreHub worlds this account can open, with their ids, to pass to list_dialogues and get_dialogue_meta."""
+    try:
+        worlds = await client().get_worlds()
+    except LoreHubError as ex:
+        raise ToolError(str(ex)) from ex
+    return {"worlds": [
+        {"id": w["id"], "name": w.get("name") or "", "url": f"{w.get('ownerUserName')}/{w.get('urlName')}", "role": w.get("currentUserRole")}
+        for w in worlds
+    ]}
+
+
+@mcp.tool(annotations=READ_ONLY)
+async def list_dialogues(
+    world_id: WorldId,
+    game_id: Annotated[str | None, Field(description="Story (game) id. Omit to list the dialogues of every story in the world.")] = None,
+    name: Annotated[str | None, Field(description="Only dialogues whose name contains this text (case-insensitive).")] = None,
+) -> dict[str, Any]:
+    """Find a dialogue's id by story and name, to pass to get_dialogue_meta."""
+    c = client()
+    try:
+        games = [{"id": game_id, "name": None}] if game_id else await c.get_games(world_id)
+        lists = await asyncio.gather(*(c.get_dialogues_for_game(world_id, g["id"]) for g in games))
+    except LoreHubError as ex:
+        raise ToolError(str(ex)) from ex
+
+    q = (name or "").lower()
+    stories = []
+    for g, dialogues in zip(games, lists):
+        found = [{"id": d["id"], "name": d.get("name") or ""} for d in dialogues if q in (d.get("name") or "").lower()]
+        if found:
+            stories.append({"story": g.get("name") or g["id"], "story_id": g["id"], "dialogues": found})
+    return {"stories": stories} if stories else {"stories": [], "message": "No dialogues found."}
+
+
+async def _none(value: Any) -> Any:
+    return value
+
+
+def main() -> None:
+    log.info("Starting lorehub-meta MCP server (stdio)")
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

lorehub_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,130 @@
+"""Runs the tools against a fake LoreHub API built from the Meta Areas spec's example."""
+
+import httpx
+import pytest
+from mcp.server.mcpserver.exceptions import ToolError
+
+from lorehub_mcp import server
+from lorehub_mcp.client import LoreHubClient, Settings
+from lorehub_mcp.meta import node_inside
+
+W, D, G = "w1", "d1", "g1"
+SHOT, BG, EMO = "11111111-0000-0000-0000-000000000001", "11111111-0000-0000-0000-000000000002", "11111111-0000-0000-0000-000000000003"
+
+AREAS = {
+    "dialogueId": D,
+    "version": 7,
+    "areas": [
+        {"id": "a-close", "title": "Close-up: Tom is crying", "note": "Tears, low light", "color": "#f00", "x": 300, "y": 0, "width": 400,
+         "height": 300, "priority": 2, "keepValuesOnLeave": False, "rulesEnabled": True,
+         "rules": [{"definitionId": SHOT, "value": "close_up"}, {"definitionId": BG, "value": "grandpas_house"}, {"definitionId": EMO, "value": "crying"}]},
+        {"id": "a-wide", "title": "Grandpa's house: wide", "note": "", "color": "#0f0", "x": 0, "y": 0, "width": 600, "height": 300,
+         "priority": 1, "keepValuesOnLeave": False, "rulesEnabled": True,
+         "rules": [{"definitionId": SHOT, "value": "wide"}, {"definitionId": BG, "value": "grandpas_house"}]},
+        {"id": "a-note", "title": "Rewrite later", "note": "Too long", "color": "#00f", "x": 0, "y": 1000, "width": 100, "height": 100,
+         "priority": 1, "keepValuesOnLeave": False, "rulesEnabled": False, "rules": []},
+    ],
+}
+NODES = [
+    {"id": "n1", "fullId": "dlg.n_01", "posX": 10, "posY": 10},  # header middle (110, 26): wide only
+    {"id": "n4", "fullId": "dlg.n_04", "posX": 320, "posY": 50},  # (420, 66): both
+    {"id": "n9", "fullId": "dlg.n_09", "posX": 2000, "posY": 2000},  # outside
+]
+SCHEMAS = [{"id": SHOT, "name": "shot", "type": "Text"}, {"id": BG, "name": "background", "type": "Text"}, {"id": EMO, "name": "tom_emotion", "type": "Text"}]
+
+
+def fake_api(token="good", calls=None):
+    def handler(req: httpx.Request) -> httpx.Response:
+        if calls is not None:
+            calls.append(req.url.path)
+        if req.url.path == "/api/Account/Login":
+            return httpx.Response(200, json={"token": "good"})
+        if req.headers.get("authorization") != f"Bearer {token}":
+            return httpx.Response(401)
+        routes = {
+            f"/api/v2/Dialogue/{W}/{D}": {"id": D, "gameId": G, "name": "Tom at Grandpa's"},
+            f"/api/v3/worlds/{W}/dialogues/{D}/metaareas": AREAS,
+            f"/api/DialogNode/{W}/{D}": NODES,
+            f"/api/MetaSchemaGame/{W}/{G}": SCHEMAS,
+            "/api/Setting": [{"id": W, "name": "Tom's World", "urlName": "toms-world", "ownerUserName": "andrei", "currentUserRole": "Owner"}],
+            f"/api/v3/worlds/{W}/games": [{"id": G, "name": "Episode 1"}],
+            f"/api/v2/Dialogue/GetForGame/{W}/{G}": [{"id": D, "name": "Tom at Grandpa's"}, {"id": "d2", "name": "Intro"}],
+        }
+        return httpx.Response(200, json=routes[req.url.path]) if req.url.path in routes else httpx.Response(404)
+
+    return httpx.MockTransport(handler)
+
+
+def use(settings_kw=None, **api_kw):
+    kw = dict(api_url="https://api.test", token="good", login=None, password=None, node_width=200, node_header_height=32, timeout=5)
+    kw.update(settings_kw or {})
+    server._client = LoreHubClient(Settings(**kw), transport=fake_api(**api_kw))
+
+
+async def test_returns_areas_with_named_rules_nodes_and_overlaps():
+    use()
+    r = await server.get_dialogue_meta(W, D)
+    assert r["dialogue"] == "Tom at Grandpa's"
+    wide, close, note = r["areas"]  # reading order: y, then x
+    assert wide["title"] == "Grandpa's house: wide" and wide["nodes"] == ["dlg.n_01", "dlg.n_04"]
+    assert close["rules"] == {"shot": "close_up", "background": "grandpas_house", "tom_emotion": "crying"}
+    assert close["note"] == "Tears, low light" and close["priority"] == 2 and close["nodes"] == ["dlg.n_04"]
+    assert "rules" not in note and note["nodes"] == []
+    assert "note" not in wide
+    assert r["overlaps"] == [{"node": "dlg.n_04", "areas": ["Close-up: Tom is crying (P2)", "Grandpa's house: wide (P1)"]}]
+
+
+async def test_area_filter_and_no_nodes():
+    calls = []
+    use(calls=calls)
+    r = await server.get_dialogue_meta(W, D, area="close-UP", include_nodes=False)
+    assert [a["title"] for a in r["areas"]] == ["Close-up: Tom is crying"]
+    assert "nodes" not in r["areas"][0] and "overlaps" not in r
+    assert f"/api/DialogNode/{W}/{D}" not in calls
+    r = await server.get_dialogue_meta(W, D, area="nothing")
+    assert r["areas"] == [] and "No Meta Areas match" in r["message"]
+
+
+async def test_signs_in_again_when_token_expired():
+    use({"token": "expired", "login": "me@x", "password": "pw"})
+    r = await server.get_dialogue_meta(W, D, include_nodes=False)
+    assert len(r["areas"]) == 3
+
+
+async def test_expired_token_without_login_is_a_clear_tool_error():
+    use({"token": "expired"})
+    with pytest.raises(ToolError, match="8 hours"):
+        await server.get_dialogue_meta(W, D)
+
+
+async def test_unknown_dialogue_is_a_tool_error():
+    use()
+    with pytest.raises(ToolError, match="Not found"):
+        await server.get_dialogue_meta(W, "nope")
+
+
+async def test_list_dialogues_by_name():
+    use()
+    r = await server.list_dialogues(W, name="grandpa")
+    assert r == {"stories": [{"story": "Episode 1", "story_id": G, "dialogues": [{"id": D, "name": "Tom at Grandpa's"}]}]}
+
+
+async def test_list_worlds():
+    use()
+    r = await server.list_worlds()
+    assert r == {"worlds": [{"id": W, "name": "Tom's World", "url": "andrei/toms-world", "role": "Owner"}]}
+
+
+def test_inside_uses_header_middle_with_left_top_edges_included():
+    area = {"x": 100, "y": 16, "width": 10, "height": 10}
+    assert node_inside(area, {"posX": 0, "posY": 0}, 200, 32)  # middle (100, 16) on the corner
+    assert not node_inside({**area, "x": 101}, {"posX": 0, "posY": 0}, 200, 32)
+    assert not node_inside({"x": 0, "y": 0, "width": 100, "height": 16}, {"posX": 0, "posY": 0}, 200, 32)  # right/bottom excluded
+
+
+async def test_tools_are_listed_with_schemas():
+    tools = {t.name: t for t in await server.mcp.list_tools()}
+    assert set(tools) == {"get_dialogue_meta", "list_dialogues", "list_worlds"}
+    props = tools["get_dialogue_meta"].input_schema["properties"]
+    assert set(props) == {"world_id", "dialogue_id", "area", "include_nodes"}
+    assert tools["get_dialogue_meta"].annotations.read_only_hint