behaviortrees 0.0.0-stage → 0.1.0

package/LICENSE-MIT

@@ -0,0 +1,28 @@
+This editor is licensed under the AGPL-3.0 (see LICENSE), but portions of it
+are derived from behavior3editor (https://github.com/behavior3/behavior3editor),
+which is licensed under the MIT License reproduced below. Notably:
+
+- src/lib/behavior/organize.ts (port of the original OrganizeManager)
+- src/lib/behavior/b3.ts (derived from the original ExportManager/ImportManager)
+
+The MIT License (MIT)
+
+Copyright (c) 2014 Renato de Pontes Pereira
+
+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,82 @@
-# Temporary Holding Version
+# behaviortrees
 
-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.
+Validate, convert and share behavior trees from the command line or any MCP client. It uses the same code as the free visual editor at [behaviortrees.com](https://www.behaviortrees.com), so what it accepts, the editor opens.
+
+- **Validate** behavior3 JSON and BehaviorTree.CPP XML: dangling children, nodes with two parents, cycles, decorators with more than one child, leaves with children, unknown node names.
+- **Convert** between behavior3 JSON and BehaviorTree.CPP XML (v4 for ROS 2 Jazzy and Groot2, v3 for ROS 2 Humble).
+- **Link**: turn a tree into a URL that opens it in the editor, laid out and editable. The tree travels inside the link, so nothing is uploaded.
+
+## CLI
+
+```sh
+npx behaviortrees validate tree.json
+npx behaviortrees convert tree.json --to btcpp-v4 -o tree.xml
+npx behaviortrees convert nav2_tree.xml --to behavior3
+npx behaviortrees link tree.json --open
+npx behaviortrees nodes            # built-in node types
+npx behaviortrees examples         # example trees; add an id to print one
+npx behaviortrees guides           # behaviortrees.com guides; add a slug to read one
+```
+
+Leave out the file, or pass `-`, to read from stdin. `--json` gives machine-readable output, and `validate` exits with status 1 when a tree has errors, so it works in CI.
+
+## MCP server
+
+Lets an AI assistant write a behavior tree, check it, and hand you a link that opens it in the editor. Tools: `validate_tree`, `create_editor_link`, `convert_tree`, `list_node_types`, `get_example`, `read_guide`.
+
+Remote, nothing to install (Streamable HTTP):
+
+```
+https://www.behaviortrees.com/mcp
+```
+
+Or run it locally over stdio:
+
+```json
+{
+  "mcpServers": {
+    "behaviortrees": { "command": "npx", "args": ["-y", "behaviortrees", "mcp"] }
+  }
+}
+```
+
+For Claude Code: `claude mcp add --transport http behaviortrees https://www.behaviortrees.com/mcp`
+
+## Tree format
+
+A minimal behavior3 tree. Positions are optional; the editor lays the tree out.
+
+```json
+{
+  "title": "Guard",
+  "root": "a",
+  "nodes": {
+    "a": { "name": "Priority", "children": ["b", "c"] },
+    "b": { "name": "Sequence", "children": ["d", "e"] },
+    "c": { "name": "Patrol" },
+    "d": { "name": "IsEnemyVisible" },
+    "e": { "name": "Attack" }
+  },
+  "custom_nodes": [
+    { "name": "IsEnemyVisible", "category": "condition" },
+    { "name": "Attack", "category": "action" },
+    { "name": "Patrol", "category": "action" }
+  ]
+}
+```
+
+Composites list `children` in run order, decorators have one `child`, and anything else is a leaf. `Priority` is behavior3's selector (fallback). Declare any node that isn't built in under `custom_nodes`.
+
+## Library
+
+```js
+import { validateTree, convertTree, createEditorLink } from 'behaviortrees';
+
+const { valid, findings } = await validateTree(json);
+const { output } = await convertTree(json, 'btcpp-v4');
+const { url } = await createEditorLink(json);
+```
+
+## License
+
+AGPL-3.0-only (see LICENSE). Portions are derived from the MIT-licensed [behavior3editor](https://github.com/behavior3/behavior3editor) by Renato de Pontes Pereira (see LICENSE-MIT). Source: [github.com/behaviortrees/behaviortrees](https://github.com/behaviortrees/behaviortrees/tree/main/packages/cli).

package/dist/chunks/chunk-7LANS4ZA.js

@@ -0,0 +1,130 @@
+import {
+  VERSION
+} from "./chunk-QW4NPMSB.js";
+import {
+  CONVERT_TARGETS,
+  SITE,
+  convertTree,
+  createEditorLink,
+  getExample,
+  listExamples,
+  listGuides,
+  listNodeTypes,
+  readGuide,
+  validateTree
+} from "./chunk-VTXL3OVS.js";
+
+// src/mcp.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+var INSTRUCTIONS = `Tools for behavior trees (game AI and robotics) from ${SITE}, a free online visual behavior tree editor.
+
+Typical flow when a user wants a behavior tree: write it as behavior3 JSON, check it with validate_tree, fix any errors, then call create_editor_link and give the user the link. It opens the tree in the editor in their browser, laid out and editable, with no account needed. convert_tree turns behavior3 JSON into BehaviorTree.CPP XML (Groot2, ROS 2 Nav2) and back. list_node_types shows the built-in nodes; get_example returns complete example trees to copy from; read_guide explains concepts.`;
+var TREE_FORMAT = `behavior3 JSON: {"title": "...", "root": "<id of the first node under the root>", "nodes": {"<id>": {"name": "<node type>", "title": "<optional label>", "children": ["<id>", ...] (composites, in run order) or "child": "<id>" (decorators), "properties": {...}}}, "custom_nodes": [{"name": "IsEnemyVisible", "category": "condition"}]}. Positions ("display") are optional. Any node name that isn't built in (see list_node_types) must be declared in custom_nodes with a category of action, condition, composite or decorator. A whole project ({"trees": [...], "custom_nodes": [...]}) or BehaviorTree.CPP XML also works.`;
+var treeInput = z.union([z.string(), z.record(z.unknown())]).describe(`The tree: ${TREE_FORMAT}`);
+var text = (value) => ({
+  content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }]
+});
+var failure = (error) => ({
+  content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
+  isError: true
+});
+function createMcpServer() {
+  const server = new McpServer({ name: "behaviortrees", title: "Behavior Trees", version: VERSION }, { instructions: INSTRUCTIONS });
+  const readOnly = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+  server.registerTool(
+    "validate_tree",
+    {
+      title: "Validate a behavior tree",
+      description: `Check a behavior tree for errors before using it: missing or dangling children, nodes with two parents, cycles, decorators with more than one child, leaves with children, unknown node names, and BehaviorTree.CPP import problems. Returns valid (true when there are no errors), the trees found, and findings at error, warning or info level.`,
+      inputSchema: { tree: treeInput },
+      annotations: readOnly
+    },
+    async ({ tree }) => text(await validateTree(tree))
+  );
+  server.registerTool(
+    "create_editor_link",
+    {
+      title: "Open a tree in the editor",
+      description: `Make a link that opens the tree in the behaviortrees.com editor in the user's browser, auto-laid-out and editable, with no account needed. The tree travels inside the link (the URL fragment), so nothing is uploaded or stored. The tree must validate without errors. Give the user the returned url.`,
+      inputSchema: { tree: treeInput },
+      annotations: readOnly
+    },
+    async ({ tree }) => {
+      try {
+        return text(await createEditorLink(tree));
+      } catch (error) {
+        return failure(error);
+      }
+    }
+  );
+  server.registerTool(
+    "convert_tree",
+    {
+      title: "Convert a behavior tree",
+      description: "Convert between behavior3 JSON and BehaviorTree.CPP XML (v4 for ROS 2 Jazzy and Groot2, v3 for ROS 2 Humble), the same way the editor imports and exports. Returns the converted text and any issues (BT.CPP has no equivalent for some behavior3 nodes and vice versa).",
+      inputSchema: {
+        tree: treeInput,
+        to: z.enum(CONVERT_TARGETS).describe("Target format: behavior3, btcpp-v4 or btcpp-v3")
+      },
+      annotations: readOnly
+    },
+    async ({ tree, to }) => {
+      try {
+        const result = await convertTree(tree, to);
+        const issues = result.issues.length ? `
+
+Issues:
+${result.issues.map((issue) => `- ${issue.level}: ${issue.message}`).join("\n")}` : "";
+        return text(`${result.output}${issues}`);
+      } catch (error) {
+        return failure(error);
+      }
+    }
+  );
+  server.registerTool(
+    "list_node_types",
+    {
+      title: "List built-in node types",
+      description: "The built-in behavior3 nodes a tree can use without declaring them: composites (Sequence, Priority = selector/fallback, MemSequence, MemPriority), decorators (Inverter, Repeater, MaxTime, ...) and leaves (Wait, Succeeder, Failer, ...), with descriptions and default properties.",
+      inputSchema: {},
+      annotations: readOnly
+    },
+    async () => text(listNodeTypes())
+  );
+  server.registerTool(
+    "get_example",
+    {
+      title: "Get an example tree",
+      description: "Complete, working example trees (enemy patrol, cooldown-gated attacks, robot navigation with recovery, and more) to learn the format from or start with. Without an id, lists the examples; with an id, returns that tree as behavior3 JSON.",
+      inputSchema: { id: z.string().optional().describe("Example id from the list; omit to list them") },
+      annotations: readOnly
+    },
+    async ({ id }) => {
+      if (!id) return text(listExamples());
+      const example = getExample(id);
+      return example ? text(example) : failure(`No example "${id}". Examples: ${listExamples().map((e) => e.id).join(", ")}`);
+    }
+  );
+  server.registerTool(
+    "read_guide",
+    {
+      title: "Read a behavior tree guide",
+      description: "Practical guides from behaviortrees.com/learn as Markdown: what behavior trees are, node types, blackboards, debugging, structuring large trees, and behavior trees in Unity, Unreal, Godot, Python and robotics (BehaviorTree.CPP, ROS 2, Nav2). Without a slug, lists the guides.",
+      inputSchema: { slug: z.string().optional().describe("Guide slug from the list; omit to list them") },
+      annotations: { ...readOnly, openWorldHint: true }
+    },
+    async ({ slug }) => {
+      try {
+        return text(slug ? await readGuide(slug) : await listGuides());
+      } catch (error) {
+        return failure(error);
+      }
+    }
+  );
+  return server;
+}
+
+export {
+  createMcpServer
+};

package/dist/chunks/chunk-QW4NPMSB.js

@@ -0,0 +1,6 @@
+// src/version.ts
+var VERSION = true ? "0.1.0" : "0.0.0-dev";
+
+export {
+  VERSION
+};