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 +25 -0
- package/PRIVACY.md +47 -0
- package/README.md +49 -20
- package/package.json +3 -1
- package/src/cli.js +12 -1
- package/src/config.js +70 -2
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
|
-
|
|
40
|
-
|
|
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
|
-
|
|
47
|
-
|
|
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
|
-
|
|
64
|
-
|
|
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
|
-
|
|
67
|
-
|
|
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
|
-
|
|
80
|
+
npx -y mcp-patchbay@0.1.1 doctor --all
|
|
75
81
|
```
|
|
76
82
|
|
|
77
|
-
4.
|
|
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.
|
|
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();
|