@alfe.ai/connectwise-automate-mcp 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# ConnectWise Automate MCP
+
+Runtime-agnostic stdio MCP server for Automate client, location and endpoint
+inventory, available scripts, computer monitors, and script/monitor history.
+Every provider operation requires an explicit Alfe `connectionId`.
+
+Create a **ConnectWise Automate** connection in Alfe using the public HTTPS
+server origin and an integrator username/password. Alfe supplies the vendor
+ClientID. This server reads Alfe configuration through `@alfe.ai/config` and
+resolves fresh connection credentials through `AgentApiClient` on every call.
+It requires no ConnectWise environment variables or copied secrets.
+
+The integration manifest starts the first release with:
+
+```yaml
+mcp_servers:
+  - id: connectwise-automate
+    command: npx
+    args: ["-y", "@alfe.ai/connectwise-automate-mcp@0.1.0"]
+    env: {}
+```
+
+Call `automate_list_connections`, then pass the chosen `connectionId` to:
+
+- `automate_check_connection`
+- `automate_list_clients`
+- `automate_list_locations`
+- `automate_list_computers`
+- `automate_list_scripts`
+- `automate_list_monitor_history`
+- `automate_list_internal_monitor_results`
+- `automate_list_computer_monitors` (also requires `computerId`)
+- `automate_list_computer_script_history` (also requires `computerId`)
+
+List tools accept a 1-based `page`, `pageSize` (1–200, default 50), and an
+Automate `condition` expression. They return `{ items, page, pageSize }` for
+one page. Scripts are discovered and their execution history can be inspected;
+these tools do not execute scripts, reboot computers, or change monitors.
+
+The server calls `/cwa/api/v1/` on the selected origin. It caches bearer tokens
+per connection, refreshes while they are still valid, and reauthenticates after
+expiration or one failed GET. Credential rotation and revoked Alfe scope take
+effect on the next tool call. Interactive/2FA login challenges return an
+actionable connection error.
+
+Private-network and loopback servers are unsupported. Each request resolves
+the hostname afresh, rejects any non-public DNS answer, and pins the HTTPS
+socket to a checked IP while retaining TLS hostname validation. Redirects are
+never followed. Requests, DNS, responses and tool results have explicit bounds;
+raw provider errors and credential-bearing fields are never forwarded.
+
+## API contract and verification
+
+The primary API reference is the [ConnectWise Automate developer
+portal](https://developer.connectwise.com/Products/Automate/Integrating_with_Automate/API),
+which requires a ConnectWise developer login. The implementation was checked
+against its exported **Automate API v1** OpenAPI contracts, preserved in the
+[System](https://github.com/covenanttechnologysolutions/connectwise-rest/blob/d04740719c5a62008af4dc31287a621b2f07f860/generator/automate-json/System.json),
+[Company](https://github.com/covenanttechnologysolutions/connectwise-rest/blob/d04740719c5a62008af4dc31287a621b2f07f860/generator/automate-json/Company.json),
+[Computers](https://github.com/covenanttechnologysolutions/connectwise-rest/blob/d04740719c5a62008af4dc31287a621b2f07f860/generator/automate-json/Computers.json),
+[Scripts](https://github.com/covenanttechnologysolutions/connectwise-rest/blob/d04740719c5a62008af4dc31287a621b2f07f860/generator/automate-json/Scripts.json)
+and [Monitors](https://github.com/covenanttechnologysolutions/connectwise-rest/blob/d04740719c5a62008af4dc31287a621b2f07f860/generator/automate-json/Monitors.json)
+files at that immutable mirror revision. The mirror is independently
+maintained; it is not a live contract obtained from the customer's server.
+
+Tests exercise the token wire format/lifecycle, endpoint and pagination
+contracts, connection selection/rotation/revocation, DNS and response bounds,
+error redaction, and real in-memory MCP protocol requests. No live customer
+Automate server was available during implementation. Before declaring a
+deployment operational, configure a real vendor ClientID and integrator
+connection, run `automate_check_connection`, page each relevant inventory tool,
+and verify refresh against the installed Automate version. An account must
+have the corresponding Automate read permissions; permission failures are
+reported without widening access.

package/dist/bin.cjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+const require_server = require("./server2.cjs");
+//#region src/bin.ts
+require_server.startServer().then(({ close }) => {
+	let stopping = false;
+	const shutdown = () => {
+		if (stopping) return;
+		stopping = true;
+		close().then(() => process.exit(0), () => process.exit(1));
+	};
+	process.once("SIGINT", shutdown);
+	process.once("SIGTERM", shutdown);
+}).catch((error) => {
+	process.stderr.write(`[ERROR] connectwise-automate-mcp startup: ${require_server.safeError(error).code}\n`);
+	process.exitCode = 1;
+});
+//#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,18 @@
+#!/usr/bin/env node
+import { a as startServer, s as safeError } from "./server2.js";
+//#region src/bin.ts
+startServer().then(({ close }) => {
+	let stopping = false;
+	const shutdown = () => {
+		if (stopping) return;
+		stopping = true;
+		close().then(() => process.exit(0), () => process.exit(1));
+	};
+	process.once("SIGINT", shutdown);
+	process.once("SIGTERM", shutdown);
+}).catch((error) => {
+	process.stderr.write(`[ERROR] connectwise-automate-mcp startup: ${safeError(error).code}\n`);
+	process.exitCode = 1;
+});
+//#endregion
+export {};

package/dist/server.cjs

@@ -0,0 +1,8 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_server = require("./server2.cjs");
+exports.AutomateClient = require_server.AutomateClient;
+exports.AutomateRuntime = require_server.AutomateRuntime;
+exports.SERVER_NAME = require_server.SERVER_NAME;
+exports.SERVER_VERSION = require_server.SERVER_VERSION;
+exports.createServer = require_server.createServer;
+exports.startServer = require_server.startServer;

package/dist/server.d.cts

@@ -0,0 +1,95 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+
+//#region src/boundary.d.ts
+
+interface AutomateCredentials {
+  serverUrl: string;
+  username: string;
+  password: string;
+  clientId: string;
+}
+interface Address {
+  address: string;
+  family: number;
+}
+type Resolver = (hostname: string) => Promise<Address[]>;
+interface HttpRequest {
+  url: URL;
+  address: Address;
+  method: "GET" | "POST";
+  headers: Record<string, string>;
+  body?: string;
+  signal: AbortSignal;
+}
+interface HttpResponse {
+  status: number;
+  body: string;
+}
+type Transport$1 = (request: HttpRequest) => Promise<HttpResponse>;
+/** TLS validates the original hostname while lookup pins the checked public IP. */
+//#endregion
+//#region src/client.d.ts
+declare const LIST_RESOURCES: readonly ["clients", "locations", "computers", "scripts", "monitor_history", "internal_monitor_results"];
+type ListResource = (typeof LIST_RESOURCES)[number];
+interface ListOptions {
+  page?: number;
+  pageSize?: number;
+  condition?: string;
+}
+interface ClientOptions {
+  resolve?: Resolver;
+  transport?: Transport$1;
+  now?: () => number;
+  timeoutMs?: number;
+}
+declare class AutomateClient {
+  private readonly credentials;
+  private readonly resolve;
+  private readonly transport;
+  private readonly now;
+  private readonly timeoutMs;
+  private token;
+  private tokenRequest;
+  constructor(credentials: AutomateCredentials, options?: ClientOptions);
+  list(resource: ListResource, options?: ListOptions): Promise<unknown>;
+  listComputer(resource: "monitors" | "script_history", computerId: number, options?: ListOptions): Promise<unknown>;
+  checkConnection(): Promise<{
+    connected: true;
+  }>;
+  private readList;
+  private getToken;
+  private acquireToken;
+  private mintToken;
+  private request;
+}
+//#endregion
+//#region src/server.d.ts
+declare const SERVER_NAME = "connectwise-automate-mcp";
+declare const SERVER_VERSION: string;
+/** Raw responses remain unknown until the runtime validates their authority. */
+interface ConnectionSource {
+  getConnectProviderAccounts(provider: string): Promise<unknown>;
+  getConnectionCredentials(connectionId: string): Promise<unknown>;
+}
+declare class AutomateRuntime {
+  private readonly source;
+  private readonly options;
+  private readonly clients;
+  constructor(source: ConnectionSource, options?: ClientOptions);
+  listConnections(): Promise<unknown>;
+  getClient(selector: string): Promise<AutomateClient>;
+  clear(): void;
+}
+declare function createServer(source: ConnectionSource, options?: ClientOptions & {
+  emit?: (line: string) => void;
+}): {
+  server: McpServer;
+  runtime: AutomateRuntime;
+};
+declare function startServer(source?: ConnectionSource, transport?: Transport): Promise<{
+  server: McpServer;
+  close: () => Promise<void>;
+}>;
+//#endregion
+export { AutomateClient, type AutomateCredentials, AutomateRuntime, type ClientOptions, ConnectionSource, type ListOptions, type ListResource, SERVER_NAME, SERVER_VERSION, createServer, startServer };

package/dist/server.d.ts

@@ -0,0 +1,95 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+
+//#region src/boundary.d.ts
+
+interface AutomateCredentials {
+  serverUrl: string;
+  username: string;
+  password: string;
+  clientId: string;
+}
+interface Address {
+  address: string;
+  family: number;
+}
+type Resolver = (hostname: string) => Promise<Address[]>;
+interface HttpRequest {
+  url: URL;
+  address: Address;
+  method: "GET" | "POST";
+  headers: Record<string, string>;
+  body?: string;
+  signal: AbortSignal;
+}
+interface HttpResponse {
+  status: number;
+  body: string;
+}
+type Transport$1 = (request: HttpRequest) => Promise<HttpResponse>;
+/** TLS validates the original hostname while lookup pins the checked public IP. */
+//#endregion
+//#region src/client.d.ts
+declare const LIST_RESOURCES: readonly ["clients", "locations", "computers", "scripts", "monitor_history", "internal_monitor_results"];
+type ListResource = (typeof LIST_RESOURCES)[number];
+interface ListOptions {
+  page?: number;
+  pageSize?: number;
+  condition?: string;
+}
+interface ClientOptions {
+  resolve?: Resolver;
+  transport?: Transport$1;
+  now?: () => number;
+  timeoutMs?: number;
+}
+declare class AutomateClient {
+  private readonly credentials;
+  private readonly resolve;
+  private readonly transport;
+  private readonly now;
+  private readonly timeoutMs;
+  private token;
+  private tokenRequest;
+  constructor(credentials: AutomateCredentials, options?: ClientOptions);
+  list(resource: ListResource, options?: ListOptions): Promise<unknown>;
+  listComputer(resource: "monitors" | "script_history", computerId: number, options?: ListOptions): Promise<unknown>;
+  checkConnection(): Promise<{
+    connected: true;
+  }>;
+  private readList;
+  private getToken;
+  private acquireToken;
+  private mintToken;
+  private request;
+}
+//#endregion
+//#region src/server.d.ts
+declare const SERVER_NAME = "connectwise-automate-mcp";
+declare const SERVER_VERSION: string;
+/** Raw responses remain unknown until the runtime validates their authority. */
+interface ConnectionSource {
+  getConnectProviderAccounts(provider: string): Promise<unknown>;
+  getConnectionCredentials(connectionId: string): Promise<unknown>;
+}
+declare class AutomateRuntime {
+  private readonly source;
+  private readonly options;
+  private readonly clients;
+  constructor(source: ConnectionSource, options?: ClientOptions);
+  listConnections(): Promise<unknown>;
+  getClient(selector: string): Promise<AutomateClient>;
+  clear(): void;
+}
+declare function createServer(source: ConnectionSource, options?: ClientOptions & {
+  emit?: (line: string) => void;
+}): {
+  server: McpServer;
+  runtime: AutomateRuntime;
+};
+declare function startServer(source?: ConnectionSource, transport?: Transport): Promise<{
+  server: McpServer;
+  close: () => Promise<void>;
+}>;
+//#endregion
+export { AutomateClient, type AutomateCredentials, AutomateRuntime, type ClientOptions, ConnectionSource, type ListOptions, type ListResource, SERVER_NAME, SERVER_VERSION, createServer, startServer };

package/dist/server.js

@@ -0,0 +1,2 @@
+import { a as startServer, i as createServer, n as SERVER_NAME, o as AutomateClient, r as SERVER_VERSION, t as AutomateRuntime } from "./server2.js";
+export { AutomateClient, AutomateRuntime, SERVER_NAME, SERVER_VERSION, createServer, startServer };