@lightsage/mcp 0.1.7

package/README.md

@@ -0,0 +1,264 @@
+# Lightsage MCP
+
+Model Context Protocol (MCP) server for the Lightsage Public API.
+
+[![Built by Speakeasy](https://img.shields.io/badge/Built_by-SPEAKEASY-374151?style=for-the-badge&labelColor=f3f4f6)](https://www.speakeasy.com/?utm_source=lightsage-mcp&utm_campaign=mcp-typescript)
+[![License: MIT](https://img.shields.io/badge/LICENSE_//_MIT-3b5bdb?style=for-the-badge&labelColor=eff6ff)](https://opensource.org/licenses/MIT)
+
+
+<br /><br />
+<!-- Start Summary [summary] -->
+## Summary
+
+Lightsage Public API: Public API for Lightsage CLI and external integrations.
+<!-- End Summary [summary] -->
+
+<!-- Start Table of Contents [toc] -->
+## Table of Contents
+<!-- $toc-max-depth=2 -->
+* [Lightsage MCP](#lightsage-mcp)
+  * [Installation](#installation)
+  * [Progressive Discovery](#progressive-discovery)
+  * [Development](#development)
+  * [Publishing to Anthropic MCP Registry](#publishing-to-anthropic-mcp-registry)
+  * [Contributions](#contributions)
+
+<!-- End Table of Contents [toc] -->
+
+<!-- Start Installation [installation] -->
+## Installation
+
+> [!TIP]
+> To finish publishing your MCP Server to npm and others you must [run your first generation action](https://www.speakeasy.com/docs/github-setup#step-by-step-guide).
+<details>
+<summary>Claude Desktop</summary>
+
+Install the MCP server as a Desktop Extension using the pre-built [`mcp-server.mcpb`](https://github.com/lightsagehq/mcp/releases/download/v0.1.7/mcp-server.mcpb) file:
+
+Simply drag and drop the [`mcp-server.mcpb`](https://github.com/lightsagehq/mcp/releases/download/v0.1.7/mcp-server.mcpb) file onto Claude Desktop to install the extension.
+
+The MCP bundle package includes the MCP server and all necessary configuration. Once installed, the server will be available without additional setup.
+
+> [!NOTE]
+> MCP bundles provide a streamlined way to package and distribute MCP servers. Learn more about [Desktop Extensions](https://www.anthropic.com/engineering/desktop-extensions).
+
+</details>
+
+<details>
+<summary>Cursor</summary>
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=LightsageMcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAdXNlc2FwaWVudC9tY3AiLCJzdGFydCIsIi0tc2FwaWVudC1hcGkta2V5LWF1dGgiLCIiXX0=)
+
+Or manually:
+
+1. Open Cursor Settings
+2. Select Tools and Integrations
+3. Select New MCP Server
+4. If the configuration file is empty paste the following JSON into the MCP Server Configuration:
+
+```json
+{
+  "command": "npx",
+  "args": [
+    "@lightsage/mcp",
+    "start",
+    "--lightsage-api-key-auth",
+    ""
+  ]
+}
+```
+
+</details>
+
+<details>
+<summary>Claude Code CLI</summary>
+
+```bash
+claude mcp add LightsageMcp -- npx -y @lightsage/mcp start --lightsage-api-key-auth YOUR_API_KEY
+```
+
+</details>
+<details>
+<summary>Gemini</summary>
+
+```bash
+gemini mcp add LightsageMcp -- npx -y @lightsage/mcp start --lightsage-api-key-auth YOUR_API_KEY
+```
+
+</details>
+<details>
+<summary>Windsurf</summary>
+
+Refer to [Official Windsurf documentation](https://docs.windsurf.com/windsurf/cascade/mcp#adding-a-new-mcp-plugin) for latest information
+
+1. Open Windsurf Settings
+2. Select Cascade on left side menu
+3. Click on `Manage MCPs`. (To Manage MCPs you should be signed in with a Windsurf Account)
+4. Click on `View raw config` to open up the mcp configuration file.
+5. If the configuration file is empty paste the full json
+
+```bash
+{
+  "command": "npx",
+  "args": [
+    "@lightsage/mcp",
+    "start",
+    "--lightsage-api-key-auth",
+    ""
+  ]
+}
+```
+</details>
+<details>
+<summary>VS Code</summary>
+
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20LightsageMcp%20MCP&color=0098FF)](vscode://ms-vscode.vscode-mcp/install?name=LightsageMcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAdXNlc2FwaWVudC9tY3AiLCJzdGFydCIsIi0tc2FwaWVudC1hcGkta2V5LWF1dGgiLCIiXX0=)
+
+Or manually:
+
+Refer to [Official VS Code documentation](https://code.visualstudio.com/api/extension-guides/ai/mcp) for latest information
+
+1. Open [Command Palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette)
+1. Search and open `MCP: Open User Configuration`. This should open mcp.json file
+2. If the configuration file is empty paste the full json
+
+```bash
+{
+  "command": "npx",
+  "args": [
+    "@lightsage/mcp",
+    "start",
+    "--lightsage-api-key-auth",
+    ""
+  ]
+}
+```
+
+</details>
+<details>
+<summary> Stdio installation via npm </summary>
+To start the MCP server, run:
+
+```bash
+npx @lightsage/mcp start --lightsage-api-key-auth "ls_cli_your_api_key"
+```
+
+For a full list of server arguments, run:
+
+```
+npx @lightsage/mcp --help
+```
+
+</details>
+<!-- End Installation [installation] -->
+
+<!-- Start Progressive Discovery [dynamic-mode] -->
+## Progressive Discovery
+
+MCP servers with many tools can bloat LLM context windows, leading to increased token usage and tool confusion. Dynamic mode solves this by exposing only a small set of meta-tools that let agents progressively discover and invoke tools on demand.
+
+To enable dynamic mode, pass the `--mode dynamic` flag when starting your server:
+
+```jsonc
+{
+  "mcpServers": {
+    "LightsageMcp": {
+      "command": "npx",
+      "args": ["@lightsage/mcp", "start", "--mode", "dynamic"],
+      // ... other server arguments
+    }
+  }
+}
+```
+
+In dynamic mode, the server registers only the following meta-tools instead of every individual tool:
+
+- **`list_tools`**: Lists all available tools with their names and descriptions.
+- **`describe_tool_input`**: Returns the input schema for one or more tools by name.
+- **`execute_tool`**: Executes a tool by name with its arguments.
+
+This approach significantly reduces the number of tokens sent to the LLM on each request, which is especially useful for servers with a large number of tools.
+<!-- End Progressive Discovery [dynamic-mode] -->
+
+<!-- Placeholder for Future Speakeasy SDK Sections -->
+
+## Development
+
+Run locally without a published npm package:
+1. Clone this repository
+2. Run `npm install`
+3. Run `npm run build`
+4. Run `node ./bin/mcp-server.js start --lightsage-api-key-auth "ls_cli_your_api_key"`
+To use this local version with Cursor, Claude or other MCP Clients, you'll need to add the following config:
+
+```json
+{
+  "command": "node",
+  "args": [
+    "./bin/mcp-server.js",
+    "start",
+    "--lightsage-api-key-auth",
+    ""
+  ]
+}
+```
+
+Or to debug the MCP server locally, use the official MCP Inspector: 
+
+```bash
+npx @modelcontextprotocol/inspector node ./bin/mcp-server.js start --lightsage-api-key-auth "ls_cli_your_api_key"
+```
+
+
+
+## Publishing to Anthropic MCP Registry
+
+This server generates a `server.json` that conforms to the [official MCP Registry schema](https://modelcontextprotocol.io/registry/about). You can publish automatically via your Speakeasy workflow or manually using the `mcp-publisher` CLI.
+
+### Automated Publishing (Recommended)
+
+Add `mcpRegistry` to the `publish` block in your `workflow.yaml`:
+
+```yaml
+targets:
+  my-mcp:
+    target: mcp-typescript
+    source: my-source
+    publish:
+      npm:
+        token: $NPM_TOKEN
+      mcpRegistry:
+        auth: github-oidc  # recommended, no token needed
+```
+
+The `github-oidc` method uses GitHub Actions OIDC — no secrets required. For other auth methods:
+- `github` — requires a `MCP_REGISTRY_TOKEN` secret (GitHub PAT with `read:org` + `read:user` scopes)
+- `dns` — requires a `MCP_REGISTRY_TOKEN` secret (Ed25519 private key for custom domain namespaces)
+
+When the Speakeasy workflow runs, it will automatically publish to npm first, then to the MCP Registry.
+
+### Manual Publishing
+
+If you prefer to publish manually, follow the [official publishing guide](https://github.com/modelcontextprotocol/registry/blob/main/docs/guides/publishing/publish-server.md):
+
+1. **Publish to npm**: `npm publish --access public`
+2. **Install the publisher CLI**:
+   ```bash
+   curl -sL "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher && sudo mv mcp-publisher /usr/local/bin/
+   ```
+3. **Authenticate** (GitHub OAuth for `io.github.*` namespaces):
+   ```bash
+   mcp-publisher login github
+   ```
+4. **Publish**: `mcp-publisher publish`
+5. **Verify**:
+   ```bash
+   curl "https://registry.modelcontextprotocol.io/v0/servers?search=<your-mcp-name>"
+   ```
+
+## Contributions
+
+While we value contributions to this MCP Server, the code is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. 
+We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release. 
+
+### MCP Server Created by [Speakeasy](https://www.speakeasy.com/?utm_source=lightsage-mcp&utm_campaign=mcp-typescript)

package/api/mcp.js

@@ -0,0 +1,158 @@
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createConsoleLogger } from "../esm/mcp-server/console-logger.js";
+import { createMCPServer } from "../esm/mcp-server/server.js";
+import { buildAnnotationFilter, buildSDK } from "../esm/mcp-server/tools.js";
+import {
+  oauthEnabled,
+  verifyOAuthToken,
+  wwwAuthenticateHeader,
+  exchangeForLightsageKey,
+} from "../lib/oauth.js";
+
+const logLevel = process.env.MCP_LOG_LEVEL || "info";
+const logger = createConsoleLogger(logLevel);
+
+function splitEnvList(value) {
+  return value
+    ? value.split(",").map((item) => item.trim()).filter(Boolean)
+    : undefined;
+}
+
+function getFlags() {
+  return {
+    tool: splitEnvList(process.env.MCP_ALLOWED_TOOLS),
+    mode: process.env.MCP_MODE === "full" ? undefined : "dynamic",
+    "tool-annotations": splitEnvList(process.env.MCP_TOOL_ANNOTATIONS),
+    "lightsage-api-key-auth": process.env.LIGHTSAGE_LIGHTSAGE_API_KEY_AUTH ||
+      process.env.LIGHTSAGE_API_KEY,
+    "server-url": process.env.LIGHTSAGE_SERVER_URL || "https://api.lightsage.com",
+    "server-index": process.env.LIGHTSAGE_SERVER_INDEX
+      ? Number(process.env.LIGHTSAGE_SERVER_INDEX)
+      : undefined,
+    "log-level": logLevel,
+  };
+}
+
+function setCors(res) {
+  res.setHeader("Access-Control-Allow-Origin", "*");
+  res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+  res.setHeader("Access-Control-Allow-Headers", "*");
+  res.setHeader("Access-Control-Expose-Headers", "WWW-Authenticate");
+}
+
+export default async function handler(req, res) {
+  setCors(res);
+
+  if (req.method === "OPTIONS") {
+    res.status(204).end();
+    return;
+  }
+
+  const useOAuth = oauthEnabled();
+
+  if (req.method === "GET") {
+    if (useOAuth) {
+      res.setHeader("WWW-Authenticate", wwwAuthenticateHeader(req));
+      res.status(401).json({ error: "unauthorized" });
+      return;
+    }
+    res.status(200).json({
+      name: "Lightsage MCP",
+      transport: "streamable-http",
+      endpoint: "/mcp",
+      auth: useOAuth
+        ? {
+          type: "oauth2",
+          resource_metadata: "/.well-known/oauth-protected-resource/mcp",
+          api_key_header: "X-Lightsage-Api-Key",
+        }
+        : { header: "X-Lightsage-Api-Key" },
+    });
+    return;
+  }
+
+  if (req.method !== "POST") {
+    res.setHeader("Allow", "GET, POST, OPTIONS");
+    res.status(405).json({ error: "Method not allowed" });
+    return;
+  }
+
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (Array.isArray(value)) {
+      for (const item of value) headers.append(key, item);
+    } else if (value !== undefined) {
+      headers.set(key, value);
+    }
+  }
+
+  const requestApiKey = (
+    headers.get("x-lightsage-api-key") ||
+    headers.get("lightsage-api-key-auth") ||
+    headers.get("x-sapient-api-key") ||
+    headers.get("sapient-api-key-auth")
+  )?.trim();
+  if (requestApiKey) {
+    headers.set("lightsage-api-key-auth", requestApiKey);
+  }
+
+  // A caller-supplied Lightsage API key remains a first-class authentication
+  // path when OAuth is enabled. If no key is present, verify the Clerk OAuth
+  // access token and exchange that identity for a Lightsage public-API key.
+  if (useOAuth && !requestApiKey) {
+    let auth;
+    try {
+      auth = await verifyOAuthToken(req);
+    } catch (error) {
+      logger.error("OAuth token verification error", {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      auth = null;
+    }
+
+    if (!auth || !auth.userId) {
+      res.setHeader("WWW-Authenticate", wwwAuthenticateHeader(req));
+      res.status(401).json({ error: "unauthorized" });
+      return;
+    }
+
+    try {
+      const apiKey = await exchangeForLightsageKey(auth.userId, auth.clientId);
+      headers.set("lightsage-api-key-auth", apiKey);
+    } catch (error) {
+      logger.error("Lightsage key exchange failed", {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      res.status(502).json({ error: "key_exchange_failed" });
+      return;
+    }
+  }
+
+  const flags = getFlags();
+  // OAuth-enabled deployments may use either a caller-supplied request key or
+  // an OAuth-exchanged key, but must never fall back to a static server key.
+  const disableStaticAuth = useOAuth
+    ? true
+    : process.env.MCP_DISABLE_STATIC_AUTH !== "false";
+  const transport = new StreamableHTTPServerTransport({});
+
+  const { server: mcpServer } = createMCPServer({
+    logger,
+    allowedTools: flags.tool,
+    dynamic: flags.mode === "dynamic",
+    annotationFilter: buildAnnotationFilter(flags["tool-annotations"]),
+    serverURL: flags["server-url"],
+    serverIdx: flags["server-index"],
+    getSDK: () => buildSDK(headers, flags, disableStaticAuth, logger),
+  });
+
+  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);
+  await transport.handleRequest(req, res, req.body);
+}

package/api/well-known-authorization-server.js

@@ -0,0 +1,38 @@
+// OAuth 2.0 Authorization Server Metadata (RFC 8414), proxied from Clerk.
+// Served (via vercel.json rewrites) at:
+//   /.well-known/oauth-authorization-server
+// No longer strictly required by the current MCP spec (clients discover the
+// AS via the protected-resource document), but kept for older clients.
+
+import { authorizationServerMetadata, corsHeaders } from "../lib/oauth.js";
+
+function setCors(res) {
+  for (const [key, value] of Object.entries(corsHeaders)) {
+    res.setHeader(key, value);
+  }
+}
+
+export default async function handler(req, res) {
+  setCors(res);
+
+  if (req.method === "OPTIONS") {
+    res.status(204).end();
+    return;
+  }
+
+  if (req.method !== "GET") {
+    res.setHeader("Allow", "GET, OPTIONS");
+    res.status(405).json({ error: "Method not allowed" });
+    return;
+  }
+
+  try {
+    const metadata = await authorizationServerMetadata();
+    res.status(200).json(metadata);
+  } catch (error) {
+    res.status(502).json({
+      error: "authorization_server_metadata_unavailable",
+      message: error instanceof Error ? error.message : String(error),
+    });
+  }
+}

package/api/well-known-protected-resource.js

@@ -0,0 +1,30 @@
+// OAuth 2.0 Protected Resource Metadata (RFC 9728).
+// Served (via vercel.json rewrites) at:
+//   /.well-known/oauth-protected-resource
+//   /.well-known/oauth-protected-resource/mcp
+// Must be publicly accessible — do not gate behind auth.
+
+import { protectedResourceMetadata, corsHeaders } from "../lib/oauth.js";
+
+function setCors(res) {
+  for (const [key, value] of Object.entries(corsHeaders)) {
+    res.setHeader(key, value);
+  }
+}
+
+export default async function handler(req, res) {
+  setCors(res);
+
+  if (req.method === "OPTIONS") {
+    res.status(204).end();
+    return;
+  }
+
+  if (req.method !== "GET") {
+    res.setHeader("Allow", "GET, OPTIONS");
+    res.status(405).json({ error: "Method not allowed" });
+    return;
+  }
+
+  res.status(200).json(protectedResourceMetadata(req));
+}