@openmbee/sysml-mcp 0.0.0-stage → 0.12.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/README.md CHANGED
@@ -1,3 +1,107 @@
1
- # Temporary Holding Version
1
+ # @openmbee/sysml-mcp
2
2
 
3
- 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.
3
+ The [OpenSysML](https://github.com/Open-MBEE/OpenSysML) Model Context Protocol server,
4
+ `sysml-mcp`, as an npm command: it serves SysML v2 and KerML to coding agents over stdio —
5
+ the language server's diagnostics, navigation, editing and rendering over the model
6
+ documents under a workspace root; the runtime's parsing, evaluation, execution,
7
+ verification, querying and conversion; and persistent REPL sessions — as tools an agent
8
+ calls.
9
+
10
+ ```sh
11
+ npx -y @openmbee/sysml-mcp -root .
12
+ ```
13
+
14
+ This package has no dependencies. Its `sysml-mcp` command resolves the platform package
15
+ for the machine's `process.platform`/`process.arch` from its optional dependencies, at
16
+ exactly its own version, and runs the release binary that package carries with the
17
+ arguments and stdio it was given: stdout stays the protocol stream, signals the host
18
+ sends are passed on, and the command exits with the binary's status. The platform
19
+ packages, `@openmbee/sysml-mcp-<os>-<cpu>` for linux/darwin × x64/arm64 and win32 x64,
20
+ each hold the release `sysml-mcp` binary, the LICENSE and the manual page. On any other
21
+ platform, or after an install with `--omit=optional`, the command names the missing
22
+ package on stderr and exits non-zero; `go install
23
+ github.com/Open-MBEE/OpenSysML/cmd/sysml-mcp@latest` builds the server there.
24
+
25
+ Node 20.11 or later is required. The same server is also published as release archives
26
+ and through `install.sh`, Homebrew, Scoop and the MSI; see the
27
+ [MCP server reference](https://github.com/Open-MBEE/OpenSysML/blob/main/docs/reference/sysml-mcp.md)
28
+ for those, for every tool, and for the `-root`, `-tools` and `-strict` options.
29
+
30
+ ## Configuring a host
31
+
32
+ Each block starts the server in the project, so `-root` can be left at its default, the
33
+ working directory. `sysml-mcp -print-config <host> -print-config-npx` writes the same
34
+ blocks from an installed binary.
35
+
36
+ Claude Code:
37
+
38
+ ```sh
39
+ claude mcp add --transport stdio sysml -- npx -y @openmbee/sysml-mcp -root .
40
+ ```
41
+
42
+ Codex:
43
+
44
+ ```sh
45
+ codex mcp add sysml -- npx -y @openmbee/sysml-mcp -root .
46
+ ```
47
+
48
+ Cursor (`.cursor/mcp.json`), Gemini CLI (`.gemini/settings.json`) and Devin
49
+ (Settings > MCP Marketplace > Add custom):
50
+
51
+ ```json
52
+ {
53
+ "mcpServers": {
54
+ "sysml": {
55
+ "command": "npx",
56
+ "args": ["-y", "@openmbee/sysml-mcp", "-root", "."]
57
+ }
58
+ }
59
+ }
60
+ ```
61
+
62
+ VS Code (`.vscode/mcp.json`):
63
+
64
+ ```json
65
+ {
66
+ "servers": {
67
+ "sysml": {
68
+ "type": "stdio",
69
+ "command": "npx",
70
+ "args": ["-y", "@openmbee/sysml-mcp", "-root", "."]
71
+ }
72
+ }
73
+ }
74
+ ```
75
+
76
+ OpenCode (`opencode.json`):
77
+
78
+ ```json
79
+ {
80
+ "$schema": "https://opencode.ai/config.json",
81
+ "mcp": {
82
+ "sysml": {
83
+ "type": "local",
84
+ "command": ["npx", "-y", "@openmbee/sysml-mcp", "-root", "."],
85
+ "enabled": true
86
+ }
87
+ }
88
+ }
89
+ ```
90
+
91
+ Claude Code also reads `.mcp.json` in the project, with the `mcpServers` block above and
92
+ `"type": "stdio"` before the command.
93
+
94
+ ## Versions
95
+
96
+ The package version is the OpenSysML release it runs: `@openmbee/sysml-mcp@X.Y.Z` pins
97
+ `@openmbee/sysml-mcp-<os>-<cpu>@X.Y.Z`, built from the `vX.Y.Z` release binaries, and
98
+ `npx -y @openmbee/sysml-mcp@X.Y.Z` runs that release. Pre-releases are published under
99
+ the `next` dist-tag and nightly snapshots under `nightly`; `latest` is always a release.
100
+ `@openmbee/opensysml-mcp` is the same runner under the name the other OpenSysML npm packages
101
+ share (`@openmbee/opensysml`, `@openmbee/opensysml-wasm`): generated from this package at
102
+ publish time, it pins the same platform packages at the same version and adds `opensysml-mcp`
103
+ as a second name for the command.
104
+
105
+ ## License
106
+
107
+ Apache-2.0, as OpenSysML.
@@ -0,0 +1,7 @@
1
+ #!/usr/bin/env node
2
+ // The `sysml-mcp` command of @openmbee/sysml-mcp: starts the release binary the
3
+ // platform package for this machine carries, with this process's arguments and
4
+ // stdio. Nothing is written to stdout here; it belongs to the protocol.
5
+ import { main } from "../lib/main.js";
6
+
7
+ process.exitCode = await main(process.argv.slice(2));
package/lib/main.js ADDED
@@ -0,0 +1,98 @@
1
+ // Starts the binary with the caller's arguments and stdio, forwards the
2
+ // signals a host sends its server, and ends with the binary's status.
3
+
4
+ import { spawn } from "node:child_process";
5
+ import { readFileSync } from "node:fs";
6
+ import { constants } from "node:os";
7
+ import { dirname, join } from "node:path";
8
+ import { fileURLToPath } from "node:url";
9
+ import { PACKAGE_NAME, ShimError, resolveBinary } from "./platform.js";
10
+
11
+ const here = dirname(fileURLToPath(import.meta.url));
12
+
13
+ /** The signals a host sends its server, each passed on to the binary. */
14
+ export const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
15
+
16
+ /** This package's version, the one the platform package must match. */
17
+ export function ownVersion() {
18
+ return JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8")).version;
19
+ }
20
+
21
+ /**
22
+ * Runs the binary and resolves to the exit code this process should end with.
23
+ * The binary's stdout is the protocol stream, so nothing is written there.
24
+ *
25
+ * @param {string[]} args the arguments to pass on
26
+ * @param {object} [options]
27
+ * @param {string} [options.binary] the binary to run, instead of the platform package's
28
+ * @param {{write(text: string): unknown}} [options.stderr] where errors are reported
29
+ * @param {NodeJS.Process} [options.host] the process whose signals are forwarded
30
+ * @returns {Promise<number>}
31
+ */
32
+ export function main(args, options = {}) {
33
+ const stderr = options.stderr ?? process.stderr;
34
+ const host = options.host ?? process;
35
+ let binary = options.binary;
36
+ if (binary === undefined) {
37
+ try {
38
+ binary = resolveBinary({ os: host.platform, cpu: host.arch, version: ownVersion() });
39
+ } catch (error) {
40
+ if (error instanceof ShimError) {
41
+ stderr.write(`${error.message}\n`);
42
+ return Promise.resolve(1);
43
+ }
44
+ throw error;
45
+ }
46
+ }
47
+ return run(binary, args, { stderr, host });
48
+ }
49
+
50
+ /**
51
+ * Starts binary with args on inherited stdio and resolves to the status to exit
52
+ * with: the child's exit code, or 128 plus the signal's number when a signal
53
+ * ended it, as a shell reports. Signals the host process receives meanwhile
54
+ * are passed on to the child.
55
+ */
56
+ export function run(binary, args, { stderr, host }) {
57
+ return new Promise((resolve) => {
58
+ const child = spawn(binary, args, { stdio: "inherit", windowsHide: true });
59
+ const listeners = FORWARDED_SIGNALS.map((signal) => {
60
+ const listener = () => {
61
+ if (child.exitCode === null && child.signalCode === null) {
62
+ child.kill(signal);
63
+ }
64
+ };
65
+ host.on(signal, listener);
66
+ return [signal, listener];
67
+ });
68
+ const done = (status) => {
69
+ for (const [signal, listener] of listeners) {
70
+ host.removeListener(signal, listener);
71
+ }
72
+ resolve(status);
73
+ };
74
+ child.on("error", (error) => {
75
+ stderr.write(`${describeSpawnError(binary, error)}\n`);
76
+ done(1);
77
+ });
78
+ child.on("exit", (code, signal) => {
79
+ done(code ?? signalStatus(signal));
80
+ });
81
+ });
82
+ }
83
+
84
+ /** The status a process ended by a signal is reported with: 128 plus the signal's number. */
85
+ export function signalStatus(signal) {
86
+ const number = constants.signals[signal];
87
+ return number === undefined ? 1 : 128 + number;
88
+ }
89
+
90
+ function describeSpawnError(binary, error) {
91
+ if (error.code === "ENOENT" || error.code === "EACCES") {
92
+ return (
93
+ `${PACKAGE_NAME}: ${binary} cannot be started (${error.code}); the platform package ` +
94
+ `is incomplete. Reinstall ${PACKAGE_NAME}.`
95
+ );
96
+ }
97
+ return `${PACKAGE_NAME}: could not start ${binary}: ${error.message}`;
98
+ }
@@ -0,0 +1,84 @@
1
+ // Which platform package carries the sysml-mcp binary for a Node platform and
2
+ // architecture, and where the binary sits inside it.
3
+
4
+ import { createRequire } from "node:module";
5
+ import { dirname, join } from "node:path";
6
+
7
+ /** The platforms a release builds, by Node's process.platform and process.arch. */
8
+ export const PLATFORMS = [
9
+ { os: "linux", cpu: "x64" },
10
+ { os: "linux", cpu: "arm64" },
11
+ { os: "darwin", cpu: "x64" },
12
+ { os: "darwin", cpu: "arm64" },
13
+ { os: "win32", cpu: "x64" },
14
+ ];
15
+
16
+ export const PACKAGE_NAME = "@openmbee/sysml-mcp";
17
+
18
+ /** The platform package name for a platform, or undefined when no release builds it. */
19
+ export function platformPackageName(os, cpu) {
20
+ const supported = PLATFORMS.some((platform) => platform.os === os && platform.cpu === cpu);
21
+ return supported ? `${PACKAGE_NAME}-${os}-${cpu}` : undefined;
22
+ }
23
+
24
+ /** The binary's path inside a platform package. */
25
+ export function binaryPath(os) {
26
+ return join("bin", os === "win32" ? "sysml-mcp.exe" : "sysml-mcp");
27
+ }
28
+
29
+ /**
30
+ * An error the shim reports to the caller as its own: the message is complete
31
+ * and the exit status is fixed, so the caller prints it and exits.
32
+ */
33
+ export class ShimError extends Error {
34
+ constructor(message) {
35
+ super(message);
36
+ this.name = "ShimError";
37
+ }
38
+ }
39
+
40
+ /**
41
+ * Resolves the binary for a platform from the platform package installed beside
42
+ * this one, at exactly this package's version.
43
+ *
44
+ * @param {object} options
45
+ * @param {string} options.os process.platform
46
+ * @param {string} options.cpu process.arch
47
+ * @param {string} options.version this package's version
48
+ * @param {string} [options.from] a file inside the installation to resolve from
49
+ * @returns {string} the absolute path of the binary
50
+ */
51
+ export function resolveBinary({ os, cpu, version, from = import.meta.url }) {
52
+ const name = platformPackageName(os, cpu);
53
+ if (name === undefined) {
54
+ const supported = PLATFORMS.map(({ os: o, cpu: c }) => `${o}-${c}`).join(", ");
55
+ throw new ShimError(
56
+ `${PACKAGE_NAME}: no release of sysml-mcp is built for ${os}-${cpu}; ` +
57
+ `the platforms are ${supported}. Build it from source with ` +
58
+ "`go install github.com/Open-MBEE/OpenSysML/cmd/sysml-mcp@latest` and run that binary instead.",
59
+ );
60
+ }
61
+ const require = createRequire(from);
62
+ let manifestPath;
63
+ try {
64
+ manifestPath = require.resolve(`${name}/package.json`);
65
+ } catch (error) {
66
+ if (error?.code === "MODULE_NOT_FOUND") {
67
+ throw new ShimError(
68
+ `${PACKAGE_NAME}: the platform package ${name}@${version} is not installed. ` +
69
+ "It is an optional dependency, so an install with --no-optional or --omit=optional " +
70
+ `leaves it out; run \`npm install ${name}@${version}\` or reinstall ${PACKAGE_NAME} ` +
71
+ "with optional dependencies.",
72
+ );
73
+ }
74
+ throw error;
75
+ }
76
+ const manifest = require(manifestPath);
77
+ if (manifest.version !== version) {
78
+ throw new ShimError(
79
+ `${PACKAGE_NAME}@${version}: the installed ${name} is ${manifest.version}; the binary ` +
80
+ `must be the same release. Run \`npm install ${name}@${version}\`.`,
81
+ );
82
+ }
83
+ return join(dirname(manifestPath), binaryPath(os));
84
+ }
package/package.json CHANGED
@@ -1,6 +1,45 @@
1
1
  {
2
2
  "name": "@openmbee/sysml-mcp",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.12.0",
4
+ "description": "Runs the OpenSysML Model Context Protocol server, sysml-mcp, from the release binary for this platform: npx -y @openmbee/sysml-mcp",
5
+ "license": "Apache-2.0",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/Open-MBEE/OpenSysML.git",
9
+ "directory": "packaging/npm/sysml-mcp"
10
+ },
11
+ "homepage": "https://github.com/Open-MBEE/OpenSysML/tree/main/packaging/npm/sysml-mcp#readme",
12
+ "keywords": [
13
+ "sysml",
14
+ "sysml-v2",
15
+ "kerml",
16
+ "mbse",
17
+ "mcp",
18
+ "model-context-protocol",
19
+ "opensysml"
20
+ ],
21
+ "mcpName": "org.opensysml/sysml-mcp",
22
+ "type": "module",
23
+ "engines": {
24
+ "node": ">=20.11"
25
+ },
26
+ "bin": {
27
+ "sysml-mcp": "bin/sysml-mcp.js"
28
+ },
29
+ "files": [
30
+ "bin",
31
+ "lib",
32
+ "README.md"
33
+ ],
34
+ "scripts": {
35
+ "test": "node --test",
36
+ "test:coverage": "node -e \"fs.mkdirSync('coverage',{recursive:true})\" && node --test --experimental-test-coverage --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage/lcov.info"
37
+ },
38
+ "optionalDependencies": {
39
+ "@openmbee/sysml-mcp-darwin-arm64": "0.12.0",
40
+ "@openmbee/sysml-mcp-darwin-x64": "0.12.0",
41
+ "@openmbee/sysml-mcp-linux-arm64": "0.12.0",
42
+ "@openmbee/sysml-mcp-linux-x64": "0.12.0",
43
+ "@openmbee/sysml-mcp-win32-x64": "0.12.0"
44
+ }
45
+ }