Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

fix(mcp): fall back to latest skill when production is unset (#19123)

tobi_kla00998383cf7
diff --git a/web/src/__tests__/server/mcp-tools-read.servertest.ts b/web/src/__tests__/server/mcp-tools-read.servertest.ts
index 428e134517..4762e830c0 100644
--- a/web/src/__tests__/server/mcp-tools-read.servertest.ts
+++ b/web/src/__tests__/server/mcp-tools-read.servertest.ts
@@ -464,6 +464,94 @@ describe("MCP Read Tools", () => {
).resolves.toBe(fixture.reference);
});
+ it("defaults to production, then latest, when no skill selector is provided", async () => {
+ const fixture = await createSkillForMcpReadTest();
+ const latestRoot = `${fixture.root}\nUpdated instructions.`;
+ const latestReference = "Updated checklist.";
+ await fixture.service.createVersion({
+ projectId: fixture.projectId,
+ createdBy: "API",
+ input: {
+ files: [
+ { path: "SKILL.md", content: latestRoot },
+ { path: "references/checklist.md", content: latestReference },
+ { path: "latest-only.txt", content: "Only in latest." },
+ ],
+ },
+ actor: fixture.actor,
+ });
+
+ const expectDefaultVersion = async (
+ version: number,
+ root: string,
+ reference: string,
+ ) => {
+ await expect(
+ handleGetSkill({ name: fixture.name }, fixture.context),
+ ).resolves.toMatchObject({ version });
+ await expect(
+ handleLoadSkill({ name: fixture.name }, fixture.context),
+ ).resolves.toBe(root);
+ await expect(
+ handleLoadSkillResource(
+ { name: fixture.name, path: "references/checklist.md" },
+ fixture.context,
+ ),
+ ).resolves.toBe(reference);
+ };
+
+ await expectDefaultVersion(2, latestRoot, latestReference);
+ await fixture.service.setLabels({
+ projectId: fixture.projectId,
+ name: fixture.name,
+ version: 1,
+ labels: ["production"],
+ actor: fixture.actor,
+ });
+ await expectDefaultVersion(1, fixture.root, fixture.reference);
+
+ await expect(
+ handleLoadSkillResource(
+ { name: fixture.name, path: "latest-only.txt" },
+ fixture.context,
+ ),
+ ).rejects.toThrow("Skill resource not found");
+ await expect(
+ handleGetSkill({ name: fixture.name, version: 2 }, fixture.context),
+ ).resolves.toMatchObject({ version: 2 });
+ await expect(
+ handleLoadSkill(
+ { name: fixture.name, label: "latest" },
+ fixture.context,
+ ),
+ ).resolves.toBe(latestRoot);
+ });
+
+ it.each([
+ ["getSkill", handleGetSkill],
+ ["loadSkill", handleLoadSkill],
+ ["loadSkillResource", handleLoadSkillResource],
+ ] as const)(
+ "does not fall back for missing explicit selectors in %s",
+ async (_name, handler) => {
+ const fixture = await createSkillForMcpReadTest();
+ for (const selector of [{ version: 99 }, { label: "production" }]) {
+ await expect(
+ handler(
+ { name: fixture.name, path: "SKILL.md", ...selector },
+ fixture.context,
+ ),
+ ).rejects.toThrow("Skill version not found");
+ }
+ await expect(
+ handler(
+ { name: `missing-${randomUUID()}`, path: "SKILL.md" },
+ fixture.context,
+ ),
+ ).rejects.toThrow("Skill version not found");
+ },
+ );
+
it.each([
["getSkill", handleGetSkill],
["loadSkill", handleLoadSkill],
@@ -501,12 +589,14 @@ describe("MCP Read Tools", () => {
handleLoadSkill,
handleLoadSkillResource,
]) {
- await expect(
- handler(
- { ...selector, path: "references/checklist.md" },
- other.context,
- ),
- ).rejects.toThrow("Skill version not found");
+ for (const input of [selector, { name: fixture.name }]) {
+ await expect(
+ handler(
+ { ...input, path: "references/checklist.md" },
+ other.context,
+ ),
+ ).rejects.toThrow("Skill version not found");
+ }
}
});
});
diff --git a/web/src/__tests__/server/unit/skill-service.servertest.ts b/web/src/__tests__/server/unit/skill-service.servertest.ts
index 5d71c59c87..51cb33e878 100644
--- a/web/src/__tests__/server/unit/skill-service.servertest.ts
+++ b/web/src/__tests__/server/unit/skill-service.servertest.ts
@@ -574,6 +574,56 @@ describe("SkillService versions", () => {
expect(test.transaction).not.toHaveBeenCalled();
});
+ it("only looks up latest when the default production version is missing", async () => {
+ const test = setup();
+ const input = {
+ projectId: "project",
+ name: "test-skill",
+ selector: {},
+ fallbackToLatest: true,
+ };
+
+ await expect(test.service.get(input)).resolves.toMatchObject({
+ version: 1,
+ });
+ expect(test.db.skill.findFirst).toHaveBeenCalledOnce();
+ test.db.skill.findFirst.mockClear();
+ test.db.skill.findFirst
+ .mockResolvedValueOnce(null)
+ .mockResolvedValueOnce({ ...test.skill, version: 2, labels: ["latest"] });
+
+ await expect(test.service.get(input)).resolves.toMatchObject({
+ version: 2,
+ });
+ expect(test.db.skill.findFirst).toHaveBeenCalledTimes(2);
+ for (const [index, label] of ["production", "latest"].entries()) {
+ expect(test.db.skill.findFirst).toHaveBeenNthCalledWith(
+ index + 1,
+ expect.objectContaining({
+ where: {
+ projectId: "project",
+ name: "test-skill",
+ labels: { has: label },
+ },
+ }),
+ );
+ }
+ });
+
+ it("keeps the default production lookup strict unless fallback is enabled", async () => {
+ const test = setup();
+ test.db.skill.findFirst.mockResolvedValueOnce(null);
+
+ await expect(
+ test.service.get({
+ projectId: "project",
+ name: "test-skill",
+ selector: {},
+ }),
+ ).rejects.toThrow("Skill version not found");
+ expect(test.db.skill.findFirst).toHaveBeenCalledOnce();
+ });
+
it("loads a resource through the batch lookup using its manifest hash", async () => {
const test = setup();
const getFileContents = vi
diff --git a/web/src/features/mcp/server/skills/tools/getSkill.ts b/web/src/features/mcp/server/skills/tools/getSkill.ts
index 31a953c0a8..08e8724564 100644
--- a/web/src/features/mcp/server/skills/tools/getSkill.ts
+++ b/web/src/features/mcp/server/skills/tools/getSkill.ts
@@ -17,7 +17,7 @@ const GetSkillInputSchema = z
export const [getSkillTool, handleGetSkill] = defineTool({
name: "getSkill",
description:
- "Get skill metadata and file paths, without file contents. Select a version or label; defaults to production. Use the returned version with loadSkill and loadSkillResource to read files from the same immutable version.",
+ "Get skill metadata and file paths, without file contents. Version and label are optional; defaults to production, or latest if no production label is set. Use the returned version with loadSkill and loadSkillResource to read files from the same immutable version.",
action: "skills:read",
baseSchema: GetSkillBaseSchema,
inputSchema: GetSkillInputSchema,
@@ -30,6 +30,7 @@ export const [getSkillTool, handleGetSkill] = defineTool({
projectId: context.projectId,
name,
selector,
+ fallbackToLatest: true,
}),
}),
readOnlyHint: true,
diff --git a/web/src/features/mcp/server/skills/tools/loadSkill.ts b/web/src/features/mcp/server/skills/tools/loadSkill.ts
index 83b0422c5d..fb632771c9 100644
--- a/web/src/features/mcp/server/skills/tools/loadSkill.ts
+++ b/web/src/features/mcp/server/skills/tools/loadSkill.ts
@@ -17,7 +17,7 @@ const LoadSkillInputSchema = z
export const [loadSkillTool, handleLoadSkill] = defineTool({
name: "loadSkill",
description:
- "Read a skill's SKILL.md as text. Select a version or label; defaults to production. Reuse the version returned by getSkill when loading multiple files.",
+ "Read a skill's SKILL.md as text. Version and label are optional; defaults to production, or latest if no production label is set. Reuse the version returned by getSkill when loading multiple files.",
action: "skills:read",
baseSchema: LoadSkillBaseSchema,
inputSchema: LoadSkillInputSchema,
@@ -30,6 +30,7 @@ export const [loadSkillTool, handleLoadSkill] = defineTool({
projectId: context.projectId,
name,
selector,
+ fallbackToLatest: true,
path: "SKILL.md",
}),
}),
diff --git a/web/src/features/mcp/server/skills/tools/loadSkillResource.ts b/web/src/features/mcp/server/skills/tools/loadSkillResource.ts
index 70b1804a39..c30691f071 100644
--- a/web/src/features/mcp/server/skills/tools/loadSkillResource.ts
+++ b/web/src/features/mcp/server/skills/tools/loadSkillResource.ts
@@ -22,7 +22,7 @@ const LoadSkillResourceInputSchema = z
export const [loadSkillResourceTool, handleLoadSkillResource] = defineTool({
name: "loadSkillResource",
description:
- "Read a skill file as text by path (see getSkill). Select a version or label; defaults to production. Reuse the version returned by getSkill when loading multiple files.",
+ "Read a skill file as text by path (see getSkill). Version and label are optional; defaults to production, or latest if no production label is set. Reuse the version returned by getSkill when loading multiple files.",
action: "skills:read",
baseSchema: LoadSkillResourceBaseSchema,
inputSchema: LoadSkillResourceInputSchema,
@@ -35,6 +35,7 @@ export const [loadSkillResourceTool, handleLoadSkillResource] = defineTool({
projectId: context.projectId,
name,
selector,
+ fallbackToLatest: true,
path,
}),
}),
diff --git a/web/src/features/skills/server/skill-service.ts b/web/src/features/skills/server/skill-service.ts
index a2f01cb429..8e390468c7 100644
--- a/web/src/features/skills/server/skill-service.ts
+++ b/web/src/features/skills/server/skill-service.ts
@@ -260,6 +260,8 @@ export class SkillService {
projectId: string;
name: string;
selector: SkillSelector;
+ /** Use latest when no selector is supplied and production is unset. */
+ fallbackToLatest?: boolean;
includeContent?: boolean;
}) {
const skill = await this.findSkillVersion(params);
@@ -286,6 +288,8 @@ export class SkillService {
projectId: string;
name: string;
selector: SkillSelector;
+ /** Use latest when no selector is supplied and production is unset. */
+ fallbackToLatest?: boolean;
path: string;
}): Promise<string> {
const skill = await this.findSkillVersion(params);
@@ -944,6 +948,7 @@ export class SkillService {
projectId: string;
name: string;
selector: SkillSelector;
+ fallbackToLatest?: boolean;
}): Promise<SkillWithRelations> {
const selectorWhere: Prisma.SkillWhereInput = params.selector.version
? { version: params.selector.version }
@@ -958,6 +963,17 @@ export class SkillService {
orderBy: { version: "desc" },
include: skillFilesInclude,
});
+ if (
+ !skill &&
+ params.fallbackToLatest &&
+ params.selector.version === undefined &&
+ params.selector.label === undefined
+ ) {
+ return this.findSkillVersion({
+ ...params,
+ selector: { label: SKILL_LATEST_LABEL },
+ });
+ }
if (!skill) throw new LangfuseNotFoundError("Skill version not found");
return skill;
}