mcp-pacemaker 2.0.1

package/bin/windows/src/PoolingSecurityHelper.cs

@@ -0,0 +1,178 @@
+using System;
+using System.ComponentModel;
+using System.IO;
+using System.Security.AccessControl;
+using System.Security.Cryptography;
+
+public sealed class PoolingSecurityHelper
+{
+    private readonly PoolingSecurityReader nativeReader = new PoolingSecurityReader();
+    private readonly AccessControlSections sections =
+        AccessControlSections.Access | AccessControlSections.Owner | AccessControlSections.Group;
+
+    /// <summary>Inspects, stages, moves, or preserves Windows file security.</summary>
+    /// <param name="args">One action. File paths come from MCP_POOL environment variables.</param>
+    /// <returns>Zero on success, three on a source security conflict, or one on failure.</returns>
+    public static int Main(string[] args)
+    {
+        return new PoolingSecurityHelper().Run(args);
+    }
+
+    /// <summary>Runs a native file operation or a legacy security operation.</summary>
+    /// <param name="args">One of inspect-access, stage, move-no-replace, inspect, or copy.</param>
+    /// <returns>Zero on success, three on a source security conflict, or one on failure.</returns>
+    public int Run(string[] args)
+    {
+        try
+        {
+            if (args.Length != 1)
+            {
+                throw new ArgumentException();
+            }
+
+            var sourcePath = this.RequiredEnvironment("MCP_POOL_SOURCE");
+            if (args[0] == "inspect-access" ||
+                args[0] == "stage" ||
+                args[0] == "move-no-replace")
+            {
+                var files = new PoolingNativeFiles();
+                Console.WriteLine(files.Run(args[0], sourcePath));
+                return 0;
+            }
+
+            if (args[0] == "inspect")
+            {
+                Console.WriteLine(this.ReadSecurity(sourcePath).Fingerprint);
+                return 0;
+            }
+
+            if (args[0] == "copy")
+            {
+                return this.CopySecurity(sourcePath);
+            }
+
+            throw new ArgumentException();
+        }
+        catch (Exception error)
+        {
+            Console.Error.WriteLine("MCPERR type=" + error.GetType().Name);
+            var nativeError = error as Win32Exception;
+            if (nativeError != null)
+            {
+                Console.Error.WriteLine("MCPERR nativeError=" + nativeError.NativeErrorCode);
+            }
+
+            bool conflict = error is PoolingConflictException ||
+                (nativeError != null &&
+                    (nativeError.NativeErrorCode == 80 ||
+                     nativeError.NativeErrorCode == 183));
+            return conflict ? 3 : 1;
+        }
+    }
+
+    private string RequiredEnvironment(string name)
+    {
+        var value = Environment.GetEnvironmentVariable(name);
+        if (string.IsNullOrEmpty(value))
+        {
+            throw new ArgumentException();
+        }
+
+        return value;
+    }
+
+    private SecurityState ReadSecurity(string path)
+    {
+        var acl = File.GetAccessControl(path);
+        var descriptor = acl.GetSecurityDescriptorSddlForm(this.sections);
+        var native = this.nativeReader.ReadControlDescriptor(path);
+        bool complete = true;
+        var audit = new byte[0];
+        try
+        {
+            audit = this.ReadAudit(path);
+        }
+        catch (PrivilegeNotHeldException)
+        {
+            complete = false;
+        }
+        catch (UnauthorizedAccessException)
+        {
+            complete = false;
+        }
+
+        int attributes = (int)File.GetAttributes(path);
+        using (var hash = SHA256.Create())
+        using (var buffer = new MemoryStream())
+        using (var writer = new BinaryWriter(buffer))
+        {
+            writer.Write(native.Length);
+            writer.Write(native);
+            writer.Write(audit.Length);
+            writer.Write(audit);
+            writer.Write(attributes);
+            writer.Flush();
+            var scope = complete ? "F:" : "P:";
+            return new SecurityState
+            {
+                Descriptor = descriptor,
+                Fingerprint = scope + Convert.ToBase64String(hash.ComputeHash(buffer.ToArray())),
+            };
+        }
+    }
+
+    private byte[] ReadAudit(string path)
+    {
+        return File.GetAccessControl(path, AccessControlSections.Audit).GetSecurityDescriptorBinaryForm();
+    }
+
+    private int CopySecurity(string sourcePath)
+    {
+        var expectedFingerprint = this.RequiredEnvironment("MCP_POOL_SECURITY");
+        var source = this.ReadSecurity(sourcePath);
+        if (!string.Equals(source.Fingerprint, expectedFingerprint, StringComparison.Ordinal))
+        {
+            return 3;
+        }
+
+        var paths = new[]
+        {
+            this.RequiredEnvironment("MCP_POOL_TEMP"),
+            this.RequiredEnvironment("MCP_POOL_BACKUP"),
+        };
+        foreach (var path in paths)
+        {
+            var actual = File.GetAccessControl(path);
+            if (!string.Equals(actual.GetSecurityDescriptorSddlForm(this.sections),
+                source.Descriptor, StringComparison.Ordinal))
+            {
+                var copy = new FileSecurity();
+                copy.SetSecurityDescriptorSddlForm(source.Descriptor, this.sections);
+                File.SetAccessControl(path, copy);
+                actual = File.GetAccessControl(path);
+            }
+
+            if (!string.Equals(actual.GetSecurityDescriptorSddlForm(this.sections),
+                source.Descriptor, StringComparison.Ordinal))
+            {
+                throw new InvalidOperationException();
+            }
+
+            if (!string.Equals(this.ReadSecurity(path).Fingerprint,
+                expectedFingerprint, StringComparison.Ordinal))
+            {
+                throw new InvalidOperationException();
+            }
+        }
+
+        return string.Equals(this.ReadSecurity(sourcePath).Fingerprint,
+            expectedFingerprint, StringComparison.Ordinal) ? 0 : 3;
+    }
+
+    private sealed class SecurityState
+    {
+        public string Descriptor { get; set; }
+
+        public string Fingerprint { get; set; }
+    }
+}

package/bin/windows/src/PoolingSecurityReader.cs

@@ -0,0 +1,50 @@
+using System;
+using System.ComponentModel;
+using System.Runtime.InteropServices;
+using System.Security.AccessControl;
+
+public sealed class PoolingSecurityReader
+{
+    private const uint ReadControlSections = 0x1f7;
+
+    /// <summary>Reads native owner, DACL and non-audit security sections.</summary>
+    /// <param name="path">File whose descriptor is queried.</param>
+    /// <returns>The unfiltered sections in canonical binary form.</returns>
+    public byte[] ReadControlDescriptor(string path)
+    {
+        var descriptor = IntPtr.Zero;
+        try
+        {
+            uint status = GetNamedSecurityInfo(path, 1, ReadControlSections,
+                IntPtr.Zero, IntPtr.Zero, IntPtr.Zero, IntPtr.Zero, out descriptor);
+            if (status != 0)
+            {
+                throw new Win32Exception((int)status);
+            }
+
+            var native = new byte[GetSecurityDescriptorLength(descriptor)];
+            Marshal.Copy(descriptor, native, 0, native.Length);
+            var raw = new RawSecurityDescriptor(native, 0);
+            var canonical = new byte[raw.BinaryLength];
+            raw.GetBinaryForm(canonical, 0);
+            return canonical;
+        }
+        finally
+        {
+            if (descriptor != IntPtr.Zero)
+            {
+                LocalFree(descriptor);
+            }
+        }
+    }
+
+    [DllImport("advapi32.dll", EntryPoint = "GetNamedSecurityInfoW", CharSet = CharSet.Unicode)]
+    private static extern uint GetNamedSecurityInfo(string path, uint objectType, uint sections,
+        IntPtr owner, IntPtr group, IntPtr dacl, IntPtr sacl, out IntPtr descriptor);
+
+    [DllImport("advapi32.dll")]
+    private static extern uint GetSecurityDescriptorLength(IntPtr descriptor);
+
+    [DllImport("kernel32.dll")]
+    private static extern IntPtr LocalFree(IntPtr memory);
+}

package/docs/shared-sessions.md

@@ -0,0 +1,181 @@
+# Shared stdio sessions
+
+Status: 1.3.0 implementation contract; not a claim that every server is compatible.
+
+## Configuration
+
+Add `"sharing": "shared"` to a stdio definition only after confirming the profile below.
+Use `/<name>/mcp`: classic SSE endpoints explicitly reject shared mode.
+Pooling buttons never enable shared mode or replace an existing shared policy.
+
+| Setting | Default | Purpose |
+|---|---|---|
+| `sharedLingerMs` | 1800000 | Keep the initialized child between compatible sessions. |
+| `sharedDrainTimeoutMs` | 30000 | Maximum drain time before terminating unresolved work. |
+| `sharedRetryDelayMs` | 1000 | Backoff after a failed generation. |
+| `sharedMaxSessions` | 128 | Virtual members plus joining clients per group. |
+| `sharedMaxInFlight` | 8 | Dispatched operations per child. |
+| `sharedMaxQueued` | 32 | Unsent operations waiting for dispatch. |
+| `sharedMaxIds` | 4096 | Retained request IDs per virtual session. |
+| `sharedMaxCursors` | 256 | Retained tools-list cursors per virtual session. |
+| `sharedMaxLineBytes` | 1048576 | Maximum JSON-line size, including translated fields. |
+| `sharedMaxBufferBytes` | 4194304 | Maximum buffered protocol data per stream. |
+
+All settings require bounded integers; invalid values fail explicitly. The bridge's existing
+session cap and request/initialization timeouts also apply. A slot is reserved before waiting
+for shared initialization or the spawn gate. Concurrent resumes of one external session ID
+share one handshake.
+Client and upstream JSON have a maximum depth of 64, counting the root as depth 0.
+An upstream depth violation terminates its generation with explicit failure metadata,
+not an uncaught serializer exception; no business call is replayed.
+
+## Purpose and approval
+
+`sharing: "shared"` reuses one initialized stdio child across compatible virtual HTTP sessions.
+This differs from `pool`: a pooled child is uninitialized and belongs exclusively to its first
+session. Both modes remain opt-in. No latency recommendation enables either mode automatically.
+
+Shared mode is for a stateless-tools profile: tools operate on explicit inputs, the configured
+credential context is common, and the server has no implicit per-client workspace, conversation,
+account or subscription state. Enabling the mode asserts that profile. Matching capabilities
+alone does not prove the implementation is stateless.
+
+The default remains `isolated`. Unsupported clients receive a clear compatibility error before
+their business request is dispatched. There is no silent sharing downgrade, guessed callback
+recipient, or automatic replay on another process.
+
+## Compatibility and initialization
+
+One group per configured server and configuration generation is allowed. Its compatibility key
+contains the complete, canonically ordered initialization parameters and configuration. Preserve
+array order, absent properties and all client identity fields. The JSON-RPC request ID is not
+part of the initialization parameters.
+
+For the first profile:
+
+- Support released protocol versions `2025-03-26`, `2025-06-18` and `2025-11-25`.
+- Require empty client capabilities. Roots, sampling, elicitation, tasks and unknown extensions
+  cannot safely be routed from an arbitrary stdio callback to an individual client.
+- Support `tools/list`, `tools/call` and `ping`.
+- Reject stateful protocol methods, subscriptions, logging changes and task-augmented calls.
+- Do not interpret arbitrary tool argument/result fields as request IDs or state handles.
+- Bind tools-list cursors to their originating virtual session and child generation.
+- Retain the actual upstream protocol version, instructions and implementation metadata.
+  The upstream may negotiate any of the three supported versions.
+- Expose only the upstream's actual `tools` capability, without inventing flags. This
+  explicitly tools-only surface does not advertise optional prompts, resources, logging,
+  completions or tasks even if the upstream supports them. An empty `experimental` object
+  is harmless; unknown or nonempty experimental extensions are incompatible.
+
+Concurrent compatible arrivals share a creation promise installed before awaiting process
+creation. Exactly one upstream `initialize` and one `notifications/initialized` are sent.
+Each virtual session receives the result with its own request ID and must complete its own
+initialized notification before dispatching tools.
+
+An incompatible client does not replace or disturb the established group. Failed initialization
+fails all waiters, removes the failed creation promise, and terminates the candidate. A later
+attempt may start a new group with bounded retry behavior.
+
+## Routing
+
+Use distinct typed keys: integer `1` and string `"1"` are different client IDs.
+
+| Message | Required behavior |
+|---|---|
+| Client request | Translate to a generation-unique upstream ID and retain owner plus original ID. |
+| Child response | Deliver only to its mapped owner, restoring the original ID. |
+| Client progress token | Translate only `_meta.progressToken`; restore it on the owner's progress notifications. |
+| Client cancellation | Translate only that session's request ID. Never cancel another client's request. |
+| Child `ping` | Answer as the bridge peer. It is not a response even if its ID matches an operation. |
+| Other child requests | Reject explicitly; never select the first/recent client or broadcast callbacks. |
+| Tools-list changes | Fan out to members only when the common catalog contract permits it. |
+| Other notifications | Drop unowned logs and unexposed catalog changes with diagnostics. Never broadcast their data; reject unknown extensions. |
+
+Classify messages by category (`method`, `result`, `error`) before consulting ID maps. Unknown
+or late responses must not become notifications. Progress associated with a POST must be
+delivered on its originating POST stream; an unrelated GET stream is not a replacement.
+
+Bound operations, queued work, input lines, retained IDs/cursors and stream buffers. Reject
+overflow explicitly instead of allocating without limit or silently truncating protocol data.
+
+## Virtual child adapter
+
+`bin/shared-sessions.mjs` exports `SharedSessionManager`. It takes:
+
+```js
+{
+  spawn: async (name, definition) => actualChild,
+  kill: (actualChild) => {},
+  onFailure: (name, detail) => {},
+  onInitialized: (name, elapsedMs) => {},
+  onResponse: (name) => {},
+  log: (name, text) => {},
+  initTimeoutMs,
+  requestTimeoutMs
+}
+```
+
+`await manager.acquire(name, definition, initializeParams)` returns an EventEmitter-compatible
+virtual child with `stdin` accepting newline-delimited JSON-RPC, readable `stdout`, the actual
+group `pid`, `exitCode`, `signalCode`, `__spawnedAt`, `__sharedSession: true`, and `detach()`.
+It plugs into the existing Streamable HTTP per-session response parser without spawning again.
+One actual child owns one stdout parser; virtual stdout contains only that session's messages.
+For already-parsed HTTP JSON, use `child.writeMessage(message)`. It applies the same input,
+depth, ID and ownership guards before serialization. Calling it after detachment throws an
+explicit `SHARED_DETACHED` admission error instead of leaving a request waiting indefinitely.
+
+The bridge's process-kill helper must detect a virtual child and detach it instead of killing
+its shared PID. Actual group creation goes through the existing spawn gate and B21 counter.
+Virtual session attachment is not an OS spawn or a cold-initialization sample.
+`onResponse` reports actual upstream responses, not locally generated rejections. Health must
+not classify errors by a numeric JSON-RPC code that an upstream can also legitimately use.
+
+Provide `recycle(name)`, `remove(name)`, `shutdown()` and `inspect(name)` methods. Inspection
+exposes only lifecycle facts such as generation, state, members and unresolved operations.
+
+## Lifetime, drain and credentials
+
+Deleting one session forgets and tombstones only that session. Remove its unsent work and send
+owner-scoped cancellation for dispatched work. Other clients and their operations remain alive.
+The actual child lingers between compatible sessions, bounded by `sharedLingerMs` (default
+30 minutes). Unresolved work prevents idle eviction.
+
+Cancellation is not proof that execution stopped. Retain execution ownership until the
+response arrives or a bounded failure/drain policy terminates the generation.
+
+Recycling marks the generation draining and stops new dispatch to it. Existing work gets a
+bounded opportunity to finish; once drained, terminate promptly rather than waiting for the
+next full recycle interval. A drain deadline fails unresolved work explicitly as potentially
+executed, terminates that generation, and permits a later fresh generation. Never replay those
+business calls. Fence old exit handlers and timers so they cannot delete a replacement.
+
+The server retains its existing credential mechanism. The bridge does not freeze a token in
+the shared initialization, infer renewal from a generic cache, or substitute an auth provider.
+Keep configured credential recycling. A synthetic short-expiry test must show: expired call
+fails unchanged; draining/replacement creates a fresh generation; a new call succeeds; the
+failed call was dispatched once. Real provider renewal still requires its own canary.
+
+Resume reattaches only compatible stateless sessions. It is not restoration of arbitrary
+application state and does not preserve TCP connections across a bridge restart; that is B14.
+
+## Acceptance gates
+
+1. More than fifty compatible initialize/DELETE cycles reuse one actual child and one upstream
+   initialization. Two simultaneously active sessions must also share that same generation.
+2. Concurrent numeric/string ID collisions, out-of-order results, progress and cancellation
+   route to the correct owner. Forged or late messages cannot cross sessions.
+3. Delete one client while another works, kill a child during a request, and recycle while busy.
+   Pending callers fail promptly and dispatched tool calls are never replayed.
+4. Incompatible initialization and unsupported callbacks/methods fail explicitly. Isolation
+   defaults and existing HTTP proxy behavior remain unchanged.
+5. Counter deltas for identical isolated and shared workloads show actual reduced launches,
+   not merely fewer latency samples or a lower instant process count.
+6. Use an isolated config directory and spare port for real-server and browser/CLI canaries.
+   Do not alter another project's client or orchestration configuration.
+
+Reference: released MCP
+[lifecycle](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle),
+[transports](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports),
+[progress](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/progress), and
+[cancellation](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/cancellation).
+Draft transport changes are not applied to clients speaking released versions.

package/examples/servers.example.json

@@ -0,0 +1,31 @@
+{
+  "filesystem": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
+  },
+  "github": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-github"],
+    "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "REPLACE_WITH_YOUR_PAT" }
+  },
+  "example-http-static-token": {
+    "type": "http",
+    "url": "https://example.com/mcp",
+    "auth": { "type": "env", "var": "EXAMPLE_TOKEN" }
+  },
+  "example-http-cli-token": {
+    "type": "http",
+    "url": "https://your-service.example.com/mcp",
+    "auth": {
+      "type": "command",
+      "command": "az account get-access-token --resource api://your-resource-id --query accessToken -o tsv",
+      "refreshMinutes": 50
+    },
+    "headers": { "x-example-header": "value" }
+  },
+  "example-http-no-auth": {
+    "type": "http",
+    "url": "https://open.example.com/mcp",
+    "auth": { "type": "none" }
+  }
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "mcp-pacemaker",
+  "version": "2.0.1",
+  "description": "Keeps your MCP servers alive across editor restarts, reboots, and token expiry — pluggable auth, cross-platform auto-start, one-command setup. Zero-dependency bridge; a small CLI for setup.",
+  "type": "module",
+  "bin": {
+    "mcp-pacemaker": "bin/cli.mjs",
+    "mcp-bridge": "bin/mcp-bridge.mjs"
+  },
+  "files": [
+    "bin/",
+    "autostart/",
+    "supervisor/",
+    "tools/windows-security-helper/",
+    "examples/",
+    "ui/dist/",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "docs/shared-sessions.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.txt",
+    "CONTRIBUTING.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "author": "Girish Konda",
+  "homepage": "https://github.com/girishkvs/mcp-pacemaker#readme",
+  "bugs": {
+    "url": "https://github.com/girishkvs/mcp-pacemaker/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/girishkvs/mcp-pacemaker.git"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "sse",
+    "bridge",
+    "proxy",
+    "vscode",
+    "cursor",
+    "claude-desktop",
+    "supervisor",
+    "keep-alive"
+  ],
+  "scripts": {
+    "bridge": "node bin/mcp-bridge.mjs",
+    "cli": "node bin/cli.mjs",
+    "consumer:check": "node tools/npm-consumer/check.mjs",
+    "compat:prepare": "node tools/compatibility/prepare.mjs",
+    "compat:prepare:baseline": "node tools/compatibility/prepare.mjs --historical",
+    "compat:clean": "node tools/compatibility/prepare.mjs --clean",
+    "test:compat": "node --test --test-concurrency=1 test/compat/gates.test.mjs test/compat/cli-api.test.mjs",
+    "test:compat:browser": "node --test --test-concurrency=1 test/compat/browser.test.mjs",
+    "test": "node --test test/bridge.test.mjs test/bridge-controls.test.mjs test/kill-tree.test.mjs test/keepalive.test.mjs test/auth-token.test.mjs test/cold-start.test.mjs test/crash-report.test.mjs test/resume.test.mjs test/config-checks.test.mjs test/config-reload.test.mjs test/health.test.mjs test/cli.test.mjs test/logs.test.mjs test/prewarm.test.mjs test/pooling-batch-scheduler.test.mjs test/pooling-batch-api.test.mjs test/pooling-batch-store.test.mjs test/pooling-batches.test.mjs test/pooling-stage-publication.test.mjs test/pooling-batch-startup.test.mjs test/pooling-postcommit-recovery.test.mjs test/pooling-config.test.mjs test/pooling-writer.test.mjs test/pooling-api.test.mjs test/pooling-deadlines.test.mjs test/pooling-queue-budget.test.mjs test/windows-security-helper.test.mjs test/windows-batch-security.test.mjs test/tui.test.mjs test/warm-pool.test.mjs test/server-metrics.test.mjs test/admission.test.mjs test/shared-sessions.test.mjs test/shared-http.test.mjs test/cross-host.test.mjs test/suite-integrity.test.mjs test/consumer-package.test.mjs test/notices.test.mjs test/notices-runtime.test.mjs test/npm-publication.test.mjs test/npm-publication-proof.test.mjs test/update-check.test.mjs test/service-lifecycle.test.mjs test/service-supervisor.test.mjs test/npm-publication-gates.test.mjs test/npm-publication-matrix.test.mjs test/publication-scanners-advisories.test.mjs test/publication-scanners.test.mjs test/service-replacement.test.mjs test/consumer-environment.test.mjs test/npm-publication-external.test.mjs test/npm-publication-peer.test.mjs test/publication-scanners-diagnostics.test.mjs test/publication-scanners-publication.test.mjs test/publication-scanners-paths.test.mjs test/npm-publication-local-enforcement.test.mjs test/publication-scanners-admission.test.mjs",
+    "notices:check": "node tools/third-party-notices/check.mjs",
+    "publication:source-gates": "node tools/npm-publication/source-gates.mjs",
+    "publication:artifact-gates": "node tools/npm-publication/artifact-gates.mjs",
+    "service:replacement:check": "node tools/service-replacement/check.mjs",
+    "publication:external-gates": "node tools/npm-publication/external-gates.mjs",
+    "publication:local-gate": "node tools/npm-publication/local-windows.mjs",
+    "publication:verify-local": "node tools/npm-publication/verify-local.mjs"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "commander": "^15.0.0",
+    "ink": "^7.1.1",
+    "picocolors": "^1.1.1",
+    "react": "^19.2.7",
+    "semver": "^7.7.3",
+    "smol-toml": "^1.8.0"
+  }
+}

package/supervisor/bridge-child.mjs

@@ -0,0 +1,14 @@
+// IPC reaches the bridge's existing graceful shutdown handler on Windows too.
+let loaded = false;
+let stopRequested = false;
+function shutdown() {
+  stopRequested = true;
+  if (loaded) process.emit('SIGTERM');
+}
+process.on('message', (message) => {
+  if (message === 'stop') shutdown();
+});
+process.on('disconnect', shutdown);
+await import('../bin/mcp-bridge.mjs');
+loaded = true;
+if (stopRequested) shutdown();