@openbone/mcp 0.0.0-stage → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +143 -2
- package/dist/atlas-schema.d.ts +149 -0
- package/dist/atlas-schema.js +42 -0
- package/dist/audio-meta.d.ts +6 -0
- package/dist/audio-meta.js +139 -0
- package/dist/bin.d.ts +2 -0
- package/dist/bin.js +80 -0
- package/dist/bridge.d.ts +16 -0
- package/dist/bridge.js +151 -0
- package/dist/export.d.ts +97 -0
- package/dist/export.js +310 -0
- package/dist/guide.d.ts +1 -0
- package/dist/guide.js +83 -0
- package/dist/image-load.d.ts +9 -0
- package/dist/image-load.js +40 -0
- package/dist/image-ops.d.ts +77 -0
- package/dist/image-ops.js +235 -0
- package/dist/index.d.ts +8 -0
- package/dist/index.js +8 -0
- package/dist/local-only.d.ts +7 -0
- package/dist/local-only.js +38 -0
- package/dist/media.d.ts +27 -0
- package/dist/media.js +124 -0
- package/dist/render.d.ts +81 -0
- package/dist/render.js +224 -0
- package/dist/server.d.ts +28 -0
- package/dist/server.js +354 -0
- package/dist/session.d.ts +16 -0
- package/dist/session.js +43 -0
- package/dist/tools-extra.d.ts +4 -0
- package/dist/tools-extra.js +355 -0
- package/dist/tools-image.d.ts +3 -0
- package/dist/tools-image.js +176 -0
- package/package.json +67 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 UX Century and OpenBone contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,144 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @openbone/mcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
An MCP server that lets AI agents build, rig, animate and wire up interactive OpenBone animations, and check their work.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@openbone/mcp)
|
|
6
|
+
[](https://github.com/UXCentury/open-bone/blob/main/LICENSE)
|
|
7
|
+
|
|
8
|
+
[OpenBone](https://github.com/UXCentury/open-bone) is open-source 2D skeletal animation: Spine-style rigging, Rive-style
|
|
9
|
+
interactive state machines and native runtimes for many engines. This package exposes the editor's own editing
|
|
10
|
+
operations as [Model Context Protocol](https://modelcontextprotocol.io) tools. An agent can create a project, add
|
|
11
|
+
bones, art, constraints, animations, state machines and sound, then render frames, simulate input and export the
|
|
12
|
+
result. Every edit op in `@openbone/core` becomes a tool automatically, so the agent can do what the editor can.
|
|
13
|
+
|
|
14
|
+
## Install
|
|
15
|
+
|
|
16
|
+
Needs Node.js 20 or newer. MCP clients usually start the server with `npx`, so there is nothing to install:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npx -y @openbone/mcp
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
To keep a copy around: `npm install -g @openbone/mcp`, which installs the `openbone-mcp` command.
|
|
23
|
+
|
|
24
|
+
## Quick start
|
|
25
|
+
|
|
26
|
+
Claude Code:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
claude mcp add openbone -- npx -y @openbone/mcp
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Claude Desktop, Cursor and other clients that use an `mcpServers` JSON file:
|
|
33
|
+
|
|
34
|
+
```json
|
|
35
|
+
{
|
|
36
|
+
"mcpServers": {
|
|
37
|
+
"openbone": { "command": "npx", "args": ["-y", "@openbone/mcp"] }
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Then ask, for example: *"Create a project at ~/anim/robot.obone: a robot with IK arms, an idle and a wave animation,
|
|
43
|
+
and a state machine that waves when clicked. Check it with render_frame."*
|
|
44
|
+
|
|
45
|
+
To watch the agent work, open the OpenBone editor and click **⚡ Connect MCP** in the toolbar (see
|
|
46
|
+
[Transports](#transports)).
|
|
47
|
+
|
|
48
|
+
## What an agent can do
|
|
49
|
+
|
|
50
|
+
- Create or open `.obone` projects. A project with a file path is saved after every edit.
|
|
51
|
+
- Build a rig: bones, slots, skins, regions, meshes (with automatic weights), shapes, paths, clipping masks, bounding
|
|
52
|
+
boxes, IK, transform, path and physics constraints, sliders.
|
|
53
|
+
- Animate: keys on any property, curves, events, sprite sequences, particles, text, lip sync from a WAV file.
|
|
54
|
+
- Make it interactive: state machines with inputs, layers, blend states, transitions, pointer listeners, bindings and
|
|
55
|
+
JavaScript scripts.
|
|
56
|
+
- Add sound: audio assets, sounds, buses, audio keys, sounds on events and states.
|
|
57
|
+
- Check the work: render a PNG (bones and hit boxes drawn on top), render a GIF, run a state machine headlessly and read
|
|
58
|
+
the log of states, events, inputs and audio commands, read bone world positions, get size and draw-call statistics.
|
|
59
|
+
- Export everything the editor's Export dialog makes (see [Tools](#tools)).
|
|
60
|
+
|
|
61
|
+
## Options
|
|
62
|
+
|
|
63
|
+
| Flag | Default | What it does |
|
|
64
|
+
|---|---|---|
|
|
65
|
+
| `--project <file.obone>` | none | Open this file at startup. If it does not exist, a new empty project is created and saved there. |
|
|
66
|
+
| `--http <port>` | off (stdio) | Serve MCP over Streamable HTTP at `http://127.0.0.1:<port>/mcp` instead of stdio. |
|
|
67
|
+
| `--no-bridge` | bridge on | Do not start the WebSocket bridge for the editor. |
|
|
68
|
+
| `--bridge-port <port>` | `7717` | Port of the WebSocket bridge. The `OPENBONE_BRIDGE_PORT` environment variable does the same. |
|
|
69
|
+
|
|
70
|
+
Pass options after the package name, for example `npx -y @openbone/mcp --project ~/anim/hero.obone --no-bridge`. In a
|
|
71
|
+
JSON config, add them to `args`.
|
|
72
|
+
|
|
73
|
+
If the `--project` file exists but can't be read as an OpenBone document, the server stops with the reason and leaves
|
|
74
|
+
the file unchanged. The `new_project` tool likewise refuses to replace an existing file unless it is called with
|
|
75
|
+
`overwrite: true`.
|
|
76
|
+
|
|
77
|
+
## Transports
|
|
78
|
+
|
|
79
|
+
| Transport | Address | Notes |
|
|
80
|
+
|---|---|---|
|
|
81
|
+
| stdio | standard input and output | The default. Logs go to standard error. |
|
|
82
|
+
| Streamable HTTP | `http://127.0.0.1:<port>/mcp` | With `--http <port>`. Stateless: every request gets a fresh MCP server, and all requests share one open project. Other paths return 404. |
|
|
83
|
+
| WebSocket bridge | `ws://127.0.0.1:7717` | For the editor, not for MCP clients. Starts with either transport unless you pass `--no-bridge`. |
|
|
84
|
+
|
|
85
|
+
The bridge keeps the editor and the server in sync. When the editor connects (**⚡ Connect MCP**), the server sends its
|
|
86
|
+
document. After that, the agent's edits appear in the editor as they happen, and your edits in the editor are applied on
|
|
87
|
+
the server, so the agent sees them. Undo and redo in the editor are forwarded to the server. The server is the source of
|
|
88
|
+
truth: if an op from the editor fails, the editor is reloaded from the server's document.
|
|
89
|
+
|
|
90
|
+
The editor connects to `ws://127.0.0.1:7717`. If that port is taken (for example by a second server), the new server
|
|
91
|
+
logs a bridge error and keeps running without the bridge.
|
|
92
|
+
|
|
93
|
+
## Tools
|
|
94
|
+
|
|
95
|
+
| Group | Tools |
|
|
96
|
+
|---|---|
|
|
97
|
+
| Project | `new_project`, `open_project`, `save_project`, `get_summary`, `get_document`, `validate`, `undo`, `redo`, `get_guide`, `import_image` (PNG, JPEG, WebP), `import_audio` (WAV, MP3, OGG), plus the project ops: `set_document`, `add_image`, `set_atlas`, `import_data`, … |
|
|
98
|
+
| Rig | `add_bone`, `update_bone`, `add_slot`, `add_skin`, `duplicate_skin`, `add_to_skin`, … |
|
|
99
|
+
| Attachments | `add_region`, `add_mesh`, `add_linked_mesh`, `add_shape`, `add_path`, `add_clipping`, `add_bounding_box`, `add_point`, `add_text`, `add_sequence`, `add_particles`, `auto_weights`, `set_weights`, `smooth_weights`, `prune_weights`, … |
|
|
100
|
+
| Constraints | `add_ik_constraint`, `add_transform_constraint`, `add_path_constraint`, `add_physics_constraint`, `set_constraint_order`, `add_slider`, … |
|
|
101
|
+
| Animation | `create_animation`, `set_keys`, `move_key`, `transform_keys`, `paste_keys`, `add_event`, `add_event_key`, … |
|
|
102
|
+
| Interactivity | `create_state_machine`, `add_layer`, `add_input`, `add_state`, `add_transition`, `add_listener`, `add_binding`, `add_script`, `attach_script`, `set_state_emitter`, … |
|
|
103
|
+
| Audio | `add_sound`, `add_bus`, `set_audio_mix`, `add_audio_key`, `set_event_sound`, `set_state_sound`, … |
|
|
104
|
+
| Rigging helpers | `trace_mesh` (replace a region with a mesh traced from its image), `pose_bones` (bend a chain so a bone's tip reaches a point), `lip_sync` (key a mouth slot to a WAV sound) |
|
|
105
|
+
| Atlas and export | `pack_atlas` (pack images into atlas pages), `export_file` (formats `obone`, `json`, `obonb`, `atlas`, `png`, `jpeg`, `apng`, `gif`, `psd`, `avi`, `mov`, `spritesheet`, `web`) |
|
|
106
|
+
| Checking the work | `render_frame` (PNG), `render_gif`, `simulate_state_machine`, `inspect_pose`, `get_stats` |
|
|
107
|
+
|
|
108
|
+
The edit tools are generated from the core ops, so the list grows with the editor. To list every op with its group and
|
|
109
|
+
description, run `npx openbone ops`. Tool names are the op names in snake case (`addBone` becomes `add_bone`).
|
|
110
|
+
|
|
111
|
+
The server also has three resources, `openbone://guide` (the authoring guide), `openbone://document` and
|
|
112
|
+
`openbone://summary`, and two prompts, `rig_character` and `interactive_button`.
|
|
113
|
+
|
|
114
|
+
## Security
|
|
115
|
+
|
|
116
|
+
- The server is meant for your own machine. Both the HTTP transport and the bridge listen on `127.0.0.1` only, so
|
|
117
|
+
other machines can't reach them.
|
|
118
|
+
- Web pages can't use them either: both refuse browser requests unless they come from the OpenBone editor (a page on
|
|
119
|
+
`localhost`, `127.0.0.1` or `[::1]`, or the desktop app) and are addressed to a loopback name, which also blocks DNS
|
|
120
|
+
rebinding. MCP clients and scripts, which send no `Origin` header, are allowed. There is no other authentication, so
|
|
121
|
+
any program running as your user can connect; use `--no-bridge` when you don't need the editor link.
|
|
122
|
+
- Tools can read and write any file your user account can. There is no folder sandbox:
|
|
123
|
+
- `open_project`, `import_image` and `import_audio` read the path they are given (relative paths resolve against the
|
|
124
|
+
server's working directory).
|
|
125
|
+
- `new_project` and `save_project` write the `.obone` file at the path they are given.
|
|
126
|
+
- `render_gif` and `export_file` write their output to `out`, relative to the project's folder (next to the project
|
|
127
|
+
by default).
|
|
128
|
+
- Rendering reads the project's images from disk relative to the project file. Image sources that are `http(s)` URLs
|
|
129
|
+
are loaded from the network.
|
|
130
|
+
- State-machine scripts (in `render_frame`, `render_gif`, `simulate_state_machine` and exports) run in a QuickJS
|
|
131
|
+
sandbox with a memory cap and a time limit per call. They only see the `ob` API, not the file system or the network.
|
|
132
|
+
|
|
133
|
+
## Documentation
|
|
134
|
+
|
|
135
|
+
- [MCP guide](https://github.com/UXCentury/open-bone/blob/main/docs/mcp.md)
|
|
136
|
+
- [OpenBone README](https://github.com/UXCentury/open-bone/blob/main/README.md)
|
|
137
|
+
- [File format](https://github.com/UXCentury/open-bone/blob/main/docs/format.md)
|
|
138
|
+
- [Command line (`@openbone/cli`)](https://github.com/UXCentury/open-bone/blob/main/packages/cli/README.md)
|
|
139
|
+
- [Changelog](https://github.com/UXCentury/open-bone/blob/main/CHANGELOG.md)
|
|
140
|
+
- [Security policy](https://github.com/UXCentury/open-bone/blob/main/SECURITY.md)
|
|
141
|
+
|
|
142
|
+
## License
|
|
143
|
+
|
|
144
|
+
[MIT](https://github.com/UXCentury/open-bone/blob/main/LICENSE) © UX Century and OpenBone contributors
|
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
/**
|
|
3
|
+
* Texture packer settings as MCP input (pack_atlas, export_file `atlas`): the same `AtlasSettings` the CLI and the
|
|
4
|
+
* Export dialog use. Everything is optional; defaults are the packer's.
|
|
5
|
+
*/
|
|
6
|
+
export declare const atlasSettingsShape: {
|
|
7
|
+
padding: z.ZodOptional<z.ZodNumber>;
|
|
8
|
+
maxSize: z.ZodOptional<z.ZodNumber>;
|
|
9
|
+
maxWidth: z.ZodOptional<z.ZodNumber>;
|
|
10
|
+
maxHeight: z.ZodOptional<z.ZodNumber>;
|
|
11
|
+
minWidth: z.ZodOptional<z.ZodNumber>;
|
|
12
|
+
minHeight: z.ZodOptional<z.ZodNumber>;
|
|
13
|
+
powerOfTwo: z.ZodOptional<z.ZodBoolean>;
|
|
14
|
+
square: z.ZodOptional<z.ZodBoolean>;
|
|
15
|
+
multipleOf4: z.ZodOptional<z.ZodBoolean>;
|
|
16
|
+
rotate: z.ZodOptional<z.ZodBoolean>;
|
|
17
|
+
scale: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"auto">]>>;
|
|
18
|
+
scales: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
19
|
+
scale: z.ZodNumber;
|
|
20
|
+
suffix: z.ZodString;
|
|
21
|
+
}, z.core.$strip>>>;
|
|
22
|
+
stripWhitespace: z.ZodOptional<z.ZodBoolean>;
|
|
23
|
+
polygons: z.ZodOptional<z.ZodBoolean>;
|
|
24
|
+
premultipliedAlpha: z.ZodOptional<z.ZodBoolean>;
|
|
25
|
+
alias: z.ZodOptional<z.ZodBoolean>;
|
|
26
|
+
ignoreBlank: z.ZodOptional<z.ZodBoolean>;
|
|
27
|
+
alphaThreshold: z.ZodOptional<z.ZodNumber>;
|
|
28
|
+
edgePadding: z.ZodOptional<z.ZodBoolean>;
|
|
29
|
+
duplicatePadding: z.ZodOptional<z.ZodBoolean>;
|
|
30
|
+
bleed: z.ZodOptional<z.ZodBoolean>;
|
|
31
|
+
filterMin: z.ZodOptional<z.ZodEnum<{
|
|
32
|
+
nearest: "nearest";
|
|
33
|
+
linear: "linear";
|
|
34
|
+
mipmap: "mipmap";
|
|
35
|
+
mipmapNearestNearest: "mipmapNearestNearest";
|
|
36
|
+
mipmapLinearNearest: "mipmapLinearNearest";
|
|
37
|
+
mipmapNearestLinear: "mipmapNearestLinear";
|
|
38
|
+
mipmapLinearLinear: "mipmapLinearLinear";
|
|
39
|
+
}>>;
|
|
40
|
+
filterMag: z.ZodOptional<z.ZodEnum<{
|
|
41
|
+
nearest: "nearest";
|
|
42
|
+
linear: "linear";
|
|
43
|
+
mipmap: "mipmap";
|
|
44
|
+
mipmapNearestNearest: "mipmapNearestNearest";
|
|
45
|
+
mipmapLinearNearest: "mipmapLinearNearest";
|
|
46
|
+
mipmapNearestLinear: "mipmapNearestLinear";
|
|
47
|
+
mipmapLinearLinear: "mipmapLinearLinear";
|
|
48
|
+
}>>;
|
|
49
|
+
wrapX: z.ZodOptional<z.ZodEnum<{
|
|
50
|
+
clamp: "clamp";
|
|
51
|
+
repeat: "repeat";
|
|
52
|
+
mirroredRepeat: "mirroredRepeat";
|
|
53
|
+
}>>;
|
|
54
|
+
wrapY: z.ZodOptional<z.ZodEnum<{
|
|
55
|
+
clamp: "clamp";
|
|
56
|
+
repeat: "repeat";
|
|
57
|
+
mirroredRepeat: "mirroredRepeat";
|
|
58
|
+
}>>;
|
|
59
|
+
pixelFormat: z.ZodOptional<z.ZodEnum<{
|
|
60
|
+
RGBA8888: "RGBA8888";
|
|
61
|
+
RGB888: "RGB888";
|
|
62
|
+
RGBA4444: "RGBA4444";
|
|
63
|
+
RGB565: "RGB565";
|
|
64
|
+
Alpha: "Alpha";
|
|
65
|
+
}>>;
|
|
66
|
+
pageFormat: z.ZodOptional<z.ZodEnum<{
|
|
67
|
+
png: "png";
|
|
68
|
+
jpeg: "jpeg";
|
|
69
|
+
}>>;
|
|
70
|
+
jpegQuality: z.ZodOptional<z.ZodNumber>;
|
|
71
|
+
resample: z.ZodOptional<z.ZodEnum<{
|
|
72
|
+
nearest: "nearest";
|
|
73
|
+
bilinear: "bilinear";
|
|
74
|
+
bicubic: "bicubic";
|
|
75
|
+
}>>;
|
|
76
|
+
debug: z.ZodOptional<z.ZodBoolean>;
|
|
77
|
+
};
|
|
78
|
+
export declare const atlasSettingsSchema: z.ZodObject<{
|
|
79
|
+
padding: z.ZodOptional<z.ZodNumber>;
|
|
80
|
+
maxSize: z.ZodOptional<z.ZodNumber>;
|
|
81
|
+
maxWidth: z.ZodOptional<z.ZodNumber>;
|
|
82
|
+
maxHeight: z.ZodOptional<z.ZodNumber>;
|
|
83
|
+
minWidth: z.ZodOptional<z.ZodNumber>;
|
|
84
|
+
minHeight: z.ZodOptional<z.ZodNumber>;
|
|
85
|
+
powerOfTwo: z.ZodOptional<z.ZodBoolean>;
|
|
86
|
+
square: z.ZodOptional<z.ZodBoolean>;
|
|
87
|
+
multipleOf4: z.ZodOptional<z.ZodBoolean>;
|
|
88
|
+
rotate: z.ZodOptional<z.ZodBoolean>;
|
|
89
|
+
scale: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"auto">]>>;
|
|
90
|
+
scales: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
91
|
+
scale: z.ZodNumber;
|
|
92
|
+
suffix: z.ZodString;
|
|
93
|
+
}, z.core.$strip>>>;
|
|
94
|
+
stripWhitespace: z.ZodOptional<z.ZodBoolean>;
|
|
95
|
+
polygons: z.ZodOptional<z.ZodBoolean>;
|
|
96
|
+
premultipliedAlpha: z.ZodOptional<z.ZodBoolean>;
|
|
97
|
+
alias: z.ZodOptional<z.ZodBoolean>;
|
|
98
|
+
ignoreBlank: z.ZodOptional<z.ZodBoolean>;
|
|
99
|
+
alphaThreshold: z.ZodOptional<z.ZodNumber>;
|
|
100
|
+
edgePadding: z.ZodOptional<z.ZodBoolean>;
|
|
101
|
+
duplicatePadding: z.ZodOptional<z.ZodBoolean>;
|
|
102
|
+
bleed: z.ZodOptional<z.ZodBoolean>;
|
|
103
|
+
filterMin: z.ZodOptional<z.ZodEnum<{
|
|
104
|
+
nearest: "nearest";
|
|
105
|
+
linear: "linear";
|
|
106
|
+
mipmap: "mipmap";
|
|
107
|
+
mipmapNearestNearest: "mipmapNearestNearest";
|
|
108
|
+
mipmapLinearNearest: "mipmapLinearNearest";
|
|
109
|
+
mipmapNearestLinear: "mipmapNearestLinear";
|
|
110
|
+
mipmapLinearLinear: "mipmapLinearLinear";
|
|
111
|
+
}>>;
|
|
112
|
+
filterMag: z.ZodOptional<z.ZodEnum<{
|
|
113
|
+
nearest: "nearest";
|
|
114
|
+
linear: "linear";
|
|
115
|
+
mipmap: "mipmap";
|
|
116
|
+
mipmapNearestNearest: "mipmapNearestNearest";
|
|
117
|
+
mipmapLinearNearest: "mipmapLinearNearest";
|
|
118
|
+
mipmapNearestLinear: "mipmapNearestLinear";
|
|
119
|
+
mipmapLinearLinear: "mipmapLinearLinear";
|
|
120
|
+
}>>;
|
|
121
|
+
wrapX: z.ZodOptional<z.ZodEnum<{
|
|
122
|
+
clamp: "clamp";
|
|
123
|
+
repeat: "repeat";
|
|
124
|
+
mirroredRepeat: "mirroredRepeat";
|
|
125
|
+
}>>;
|
|
126
|
+
wrapY: z.ZodOptional<z.ZodEnum<{
|
|
127
|
+
clamp: "clamp";
|
|
128
|
+
repeat: "repeat";
|
|
129
|
+
mirroredRepeat: "mirroredRepeat";
|
|
130
|
+
}>>;
|
|
131
|
+
pixelFormat: z.ZodOptional<z.ZodEnum<{
|
|
132
|
+
RGBA8888: "RGBA8888";
|
|
133
|
+
RGB888: "RGB888";
|
|
134
|
+
RGBA4444: "RGBA4444";
|
|
135
|
+
RGB565: "RGB565";
|
|
136
|
+
Alpha: "Alpha";
|
|
137
|
+
}>>;
|
|
138
|
+
pageFormat: z.ZodOptional<z.ZodEnum<{
|
|
139
|
+
png: "png";
|
|
140
|
+
jpeg: "jpeg";
|
|
141
|
+
}>>;
|
|
142
|
+
jpegQuality: z.ZodOptional<z.ZodNumber>;
|
|
143
|
+
resample: z.ZodOptional<z.ZodEnum<{
|
|
144
|
+
nearest: "nearest";
|
|
145
|
+
bilinear: "bilinear";
|
|
146
|
+
bicubic: "bicubic";
|
|
147
|
+
}>>;
|
|
148
|
+
debug: z.ZodOptional<z.ZodBoolean>;
|
|
149
|
+
}, z.core.$strip>;
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import { ATLAS_FILTERS, ATLAS_PIXEL_FORMATS, ATLAS_WRAPS } from "@openbone/core";
|
|
2
|
+
import { z } from "zod";
|
|
3
|
+
/**
|
|
4
|
+
* Texture packer settings as MCP input (pack_atlas, export_file `atlas`): the same `AtlasSettings` the CLI and the
|
|
5
|
+
* Export dialog use. Everything is optional; defaults are the packer's.
|
|
6
|
+
*/
|
|
7
|
+
export const atlasSettingsShape = {
|
|
8
|
+
padding: z.number().int().min(0).max(32).optional().describe("Empty pixels around each image (default 2)"),
|
|
9
|
+
maxSize: z.number().int().min(16).max(8192).optional().describe("Largest page width and height (default 2048); maxWidth / maxHeight override one axis"),
|
|
10
|
+
maxWidth: z.number().int().min(16).max(8192).optional(),
|
|
11
|
+
maxHeight: z.number().int().min(16).max(8192).optional(),
|
|
12
|
+
minWidth: z.number().int().min(0).max(8192).optional().describe("Smallest page width (default 0)"),
|
|
13
|
+
minHeight: z.number().int().min(0).max(8192).optional(),
|
|
14
|
+
powerOfTwo: z.boolean().optional().describe("Page sizes are powers of two (default true)"),
|
|
15
|
+
square: z.boolean().optional().describe("Pages are square (default false)"),
|
|
16
|
+
multipleOf4: z.boolean().optional().describe("Page sizes are multiples of 4, for block-compressed formats (default false)"),
|
|
17
|
+
rotate: z.boolean().optional().describe("Turn images 90° when that packs tighter (images used by particles stay upright)"),
|
|
18
|
+
scale: z.union([z.number().min(0.05).max(1), z.literal("auto")]).optional().describe('Store images at this fraction of their size; "auto" shrinks only as much as needed to fit one page'),
|
|
19
|
+
scales: z
|
|
20
|
+
.array(z.object({ scale: z.number().min(0.05).max(1), suffix: z.string().max(40).regex(/^[\w@.-]*$/) }))
|
|
21
|
+
.optional()
|
|
22
|
+
.describe('export_file atlas format: several scales in one pack, one data file + page set each, e.g. [{scale:1,suffix:""},{scale:0.5,suffix:"@0.5x"}]'),
|
|
23
|
+
stripWhitespace: z.boolean().optional().describe("Pack each image by its visible bounds (meshes keep what their uvs cover; particle images stay whole)"),
|
|
24
|
+
polygons: z.boolean().optional().describe("Polygon packing: region attachments draw a tight outline around the visible pixels instead of the full quad"),
|
|
25
|
+
premultipliedAlpha: z.boolean().optional().describe("Store page pixels premultiplied (rgb × alpha); renderers use the matching blend"),
|
|
26
|
+
alias: z.boolean().optional().describe("Store identical images (same pixels after trimming) once; their regions share a rect (default true)"),
|
|
27
|
+
ignoreBlank: z.boolean().optional().describe("Fully transparent images take no space; their regions are marked empty (default true)"),
|
|
28
|
+
alphaThreshold: z.number().int().min(0).max(255).optional().describe("Alpha at or below this counts as transparent for trimming, polygons and blank images (default 0)"),
|
|
29
|
+
edgePadding: z.boolean().optional().describe("Repeat each image's edge pixels into half its padding so filtering never reads neighbours (default true)"),
|
|
30
|
+
duplicatePadding: z.boolean().optional().describe("With edge padding, copy opaque edges opaque too: hard edges like a loose texture (default true; off = opaque edges fade out)"),
|
|
31
|
+
bleed: z.boolean().optional().describe("Give fully transparent pixels the colour of the nearest visible one (alpha stays 0): no dark fringes when filtered (default on unless premultipliedAlpha)"),
|
|
32
|
+
filterMin: z.enum(ATLAS_FILTERS).optional().describe("Texture minification filter written for runtimes (default linear)"),
|
|
33
|
+
filterMag: z.enum(ATLAS_FILTERS).optional().describe("Texture magnification filter (default linear)"),
|
|
34
|
+
wrapX: z.enum(ATLAS_WRAPS).optional().describe("Texture wrap along x (default clamp)"),
|
|
35
|
+
wrapY: z.enum(ATLAS_WRAPS).optional(),
|
|
36
|
+
pixelFormat: z.enum(ATLAS_PIXEL_FORMATS).optional().describe("Pixel format hint for runtimes (default RGBA8888)"),
|
|
37
|
+
pageFormat: z.enum(["png", "jpeg"]).optional().describe("Page image format (default png); JPEG pages are opaque"),
|
|
38
|
+
jpegQuality: z.number().int().min(1).max(100).optional().describe("JPEG quality (default 90)"),
|
|
39
|
+
resample: z.enum(["bilinear", "bicubic", "nearest"]).optional().describe("Resampling for scaled packs (default bilinear)"),
|
|
40
|
+
debug: z.boolean().optional().describe("Draw a magenta outline around every region on the pages (for checking a pack)"),
|
|
41
|
+
};
|
|
42
|
+
export const atlasSettingsSchema = z.object(atlasSettingsShape);
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Duration (seconds) of an audio file from its bytes, without decoding it: WAV (RIFF data chunk), MP3 (Xing/Info or
|
|
3
|
+
* VBRI header, else every frame counted), OGG Vorbis / Opus (last page's granule position) and FLAC (STREAMINFO).
|
|
4
|
+
* 0 when the format is not recognised.
|
|
5
|
+
*/
|
|
6
|
+
export declare function audioDuration(buf: Uint8Array): number;
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Duration (seconds) of an audio file from its bytes, without decoding it: WAV (RIFF data chunk), MP3 (Xing/Info or
|
|
3
|
+
* VBRI header, else every frame counted), OGG Vorbis / Opus (last page's granule position) and FLAC (STREAMINFO).
|
|
4
|
+
* 0 when the format is not recognised.
|
|
5
|
+
*/
|
|
6
|
+
export function audioDuration(buf) {
|
|
7
|
+
const b = Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength);
|
|
8
|
+
const round = (s) => (Number.isFinite(s) && s > 0 ? Math.round(s * 1000) / 1000 : 0);
|
|
9
|
+
if (b.length >= 12 && b.toString("ascii", 0, 4) === "RIFF" && b.toString("ascii", 8, 12) === "WAVE")
|
|
10
|
+
return round(wav(b));
|
|
11
|
+
if (b.length >= 4 && b.toString("ascii", 0, 4) === "OggS")
|
|
12
|
+
return round(ogg(b));
|
|
13
|
+
if (b.length >= 4 && b.toString("ascii", 0, 4) === "fLaC")
|
|
14
|
+
return round(flac(b));
|
|
15
|
+
return round(mp3(b));
|
|
16
|
+
}
|
|
17
|
+
function wav(b) {
|
|
18
|
+
let byteRate = 0;
|
|
19
|
+
for (let p = 12; p + 8 <= b.length;) {
|
|
20
|
+
const id = b.toString("ascii", p, p + 4);
|
|
21
|
+
const size = b.readUInt32LE(p + 4);
|
|
22
|
+
if (id === "fmt " && p + 16 <= b.length)
|
|
23
|
+
byteRate = b.readUInt32LE(p + 16);
|
|
24
|
+
if (id === "data")
|
|
25
|
+
return byteRate ? Math.min(size, b.length - p - 8) / byteRate : 0;
|
|
26
|
+
p += 8 + size + (size % 2);
|
|
27
|
+
}
|
|
28
|
+
return 0;
|
|
29
|
+
}
|
|
30
|
+
// MPEG audio: bitrates (kbps) by [version (1 / 2 and 2.5)][layer 1..3][index], sample rates by version.
|
|
31
|
+
const BITRATES = {
|
|
32
|
+
"1-1": [0, 32, 64, 96, 128, 160, 192, 224, 256, 288, 320, 352, 384, 416, 448],
|
|
33
|
+
"1-2": [0, 32, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 384],
|
|
34
|
+
"1-3": [0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320],
|
|
35
|
+
"2-1": [0, 32, 48, 56, 64, 80, 96, 112, 128, 144, 160, 176, 192, 224, 256],
|
|
36
|
+
"2-2": [0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160],
|
|
37
|
+
"2-3": [0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160],
|
|
38
|
+
};
|
|
39
|
+
const RATES = { 3: [44100, 48000, 32000], 2: [22050, 24000, 16000], 0: [11025, 12000, 8000] };
|
|
40
|
+
function frameAt(b, p) {
|
|
41
|
+
if (p + 4 > b.length || b[p] !== 0xff || (b[p + 1] & 0xe0) !== 0xe0)
|
|
42
|
+
return null;
|
|
43
|
+
const v = (b[p + 1] >> 3) & 3; // 3 = MPEG1, 2 = MPEG2, 0 = MPEG2.5
|
|
44
|
+
const layerBits = (b[p + 1] >> 1) & 3; // 3 = layer I, 2 = II, 1 = III
|
|
45
|
+
const bi = (b[p + 2] >> 4) & 15;
|
|
46
|
+
const ri = (b[p + 2] >> 2) & 3;
|
|
47
|
+
if (v === 1 || layerBits === 0 || bi === 0 || bi === 15 || ri === 3)
|
|
48
|
+
return null;
|
|
49
|
+
const layer = 4 - layerBits;
|
|
50
|
+
const kbps = BITRATES[`${v === 3 ? 1 : 2}-${layer}`][bi];
|
|
51
|
+
const rate = RATES[v][ri];
|
|
52
|
+
const pad = (b[p + 2] >> 1) & 1;
|
|
53
|
+
const samples = layer === 1 ? 384 : layer === 3 && v !== 3 ? 576 : 1152;
|
|
54
|
+
const size = layer === 1 ? (Math.floor((12 * kbps * 1000) / rate) + pad) * 4 : Math.floor(((samples / 8) * kbps * 1000) / rate) + pad;
|
|
55
|
+
const channels = ((b[p + 3] >> 6) & 3) === 3 ? 1 : 2;
|
|
56
|
+
return size > 4 ? { size, samples, rate, version: v, channels } : null;
|
|
57
|
+
}
|
|
58
|
+
function mp3(b) {
|
|
59
|
+
let p = 0;
|
|
60
|
+
// ID3v2 tag(s) at the start.
|
|
61
|
+
while (p + 10 <= b.length && b.toString("ascii", p, p + 3) === "ID3") {
|
|
62
|
+
const size = ((b[p + 6] & 0x7f) << 21) | ((b[p + 7] & 0x7f) << 14) | ((b[p + 8] & 0x7f) << 7) | (b[p + 9] & 0x7f);
|
|
63
|
+
p += 10 + size + (b[p + 5] & 0x10 ? 10 : 0);
|
|
64
|
+
}
|
|
65
|
+
// First frame: a header followed by another valid header (avoids false syncs in junk).
|
|
66
|
+
let first = null;
|
|
67
|
+
for (; p + 4 <= b.length; p++) {
|
|
68
|
+
const f = frameAt(b, p);
|
|
69
|
+
if (f && (p + f.size >= b.length || frameAt(b, p + f.size))) {
|
|
70
|
+
first = f;
|
|
71
|
+
break;
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
if (!first)
|
|
75
|
+
return 0;
|
|
76
|
+
// Xing / Info (VBR or LAME CBR) header: total frame count.
|
|
77
|
+
const side = first.version === 3 ? (first.channels === 1 ? 17 : 32) : first.channels === 1 ? 9 : 17;
|
|
78
|
+
const x = p + 4 + side;
|
|
79
|
+
const tag = b.toString("ascii", x, x + 4);
|
|
80
|
+
if ((tag === "Xing" || tag === "Info") && b.readUInt32BE(x + 4) & 1) {
|
|
81
|
+
const frames = b.readUInt32BE(x + 8);
|
|
82
|
+
// The LAME tag (when present) gives the encoder delay and padding to leave out.
|
|
83
|
+
let gapless = 0;
|
|
84
|
+
if (b.toString("ascii", x + 120, x + 124) === "LAME" || b.toString("ascii", x + 120, x + 124) === "Lavc") {
|
|
85
|
+
const d = b.readUIntBE(x + 141, 3);
|
|
86
|
+
gapless = (d >> 12) + (d & 0xfff);
|
|
87
|
+
}
|
|
88
|
+
return (frames * first.samples - gapless) / first.rate;
|
|
89
|
+
}
|
|
90
|
+
// VBRI (Fraunhofer) header, 32 bytes after the frame header.
|
|
91
|
+
if (b.toString("ascii", p + 36, p + 40) === "VBRI")
|
|
92
|
+
return (b.readUInt32BE(p + 36 + 14) * first.samples) / first.rate;
|
|
93
|
+
// Otherwise count the frames.
|
|
94
|
+
let samples = 0;
|
|
95
|
+
while (p + 4 <= b.length) {
|
|
96
|
+
const f = frameAt(b, p);
|
|
97
|
+
if (!f) {
|
|
98
|
+
if (b.toString("ascii", p, p + 3) === "TAG")
|
|
99
|
+
break; // ID3v1 at the end
|
|
100
|
+
p++;
|
|
101
|
+
continue;
|
|
102
|
+
}
|
|
103
|
+
samples += f.samples;
|
|
104
|
+
p += f.size;
|
|
105
|
+
}
|
|
106
|
+
return samples / first.rate;
|
|
107
|
+
}
|
|
108
|
+
function ogg(b) {
|
|
109
|
+
// Codec from the first packet of the first page.
|
|
110
|
+
const segs = b[26];
|
|
111
|
+
const body = 27 + segs;
|
|
112
|
+
let rate = 0;
|
|
113
|
+
let preSkip = 0;
|
|
114
|
+
if (b[body] === 1 && b.toString("ascii", body + 1, body + 7) === "vorbis")
|
|
115
|
+
rate = b.readUInt32LE(body + 12);
|
|
116
|
+
else if (b.toString("ascii", body, body + 8) === "OpusHead") {
|
|
117
|
+
rate = 48000; // Opus granule positions always count 48 kHz samples
|
|
118
|
+
preSkip = b.readUInt16LE(body + 10);
|
|
119
|
+
}
|
|
120
|
+
if (!rate)
|
|
121
|
+
return 0;
|
|
122
|
+
// Granule position of the last page.
|
|
123
|
+
for (let p = b.length - 27; p >= 0; p--) {
|
|
124
|
+
if (b[p] === 0x4f && b.toString("ascii", p, p + 4) === "OggS") {
|
|
125
|
+
const granule = Number(b.readBigUInt64LE(p + 6));
|
|
126
|
+
return (granule - preSkip) / rate;
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
return 0;
|
|
130
|
+
}
|
|
131
|
+
function flac(b) {
|
|
132
|
+
// STREAMINFO is the first metadata block: 20-bit sample rate, 36-bit total samples.
|
|
133
|
+
const p = 8;
|
|
134
|
+
if (b.length < p + 18)
|
|
135
|
+
return 0;
|
|
136
|
+
const rate = (b[p + 10] << 12) | (b[p + 11] << 4) | (b[p + 12] >> 4);
|
|
137
|
+
const total = (b[p + 13] & 0x0f) * 2 ** 32 + b.readUInt32BE(p + 14);
|
|
138
|
+
return rate ? total / rate : 0;
|
|
139
|
+
}
|
package/dist/bin.d.ts
ADDED
package/dist/bin.js
ADDED
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { existsSync } from "node:fs";
|
|
3
|
+
import { createServer as createHttpServer } from "node:http";
|
|
4
|
+
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
5
|
+
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
|
|
6
|
+
import { startBridge } from "./bridge.js";
|
|
7
|
+
import { isLocalRequest } from "./local-only.js";
|
|
8
|
+
import { createServer } from "./server.js";
|
|
9
|
+
import { ProjectSession } from "./session.js";
|
|
10
|
+
const args = process.argv.slice(2);
|
|
11
|
+
const flag = (name) => {
|
|
12
|
+
const i = args.indexOf(`--${name}`);
|
|
13
|
+
return i >= 0 ? (args[i + 1] ?? "") : undefined;
|
|
14
|
+
};
|
|
15
|
+
const log = (m) => process.stderr.write(`[openbone-mcp] ${m}\n`);
|
|
16
|
+
const session = new ProjectSession();
|
|
17
|
+
const project = flag("project");
|
|
18
|
+
if (project) {
|
|
19
|
+
if (existsSync(project)) {
|
|
20
|
+
// Never replace an existing file: if it can't be read (corrupt, wrong format, newer version), stop and say why.
|
|
21
|
+
try {
|
|
22
|
+
await session.open(project);
|
|
23
|
+
}
|
|
24
|
+
catch (e) {
|
|
25
|
+
log(`cannot open ${project}: ${e.message}`);
|
|
26
|
+
log("the file was left unchanged; fix or move it, or pass a different --project path");
|
|
27
|
+
process.exit(1);
|
|
28
|
+
}
|
|
29
|
+
log(`opened ${session.filePath}`);
|
|
30
|
+
}
|
|
31
|
+
else {
|
|
32
|
+
session.newProject("Untitled", project);
|
|
33
|
+
await session.save();
|
|
34
|
+
log(`created ${session.filePath}`);
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
const bridgePort = Number(flag("bridge-port") ?? process.env.OPENBONE_BRIDGE_PORT ?? 7717);
|
|
38
|
+
if (!args.includes("--no-bridge"))
|
|
39
|
+
startBridge(session, bridgePort, log);
|
|
40
|
+
const httpPort = flag("http");
|
|
41
|
+
if (httpPort !== undefined) {
|
|
42
|
+
// Streamable HTTP (stateless): a fresh MCP server per request sharing one project session.
|
|
43
|
+
const http = createHttpServer(async (req, res) => {
|
|
44
|
+
if (req.url !== "/mcp") {
|
|
45
|
+
res.writeHead(404).end();
|
|
46
|
+
return;
|
|
47
|
+
}
|
|
48
|
+
// Refuse browser pages from other sites, including DNS rebinding (see local-only.ts).
|
|
49
|
+
if (!isLocalRequest({ origin: req.headers.origin, host: req.headers.host })) {
|
|
50
|
+
log(`http: refused a request from ${req.headers.origin ?? "?"} for host ${req.headers.host ?? "?"}`);
|
|
51
|
+
res.writeHead(403, { "content-type": "text/plain" }).end("Forbidden: only local MCP clients and the OpenBone editor\n");
|
|
52
|
+
return;
|
|
53
|
+
}
|
|
54
|
+
const chunks = [];
|
|
55
|
+
for await (const c of req)
|
|
56
|
+
chunks.push(c);
|
|
57
|
+
let body;
|
|
58
|
+
try {
|
|
59
|
+
body = chunks.length ? JSON.parse(Buffer.concat(chunks).toString()) : undefined;
|
|
60
|
+
}
|
|
61
|
+
catch {
|
|
62
|
+
res.writeHead(400, { "content-type": "text/plain" }).end("Bad request: body is not JSON\n");
|
|
63
|
+
return;
|
|
64
|
+
}
|
|
65
|
+
const { server } = createServer({ session });
|
|
66
|
+
const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
|
|
67
|
+
res.on("close", () => {
|
|
68
|
+
transport.close();
|
|
69
|
+
server.close();
|
|
70
|
+
});
|
|
71
|
+
await server.connect(transport);
|
|
72
|
+
await transport.handleRequest(req, res, body);
|
|
73
|
+
});
|
|
74
|
+
http.listen(Number(httpPort) || 7718, "127.0.0.1", () => log(`MCP over HTTP at http://127.0.0.1:${Number(httpPort) || 7718}/mcp`));
|
|
75
|
+
}
|
|
76
|
+
else {
|
|
77
|
+
const { server } = createServer({ session });
|
|
78
|
+
await server.connect(new StdioServerTransport());
|
|
79
|
+
log("MCP server ready on stdio");
|
|
80
|
+
}
|
package/dist/bridge.d.ts
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { type OpenBoneDocument } from "@openbone/core";
|
|
2
|
+
import type { IncomingMessage } from "node:http";
|
|
3
|
+
import { type WebSocket } from "ws";
|
|
4
|
+
import type { ProjectSession } from "./session.js";
|
|
5
|
+
export interface BridgeFile {
|
|
6
|
+
src: string;
|
|
7
|
+
kind: "image" | "audio";
|
|
8
|
+
mime: string;
|
|
9
|
+
base64: string;
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* Files the document refers to by a relative path that `sent` (src → modification time) hasn't had yet, or that
|
|
13
|
+
* changed on disk since. Only image and audio files, read from `baseDir`. Missing files are skipped.
|
|
14
|
+
*/
|
|
15
|
+
export declare function pendingFiles(doc: OpenBoneDocument, baseDir: string, sent: Map<string, number>): BridgeFile[];
|
|
16
|
+
export declare function startBridge(session: ProjectSession, port: number, log: (m: string) => void): import("ws").Server<typeof WebSocket, typeof IncomingMessage>;
|