@lightsage/mcp 0.1.7

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

@@ -0,0 +1,225 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import express from "express";
+import { LocalContext } from "../../cli.js";
+import {
+  ConsoleLoggerLevel,
+  createConsoleLogger,
+} from "../../console-logger.js";
+import {
+  MCPServerFlags,
+  resolveMCPServerAPIKey,
+} from "../../flags.js";
+import { createMCPServer } from "../../server.js";
+import { buildAnnotationFilter } from "../../tools.js";
+
+import { landingPageExpress } from "../../../landing-page.js";
+
+interface StartCommandFlags extends MCPServerFlags {
+  readonly transport: "stdio" | "sse";
+  readonly port: number;
+  readonly "log-level": ConsoleLoggerLevel;
+  readonly env?: [string, string][];
+}
+
+interface Session {
+  mcpServer: ReturnType<typeof createMCPServer>["server"];
+  transport: SSEServerTransport;
+  cleanup: () => Promise<void>;
+}
+
+export function toWebHeaders(
+  incoming: Record<string, string | string[] | undefined>,
+): Headers {
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(incoming)) {
+    if (Array.isArray(value)) {
+      for (const item of value) headers.append(key, item);
+    } else if (value !== undefined) {
+      headers.set(key, value);
+    }
+  }
+  return headers;
+}
+
+export async function main(this: LocalContext, flags: StartCommandFlags) {
+  flags.env?.forEach(([key, value]) => {
+    process.env[key] = value;
+  });
+
+  switch (flags.transport) {
+    case "stdio":
+      await startStdio(flags);
+      break;
+    case "sse":
+      await startSSE(flags);
+      break;
+    default:
+      throw new Error(`Invalid transport: ${flags.transport}`);
+  }
+}
+
+async function startStdio(flags: StartCommandFlags) {
+  const logger = createConsoleLogger(flags["log-level"]);
+  const transport = new StdioServerTransport();
+  const { server } = createMCPServer({
+    logger,
+    allowedTools: flags.tool,
+    dynamic: flags.mode === "dynamic",
+    annotationFilter: buildAnnotationFilter(flags["tool-annotations"]),
+    security: { LightsageApiKeyAuth: resolveMCPServerAPIKey(flags) ?? "" },
+    serverURL: flags["server-url"],
+    serverIdx: flags["server-index"],
+  });
+  await server.connect(transport);
+
+  const abort = async () => {
+    await server.close();
+    process.exit(0);
+  };
+  process.on("SIGTERM", abort);
+  process.on("SIGINT", abort);
+}
+
+async function startSSE(cliFlags: StartCommandFlags) {
+  const logger = createConsoleLogger(cliFlags["log-level"]);
+  const app = express();
+  const sessions = new Map<string, Session>();
+  const controller = new AbortController();
+
+  app.get("/sse", async (req, res) => {
+    const sessionId = crypto.randomUUID();
+
+    logger.info("SSE connection initiated", {
+      sessionId,
+      userAgent: req.headers["user-agent"],
+    });
+
+    // Track early disconnection
+    let connectionClosed = false;
+    res.on("close", () => {
+      if (!connectionClosed) {
+        logger.info("Connection closed early", { sessionId });
+      }
+      connectionClosed = true;
+    });
+
+    const requestHeaders = toWebHeaders(req.headers);
+
+    // Merge CLI flags with header overrides for security credentials
+    const flags: StartCommandFlags = {
+      ...cliFlags,
+      // Security fields can be overridden via headers
+      "lightsage-api-key-auth": resolveMCPServerAPIKey(
+        cliFlags,
+        requestHeaders,
+      ),
+    };
+
+    // Create a new MCP server for this connection with its auth
+    const { server: mcpServer } = createMCPServer({
+      logger,
+      allowedTools: flags.tool,
+      dynamic: flags.mode === "dynamic",
+      annotationFilter: buildAnnotationFilter(flags["tool-annotations"]),
+      security: { LightsageApiKeyAuth: resolveMCPServerAPIKey(flags) ?? "" },
+      serverURL: flags["server-url"],
+      serverIdx: flags["server-index"],
+    });
+
+    // Message path includes session ID for routing
+    const transport = new SSEServerTransport(`/message/${sessionId}`, res);
+
+    const cleanup = async () => {
+      await mcpServer.close();
+    };
+
+    sessions.set(sessionId, { mcpServer, transport, cleanup });
+    logger.info("Session created", { sessionId, totalSessions: sessions.size });
+    controller.signal.addEventListener("abort", cleanup);
+
+    // Log server-side errors for debugging (e.g. tools/list handler failures)
+    mcpServer.server.onerror = (error) => {
+      logger.error("MCP protocol error", {
+        sessionId,
+        error: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+      });
+    };
+
+    // Wrap transport.send to log error responses for debugging
+    const originalSend = transport.send.bind(transport);
+    transport.send = async (message) => {
+      if ("error" in message && message.error) {
+        logger.error("MCP sending error response", {
+          sessionId,
+          id: message.id,
+          errorCode: message.error.code,
+          errorMessage: message.error.message,
+        });
+      }
+      return originalSend(message);
+    };
+
+    await mcpServer.connect(transport);
+
+    mcpServer.server.onclose = async () => {
+      connectionClosed = true;
+      controller.signal.removeEventListener("abort", cleanup);
+      sessions.delete(sessionId);
+      logger.info("Session closed", {
+        sessionId,
+        totalSessions: sessions.size,
+      });
+      res.end();
+    };
+  });
+
+  app.post("/message/:sessionId", async (req, res) => {
+    const session = sessions.get(req.params.sessionId);
+    if (!session) {
+      res.status(404).send("Session not found");
+      return;
+    }
+
+    await session.transport.handlePostMessage(req, res);
+  });
+
+  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 HTTP server started", { host });
+  });
+
+  let closing = false;
+  controller.signal.addEventListener("abort", async () => {
+    if (closing) {
+      logger.info("Received second signal. Forcing shutdown.");
+      process.exit(1);
+    }
+    closing = true;
+
+    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);
+    });
+  });
+
+  const abort = () => controller.abort();
+  process.on("SIGTERM", abort);
+  process.on("SIGINT", abort);
+}

package/src/mcp-server/cli.ts

@@ -0,0 +1,13 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { CommandContext, StricliProcess } from "@stricli/core";
+
+export interface LocalContext extends CommandContext {
+  readonly process: StricliProcess;
+}
+
+export function buildContext(process: NodeJS.Process): LocalContext {
+  return { process: process as StricliProcess };
+}

package/src/mcp-server/console-logger.ts

@@ -0,0 +1,76 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+export const consoleLoggerLevels = [
+  "debug",
+  "warning",
+  "info",
+  "error",
+] as const;
+
+export type ConsoleLoggerLevel = (typeof consoleLoggerLevels)[number];
+
+export type ConsoleLogger =
+  & {
+    [key in ConsoleLoggerLevel]: (
+      message: string,
+      data?: Record<string, unknown>,
+    ) => void;
+  }
+  & {
+    level: ConsoleLoggerLevel;
+  };
+
+export function createConsoleLogger(level: ConsoleLoggerLevel): ConsoleLogger {
+  const min = consoleLoggerLevels.indexOf(level);
+  const noop = () => {};
+
+  const logger: ConsoleLogger = {
+    debug: noop,
+    warning: noop,
+    info: noop,
+    error: noop,
+    level,
+  };
+
+  return consoleLoggerLevels.reduce((logger, level, i) => {
+    if (i < min) {
+      return logger;
+    }
+
+    logger[level] = log.bind(null, level);
+
+    return logger;
+  }, logger);
+}
+
+function log(
+  level: ConsoleLoggerLevel,
+  message: string,
+  data?: Record<string, unknown>,
+) {
+  let line = "";
+  const allData = [{ msg: message, l: level }, data];
+
+  for (const ctx of allData) {
+    for (const [key, value] of Object.entries(ctx || {})) {
+      if (value == null) {
+        line += ` ${key}=<${value}>`;
+      } else if (typeof value === "function") {
+        line += ` ${key}=<function>`;
+      } else if (typeof value === "symbol") {
+        line += ` ${key}=${value.toString()}`;
+      } else if (typeof value === "string") {
+        const v = value.search(/\s/g) >= 0 ? JSON.stringify(value) : value;
+        line += ` ${key}=${v}`;
+      } else if (typeof value !== "object") {
+        line += ` ${key}=${value}`;
+      } else {
+        line += ` ${key}="${JSON.stringify(value)}"`;
+      }
+    }
+  }
+
+  console.error(line);
+}

package/src/mcp-server/extensions.ts

@@ -0,0 +1,19 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { ZodRawShapeCompat } from "@modelcontextprotocol/sdk/server/zod-compat.js";
+import { PromptDefinition } from "./prompts.js";
+import { ResourceDefinition, ResourceTemplateDefinition } from "./resources.js";
+import { ToolDefinition } from "./tools.js";
+
+export type Register = {
+  tool: <A extends ZodRawShapeCompat | undefined>(
+    def: ToolDefinition<A>,
+  ) => void;
+  resource: (def: ResourceDefinition) => void;
+  resourceTemplate: (def: ResourceTemplateDefinition) => void;
+  prompt: <A extends ZodRawShapeCompat | undefined>(
+    prompt: PromptDefinition<A>,
+  ) => void;
+};

package/src/mcp-server/flags.ts

@@ -0,0 +1,32 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { SDKOptions } from "../lib/config.js";
+
+/**
+ * Base flags interface for MCP server configuration.
+ * Used by both CLI start command and Gram deployment wrapper.
+ */
+export interface MCPServerFlags {
+  readonly tool?: string[];
+  readonly mode?: "dynamic" | undefined;
+  readonly "tool-annotations"?: string[] | undefined;
+  readonly "lightsage-api-key-auth"?: string | undefined;
+  readonly "server-url"?: string | undefined;
+  readonly "server-index"?: SDKOptions["serverIdx"];
+}
+
+export function resolveMCPServerAPIKey(
+  flags: MCPServerFlags,
+  headers?: Headers,
+  allowStaticAuth = true,
+): string | undefined {
+  const requestKey = headers?.get("lightsage-api-key-auth");
+  if (requestKey) return requestKey;
+  if (!allowStaticAuth) return undefined;
+
+  return flags["lightsage-api-key-auth"]
+    ?? process.env["LIGHTSAGE_LIGHTSAGE_API_KEY_AUTH"]
+    ?? process.env["LIGHTSAGE_API_KEY"];
+}

package/src/mcp-server/mcp-server.ts

@@ -0,0 +1,28 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { buildApplication, buildRouteMap, run } from "@stricli/core";
+import process from "node:process";
+import { buildContext } from "./cli.js";
+import { serveCommand } from "./cli/serve/command.js";
+import { startCommand } from "./cli/start/command.js";
+
+const routes = buildRouteMap({
+  routes: {
+    start: startCommand,
+    serve: serveCommand,
+  },
+  docs: {
+    brief: "MCP server CLI",
+  },
+});
+
+export const app = buildApplication(routes, {
+  name: "mcp",
+  versionInfo: {
+    currentVersion: "0.1.7",
+  },
+});
+
+run(app, process.argv.slice(2), buildContext(process));

package/src/mcp-server/prompts.ts

@@ -0,0 +1,111 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  ShapeOutput,
+  ZodRawShapeCompat,
+} from "@modelcontextprotocol/sdk/server/zod-compat.js";
+import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import {
+  GetPromptResult,
+  ServerNotification,
+  ServerRequest,
+} from "@modelcontextprotocol/sdk/types.js";
+import { LightsageMcpCore } from "../core.js";
+import { ConsoleLogger } from "./console-logger.js";
+import { MCPScope } from "./scopes.js";
+
+export type PromptDefinition<
+  Args extends undefined | ZodRawShapeCompat = undefined,
+> = Args extends ZodRawShapeCompat ? {
+    name: string;
+    description?: string;
+    scopes?: MCPScope[];
+    args: Args;
+    prompt: (
+      client: LightsageMcpCore,
+      args: ShapeOutput<Args>,
+      extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+    ) => GetPromptResult | Promise<GetPromptResult>;
+  }
+  : {
+    name: string;
+    description?: string;
+    scopes?: MCPScope[];
+    args?: undefined;
+    prompt: (
+      client: LightsageMcpCore,
+      extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+    ) => GetPromptResult | Promise<GetPromptResult>;
+  };
+
+// Optional function to assist with formatting prompt results
+export async function formatResult(value: string): Promise<GetPromptResult> {
+  return {
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: value,
+        },
+      },
+    ],
+  };
+}
+
+export function createRegisterPrompt(
+  logger: ConsoleLogger,
+  server: McpServer,
+  getSDK: () => LightsageMcpCore,
+  allowedScopes: Set<MCPScope>,
+): <A extends ZodRawShapeCompat | undefined>(
+  prompt: PromptDefinition<A>,
+) => void {
+  return <A extends ZodRawShapeCompat | undefined>(
+    prompt: PromptDefinition<A>,
+  ): void => {
+    const scopes = prompt.scopes ?? [];
+    if (allowedScopes.size > 0 && scopes.length === 0) {
+      return;
+    }
+
+    if (
+      allowedScopes.size > 0
+      && !scopes.every((s: MCPScope) => allowedScopes.has(s))
+    ) {
+      return;
+    }
+
+    if (prompt.args) {
+      if (prompt.description) {
+        server.prompt(
+          prompt.name,
+          prompt.description,
+          prompt.args,
+          async (args, ctx) => prompt.prompt(getSDK(), args, ctx),
+        );
+      } else {
+        server.prompt(
+          prompt.name,
+          prompt.args,
+          async (args, ctx) => prompt.prompt(getSDK(), args, ctx),
+        );
+      }
+    } else {
+      if (prompt.description) {
+        server.prompt(
+          prompt.name,
+          prompt.description,
+          async (ctx) => prompt.prompt(getSDK(), ctx),
+        );
+      } else {
+        server.prompt(prompt.name, async (ctx) => prompt.prompt(getSDK(), ctx));
+      }
+    }
+
+    logger.debug("Registered prompt", { name: prompt.name });
+  };
+}

package/src/mcp-server/resources.ts

@@ -0,0 +1,141 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import {
+  McpServer,
+  ResourceMetadata,
+  ResourceTemplate,
+} from "@modelcontextprotocol/sdk/server/mcp.js";
+import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import { Variables } from "@modelcontextprotocol/sdk/shared/uriTemplate.js";
+import {
+  ReadResourceResult,
+  ServerNotification,
+  ServerRequest,
+} from "@modelcontextprotocol/sdk/types.js";
+import { LightsageMcpCore } from "../core.js";
+import { ConsoleLogger } from "./console-logger.js";
+import { MCPScope } from "./scopes.js";
+import { valueToBase64 } from "./shared.js";
+
+export type ReadResourceCallback = (
+  client: LightsageMcpCore,
+  uri: URL,
+  extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+) => ReadResourceResult | Promise<ReadResourceResult>;
+
+export type ResourceDefinition = {
+  name: string;
+  description?: string;
+  metadata?: ResourceMetadata;
+  scopes?: MCPScope[];
+  resource: string;
+  read: ReadResourceCallback;
+};
+
+export type ReadResourceTemplateCallback = (
+  client: LightsageMcpCore,
+  uri: URL,
+  vars: Variables,
+  extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+) => ReadResourceResult | Promise<ReadResourceResult>;
+
+export type ResourceTemplateDefinition = {
+  name: string;
+  description: string;
+  metadata?: ResourceMetadata;
+  scopes?: MCPScope[];
+  resource: ResourceTemplate;
+  read: ReadResourceTemplateCallback;
+};
+
+// Optional function to assist with formatting tool results
+export async function formatResult(
+  response: Response,
+  uri: URL,
+  init?: { mimeType?: string | undefined },
+): Promise<ReadResourceResult> {
+  let contents: ReadResourceResult["contents"] = [];
+  const mimeType = init?.mimeType ?? response.headers.get("content-type") ?? "";
+
+  if (mimeType.startsWith("image/") || mimeType.startsWith("audio/")) {
+    const blob = await valueToBase64(await response.arrayBuffer());
+    contents = blob == null ? [] : [{ uri: uri.toString(), blob, mimeType }];
+  } else {
+    const text = await response.text();
+    contents = [{ uri: uri.toString(), mimeType, text }];
+  }
+
+  return { contents };
+}
+
+export function createRegisterResource(
+  logger: ConsoleLogger,
+  server: McpServer,
+  getSDK: () => LightsageMcpCore,
+  allowedScopes: Set<MCPScope>,
+): (resource: ResourceDefinition) => void {
+  return (resource: ResourceDefinition): void => {
+    const scopes = resource.scopes ?? [];
+    if (allowedScopes.size > 0 && scopes.length === 0) {
+      return;
+    }
+
+    if (
+      allowedScopes.size > 0
+      && !scopes.every((s: MCPScope) => allowedScopes.has(s))
+    ) {
+      return;
+    }
+
+    const metadata: ResourceMetadata = {
+      ...resource.metadata,
+      description: resource.description,
+    };
+
+    server.resource(
+      resource.name,
+      resource.resource,
+      metadata,
+      async (uri, ctx) => resource.read(getSDK(), uri, ctx),
+    );
+
+    logger.debug("Registered resource", { name: resource.name });
+  };
+}
+
+export function createRegisterResourceTemplate(
+  logger: ConsoleLogger,
+  server: McpServer,
+  getSDK: () => LightsageMcpCore,
+  allowedScopes: Set<MCPScope>,
+): (resource: ResourceTemplateDefinition) => void {
+  return (resource: ResourceTemplateDefinition): void => {
+    const scopes = resource.scopes ?? [];
+    if (allowedScopes.size > 0 && scopes.length === 0) {
+      return;
+    }
+
+    if (
+      allowedScopes.size > 0
+      && !scopes.every((s: MCPScope) => allowedScopes.has(s))
+    ) {
+      return;
+    }
+
+    const metadata: ResourceMetadata = {
+      ...resource.metadata,
+      description: resource.description,
+    };
+
+    server.resource(
+      resource.name,
+      resource.resource,
+      metadata,
+      async (uri, vars, ctx) => resource.read(getSDK(), uri, vars, ctx),
+    );
+
+    logger.debug("Registered resource template", { name: resource.name });
+  };
+}

package/src/mcp-server/scopes.ts

@@ -0,0 +1,7 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+export const mcpScopes = [] as const;
+
+export type MCPScope = (typeof mcpScopes)[number];