@lightsage/mcp 0.4.14 → 0.4.15

package/lib/oauth.js

@@ -65,6 +65,86 @@ export function protectedResourceMetadataUrl(req) {
   return `${proto}://${host}/.well-known/oauth-protected-resource/mcp`;
 }
 
+/** Resource identifiers an access token may be audience-bound to. */
+export function acceptedResourceUrls(req) {
+  const urls = [
+    "https://mcp.lightsage.com/mcp",
+    "https://mcp.usesapient.com/mcp",
+    process.env.MCP_RESOURCE_URL,
+    resourceUrl(req),
+  ];
+  return new Set(urls.filter(Boolean).map(normalizeResourceUrl));
+}
+
+function normalizeResourceUrl(value) {
+  return String(value).replace(/\/+$/, "");
+}
+
+/** Origin and slash-trimmed path of a resource URL, or null if it is not one. */
+function parseResourceUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") return null;
+  return { origin: url.origin, path: url.pathname.replace(/\/+$/, "") };
+}
+
+/**
+ * Whether an audience names an accepted resource. Clerk copies the client's
+ * `resource` parameter into `aud` unchanged, so the same server can arrive as
+ * its exact URL, with a trailing slash or default port, or as its origin
+ * alone. An audience on another origin, or on another path of this origin,
+ * does not match.
+ */
+function audienceNamesResource(audience, accepted) {
+  const named = parseResourceUrl(audience);
+  const resource = parseResourceUrl(accepted);
+  if (!named || !resource || named.origin !== resource.origin) return false;
+  return (
+    named.path === resource.path || resource.path.startsWith(`${named.path}/`)
+  );
+}
+
+/** Resource URLs a JWT access token names in its `aud` / `resource` claims. */
+function tokenResourceAudiences(token) {
+  const segments = token.split(".");
+  if (segments.length !== 3) return [];
+  let payload;
+  try {
+    payload = JSON.parse(Buffer.from(segments[1], "base64url").toString("utf8"));
+  } catch {
+    return [];
+  }
+  return [payload?.aud, payload?.resource]
+    .flat()
+    .filter((value) => typeof value === "string" && /^https?:\/\//i.test(value));
+}
+
+/** Whether the resource URLs a token names include this MCP server. */
+function audiencesAllowed(audiences, req) {
+  if (audiences.length === 0) return true;
+  const accepted = [...acceptedResourceUrls(req)];
+  return audiences.some((audience) =>
+    accepted.some((resource) => audienceNamesResource(audience, resource)),
+  );
+}
+
+/**
+ * Check that a verified access token was minted for this MCP server.
+ *
+ * A token that names resource URLs must name this one, so a token issued for
+ * another resource server cannot be replayed here. A token that names none is
+ * accepted: Clerk only binds a token to a resource when the client sent one,
+ * and never for a connection authorized before `aud_claim_enabled` was on.
+ * Call only after the signature is verified.
+ */
+export function tokenAudienceAllowed(token, req) {
+  return audiencesAllowed(tokenResourceAudiences(token), req);
+}
+
 export function oauthAuthenticationOptions() {
   // Do not set `authorizedParties` for OAuth access tokens. Clerk uses the
   // dynamically registered OAuth client ID (for example, Claude's client ID)
@@ -77,8 +157,10 @@ export function oauthAuthenticationOptions() {
  * Verify the incoming Authorization: Bearer OAuth access token with Clerk.
  * Returns the Clerk auth object ({ userId, scopes, clientId, ... }) on success,
  * or null when the request is unauthenticated / the token is invalid.
+ *
+ * Pass `logger` to record tokens the audience check rejects.
  */
-export async function verifyOAuthToken(req) {
+export async function verifyOAuthToken(req, logger) {
   const authorization = req.headers["authorization"];
   if (!authorization || !/^bearer\s+/i.test(authorization)) {
     return null;
@@ -97,22 +179,53 @@ export async function verifyOAuthToken(req) {
   if (!requestState.isAuthenticated) {
     return null;
   }
-  return requestState.toAuth();
+  const auth = requestState.toAuth();
+  const token = authorization.replace(/^bearer\s+/i, "").trim();
+  const audiences = tokenResourceAudiences(token);
+  if (!audiencesAllowed(audiences, req)) {
+    logger?.warning("OAuth token rejected by the audience check", {
+      audiences,
+      clientId: auth?.clientId,
+    });
+    return null;
+  }
+  return auth;
 }
 
-/** RFC 6750 challenge header pointing clients at our protected-resource metadata. */
-export function wwwAuthenticateHeader(req) {
+/**
+ * RFC 6750 challenge header pointing clients at our protected-resource
+ * metadata. Pass `error` / `errorDescription` when a presented token was
+ * rejected, so the client knows to run the OAuth flow again.
+ */
+export function wwwAuthenticateHeader(req, { error, errorDescription } = {}) {
   const metadata = protectedResourceMetadataUrl(req);
   const scope = MCP_SUPPORTED_SCOPES.join(" ");
-  return `Bearer resource_metadata="${metadata}", scope="${scope}"`;
+  const params = [`resource_metadata="${metadata}"`, `scope="${scope}"`];
+  if (error) params.push(`error="${error}"`);
+  if (errorDescription) {
+    params.push(`error_description="${errorDescription.replace(/["\\]/g, "")}"`);
+  }
+  return `Bearer ${params.join(", ")}`;
+}
+
+/** A key exchange the backend refused, with its machine-readable reason. */
+export class KeyExchangeError extends Error {
+  constructor(message, { status, code } = {}) {
+    super(message);
+    this.name = "KeyExchangeError";
+    this.status = status;
+    this.code = code;
+  }
 }
 
 /**
  * Exchange a verified Clerk identity for a Lightsage public-API key.
  * Calls the private backend exchange endpoint with the shared service secret.
- * Returns the plaintext ls_cli_ key, or throws on failure.
+ * Returns `{ apiKey, profile }`, where `profile` is the connected Lightsage
+ * profile (absent on backends that predate it). Throws KeyExchangeError when
+ * the backend refuses the exchange.
  */
-export async function exchangeForLightsageKey(clerkUserId, oauthClientId) {
+export async function exchangeForLightsageIdentity(clerkUserId, oauthClientId) {
   const baseUrl = process.env.LIGHTSAGE_EXCHANGE_URL;
   const secret = process.env.MCP_EXCHANGE_SECRET;
   if (!baseUrl || !secret || !oauthClientId) {
@@ -135,14 +248,74 @@ export async function exchangeForLightsageKey(clerkUserId, oauthClientId) {
 
   if (!res.ok) {
     const text = await res.text().catch(() => "");
-    throw new Error(`Key exchange failed (${res.status}): ${text.slice(0, 200)}`);
+    throw new KeyExchangeError(
+      `Key exchange failed (${res.status}): ${text.slice(0, 200)}`,
+      {
+        status: res.status,
+        code: res.headers.get("x-mcp-exchange-error") || undefined,
+      },
+    );
   }
 
   const data = await res.json();
   if (!data || typeof data.api_key !== "string") {
     throw new Error("Key exchange returned no api_key");
   }
-  return data.api_key;
+  return { apiKey: data.api_key, profile: data.profile ?? null };
+}
+
+// Exchange refusals a new sign-in fixes: the consent page saves the
+// organization this connection uses.
+const REAUTHORIZE_EXCHANGE_ERRORS = new Set([
+  "organization_selection_required",
+  "not_an_organization_member",
+]);
+// Exchange refusals a new sign-in cannot fix until the account has a workspace.
+const NO_WORKSPACE_EXCHANGE_ERRORS = new Set([
+  "user_not_provisioned",
+  "no_organization",
+]);
+
+/**
+ * Map a failed key exchange to the HTTP response the MCP client should get:
+ * a re-authorization challenge, an access-denied explanation, or a 502.
+ */
+export function exchangeFailureResponse(req, error) {
+  if (REAUTHORIZE_EXCHANGE_ERRORS.has(error?.code)) {
+    const errorDescription =
+      "Sign in again and choose a Lightsage organization for this connection.";
+    return {
+      status: 401,
+      headers: {
+        "WWW-Authenticate": wwwAuthenticateHeader(req, {
+          error: "invalid_token",
+          errorDescription,
+        }),
+      },
+      body: { error: "invalid_token", error_description: errorDescription },
+    };
+  }
+  if (NO_WORKSPACE_EXCHANGE_ERRORS.has(error?.code)) {
+    return {
+      status: 403,
+      headers: {},
+      body: {
+        error: "access_denied",
+        error_description:
+          "This account has no Lightsage workspace. Sign up at https://app.lightsage.com, then connect again.",
+      },
+    };
+  }
+  return { status: 502, headers: {}, body: { error: "key_exchange_failed" } };
+}
+
+/** Exchange a verified Clerk identity for just the plaintext ls_cli_ key. */
+export async function exchangeForLightsageKey(clerkUserId, oauthClientId) {
+  const { apiKey } = await exchangeForLightsageIdentity(
+    clerkUserId,
+    oauthClientId,
+  );
+  return apiKey;
 }
 
 // ---- Well-known metadata documents ---------------------------------------

package/lib/profile.js

@@ -0,0 +1,79 @@
+// Authenticated profile tool for OAuth-connected MCP clients.
+//
+// OpenAI hosts (ChatGPT, Codex) call the tool marked `openai/profile` to label
+// a connected account and to recognize the same account after it reconnects.
+// The profile comes from the backend key exchange, which derives a stable
+// opaque id from the Lightsage user and organization behind the access token.
+//
+// Hand-written (not Speakeasy-generated) so regeneration does not remove it.
+
+import { z } from "zod";
+
+export const PROFILE_TOOL_NAME = "get_profile";
+
+const profileOutputSchema = z.strictObject({
+  id: z.string().min(1).regex(/\S/).describe(
+    "Opaque profile identifier, unique within Lightsage and unchanged across token refresh, reconnection, and display-metadata changes. Never reassigned to another profile.",
+  ),
+  email: z.string().optional().describe(
+    "Email address for display; not used as the profile identity.",
+  ),
+  nickname: z.string().optional().describe(
+    "The Lightsage organization this connection can access.",
+  ),
+});
+
+/** Build the profile tool result, or an error when no stable id is available. */
+export function profileToolResult(profile) {
+  const id = typeof profile?.id === "string" ? profile.id.trim() : "";
+  if (!id) {
+    return {
+      isError: true,
+      content: [{ type: "text", text: "Profile identity unavailable." }],
+    };
+  }
+
+  const result = {
+    id,
+    ...(typeof profile.email === "string" && profile.email
+      ? { email: profile.email }
+      : {}),
+    ...(typeof profile.nickname === "string" && profile.nickname
+      ? { nickname: profile.nickname }
+      : {}),
+  };
+  return {
+    isError: false,
+    structuredContent: result,
+    content: [{ type: "text", text: JSON.stringify(result) }],
+  };
+}
+
+/** Register the profile tool for the profile behind this request's token. */
+export function registerProfileTool(mcpServer, profile) {
+  const securitySchemes = [{ type: "oauth2", scopes: [] }];
+  mcpServer.registerTool(
+    PROFILE_TOOL_NAME,
+    {
+      title: "Get Profile",
+      description:
+        "Return the Lightsage profile represented by this request's authenticated credentials. The opaque id is unique within Lightsage and remains unchanged across token refresh, reconnection, and display-metadata changes.",
+      inputSchema: z.strictObject({}),
+      outputSchema: profileOutputSchema,
+      annotations: {
+        title: "Get Profile",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+      _meta: {
+        "openai/profile": true,
+        // The MCP SDK drops unknown top-level descriptor fields, so declare
+        // the auth policy through the `_meta` mirror OpenAI hosts also read.
+        securitySchemes,
+      },
+    },
+    async () => profileToolResult(profile),
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightsage/mcp",
-  "version": "0.4.14",
+  "version": "0.4.15",
   "author": "Speakeasy",
   "type": "module",
   "sideEffects": false,
@@ -23,13 +23,13 @@
   "dependencies": {
     "@clerk/backend": "^3.11.4",
     "@clerk/mcp-tools": "^0.5.0",
-    "@modelcontextprotocol/sdk": "1.26.0",
+    "@modelcontextprotocol/sdk": "1.32.1",
     "@stricli/core": "^1.1.2",
     "express": "^5.1.0",
     "zod": "^4.0.0"
   },
   "overrides": {
-    "@modelcontextprotocol/sdk": "1.26.0",
+    "@modelcontextprotocol/sdk": "1.32.1",
     "hono": ">=4.13.7 <5.0.0",
     "fast-uri": ">=4.1.3 <5.0.0",
     "js-yaml": ">=4.3.2 <5.0.0",
@@ -40,8 +40,10 @@
     "@hono/node-server": ">=1.19.15 <2.0.0",
     "brace-expansion@^1.1.7": ">=1.1.18 <2.0.0",
     "brace-expansion@^5.0.0": ">=5.0.9 <6.0.0",
+    "proxy-addr": ">=2.0.8 <3.0.0",
     "qs": ">=6.16.0 <7.0.0",
-    "tmp": ">=0.2.6 <0.3.0"
+    "tmp": ">=0.2.6 <0.3.0",
+    "node-forge": "$node-forge"
   },
   "devDependencies": {
     "@anthropic-ai/mcpb": "^1.2.0",
@@ -52,6 +54,7 @@
     "bun": "^1.2.12",
     "eslint": "^9.26.0",
     "globals": "^16.0.0",
+    "node-forge": "file:vendor/node-forge",
     "typescript": "~5.8.3",
     "typescript-eslint": "^8.31.1"
   }

package/src/funcs/evalRunsList.ts

@@ -30,7 +30,7 @@ import { Result } from "../types/fp.js";
  * List Runs
  *
  * @remarks
- * Returns jobs created through `POST /v2/eval-runs`, ordered newest first, with lifecycle state and progress.
+ * Returns custom eval runs, ordered newest first, with lifecycle state and progress. Includes scheduled, onboarding, and pull request runs and runs started in the Lightsage app, as well as runs started through `POST /v2/eval-runs`.
  */
 export function evalRunsList(
   client$: LightsageMcpCore,

package/src/landing-page.ts

@@ -931,7 +931,7 @@ http_headers = { "lightsage-api-key-auth" = "YOUR_LIGHTSAGE_API_KEY_AUTH" }`;
         <h1>Instructions</h1>
         <p>One-click installation for Claude Desktop users</p>
         <div class="instruction-item">
-          <a href="https://github.com/lightsagehq/mcp/releases/download/v0.4.14/mcp-server.mcpb" download="mcp-server.mcpb" class="action-button header-action" style="display: inline-flex; margin-bottom: 16px;">
+          <a href="https://github.com/lightsagehq/mcp/releases/download/v0.4.15/mcp-server.mcpb" download="mcp-server.mcpb" class="action-button header-action" style="display: inline-flex; margin-bottom: 16px;">
             📥 Download MCP Bundle
           </a>
         </div>

package/src/lib/config.ts

@@ -66,7 +66,7 @@ export function serverURLFromOptions(options: SDKOptions): URL | null {
 export const SDK_METADATA = {
   language: "typescript",
   openapiDocVersion: "1.0.0",
-  sdkVersion: "0.4.14",
-  genVersion: "2.943.0",
-  userAgent: "speakeasy-sdk/mcp-typescript 0.4.14 2.943.0 1.0.0 @lightsage/mcp",
+  sdkVersion: "0.4.15",
+  genVersion: "2.948.4",
+  userAgent: "speakeasy-sdk/mcp-typescript 0.4.15 2.948.4 1.0.0 @lightsage/mcp",
 } as const;

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

@@ -22,7 +22,7 @@ const routes = buildRouteMap({
 export const app = buildApplication(routes, {
   name: "mcp",
   versionInfo: {
-    currentVersion: "0.4.14",
+    currentVersion: "0.4.15",
   },
 });
 

package/src/mcp-server/server.ts

@@ -103,7 +103,7 @@ export function createMCPServer(deps: {
       sizes: ["any"],
     }],
     name: "LightsageMcp",
-    version: "0.4.14",
+    version: "0.4.15",
   });
 
   const getClient = deps.getSDK || (() =>

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

@@ -15,7 +15,7 @@ export const tool$evalRunsList: ToolDefinition<typeof args> = {
   name: "eval-runs-list",
   description: `List Runs
 
-Returns jobs created through \`POST /v2/eval-runs\`, ordered newest first, with lifecycle state and progress.`,
+Returns custom eval runs, ordered newest first, with lifecycle state and progress. Includes scheduled, onboarding, and pull request runs and runs started in the Lightsage app, as well as runs started through \`POST /v2/eval-runs\`.`,
   annotations: {
     "title": "",
     "destructiveHint": false,

package/src/models/createevaltemplaterequest.ts

@@ -83,11 +83,12 @@ export const CreateEvalTemplateRequestIncludedComponent$zodSchema = z.enum([
 ]);
 
 /**
- * Create reusable configuration before supplying prompt-specific evals.
+ * Create a reusable eval that can be applied to many brands or prompts.
  */
 export type CreateEvalTemplateRequest = {
   name: string;
   description?: string | undefined;
+  prompt?: string | undefined;
   eval_type?: CreateEvalTemplateRequestEvalType | undefined;
   included_components: Array<CreateEvalTemplateRequestIncludedComponent>;
   persona?: string | undefined;
@@ -131,6 +132,9 @@ export const CreateEvalTemplateRequest$zodSchema: z.ZodType<
   persona: z.string().optional().describe(
     "Optional persona copied when `persona` is included.",
   ),
+  prompt: z.string().optional().describe(
+    "Prompt filled into the new eval form when the template is applied, or the scenario for Agent Preference, where `{{\"{{\"}}competitor_name}}` names the brand each comparison is against. Requests that create evals from a template still supply their own prompts.",
+  ),
   runs_per_execution: z.int().default(1).describe(
     "Attempt count copied when `runs` is included.",
   ),
@@ -147,5 +151,5 @@ export const CreateEvalTemplateRequest$zodSchema: z.ZodType<
     "Runnable target keys copied when `targets` is included, such as `agent:codex:gpt-5.6-terra`.",
   ),
 }).describe(
-  "Create reusable configuration before supplying prompt-specific evals.",
+  "Create a reusable eval that can be applied to many brands or prompts.",
 );

package/src/models/evaltemplate.ts

@@ -83,6 +83,7 @@ export const EvalTemplateIncludedComponent$zodSchema = z.enum([
 export type EvalTemplate = {
   name: string;
   description?: string | null | undefined;
+  prompt?: string | null | undefined;
   eval_type?: EvalTemplateEvalType | undefined;
   included_components: Array<EvalTemplateIncludedComponent>;
   persona?: string | null | undefined;
@@ -134,6 +135,9 @@ export const EvalTemplate$zodSchema: z.ZodType<EvalTemplate> = z.object({
   persona: z.string().nullable().optional().describe(
     "Optional persona copied when `persona` is included.",
   ),
+  prompt: z.string().nullable().optional().describe(
+    "Prompt filled into the new eval form when the template is applied, or the scenario for Agent Preference, where `{{\"{{\"}}competitor_name}}` names the brand each comparison is against. Requests that create evals from a template still supply their own prompts.",
+  ),
   runs_per_execution: z.int().default(1).describe(
     "Attempt count copied when `runs` is included.",
   ),

package/src/models/updateevaltemplaterequest.ts

@@ -78,6 +78,7 @@ export type UpdateEvalTemplateRequest = {
   expected_template_version?: number | undefined;
   name?: string | undefined;
   description?: string | undefined;
+  prompt?: string | undefined;
   eval_type?: UpdateEvalTemplateRequestEvalType | undefined;
   included_components?:
     | Array<UpdateEvalTemplateRequestIncludedComponent>
@@ -108,6 +109,7 @@ export const UpdateEvalTemplateRequest$zodSchema: z.ZodType<
   judges: z.array(GraderDefinition$zodSchema).nullable().optional(),
   name: z.string().optional(),
   persona: z.string().optional(),
+  prompt: z.string().optional(),
   runs_per_execution: z.int().optional(),
   runtime: EvalTemplateRuntime$zodSchema.nullable().optional(),
   schedule: EvalTemplateSchedule$zodSchema.nullable().optional(),

package/src/models/v2publictask.ts

@@ -5,6 +5,28 @@
 
 import * as z from "zod";
 import { collectExtraKeys as collectExtraKeys$ } from "../lib/schemas.js";
+import { ClosedEnum } from "../types/enums.js";
+
+/**
+ * Progress of the Markdown write-up in `content`.
+ */
+export const ContentStatus = {
+  None: "none",
+  Writing: "writing",
+  Ready: "ready",
+  Failed: "failed",
+} as const;
+/**
+ * Progress of the Markdown write-up in `content`.
+ */
+export type ContentStatus = ClosedEnum<typeof ContentStatus>;
+
+export const ContentStatus$zodSchema = z.enum([
+  "none",
+  "writing",
+  "ready",
+  "failed",
+]).describe("Progress of the Markdown write-up in `content`.");
 
 export type V2PublicTask = {
   id: string;
@@ -18,6 +40,10 @@ export type V2PublicTask = {
   next_action: string;
   description?: string | null | undefined;
   execution_prompt: string;
+  content?: string | null | undefined;
+  target_url?: string | null | undefined;
+  content_status?: ContentStatus | undefined;
+  content_written_at?: string | null | undefined;
   reasoning?: string | null | undefined;
   evidence?: { [k: string]: any } | undefined;
   score?: number | null | undefined;
@@ -43,6 +69,15 @@ export const V2PublicTask$zodSchema: z.ZodType<V2PublicTask> =
       action_type: z.string().nullable().optional(),
       assignee_user_id: z.string().nullable().optional(),
       batch_number: z.int(),
+      content: z.string().nullable().optional().describe(
+        "The task's Markdown write-up covering what went wrong, how to fix it, the impact, and the evidence. Null until the write-up is generated; see `content_status`.",
+      ),
+      content_status: ContentStatus$zodSchema.default("none").describe(
+        "Progress of the Markdown write-up in `content`.",
+      ),
+      content_written_at: z.string().nullable().optional().describe(
+        "When the write-up in `content` was last generated.",
+      ),
       created_at: z.string().nullable().optional(),
       description: z.string().nullable().optional(),
       effort: z.string().describe(
@@ -79,6 +114,9 @@ export const V2PublicTask$zodSchema: z.ZodType<V2PublicTask> =
       status: z.string().describe(
         "The workflow status. New tasks start as `new`. A task is `in_review` while its content waits to go live, as an open pull request or a CMS draft; it is listed with `in_progress` tasks. `added_to_sheet` and `snoozed` tasks are listed only when `status=all`.",
       ),
+      target_url: z.string().nullable().optional().describe(
+        "The page the fix should be made on, when the task targets one.",
+      ),
       task_type: z.string().describe(
         "A free-form label such as `Redirect` or `Docs`; this field is not an enum.",
       ),
@@ -96,6 +134,9 @@ export const V2PublicTask$zodSchemaOutbound: z.ZodType<any> = z.object({
   action_type: z.nullable(z.string()).optional(),
   assignee_user_id: z.nullable(z.string()).optional(),
   batch_number: z.int(),
+  content: z.nullable(z.string()).optional(),
+  content_status: ContentStatus$zodSchema.default("none"),
+  content_written_at: z.nullable(z.string()).optional(),
   created_at: z.nullable(z.string()).optional(),
   description: z.nullable(z.string()).optional(),
   effort: z.string(),
@@ -114,6 +155,7 @@ export const V2PublicTask$zodSchemaOutbound: z.ZodType<any> = z.object({
   source_refs: z.record(z.string(), z.any()).optional(),
   source_type: z.nullable(z.string()).optional(),
   status: z.string(),
+  target_url: z.nullable(z.string()).optional(),
   task_type: z.string(),
   title: z.string(),
   updated_at: z.nullable(z.string()).optional(),

package/src/tool-names.ts

@@ -186,7 +186,7 @@ export const toolNames: Array<{ name: string; description: string }>= [
   },
   {
     "name": "eval-runs-list",
-    "description": "List Runs\n\nReturns jobs created through `POST /v2/eval-runs`, ordered newest first, with lifecycle state and progress."
+    "description": "List Runs\n\nReturns custom eval runs, ordered newest first, with lifecycle state and progress. Includes scheduled, onboarding, and pull request runs and runs started in the Lightsage app, as well as runs started through `POST /v2/eval-runs`."
   },
   {
     "name": "agent-preference-competitors-list",