mcp-patchbay 0.1.0 → 0.1.1

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/CHANGELOG.md CHANGED
@@ -4,6 +4,31 @@ All notable changes to this project are documented here. The format follows
4
4
  [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
5
5
  [Semantic Versioning](https://semver.org/).
6
6
 
7
+ ## 0.1.1 - 2026-11-16
8
+
9
+ ### Added
10
+
11
+ - Zero-config first run. When the default config, `~/.config/mcp-patchbay/servers.json`, does
12
+ not exist, the patchbay creates it with no servers (`{"version": 1, "servers": {}}`; on POSIX
13
+ the file at mode 600 and, if it has to create it, the directory at mode 700), logs one stderr
14
+ line saying where and how to add servers, and serves its own tools. Before, it exited 78. An existing group- or
15
+ world-writable directory is still refused before anything is written, and a missing
16
+ `--config` or `$MCP_PATCHBAY_CONFIG` file anywhere else is still an error (exit 78).
17
+ - A leading `~` or `${HOME}` in `--config` and `$MCP_PATCHBAY_CONFIG` is expanded. An empty
18
+ `--config=` is now a usage error (exit 64) instead of meaning the default.
19
+ - MCP Registry listing as `io.github.distronode-corporation/mcp-patchbay`: `server.json`, the
20
+ `mcpName` field in `package.json`, and a release step that publishes it with
21
+ `mcp-publisher` through GitHub OIDC once the npm version is out.
22
+ - A Claude Desktop extension bundle, `mcp-patchbay-<version>.mcpb`, built and validated with
23
+ the MCPB CLI, smoke-tested on macOS, Windows and Linux, and attached to each GitHub release.
24
+ - PRIVACY.md and a Privacy Policy section in the README: the patchbay collects and sends
25
+ nothing.
26
+
27
+ ### Documentation
28
+
29
+ - README Quick start: `claude mcp add` comes first and works on its own; adding connectors is
30
+ the next step.
31
+
7
32
  ## 0.1.0 - 2026-11-14
8
33
 
9
34
  ### Added
package/PRIVACY.md ADDED
@@ -0,0 +1,47 @@
1
+ # Privacy policy
2
+
3
+ This policy covers mcp-patchbay, the npm package `mcp-patchbay` and the Claude Desktop
4
+ extension bundle (`.mcpb`) built from this repository, published by Distronode Corporation.
5
+
6
+ ## Data collection
7
+
8
+ mcp-patchbay collects nothing about you. It has no telemetry, no analytics, no crash reporting
9
+ and no update check, and it never contacts Distronode or any service of its own.
10
+
11
+ ## Usage and storage
12
+
13
+ mcp-patchbay runs on your computer and stores only these files, all under your control:
14
+
15
+ - your config, `~/.config/mcp-patchbay/servers.json` (or the path you choose), which you write;
16
+ - sign-in tokens for remote servers you configure, kept by mcp-remote in the directory set by
17
+ `oauth.configDir` (by default `~/.config/mcp-patchbay/oauth`, mode 700);
18
+ - small pidfiles in your runtime directory, so leftovers can be cleaned up after a crash;
19
+ - when you run `import` or `rename-permissions --write` yourself, a timestamped `.bak` copy of
20
+ the file it changes, next to that file.
21
+
22
+ The modes above apply on macOS and Linux. Windows has no such modes, so there these files get
23
+ the permissions of the folder they are in.
24
+
25
+ It passes tool calls and results between your MCP client (such as Claude Code or Claude Desktop)
26
+ and the servers you configured. It keeps no copy of them. Its own logs go to stderr, where your
27
+ client keeps them, and are redacted for tokens, query strings and each server's env, args and
28
+ headers (values of 6 characters or more; SECURITY-MODEL.md has the exact rules).
29
+
30
+ ## Third-party sharing
31
+
32
+ mcp-patchbay shares nothing with Distronode or anyone else. The servers you add to the config
33
+ are separate programs: when you switch one on, it may send data to its own service under that
34
+ service's privacy policy. mcp-patchbay does not add any service to your config by itself; the
35
+ config it creates on first run has no servers.
36
+
37
+ ## Data retention
38
+
39
+ Nothing is retained by Distronode, because nothing is sent to it. The files above stay on your
40
+ computer until you delete them; [Uninstall and rollback](README.md#uninstall-and-rollback) lists
41
+ them.
42
+
43
+ ## Contact
44
+
45
+ Questions about this policy: open an issue at
46
+ <https://github.com/distronode-corporation/mcp-patchbay/issues>, or email
47
+ **opensource@distronode.com**. Security reports: see [SECURITY.md](SECURITY.md).
package/README.md CHANGED
@@ -32,19 +32,30 @@ patchbay fails closed.
32
32
  Contents: [Quick start](#quick-start) · [Config reference](#config-reference) ·
33
33
  [Naming contract](#naming-contract) · [Moving from Claude Code: `import` and
34
34
  `rename-permissions`](#moving-from-claude-code) · [Policy and safety model](#policy-and-safety-model) ·
35
- [Known limits](#known-limits) · [Comparison](#comparison) · [Uninstall and rollback](#uninstall-and-rollback)
35
+ [Known limits](#known-limits) · [Comparison](#comparison) · [Uninstall and rollback](#uninstall-and-rollback) ·
36
+ [Privacy Policy](#privacy-policy)
36
37
 
37
38
  ## Quick start
38
39
 
39
- This example hosts the public filesystem server
40
- ([`@modelcontextprotocol/server-filesystem@2.2.0`](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem)).
41
-
42
- 1. Write a config file and make it private. The patchbay refuses to start if the file, or the
43
- directory it is in, is group- or world-writable.
40
+ 1. Register the patchbay with Claude Code under the name **`patchbay`**. The naming contract and
41
+ the 128-character rule assume that name.
44
42
 
45
43
  ```sh
46
- mkdir -p -m 700 ~/.config/mcp-patchbay
47
- cat > ~/.config/mcp-patchbay/servers.json <<'EOF'
44
+ claude mcp add --scope user patchbay -- npx -y mcp-patchbay@0.1.1
45
+ ```
46
+
47
+ That is all the first run needs. When `~/.config/mcp-patchbay/servers.json` does not exist,
48
+ the patchbay creates it with no servers (`{"version": 1, "servers": {}}`), says so in one
49
+ line on stderr, and serves its own tools. Nothing is switched on and the file holds no
50
+ secrets. On macOS and Linux the file is mode 600, and the directory, if the patchbay has to
51
+ create it, mode 700; an existing directory is kept as it is, provided nobody else can write
52
+ it. Windows has no such modes (see [Known limits](#known-limits)).
53
+
54
+ 2. Then add your connectors. This example hosts the public filesystem server
55
+ ([`@modelcontextprotocol/server-filesystem@2.2.0`](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem)).
56
+ Edit `~/.config/mcp-patchbay/servers.json` so it reads:
57
+
58
+ ```json
48
59
  {
49
60
  "version": 1,
50
61
  "servers": {
@@ -56,30 +67,40 @@ This example hosts the public filesystem server
56
67
  }
57
68
  }
58
69
  }
59
- EOF
60
- chmod 600 ~/.config/mcp-patchbay/servers.json
61
70
  ```
62
71
 
63
- 2. Check it. `doctor` validates the file and briefly starts every `allow` server. Add `--all` to
64
- also start `confirm` servers like this one.
72
+ Keep the file private. The patchbay refuses to start if the file, or the directory it is in,
73
+ is group- or world-writable (`chmod 600 ~/.config/mcp-patchbay/servers.json` fixes the file).
74
+ Already have servers in Claude Code? [`import`](#import) writes this file from them.
65
75
 
66
- ```sh
67
- npx -y mcp-patchbay@0.1.0 doctor --all
68
- ```
69
-
70
- 3. Register the patchbay with Claude Code under the name **`patchbay`**. The naming contract and
71
- the 128-character rule assume that name.
76
+ 3. Check it. `doctor` validates the file and briefly starts every `allow` server. Add `--all` to
77
+ also start `confirm` servers like this one.
72
78
 
73
79
  ```sh
74
- claude mcp add --scope user patchbay -- npx -y mcp-patchbay@0.1.0
80
+ npx -y mcp-patchbay@0.1.1 doctor --all
75
81
  ```
76
82
 
77
- 4. In a session, ask the agent to "enable example-files". Claude Code shows the prompt
83
+ 4. The config is read once, at startup, so reconnect the patchbay (`/mcp`, then `patchbay`). In
84
+ a session, ask the agent to "enable example-files". Claude Code shows the prompt
78
85
  *"Allow the agent to turn on example-files (Read and write files in /path/to/project)?"*.
79
86
  Once you approve, tools such as `mcp__patchbay__example-files__read_text_file` are available.
80
87
 
81
88
  A longer, synthetic example is in [`examples/servers.json`](examples/servers.json).
82
89
 
90
+ `--config <path>` and `$MCP_PATCHBAY_CONFIG` stay strict: only the default path is ever created
91
+ for you, and a missing file anywhere else exits with code 78.
92
+
93
+ ### Claude Desktop
94
+
95
+ Each [release](https://github.com/distronode-corporation/mcp-patchbay/releases) carries
96
+ `mcp-patchbay-<version>.mcpb`, a desktop extension bundle with its dependencies included.
97
+ Double-click it, or use **Settings > Extensions > Advanced settings > Install Extension...** in
98
+ Claude Desktop. Its one setting is the config file, `~/.config/mcp-patchbay/servers.json` by
99
+ default, which the first run creates as above. Then add your connectors to it and turn the
100
+ extension off and on again in **Settings > Extensions** so it rereads the file. If a `confirm`
101
+ server cannot be enabled because the client shows no approval form, set
102
+ [`"confirmVia": "host"`](#confirmvia-elicitation-or-host).
103
+
83
104
  ## Config reference
84
105
 
85
106
  The config location is `--config <path>`, else `$MCP_PATCHBAY_CONFIG`, else
@@ -359,6 +380,14 @@ extra process, when a fixed set per subagent is enough.
359
380
  `${XDG_RUNTIME_DIR:-/tmp}/mcp-patchbay-$(id -u)` (pidfiles).
360
381
  5. If you installed it globally: `npm uninstall -g mcp-patchbay`.
361
382
 
383
+ ## Privacy Policy
384
+
385
+ mcp-patchbay collects no data and sends nothing to Distronode or anyone else: no telemetry, no
386
+ analytics, no update check. It stores only your config, sign-in tokens for remote servers you
387
+ configure (in `oauth.configDir`), pidfiles, and the `.bak` copies that `import` and
388
+ `rename-permissions --write` make, all on your computer, until you delete them. The servers you configure are separate programs with their own privacy policies.
389
+ The full policy, with the contact, is [PRIVACY.md](PRIVACY.md).
390
+
362
391
  ## Development
363
392
 
364
393
  ```sh
package/package.json CHANGED
@@ -1,6 +1,7 @@
1
1
  {
2
2
  "name": "mcp-patchbay",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
+ "mcpName": "io.github.distronode-corporation/mcp-patchbay",
4
5
  "description": "An MCP server that hosts other MCP servers as child processes and lets the agent switch them on and off mid-session, with a person confirming risky ones.",
5
6
  "keywords": [
6
7
  "mcp",
@@ -30,6 +31,7 @@
30
31
  "README.md",
31
32
  "SECURITY-MODEL.md",
32
33
  "SECURITY.md",
34
+ "PRIVACY.md",
33
35
  "CHANGELOG.md",
34
36
  "LICENSE",
35
37
  "NOTICE",
package/src/cli.js CHANGED
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  // mcp-patchbay command line. With no subcommand it serves MCP over stdio.
3
3
  import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
4
- import { ConfigError, EX_CONFIG, loadConfig, resolveConfigPath } from './config.js';
4
+ import { ConfigError, EX_CONFIG, ensureStarterConfig, loadConfig, resolveConfigPath } from './config.js';
5
5
  import { createLogger } from './log.js';
6
6
  import { PidFiles, pidDirFor } from './process.js';
7
7
  import { redact } from './redact.js';
@@ -70,9 +70,20 @@ async function serve(argv) {
70
70
  process.stderr.write(`mcp-patchbay: unknown option --${unknown[0]}\n\n${USAGE}`);
71
71
  process.exit(64);
72
72
  }
73
+ if (flags.config === '') {
74
+ process.stderr.write(`mcp-patchbay: --config needs a path\n\n${USAGE}`);
75
+ process.exit(64);
76
+ }
73
77
  const configPath = resolveConfigPath({ flag: /** @type {string | undefined} */ (flags.config) });
74
78
  let config;
75
79
  try {
80
+ if (ensureStarterConfig(configPath)) {
81
+ log.info(
82
+ `created a starter config with no servers at ${configPath}. ` +
83
+ `Add your connectors to it as the README's Quick start shows ` +
84
+ `(https://github.com/distronode-corporation/mcp-patchbay#quick-start), then reconnect.`,
85
+ );
86
+ }
76
87
  config = loadConfig(configPath);
77
88
  } catch (e) {
78
89
  if (e instanceof ConfigError) {
package/src/config.js CHANGED
@@ -36,15 +36,83 @@ export function defaultConfigPath(home = os.homedir()) {
36
36
  return path.join(home, '.config', 'mcp-patchbay', 'servers.json');
37
37
  }
38
38
 
39
+ /** The config the first run writes at the default path: version 1, no servers, no secrets. */
40
+ export const STARTER_CONFIG = '{\n "version": 1,\n "servers": {}\n}\n';
41
+
42
+ /** @param {string} p */
43
+ const samePath = (p) => (process.platform === 'win32' ? path.resolve(p).toLowerCase() : path.resolve(p));
44
+
45
+ /**
46
+ * Creates the starter config when `file` is the default config path and nothing is there yet:
47
+ * a missing directory at 0700 and the file at 0600 (POSIX; Windows has no such modes) (DECISIONS.md, "Zero-config first run"). Any other
48
+ * path is left alone, so a missing `--config` or `$MCP_PATCHBAY_CONFIG` file stays an error in
49
+ * loadConfig. An existing directory must pass checkDirPermissions before anything is written,
50
+ * and an existing entry (a file, or a dangling symlink) is never replaced or followed.
51
+ * @param {string} file
52
+ * @param {string} [home]
53
+ * @returns {boolean} true if this call created the file
54
+ */
55
+ export function ensureStarterConfig(file, home = os.homedir()) {
56
+ const def = defaultConfigPath(home);
57
+ // A trailing separator names a directory, which loadConfig must still refuse.
58
+ if (/[\\/]$/.test(file) || samePath(file) !== samePath(def)) return false;
59
+ try {
60
+ fs.lstatSync(def);
61
+ return false;
62
+ } catch (e) {
63
+ if (/** @type {any} */ (e).code !== 'ENOENT') return false; // loadConfig reports it
64
+ }
65
+ const dir = path.dirname(def);
66
+ const posix = process.platform !== 'win32';
67
+ try {
68
+ const made = fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
69
+ if (posix && made !== undefined) fs.chmodSync(dir, 0o700);
70
+ } catch (e) {
71
+ throw new ConfigError(`cannot create the config directory ${dir}: ${/** @type {any} */ (e).code ?? e}`);
72
+ }
73
+ if (posix) checkDirPermissions(def, dir);
74
+ let fd;
75
+ try {
76
+ // 'wx': never replaces or follows anything that appeared since the check above.
77
+ fd = fs.openSync(def, 'wx', 0o600);
78
+ } catch (e) {
79
+ if (/** @type {any} */ (e).code === 'EEXIST') return false;
80
+ throw new ConfigError(`cannot create config ${def}: ${/** @type {any} */ (e).code ?? e}`);
81
+ }
82
+ try {
83
+ if (posix) fs.fchmodSync(fd, 0o600);
84
+ fs.writeFileSync(fd, STARTER_CONFIG); // loops over short writes, unlike writeSync
85
+ fs.fsyncSync(fd);
86
+ } catch (e) {
87
+ // Never leave a half-written file that the next start would report as invalid JSON.
88
+ fs.closeSync(fd);
89
+ try { fs.rmSync(def, { force: true }); } catch { /* best effort */ }
90
+ throw new ConfigError(`cannot write config ${def}: ${/** @type {any} */ (e).code ?? e}`);
91
+ }
92
+ fs.closeSync(fd);
93
+ return true;
94
+ }
95
+
39
96
  /**
40
97
  * @param {{flag?: string, env?: NodeJS.ProcessEnv}} o
41
98
  */
42
99
  export function resolveConfigPath({ flag, env = process.env }) {
43
- if (flag) return flag;
44
- if (env.MCP_PATCHBAY_CONFIG) return env.MCP_PATCHBAY_CONFIG;
100
+ if (flag) return expandConfigPath(flag);
101
+ if (env.MCP_PATCHBAY_CONFIG) return expandConfigPath(env.MCP_PATCHBAY_CONFIG);
45
102
  return defaultConfigPath();
46
103
  }
47
104
 
105
+ /**
106
+ * Expands a leading `~` or `${HOME}` in a config path. A client that runs the Claude Desktop
107
+ * bundle may pass the manifest's default (`${HOME}/...`) through unexpanded; nothing else in
108
+ * the path is touched.
109
+ * @param {string} p
110
+ */
111
+ export function expandConfigPath(p) {
112
+ if (p === '${HOME}' || p.startsWith('${HOME}/') || p.startsWith('${HOME}\\')) return os.homedir() + p.slice('${HOME}'.length);
113
+ return expandHome(p);
114
+ }
115
+
48
116
  /** @param {string} p */
49
117
  export function expandHome(p) {
50
118
  if (p === '~') return os.homedir();