@lightsage/mcp 0.1.7

package/src/lib/security.ts

@@ -0,0 +1,281 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { Security } from "../models/security.js";
+import { env } from "./env.js";
+
+type OAuth2PasswordFlow = {
+  username: string;
+  password: string;
+  clientID?: string | undefined;
+  clientSecret?: string | undefined;
+  tokenURL: string;
+};
+
+export const SecurityErrorCode = {
+  Incomplete: "incomplete",
+  UnrecognisedSecurityType: "unrecognized_security_type",
+} as const;
+export type SecurityErrorCode =
+  (typeof SecurityErrorCode)[keyof typeof SecurityErrorCode];
+
+export class SecurityError extends Error {
+  public code: SecurityErrorCode;
+
+  constructor(
+    code: SecurityErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.code = code;
+    this.name = "SecurityError";
+  }
+
+  static incomplete(): SecurityError {
+    return new SecurityError(
+      SecurityErrorCode.Incomplete,
+      "Security requirements not met in order to perform the operation",
+    );
+  }
+  static unrecognizedType(type: string): SecurityError {
+    return new SecurityError(
+      SecurityErrorCode.UnrecognisedSecurityType,
+      `Unrecognised security type: ${type}`,
+    );
+  }
+}
+
+export type SecurityState = {
+  basic: { username?: string | undefined; password?: string | undefined };
+  headers: Record<string, string>;
+  queryParams: Record<string, string>;
+  cookies: Record<string, string>;
+  oauth2: ({ type: "password" } & OAuth2PasswordFlow) | { type: "none" };
+};
+
+type SecurityInputBasic = {
+  type: "http:basic";
+  value:
+    | { username?: string | undefined; password?: string | undefined }
+    | null
+    | undefined;
+};
+
+type SecurityInputBearer = {
+  type: "http:bearer";
+  value: string | null | undefined;
+  fieldName: string;
+};
+
+type SecurityInputAPIKey = {
+  type: "apiKey:header" | "apiKey:query" | "apiKey:cookie";
+  value: string | null | undefined;
+  fieldName: string;
+};
+
+type SecurityInputOIDC = {
+  type: "openIdConnect";
+  value: string | null | undefined;
+  fieldName: string;
+};
+
+type SecurityInputOAuth2 = {
+  type: "oauth2";
+  value: string | null | undefined;
+  fieldName: string;
+};
+
+type SecurityInputOAuth2ClientCredentials = {
+  type: "oauth2:client_credentials";
+  value:
+    | {
+      clientID?: string | undefined;
+      clientSecret?: string | undefined;
+    }
+    | null
+    | string
+    | undefined;
+  fieldName?: string;
+};
+
+type SecurityInputOAuth2PasswordCredentials = {
+  type: "oauth2:password";
+  value:
+    | string
+    | null
+    | undefined;
+  fieldName?: string;
+};
+
+type SecurityInputCustom = {
+  type: "http:custom";
+  value: any | null | undefined;
+  fieldName?: string;
+};
+
+export type SecurityInput =
+  | SecurityInputBasic
+  | SecurityInputBearer
+  | SecurityInputAPIKey
+  | SecurityInputOAuth2
+  | SecurityInputOAuth2ClientCredentials
+  | SecurityInputOAuth2PasswordCredentials
+  | SecurityInputOIDC
+  | SecurityInputCustom;
+
+export function resolveSecurity(
+  ...options: SecurityInput[][]
+): SecurityState | null {
+  const state: SecurityState = {
+    basic: {},
+    headers: {},
+    queryParams: {},
+    cookies: {},
+    oauth2: { type: "none" },
+  };
+
+  const option = options.find((opts) => {
+    return opts.every((o) => {
+      if (o.value == null) {
+        return false;
+      } else if (o.type === "http:basic") {
+        return o.value.username != null || o.value.password != null;
+      } else if (o.type === "http:custom") {
+        return null;
+      } else if (o.type === "oauth2:password") {
+        return (
+          typeof o.value === "string" && !!o.value
+        );
+      } else if (o.type === "oauth2:client_credentials") {
+        if (typeof o.value == "string") {
+          return !!o.value;
+        }
+        return o.value.clientID != null || o.value.clientSecret != null;
+      } else if (typeof o.value === "string") {
+        return !!o.value;
+      } else {
+        throw new Error(
+          `Unrecognized security type: ${o.type} (value type: ${typeof o
+            .value})`,
+        );
+      }
+    });
+  });
+  if (option == null) {
+    return null;
+  }
+
+  option.forEach((spec) => {
+    if (spec.value == null) {
+      return;
+    }
+
+    const { type } = spec;
+
+    switch (type) {
+      case "apiKey:header":
+        state.headers[spec.fieldName] = spec.value;
+        break;
+      case "apiKey:query":
+        state.queryParams[spec.fieldName] = spec.value;
+        break;
+      case "apiKey:cookie":
+        state.cookies[spec.fieldName] = spec.value;
+        break;
+      case "http:basic":
+        applyBasic(state, spec);
+        break;
+      case "http:custom":
+        break;
+      case "http:bearer":
+        applyBearer(state, spec);
+        break;
+      case "oauth2":
+        applyBearer(state, spec);
+        break;
+      case "oauth2:password":
+        applyBearer(state, spec);
+        break;
+      case "oauth2:client_credentials":
+        break;
+      case "openIdConnect":
+        applyBearer(state, spec);
+        break;
+      default:
+        spec satisfies never;
+        throw SecurityError.unrecognizedType(type);
+    }
+  });
+
+  return state;
+}
+
+function applyBasic(
+  state: SecurityState,
+  spec: SecurityInputBasic,
+) {
+  if (spec.value == null) {
+    return;
+  }
+
+  state.basic = spec.value;
+}
+
+function applyBearer(
+  state: SecurityState,
+  spec:
+    | SecurityInputBearer
+    | SecurityInputOAuth2
+    | SecurityInputOIDC
+    | SecurityInputOAuth2PasswordCredentials,
+) {
+  if (typeof spec.value !== "string" || !spec.value) {
+    return;
+  }
+
+  let value = spec.value;
+  if (value.slice(0, 7).toLowerCase() !== "bearer ") {
+    value = `Bearer ${value}`;
+  }
+
+  if (spec.fieldName !== undefined) {
+    state.headers[spec.fieldName] = value;
+  }
+}
+export function resolveGlobalSecurity(
+  security: Partial<Security> | null | undefined,
+  allowedFields?: number[],
+): SecurityState | null {
+  let inputs: SecurityInput[][] = [
+    [
+      {
+        fieldName: "X-Lightsage-Api-Key",
+        type: "apiKey:header",
+        value: security?.LightsageApiKeyAuth
+          || env().LIGHTSAGE_LIGHTSAGE_API_KEY_AUTH,
+      },
+    ],
+  ];
+
+  if (allowedFields) {
+    inputs = allowedFields.map((i) => {
+      if (i < 0 || i >= inputs.length) {
+        throw new RangeError(`invalid allowedFields index ${i}`);
+      }
+      return inputs[i]!;
+    });
+  }
+
+  return resolveSecurity(...inputs);
+}
+
+export async function extractSecurity<
+  T extends string | Record<string, unknown>,
+>(sec: T | (() => Promise<T>) | undefined): Promise<T | undefined> {
+  if (sec == null) {
+    return;
+  }
+
+  return typeof sec === "function" ? sec() : sec;
+}

package/src/lib/url.ts

@@ -0,0 +1,33 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+const hasOwn = Object.prototype.hasOwnProperty;
+
+export type Params = Partial<Record<string, string | number>>;
+
+export function pathToFunc(
+  pathPattern: string,
+  options?: { charEncoding?: "percent" | "none" },
+): (params?: Params) => string {
+  const paramRE = /\{([a-zA-Z0-9_]+?)\}/g;
+
+  return function buildURLPath(params: Record<string, unknown> = {}): string {
+    return pathPattern.replace(paramRE, function (_, placeholder) {
+      if (!hasOwn.call(params, placeholder)) {
+        throw new Error(`Parameter '${placeholder}' is required`);
+      }
+
+      const value = params[placeholder];
+      if (typeof value !== "string" && typeof value !== "number") {
+        throw new Error(
+          `Parameter '${placeholder}' must be a string or number`,
+        );
+      }
+
+      return options?.charEncoding === "percent"
+        ? encodeURIComponent(`${value}`)
+        : `${value}`;
+    });
+  };
+}

package/src/mcp-server/cli/serve/command.ts

@@ -0,0 +1,108 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { buildCommand } from "@stricli/core";
+import { numberParser } from "@stricli/core";
+import * as z from "zod";
+import { consoleLoggerLevels } from "../../console-logger.js";
+
+export const serveCommand = buildCommand({
+  loader: async () => {
+    const { main } = await import("./impl.js");
+    return main;
+  },
+  parameters: {
+    flags: {
+      port: {
+        kind: "parsed",
+        brief: "The port to listen on for Streamable HTTP connections",
+        default: "2718",
+        parse: (val: string) =>
+          z.coerce.number().int().gte(0).lt(65536).parse(val),
+      },
+      "disable-static-auth": {
+        kind: "boolean",
+        brief:
+          "Disable static authentication, allowing credentials to be passed via request headers only",
+        default: false,
+      },
+      tool: {
+        kind: "parsed",
+        brief: "Specify tools to mount on the server",
+        optional: true,
+        variadic: true,
+        parse: (value) => {
+          return z.string().parse(value);
+        },
+      },
+      mode: {
+        kind: "enum",
+        brief:
+          "Server mode (dynamic: expose list_tools, describe_tool_input, and execute_tool instead of individual tools)",
+        values: ["dynamic"],
+        optional: true,
+      },
+      "tool-annotations": {
+        kind: "parsed",
+        brief:
+          "Filter tools by annotations (comma-separated: readOnly, destructive, idempotent, openWorld). Listed = required true, unlisted = required false.",
+        optional: true,
+        parse: (value) => value.split(",").map(s => s.trim()),
+      },
+      "lightsage-api-key-auth": {
+        kind: "parsed",
+        brief: "Sets the LightsageApiKeyAuth auth field for the API",
+        optional: true,
+        parse: (value) => {
+          return z.string().parse(value);
+        },
+      },
+      "server-url": {
+        kind: "parsed",
+        brief: "Overrides the default server URL used by the SDK",
+        optional: true,
+        parse: (value) => new URL(value).toString(),
+      },
+      "server-index": {
+        kind: "parsed",
+        brief: "Selects a predefined server used by the SDK",
+        optional: true,
+        parse: numberParser,
+      },
+      "log-level": {
+        kind: "enum",
+        brief: "The log level to use for the server",
+        default: "info",
+        values: consoleLoggerLevels,
+      },
+      env: {
+        kind: "parsed",
+        brief: "Environment variables made available to the server",
+        optional: true,
+        variadic: true,
+        parse: (val: string) => {
+          const sepIdx = val.indexOf("=");
+          if (sepIdx === -1) {
+            throw new Error("Invalid environment variable format");
+          }
+
+          const key = val.slice(0, sepIdx);
+          const value = val.slice(sepIdx + 1);
+
+          return [
+            z.string().nonempty({
+              message: "Environment variable key must be a non-empty string",
+            }).parse(key),
+            z.string().nonempty({
+              message: "Environment variable value must be a non-empty string",
+            }).parse(value),
+          ] satisfies [string, string];
+        },
+      },
+    },
+  },
+  docs: {
+    brief: "Run the MCP server with Streamable HTTP transport",
+  },
+});

package/src/mcp-server/cli/serve/impl.ts

@@ -0,0 +1,112 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import express from "express";
+import { LocalContext } from "../../cli.js";
+import {
+  ConsoleLoggerLevel,
+  createConsoleLogger,
+} from "../../console-logger.js";
+import { MCPServerFlags } from "../../flags.js";
+import { createMCPServer } from "../../server.js";
+import { buildAnnotationFilter } from "../../tools.js";
+import { buildSDK } from "../../tools.js";
+
+import { landingPageExpress } from "../../../landing-page.js";
+
+interface ServeCommandFlags extends MCPServerFlags {
+  readonly port: number;
+  readonly "disable-static-auth": boolean;
+  readonly "log-level": ConsoleLoggerLevel;
+  readonly env?: [string, string][];
+}
+
+export async function main(this: LocalContext, flags: ServeCommandFlags) {
+  flags.env?.forEach(([key, value]) => {
+    process.env[key] = value;
+  });
+
+  await startStreamableHTTP(flags);
+}
+
+async function startStreamableHTTP(cliFlags: ServeCommandFlags) {
+  const logger = createConsoleLogger(cliFlags["log-level"]);
+  const app = express();
+
+  // Enable CORS for cross-origin requests
+  app.use((req, res, next) => {
+    res.header("Access-Control-Allow-Origin", "*");
+    res.header("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    res.header("Access-Control-Allow-Headers", "*");
+    if (req.method === "OPTIONS") {
+      res.sendStatus(204);
+      return;
+    }
+    next();
+  });
+
+  app.use(express.json());
+
+  app.post("/mcp", async (req, res) => {
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(req.headers)) {
+      if (Array.isArray(value)) {
+        for (const v of value) headers.append(key, v);
+      } else if (value !== undefined) {
+        headers.set(key, value);
+      }
+    }
+
+    const transport = new StreamableHTTPServerTransport({});
+
+    const { server: mcpServer } = createMCPServer({
+      logger,
+      allowedTools: cliFlags.tool,
+      dynamic: cliFlags.mode === "dynamic",
+      annotationFilter: buildAnnotationFilter(cliFlags["tool-annotations"]),
+      serverURL: cliFlags["server-url"],
+      getSDK: () =>
+        buildSDK(headers, cliFlags, cliFlags["disable-static-auth"], logger),
+      serverIdx: cliFlags["server-index"],
+    });
+
+    mcpServer.server.onerror = (error) => {
+      logger.error("MCP protocol error", {
+        error: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+      });
+    };
+
+    await mcpServer.connect(transport as Transport);
+    await transport.handleRequest(req, res, req.body);
+  });
+
+  app.get("/", landingPageExpress);
+
+  const httpServer = app.listen(cliFlags.port, "0.0.0.0", () => {
+    const ha = httpServer.address();
+    const host = typeof ha === "string" ? ha : `${ha?.address}:${ha?.port}`;
+    logger.info("MCP Streamable HTTP server started", { host });
+  });
+
+  const shutdown = () => {
+    logger.info("Shutting down HTTP server");
+
+    const timer = setTimeout(() => {
+      logger.info("Forcing shutdown");
+      process.exit(1);
+    }, 5000);
+
+    httpServer.close(() => {
+      clearTimeout(timer);
+      logger.info("Graceful shutdown complete");
+      process.exit(0);
+    });
+  };
+
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+}

package/src/mcp-server/cli/start/command.ts

@@ -0,0 +1,108 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { buildCommand } from "@stricli/core";
+import { numberParser } from "@stricli/core";
+import * as z from "zod";
+import { consoleLoggerLevels } from "../../console-logger.js";
+
+export const startCommand = buildCommand({
+  loader: async () => {
+    const { main } = await import("./impl.js");
+    return main;
+  },
+  parameters: {
+    flags: {
+      transport: {
+        kind: "enum",
+        brief: "The transport to use for communicating with the server",
+        default: "stdio",
+        values: ["stdio", "sse"],
+      },
+      port: {
+        kind: "parsed",
+        brief: "The port to use when the SSE transport is enabled",
+        default: "2718",
+        parse: (val: string) =>
+          z.coerce.number().int().gte(0).lt(65536).parse(val),
+      },
+      tool: {
+        kind: "parsed",
+        brief: "Specify tools to mount on the server",
+        optional: true,
+        variadic: true,
+        parse: (value) => {
+          return z.string().parse(value);
+        },
+      },
+      mode: {
+        kind: "enum",
+        brief:
+          "Server mode (dynamic: expose list_tools, describe_tool_input, and execute_tool instead of individual tools)",
+        values: ["dynamic"],
+        optional: true,
+      },
+      "tool-annotations": {
+        kind: "parsed",
+        brief:
+          "Filter tools by annotations (comma-separated: readOnly, destructive, idempotent, openWorld). Listed = required true, unlisted = required false.",
+        optional: true,
+        parse: (value) => value.split(",").map(s => s.trim()),
+      },
+      "lightsage-api-key-auth": {
+        kind: "parsed",
+        brief: "Sets the LightsageApiKeyAuth auth field for the API",
+        optional: true,
+        parse: (value) => {
+          return z.string().parse(value);
+        },
+      },
+      "server-url": {
+        kind: "parsed",
+        brief: "Overrides the default server URL used by the SDK",
+        optional: true,
+        parse: (value) => new URL(value).toString(),
+      },
+      "server-index": {
+        kind: "parsed",
+        brief: "Selects a predefined server used by the SDK",
+        optional: true,
+        parse: numberParser,
+      },
+      "log-level": {
+        kind: "enum",
+        brief: "The log level to use for the server",
+        default: "info",
+        values: consoleLoggerLevels,
+      },
+      env: {
+        kind: "parsed",
+        brief: "Environment variables made available to the server",
+        optional: true,
+        variadic: true,
+        parse: (val: string) => {
+          const sepIdx = val.indexOf("=");
+          if (sepIdx === -1) {
+            throw new Error("Invalid environment variable format");
+          }
+
+          const key = val.slice(0, sepIdx);
+          const value = val.slice(sepIdx + 1);
+
+          return [
+            z.string().nonempty({
+              message: "Environment variable key must be a non-empty string",
+            }).parse(key),
+            z.string().nonempty({
+              message: "Environment variable value must be a non-empty string",
+            }).parse(value),
+          ] satisfies [string, string];
+        },
+      },
+    },
+  },
+  docs: {
+    brief: "Run the Model Context Protocol server",
+  },
+});