shireautomations 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,103 @@
-# Temporary Holding Version
+# Shire Automations CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `shire` CLI and its MCP mode give agents and people access to Shire Automations' public catalog and workflow planning tools.
+
+## Install
+
+Install the CLI:
+
+```sh
+npm install --global shireautomations
+shire --help
+```
+
+Or run a command without a global install:
+
+```sh
+npx --yes shireautomations tools
+```
+
+## JavaScript SDK
+
+Install the package in a Node.js 20 or later project:
+
+```sh
+npm install shireautomations
+```
+
+Use the client to read the catalog and run a planning tool:
+
+```js
+import { ShireAutomationsClient } from "shireautomations";
+
+const shire = new ShireAutomationsClient();
+const catalog = await shire.getCatalog();
+const tools = await shire.listTools();
+const result = await shire.plan("workflow-mapper", {
+  workflowName: "New client onboarding",
+  trigger: "A new client signs an agreement",
+  outcome: "The client is ready for kickoff",
+  steps: [
+    { name: "Collect intake", kind: "task" },
+    { name: "Review requirements", kind: "task" },
+    { name: "Schedule kickoff", kind: "handoff" },
+  ],
+});
+```
+
+The client uses the public API by default. Pass `baseUrl` to use a compatible API origin or
+`fetchImpl` to provide a custom fetch implementation. No account, API key, or payment method is
+required. Results are planning estimates, not forecasts or guaranteed outcomes.
+
+To run from a source checkout before publication:
+
+```sh
+npm install --prefix cli
+node cli/bin/shire.js tools
+```
+
+## Commands
+
+```sh
+shire services
+shire pricing
+shire tools
+shire catalog
+shire plan workflow-mapper --input workflow.json
+cat workflow.json | shire plan workflow-mapper --input -
+```
+
+Planning commands accept JSON and print JSON. The workflow mapper returns an editable SOP draft. Other tools score an automation opportunity, assess AI readiness, plan an integration, build an onboarding checklist, or estimate workload and ROI.
+
+Set `SHIRE_API_URL` to an alternate API origin for development. The default is `https://shireautomations.com`.
+
+## MCP server
+
+The package also runs a local stdio MCP server:
+
+```sh
+shire mcp
+```
+
+Example client configuration:
+
+```json
+{
+  "mcpServers": {
+    "shireautomations": {
+      "command": "shire",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+The server exposes `shire_catalog`, `shire_list_planning_tools`, and `shire_plan`. It calls the same versioned API as the CLI. It does not ask for API credentials, submit intake forms, or start paid work.
+
+## API and privacy
+
+See the [API and developer resources](https://shireautomations.com/developers), [JavaScript SDK guide](https://shireautomations.com/sdk), [OpenAPI specification](https://shireautomations.com/openapi.json), or [Postman collection](https://shireautomations.com/postman-collection.json). The API does not save synchronous planning requests. Do not send credentials or sensitive customer, patient, or financial-account data. Estimates depend on the input values and are not forecasts or guarantees.
+
+## About Shire Automations
+
+Shire Automations is a Houston-based business automation and software studio. We connect workflows and build AI agents, apps, and dashboards for small and midsize businesses. Learn more at [shireautomations.com](https://shireautomations.com).

package/bin/shire.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import { stdin, stdout, stderr } from "node:process";
+import { fetchShireJson } from "../src/client.js";
+
+const HELP = `Shire Automations CLI
+
+Usage:
+  shire catalog
+  shire services
+  shire pricing
+  shire tools
+  shire plan <tool> --input <file|->
+  shire mcp
+
+Planning results are estimates from your inputs. Requests are not saved by the API.
+Set SHIRE_API_URL to use another Shire-compatible API origin.`;
+
+function print(value) {
+  stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+async function readStdin() {
+  let value = "";
+  for await (const chunk of stdin) value += chunk;
+  return value;
+}
+
+async function readInput(args) {
+  const index = args.indexOf("--input");
+  if (index === -1 || !args[index + 1]) throw new Error("Pass --input <file|-> with a JSON object.");
+  const raw = args[index + 1] === "-" ? await readStdin() : await readFile(args[index + 1], "utf8");
+  const value = JSON.parse(raw);
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("The planning input must be a JSON object.");
+  }
+  return value;
+}
+
+async function main() {
+  const [command, ...args] = process.argv.slice(2);
+
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    stdout.write(`${HELP}\n`);
+    return;
+  }
+
+  if (command === "mcp") {
+    await import("../src/mcp.js");
+    return;
+  }
+
+  if (command === "catalog") {
+    print(await fetchShireJson("/api/v1/catalog"));
+    return;
+  }
+
+  if (command === "services" || command === "pricing") {
+    const catalog = await fetchShireJson("/api/v1/catalog");
+    print(command === "services" ? catalog.services : { pricing: catalog.pricing, note: catalog.pricingNote });
+    return;
+  }
+
+  if (command === "tools") {
+    print(await fetchShireJson("/api/v1/tools"));
+    return;
+  }
+
+  if (command === "plan") {
+    const slug = args[0];
+    if (!slug) throw new Error("Pass the planning tool name after plan.");
+    const input = await readInput(args.slice(1));
+    print(await fetchShireJson(`/api/v1/tools/${encodeURIComponent(slug)}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ input }),
+    }));
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}\n\n${HELP}`);
+}
+
+main().catch((error) => {
+  stderr.write(`${error instanceof Error ? error.message : "Shire request failed."}\n`);
+  process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "shireautomations",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "license": "UNLICENSED",
+  "description": "JavaScript SDK, CLI, and MCP server for the Shire Automations public API, built by a Houston-based business automation studio.",
+  "type": "module",
+  "engines": { "node": ">=20" },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "types": "./src/index.d.ts",
+  "bin": {
+    "shire": "bin/shire.js"
+  },
+  "files": ["bin", "src", "README.md", "server.json"],
+  "keywords": ["shire-automations", "workflow-automation", "business-planning", "sdk", "api-client", "mcp", "cli"],
+  "homepage": "https://shireautomations.com/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/praisondani/shireautomations-cli.git"
+  },
+  "bugs": { "url": "https://github.com/praisondani/shireautomations-cli/issues" },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.3.1",
+    "zod": "^4.6.7"
+  }
+}

package/server.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.praisondani/shireautomations-cli",
+  "title": "Shire Automations",
+  "description": "Read Shire Automations services and published prices, and run stateless workflow planning tools through a local MCP server.",
+  "websiteUrl": "https://shireautomations.com/developers",
+  "repository": {
+    "url": "https://github.com/praisondani/shireautomations-cli",
+    "source": "github"
+  },
+  "version": "0.1.1",
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "shireautomations",
+      "version": "0.1.1",
+      "runtimeHint": "npx",
+      "transport": { "type": "stdio" },
+      "packageArguments": [{ "type": "positional", "value": "mcp" }]
+    }
+  ]
+}

package/src/client.js

@@ -0,0 +1,9 @@
+import { ShireAutomationsClient } from "./index.js";
+
+const client = new ShireAutomationsClient({
+  baseUrl: process.env.SHIRE_API_URL || "https://shireautomations.com",
+});
+
+export async function fetchShireJson(path, options = {}) {
+  return client.request(path, options);
+}

package/src/index.d.ts

@@ -0,0 +1,102 @@
+export interface ShireAutomationsClientOptions {
+  /** API origin. Defaults to https://shireautomations.com. */
+  baseUrl?: string;
+  /** Fetch-compatible implementation. Defaults to the Node.js global fetch. */
+  fetchImpl?: typeof fetch;
+  /** Request timeout in milliseconds. Defaults to 15000. */
+  timeoutMs?: number;
+}
+
+export interface ShireService {
+  name: string;
+  path: string;
+  url: string;
+}
+
+export interface ShirePrice {
+  id: string;
+  title: string;
+  priceLabel: string;
+  scope: string;
+  description: string;
+  price?: number;
+  minPrice?: number;
+  maxPrice?: number;
+  unitText?: string;
+}
+
+export interface ShireCatalog {
+  name: string;
+  description: string;
+  version: string;
+  website: string;
+  developerResources: string;
+  contact: string;
+  services: ShireService[];
+  pricing: ShirePrice[];
+  pricingNote: string;
+  planningTools: ShirePlanningTool[];
+  [key: string]: unknown;
+}
+
+export interface ShirePlanningTool {
+  id: string;
+  name: string;
+  description: string;
+  path: string;
+  endpoint: string;
+  method: "POST";
+}
+
+export interface ShireToolList {
+  version: "1";
+  tools: ShirePlanningTool[];
+  pagination: {
+    limit: number;
+    nextCursor: string | null;
+    hasMore: boolean;
+  };
+  openapi: string;
+}
+
+export interface ShirePlanningResult {
+  version: "1";
+  tool: string;
+  result: Record<string, unknown>;
+}
+
+export interface ShireSandboxInfo {
+  mode: "sandbox";
+  description: string;
+  safeguards: Record<string, string>;
+  tools: string[];
+  toolsEndpoint: string;
+  request: Record<string, unknown>;
+}
+
+export interface ShireSandboxResult {
+  version: "1";
+  mode: "sandbox";
+  tool: string;
+  result: Record<string, unknown>;
+}
+
+export class ShireApiError extends Error {
+  status?: number;
+  response?: unknown;
+}
+
+export class ShireAutomationsClient {
+  constructor(options?: ShireAutomationsClientOptions);
+  request<T = unknown>(
+    path: string,
+    options?: { method?: string; headers?: HeadersInit; body?: unknown },
+  ): Promise<T>;
+  getCatalog(): Promise<ShireCatalog>;
+  getServices(): Promise<ShireService[]>;
+  getPricing(): Promise<{ pricing: ShirePrice[]; note: string }>;
+  listTools(): Promise<ShireToolList>;
+  getSandboxInfo(): Promise<ShireSandboxInfo>;
+  plan(toolId: string, input: Record<string, unknown>): Promise<ShirePlanningResult>;
+  runSandbox(toolId: string, input: Record<string, unknown>): Promise<ShireSandboxResult>;
+}

package/src/index.js

@@ -0,0 +1,127 @@
+const DEFAULT_API_URL = "https://shireautomations.com";
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+export class ShireApiError extends Error {
+  constructor(message, { status, response } = {}) {
+    super(message);
+    this.name = "ShireApiError";
+    this.status = status;
+    this.response = response;
+  }
+}
+
+export class ShireAutomationsClient {
+  #apiUrl;
+  #fetch;
+  #timeoutMs;
+
+  constructor({ baseUrl = DEFAULT_API_URL, fetchImpl = globalThis.fetch, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+    let url;
+    try {
+      url = new URL(baseUrl);
+    } catch {
+      throw new TypeError("baseUrl must be a valid HTTP or HTTPS URL.");
+    }
+
+    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password) {
+      throw new TypeError("baseUrl must use HTTP or HTTPS and cannot include credentials.");
+    }
+    if (typeof fetchImpl !== "function") {
+      throw new TypeError("fetchImpl must be a fetch-compatible function.");
+    }
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1) {
+      throw new TypeError("timeoutMs must be a positive integer.");
+    }
+
+    this.#apiUrl = url.origin;
+    this.#fetch = fetchImpl;
+    this.#timeoutMs = timeoutMs;
+  }
+
+  async request(path, { method = "GET", headers, body } = {}) {
+    let url;
+    try {
+      url = new URL(path, this.#apiUrl);
+    } catch {
+      throw new TypeError("path must be a valid URL path.");
+    }
+    if (url.origin !== this.#apiUrl) {
+      throw new TypeError("path must resolve to the configured API origin.");
+    }
+
+    const requestHeaders = new Headers(headers);
+    let requestBody = body;
+    if (body !== undefined && typeof body !== "string") {
+      requestBody = JSON.stringify(body);
+      if (!requestHeaders.has("content-type")) {
+        requestHeaders.set("content-type", "application/json");
+      }
+    }
+
+    const response = await this.#fetch(url, {
+      method,
+      headers: requestHeaders,
+      ...(requestBody === undefined ? {} : { body: requestBody }),
+      signal: AbortSignal.timeout(this.#timeoutMs),
+    });
+
+    let payload;
+    try {
+      payload = await response.json();
+    } catch {
+      throw new ShireApiError(`Shire API returned invalid JSON (HTTP ${response.status}).`, {
+        status: response.status,
+      });
+    }
+
+    if (!response.ok) {
+      const message = typeof payload?.error === "string"
+        ? payload.error
+        : `Shire API request failed (HTTP ${response.status}).`;
+      throw new ShireApiError(message, { status: response.status, response: payload });
+    }
+
+    return payload;
+  }
+
+  getCatalog() {
+    return this.request("/api/v1/catalog");
+  }
+
+  async getServices() {
+    const catalog = await this.getCatalog();
+    return catalog.services;
+  }
+
+  async getPricing() {
+    const catalog = await this.getCatalog();
+    return { pricing: catalog.pricing, note: catalog.pricingNote };
+  }
+
+  listTools() {
+    return this.request("/api/v1/tools");
+  }
+
+  getSandboxInfo() {
+    return this.request("/api/v1/sandbox");
+  }
+
+  plan(toolId, input) {
+    return this.#runTool(`/api/v1/tools/${encodeURIComponent(toolId)}`, toolId, input);
+  }
+
+  runSandbox(toolId, input) {
+    return this.#runTool(`/api/v1/sandbox/tools/${encodeURIComponent(toolId)}`, toolId, input);
+  }
+
+  #runTool(path, toolId, input) {
+    if (typeof toolId !== "string" || !toolId.trim()) {
+      throw new TypeError("toolId must be a non-empty string.");
+    }
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+      throw new TypeError("input must be a JSON object.");
+    }
+
+    return this.request(path, { method: "POST", body: { input } });
+  }
+}

package/src/mcp.js

@@ -0,0 +1,55 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import * as z from "zod/v4";
+import { fetchShireJson } from "./client.js";
+
+const planningToolIds = [
+  "automation-opportunity-scorecard",
+  "workflow-mapper",
+  "lead-response-calculator",
+  "ai-readiness-assessment",
+  "integration-finder",
+  "client-onboarding-builder",
+  "invoice-follow-up-calculator",
+  "roi-calculator",
+];
+
+function createServer() {
+  const server = new McpServer({ name: "shireautomations", version: "0.1.1" });
+
+  server.registerTool("shire_catalog", {
+    description: "Read Shire Automations services, starting prices, and public planning tools. Does not create a quote or start paid work.",
+    inputSchema: z.object({}),
+  }, async () => {
+    const catalog = await fetchShireJson("/api/v1/catalog");
+    return { content: [{ type: "text", text: JSON.stringify(catalog, null, 2) }] };
+  });
+
+  server.registerTool("shire_list_planning_tools", {
+    description: "List the public Shire Automations workflow planning calculators.",
+    inputSchema: z.object({}),
+  }, async () => {
+    const tools = await fetchShireJson("/api/v1/tools");
+    return { content: [{ type: "text", text: JSON.stringify(tools, null, 2) }] };
+  });
+
+  server.registerTool("shire_plan", {
+    description: "Run one stateless Shire workflow planning tool using values you provide. Results are estimates, not forecasts. Do not send credentials or sensitive customer, patient, or financial-account data.",
+    inputSchema: z.object({
+      tool: z.enum(planningToolIds),
+      input: z.record(z.string(), z.unknown()),
+    }),
+  }, async ({ tool, input }) => {
+    const result = await fetchShireJson(`/api/v1/tools/${encodeURIComponent(tool)}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ input }),
+    });
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  });
+
+  return server;
+}
+
+await serveStdio(createServer);
+console.error("Shire Automations MCP server ready on stdio.");