@alfe.ai/connectwise-screenconnect-mcp 0.1.0

package/README.md

@@ -0,0 +1,104 @@
+# ConnectWise ScreenConnect MCP
+
+Runtime-independent stdio MCP server for ScreenConnect's RESTful API Manager
+extension. Alfe Connections supplies credentials at execution time. Every
+provider operation requires the exact `connectionId` returned by
+`screenconnect_list_connections`.
+
+## Setup
+
+1. Install the **RESTful API Manager** extension in the ScreenConnect
+   administration Extension Marketplace. This integration implements the
+   documented 1.0.8 API contract (server 22.3 or newer); notes need 1.0.6+.
+2. Set the extension's `RESTfulAuthenticationSecret` to a strong random secret
+   and configure its execution user/permissions for the operations you need.
+3. Leave `RESTfulAllowedOrigin` empty or set it to the ScreenConnect site's
+   origin, such as `https://support.example.com`. The runtime sends that origin
+   on requests.
+4. Add a **ConnectWise ScreenConnect** connection in Alfe with that site's
+   HTTPS origin and authentication secret, at a scope the agent can access.
+5. The connection-driven integration launches the server automatically.
+   For manual testing on an already configured agent:
+
+   ```sh
+   npx -y @alfe.ai/connectwise-screenconnect-mcp@0.1.0
+   ```
+
+`@alfe.ai/config` supplies the Alfe API key and API URL from the normal agent
+configuration. No ScreenConnect credentials are passed through command-line
+arguments or integration environment variables. The binary is
+`connectwise-screenconnect-mcp`.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `screenconnect_list_connections` | Discover connections without exposing secrets |
+| `screenconnect_check_connection` | Verify extension access with a read that matches no sessions |
+| `screenconnect_list_sessions` | Query sessions by a required session filter |
+| `screenconnect_find_sessions` | Find sessions by name |
+| `screenconnect_get_session` | Retrieve a session by its GUID |
+| `screenconnect_get_session_details` | Inspect events and connections, omitting screenshot bytes |
+| `screenconnect_create_session` | Create Support or Meeting sessions |
+| `screenconnect_rename_session` | Replace a session's display name |
+| `screenconnect_update_custom_properties` | Replace up to eight positional custom properties |
+| `screenconnect_add_note` | Append a session note |
+| `screenconnect_send_message` | Send a message attributed to a host |
+| `screenconnect_run_command` | Queue a remote command with exact target/content confirmation |
+| `screenconnect_run_toolbox_item` | Queue an existing toolbox item with exact target/item confirmation |
+
+The API has no session pagination. The required filter controls the provider
+query; `limit` (1–500, default 100) limits the returned tool result and reports
+truncation. Narrow filters when the provider response exceeds 5 MiB.
+
+Create supports `Support` and `Meeting`, and private sessions require a join
+code. Access agent installation is a different API and is not exposed here.
+Custom-property updates replace the entire positional array, so read the
+current values and preserve those you want to keep.
+
+Remote command/toolbox responses mean **accepted**, not completed. Inspect
+session details for execution results. Requests are never automatically
+retried; check the resulting session state before retrying a mutation after a
+timeout or transport error.
+
+## Request contract
+
+All requests target the fixed extension prefix
+`/App_Extensions/2d558935-686a-4bd0-9991-07539f5fe749/Service.ashx/`.
+Read methods use GET and mutations use POST, with `application/json` positional
+array bodies and the `CTRLAuthHeader` authentication header. Node's HTTPS
+transport supports the documented GET request bodies.
+
+Before every request, all DNS answers must be public. The connection is pinned
+to those checked addresses with the original TLS hostname/certificate checks.
+Redirects are never followed. DNS, connection, and response streaming share a
+30-second deadline. Request bodies are capped at 128 KiB and responses at
+5 MiB. Errors omit provider bodies, URLs, credential bundles, and original
+network exception causes.
+
+## Verification
+
+```sh
+pnpm --filter @alfe.ai/connectwise-screenconnect-mcp typecheck
+pnpm --filter @alfe.ai/connectwise-screenconnect-mcp lint
+pnpm --filter @alfe.ai/connectwise-screenconnect-mcp test
+pnpm --filter @alfe.ai/connectwise-screenconnect-mcp build
+```
+
+Contract tests verify transport/authentication, pinned DNS and SSRF rejection,
+response bounds, no mutation retries, credential rotation/isolation, and real
+MCP client/server exchanges. These tests do not constitute live tenant
+verification. Before rollout, use an approved ScreenConnect test instance with
+the extension configured to verify creation, updates, notes, messaging, and
+command/toolbox execution against a disposable session.
+
+Official references verified 2026-09-08:
+
+- [RESTful API Manager](https://docs.connectwise.com/ScreenConnect_Documentation/Developers/RESTful_API_Manager)
+- [Session Manager API](https://docs.connectwise.com/ScreenConnect_Documentation/Developers/Session_Manager_API_Reference)
+- [Session and session-details objects](https://docs.connectwise.com/ScreenConnect_Documentation/Developers/Session_Manager_API_Reference/Objects)
+- [Extension release notes](https://screenconnect.product.connectwise.com/communities/26/topics/4301-restful-api-manager)
+
+The documentation site may redirect to ConnectWise University authentication.
+The protocol contract was also available through the official page's search
+index at implementation time.

package/dist/bin.cjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+const require_screenconnect_client = require("./screenconnect-client2.cjs");
+const require_server = require("./server2.cjs");
+//#region src/cli.ts
+async function runCli(start = require_server.startServer, runtime = process) {
+	let server;
+	try {
+		server = await start();
+	} catch (error) {
+		runtime.stderr.write(`[screenconnect-mcp] Failed to start: ${require_screenconnect_client.safeErrorMessage(error)}\n`);
+		runtime.exitCode = 1;
+		return;
+	}
+	let closing = false;
+	const shutdown = () => {
+		if (closing) return;
+		closing = true;
+		runtime.off("SIGINT", shutdown);
+		runtime.off("SIGTERM", shutdown);
+		server.close().catch(() => {
+			runtime.stderr.write("[screenconnect-mcp] Transport cleanup failed.\n");
+		}).finally(() => runtime.exit(0));
+	};
+	runtime.once("SIGINT", shutdown);
+	runtime.once("SIGTERM", shutdown);
+}
+//#endregion
+//#region src/bin.ts
+runCli();
+//#endregion

package/dist/bin.d.cts

@@ -0,0 +1 @@
+export {};

package/dist/bin.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bin.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { d as safeErrorMessage } from "./screenconnect-client2.js";
+import { i as startServer } from "./server2.js";
+//#region src/cli.ts
+async function runCli(start = startServer, runtime = process) {
+	let server;
+	try {
+		server = await start();
+	} catch (error) {
+		runtime.stderr.write(`[screenconnect-mcp] Failed to start: ${safeErrorMessage(error)}\n`);
+		runtime.exitCode = 1;
+		return;
+	}
+	let closing = false;
+	const shutdown = () => {
+		if (closing) return;
+		closing = true;
+		runtime.off("SIGINT", shutdown);
+		runtime.off("SIGTERM", shutdown);
+		server.close().catch(() => {
+			runtime.stderr.write("[screenconnect-mcp] Transport cleanup failed.\n");
+		}).finally(() => runtime.exit(0));
+	};
+	runtime.once("SIGINT", shutdown);
+	runtime.once("SIGTERM", shutdown);
+}
+//#endregion
+//#region src/bin.ts
+runCli();
+//#endregion
+export {};

package/dist/screenconnect-client.cjs

@@ -0,0 +1,5 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_screenconnect_client = require("./screenconnect-client2.cjs");
+exports.EXTENSION_PATH = require_screenconnect_client.EXTENSION_PATH;
+exports.ScreenConnectClient = require_screenconnect_client.ScreenConnectClient;
+exports.pinnedLookup = require_screenconnect_client.pinnedLookup;

package/dist/screenconnect-client.d.cts

@@ -0,0 +1,92 @@
+import { RequestOptions } from "node:https";
+import { ClientRequest, IncomingMessage } from "node:http";
+import { LookupFunction } from "node:net";
+import { z } from "zod";
+
+//#region src/boundary.d.ts
+
+interface ResolvedAddress {
+  address: string;
+  family: number;
+}
+type ResolveHost = (hostname: string) => Promise<ResolvedAddress[]>;
+//#endregion
+//#region src/screenconnect-client.d.ts
+declare const EXTENSION_PATH = "/App_Extensions/2d558935-686a-4bd0-9991-07539f5fe749/Service.ashx/";
+/** Positional contracts from the official RESTful API Manager reference. */
+declare const methods: {
+  readonly GetSessionsByFilter: {
+    readonly method: "GET";
+    readonly parameters: z.ZodTuple<[z.ZodString], null>;
+  };
+  readonly GetSessionsByName: {
+    readonly method: "GET";
+    readonly parameters: z.ZodTuple<[z.ZodString], null>;
+  };
+  readonly GetSessionBySessionID: {
+    readonly method: "GET";
+    readonly parameters: z.ZodTuple<[z.ZodUUID], null>;
+  };
+  readonly GetSessionDetailsBySessionID: {
+    readonly method: "GET";
+    readonly parameters: z.ZodTuple<[z.ZodUUID], null>;
+  };
+  readonly CreateSession: {
+    readonly method: "POST";
+    readonly parameters: z.ZodTuple<[z.ZodEnum<{
+      Support: "Support";
+      Meeting: "Meeting";
+    }>, z.ZodString, z.ZodBoolean, z.ZodString, z.ZodArray<z.ZodString>], null>;
+  };
+  readonly UpdateSessionName: {
+    readonly method: "POST";
+    readonly parameters: z.ZodTuple<[z.ZodUUID, z.ZodString], null>;
+  };
+  readonly UpdateSessionCustomProperties: {
+    readonly method: "POST";
+    readonly parameters: z.ZodTuple<[z.ZodUUID, z.ZodArray<z.ZodString>], null>;
+  };
+  readonly AddNoteToSession: {
+    readonly method: "POST";
+    readonly parameters: z.ZodTuple<[z.ZodUUID, z.ZodString], null>;
+  };
+  readonly SendMessageToSession: {
+    readonly method: "POST";
+    readonly parameters: z.ZodTuple<[z.ZodUUID, z.ZodString, z.ZodString], null>;
+  };
+  readonly SendCommandToSession: {
+    readonly method: "POST";
+    readonly parameters: z.ZodTuple<[z.ZodUUID, z.ZodString], null>;
+  };
+  readonly SendToolboxItemToSession: {
+    readonly method: "POST";
+    readonly parameters: z.ZodTuple<[z.ZodUUID, z.ZodString], null>;
+  };
+};
+type ScreenConnectMethod = keyof typeof methods;
+interface ScreenConnectApi {
+  call(method: ScreenConnectMethod, parameters: unknown[]): Promise<unknown>;
+}
+type RequestFactory = (url: URL, options: RequestOptions, onResponse: (response: IncomingMessage) => void) => ClientRequest;
+interface ScreenConnectClientOptions {
+  siteUrl: string;
+  authenticationSecret: string;
+  /** Injection boundaries for contract tests; never sourced from tool input. */
+  resolveHost?: ResolveHost;
+  requestFactory?: RequestFactory;
+  requestTimeoutMs?: number;
+}
+declare class ScreenConnectClient implements ScreenConnectApi {
+  readonly siteUrl: string;
+  private readonly secret;
+  private readonly resolveHost?;
+  private readonly requestFactory;
+  private readonly timeoutMs;
+  constructor(options: ScreenConnectClientOptions);
+  call(method: ScreenConnectMethod, parameters: unknown[]): Promise<unknown>;
+  private send;
+}
+/** No second DNS resolution is allowed between validation and connection. */
+declare function pinnedLookup(addresses: ResolvedAddress[]): LookupFunction;
+//#endregion
+export { ScreenConnectClientOptions as a, ScreenConnectClient as i, RequestFactory as n, ScreenConnectMethod as o, ScreenConnectApi as r, pinnedLookup as s, EXTENSION_PATH as t };

package/dist/screenconnect-client.d.ts

@@ -0,0 +1,92 @@
+import { LookupFunction } from "node:net";
+import { z } from "zod";
+import { RequestOptions } from "node:https";
+import { ClientRequest, IncomingMessage } from "node:http";
+
+//#region src/boundary.d.ts
+
+interface ResolvedAddress {
+  address: string;
+  family: number;
+}
+type ResolveHost = (hostname: string) => Promise<ResolvedAddress[]>;
+//#endregion
+//#region src/screenconnect-client.d.ts
+declare const EXTENSION_PATH = "/App_Extensions/2d558935-686a-4bd0-9991-07539f5fe749/Service.ashx/";
+/** Positional contracts from the official RESTful API Manager reference. */
+declare const methods: {
+  readonly GetSessionsByFilter: {
+    readonly method: "GET";
+    readonly parameters: z.ZodTuple<[z.ZodString], null>;
+  };
+  readonly GetSessionsByName: {
+    readonly method: "GET";
+    readonly parameters: z.ZodTuple<[z.ZodString], null>;
+  };
+  readonly GetSessionBySessionID: {
+    readonly method: "GET";
+    readonly parameters: z.ZodTuple<[z.ZodUUID], null>;
+  };
+  readonly GetSessionDetailsBySessionID: {
+    readonly method: "GET";
+    readonly parameters: z.ZodTuple<[z.ZodUUID], null>;
+  };
+  readonly CreateSession: {
+    readonly method: "POST";
+    readonly parameters: z.ZodTuple<[z.ZodEnum<{
+      Support: "Support";
+      Meeting: "Meeting";
+    }>, z.ZodString, z.ZodBoolean, z.ZodString, z.ZodArray<z.ZodString>], null>;
+  };
+  readonly UpdateSessionName: {
+    readonly method: "POST";
+    readonly parameters: z.ZodTuple<[z.ZodUUID, z.ZodString], null>;
+  };
+  readonly UpdateSessionCustomProperties: {
+    readonly method: "POST";
+    readonly parameters: z.ZodTuple<[z.ZodUUID, z.ZodArray<z.ZodString>], null>;
+  };
+  readonly AddNoteToSession: {
+    readonly method: "POST";
+    readonly parameters: z.ZodTuple<[z.ZodUUID, z.ZodString], null>;
+  };
+  readonly SendMessageToSession: {
+    readonly method: "POST";
+    readonly parameters: z.ZodTuple<[z.ZodUUID, z.ZodString, z.ZodString], null>;
+  };
+  readonly SendCommandToSession: {
+    readonly method: "POST";
+    readonly parameters: z.ZodTuple<[z.ZodUUID, z.ZodString], null>;
+  };
+  readonly SendToolboxItemToSession: {
+    readonly method: "POST";
+    readonly parameters: z.ZodTuple<[z.ZodUUID, z.ZodString], null>;
+  };
+};
+type ScreenConnectMethod = keyof typeof methods;
+interface ScreenConnectApi {
+  call(method: ScreenConnectMethod, parameters: unknown[]): Promise<unknown>;
+}
+type RequestFactory = (url: URL, options: RequestOptions, onResponse: (response: IncomingMessage) => void) => ClientRequest;
+interface ScreenConnectClientOptions {
+  siteUrl: string;
+  authenticationSecret: string;
+  /** Injection boundaries for contract tests; never sourced from tool input. */
+  resolveHost?: ResolveHost;
+  requestFactory?: RequestFactory;
+  requestTimeoutMs?: number;
+}
+declare class ScreenConnectClient implements ScreenConnectApi {
+  readonly siteUrl: string;
+  private readonly secret;
+  private readonly resolveHost?;
+  private readonly requestFactory;
+  private readonly timeoutMs;
+  constructor(options: ScreenConnectClientOptions);
+  call(method: ScreenConnectMethod, parameters: unknown[]): Promise<unknown>;
+  private send;
+}
+/** No second DNS resolution is allowed between validation and connection. */
+declare function pinnedLookup(addresses: ResolvedAddress[]): LookupFunction;
+//#endregion
+export { ScreenConnectClientOptions as a, ScreenConnectClient as i, RequestFactory as n, ScreenConnectMethod as o, ScreenConnectApi as r, pinnedLookup as s, EXTENSION_PATH as t };

package/dist/screenconnect-client.js

@@ -0,0 +1,2 @@
+import { n as ScreenConnectClient, r as pinnedLookup, t as EXTENSION_PATH } from "./screenconnect-client2.js";
+export { EXTENSION_PATH, ScreenConnectClient, pinnedLookup };