Skip to content

A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source and free forever. Try it out today!

feat: publish integration discovery documents (#3628)

Amruth Pillaiaaf37a0d002e
diff --git a/apps/server/src/http/app.test.ts b/apps/server/src/http/app.test.ts
index fcdd7ef2c..b3de3a9fe 100644
--- a/apps/server/src/http/app.test.ts
+++ b/apps/server/src/http/app.test.ts
@@ -7,12 +7,15 @@ const mocks = vi.hoisted(() => ({
handleOAuth: vi.fn(),
handleRpc: vi.fn(),
handleOpenApi: vi.fn(),
+ handleOpenApiDocument: vi.fn(),
handleHealth: vi.fn(),
handleUpload: vi.fn(),
handleMcp: vi.fn(),
handleResumePdfDownload: vi.fn(),
handlePublicResumePdf: vi.fn(),
handleMcpServerCard: vi.fn(),
+ handleIntegrations: vi.fn(),
+ handleApiCatalog: vi.fn(),
handleOAuthAuthorizationServer: vi.fn(),
handleOAuthProtectedResource: vi.fn(),
handleOpenIdConfiguration: vi.fn(),
@@ -44,10 +47,13 @@ vi.mock("../rpc/handler", () => ({
vi.mock("../openapi/handler", () => ({
handleOpenApi: mocks.handleOpenApi,
+ handleOpenApiDocument: mocks.handleOpenApiDocument,
}));
vi.mock("../openapi/metadata", () => ({
handleMcpServerCard: mocks.handleMcpServerCard,
+ handleIntegrations: mocks.handleIntegrations,
+ handleApiCatalog: mocks.handleApiCatalog,
handleOAuthAuthorizationServer: mocks.handleOAuthAuthorizationServer,
handleOAuthProtectedResource: mocks.handleOAuthProtectedResource,
handleOpenIdConfiguration: mocks.handleOpenIdConfiguration,
@@ -99,6 +105,9 @@ beforeEach(() => {
mocks.handleResumePdfDownload.mockResolvedValue(new Response("pdf"));
mocks.handlePublicResumePdf.mockResolvedValue(new Response("public-pdf"));
mocks.handleMcpServerCard.mockReturnValue(new Response("server-card"));
+ mocks.handleIntegrations.mockReturnValue(new Response("integrations"));
+ mocks.handleApiCatalog.mockReturnValue(new Response("api-catalog"));
+ mocks.handleOpenApiDocument.mockResolvedValue(new Response("openapi-document"));
mocks.handleOAuthAuthorizationServer.mockReturnValue(new Response("oauth-authorization-server"));
mocks.handleOAuthProtectedResource.mockReturnValue(new Response("oauth-protected-resource"));
mocks.handleOpenIdConfiguration.mockReturnValue(new Response("openid-configuration"));
@@ -191,6 +200,20 @@ describe("createApp", () => {
expect(mocks.handleOpenApi).toHaveBeenNthCalledWith(2, unknownOpenApiRequest, "unknown");
});
+ it.each([
+ ["/openapi.json", "openapi-document"],
+ ["/.well-known/integrations.json", "integrations"],
+ ["/.well-known/api-catalog", "api-catalog"],
+ ["/.well-known/mcp/server-card.json", "server-card"],
+ ])("routes discovery document %s before the well-known fallback", async (path, body) => {
+ const { createApp } = await import("./app");
+
+ const response = await createApp().fetch(new Request(`http://localhost:3001${path}`));
+
+ expect(await response.text()).toBe(body);
+ expect(mocks.handleWellKnownFallback).not.toHaveBeenCalled();
+ });
+
it("routes GET / to the web app before static files", async () => {
const { createApp } = await import("./app");
const app = createApp();
diff --git a/apps/server/src/http/app.ts b/apps/server/src/http/app.ts
index 6795ac589..5115ee92e 100644
--- a/apps/server/src/http/app.ts
+++ b/apps/server/src/http/app.ts
@@ -10,8 +10,10 @@ import { prepareStagedBody, withStagedBody } from "@reactive-resume/api/features
import { env } from "@reactive-resume/env/server";
import { prepareMcpDiscovery } from "@reactive-resume/mcp";
import { handleMcp } from "../mcp/handler";
-import { handleOpenApi } from "../openapi/handler";
+import { handleOpenApi, handleOpenApiDocument } from "../openapi/handler";
import {
+ handleApiCatalog,
+ handleIntegrations,
handleMcpServerCard,
handleOAuthAuthorizationServer,
handleOAuthProtectedResource,
@@ -20,6 +22,7 @@ import {
handleWellKnownFallback,
} from "../openapi/metadata";
import { handleRpc } from "../rpc/handler";
+import { handleAgentSkillArchive, handleAgentSkillsIndex } from "../static/agent-skills";
import { handleSchemaJson } from "../static/schema";
import { handleLlms, handleRobots, handleSitemap } from "../static/seo";
import { handleUpload } from "../static/uploads";
@@ -107,9 +110,18 @@ export function createApp(options: AppOptions = {}) {
app.get("/api/uploads/*", (c) => handleUpload(c.req.raw));
app.get("/uploads/*", (c) => handleUpload(c.req.raw));
app.get("/schema.json", () => handleSchemaJson());
+ app.get("/openapi.json", () => handleOpenApiDocument());
app.all("/mcp", (c) => handleMcp(c.req.raw, client(c)));
app.all("/mcp/*", (c) => handleMcp(c.req.raw, client(c)));
+ app.get("/.well-known/integrations.json", () => handleIntegrations());
+ app.on(["GET", "HEAD"], "/.well-known/api-catalog", (c) => handleApiCatalog({ head: c.req.method === "HEAD" }));
+ app.on(["GET", "HEAD"], "/.well-known/agent-skills/index.json", (c) =>
+ handleAgentSkillsIndex({ head: c.req.method === "HEAD" }),
+ );
+ app.on(["GET", "HEAD"], "/.well-known/agent-skills/:filename", (c) =>
+ handleAgentSkillArchive(c.req.param("filename"), { head: c.req.method === "HEAD" }),
+ );
app.get("/.well-known/mcp/server-card.json", () => handleMcpServerCard());
app.get("/.well-known/oauth-authorization-server", (c) => handleOAuthAuthorizationServer(c.req.raw));
app.get("/.well-known/oauth-authorization-server/*", (c) => handleOAuthAuthorizationServer(c.req.raw));
diff --git a/apps/server/src/openapi/handler.ts b/apps/server/src/openapi/handler.ts
index 75ad8eb81..a2d6f1482 100644
--- a/apps/server/src/openapi/handler.ts
+++ b/apps/server/src/openapi/handler.ts
@@ -25,6 +25,13 @@ const openAPIHandler = new OpenAPIHandler(openAPIRouter, {
],
});
+/** The OpenAPI document at its well-known root address, `/openapi.json`, for API discovery tools. */
+export async function handleOpenApiDocument() {
+ return Response.json(await generateOpenApiSpec({ appUrl: env.APP_URL, version: appVersion }), {
+ headers: { "Cache-Control": "public, max-age=3600" },
+ });
+}
+
export async function handleOpenApi(request: Request, trustedClient: string) {
const pathname = new URL(request.url).pathname;
if (request.method === "GET" && ["/api/openapi/spec.json", "/api/openapi/spec"].includes(pathname)) {
diff --git a/apps/server/src/openapi/metadata.test.ts b/apps/server/src/openapi/metadata.test.ts
index ebf622cd6..23da00c1e 100644
--- a/apps/server/src/openapi/metadata.test.ts
+++ b/apps/server/src/openapi/metadata.test.ts
@@ -40,3 +40,59 @@ describe("handleOAuthProtectedResource", () => {
});
});
});
+
+describe("handleMcpServerCard", () => {
+ it("advertises the connect URL and OAuth authorization server", async () => {
+ const { handleMcpServerCard } = await import("./metadata");
+
+ const response = handleMcpServerCard();
+
+ await expect(response.json()).resolves.toMatchObject({
+ url: "https://rxresu.me/mcp",
+ authentication: { type: "oauth2", authorization_server: "https://rxresu.me/api/auth" },
+ });
+ });
+});
+
+describe("handleIntegrations", () => {
+ it("serves a cacheable v3 document whose surfaces reference declared credentials", async () => {
+ const { handleIntegrations } = await import("./metadata");
+
+ const response = handleIntegrations();
+ const document = await response.json();
+
+ expect(response.headers.get("Content-Type")).toBe("application/json");
+ expect(response.headers.get("Cache-Control")).toBe("public, max-age=3600");
+ expect(document).toMatchObject({ version: 3 });
+ expect(document.surfaces.map((surface: { type: string; url: string }) => [surface.type, surface.url])).toEqual([
+ ["http", "https://rxresu.me/api/openapi"],
+ ["mcp", "https://rxresu.me/mcp"],
+ ]);
+
+ const source = "https://rxresu.me/.well-known/integrations.json";
+ for (const surface of document.surfaces) {
+ expect(surface.basis).toEqual({ via: "declared", source });
+ for (const entry of surface.auth.entries) {
+ expect(entry.basis).toEqual({ via: "declared", source });
+ for (const use of entry.use) expect(Object.keys(document.credentials)).toContain(use.id);
+ }
+ }
+ });
+});
+
+describe("handleApiCatalog", () => {
+ it("serves an RFC 9727 linkset for the REST API and MCP server", async () => {
+ const { handleApiCatalog } = await import("./metadata");
+
+ const response = handleApiCatalog();
+ const catalog = await response.json();
+
+ expect(response.headers.get("Content-Type")).toContain("application/linkset+json");
+ expect(catalog.linkset.map((link: { anchor: string }) => link.anchor)).toEqual([
+ "https://rxresu.me/api/openapi",
+ "https://rxresu.me/mcp",
+ ]);
+ expect(catalog.linkset[0]["service-desc"][0].href).toBe("https://rxresu.me/openapi.json");
+ expect(await handleApiCatalog({ head: true }).text()).toBe("");
+ });
+});
diff --git a/apps/server/src/openapi/metadata.ts b/apps/server/src/openapi/metadata.ts
index 6cfd85178..86d1b07b0 100644
--- a/apps/server/src/openapi/metadata.ts
+++ b/apps/server/src/openapi/metadata.ts
@@ -4,9 +4,19 @@ import { env } from "@reactive-resume/env/server";
import { buildMcpServerCard } from "@reactive-resume/mcp/server-card";
import { appVersion } from "../app-version";
+const DOCS_URL = "https://docs.rxresu.me";
+
export const handleOAuthAuthorizationServer = oauthProviderAuthServerMetadata(auth);
export const handleOpenIdConfiguration = oauthProviderOpenIdConfigMetadata(auth);
+function appUrl() {
+ return env.APP_URL.replace(/\/+$/, "");
+}
+
+function authorizationServer() {
+ return `${appUrl()}/api/auth`;
+}
+
export function handleOpenAiAppsChallenge() {
if (!env.OPENAI_APPS_CHALLENGE_TOKEN) return new Response("Not Found", { status: 404 });
return new Response(env.OPENAI_APPS_CHALLENGE_TOKEN, {
@@ -19,19 +29,28 @@ export function handleWellKnownFallback() {
}
export function handleMcpServerCard() {
- return Response.json(buildMcpServerCard(appVersion), {
- headers: {
- "Content-Type": "application/json",
- "Cache-Control": "public, max-age=60, stale-while-revalidate=120",
+ const card = buildMcpServerCard(appVersion);
+
+ return Response.json(
+ {
+ ...card,
+ url: `${appUrl()}/mcp`,
+ authentication: { ...card.authentication, type: "oauth2", authorization_server: authorizationServer() },
},
- });
+ {
+ headers: {
+ "Content-Type": "application/json",
+ "Cache-Control": "public, max-age=60, stale-while-revalidate=120",
+ },
+ },
+ );
}
export function handleOAuthProtectedResource() {
const metadata = {
resource: env.APP_URL,
bearer_methods_supported: ["header"],
- authorization_servers: [`${env.APP_URL}/api/auth`],
+ authorization_servers: [authorizationServer()],
};
return Response.json(metadata, {
@@ -41,3 +60,115 @@ export function handleOAuthProtectedResource() {
},
});
}
+
+/** integrations.sh discovery document (v3): every agent-facing surface of this instance and how it authenticates. */
+function buildIntegrations() {
+ const baseUrl = appUrl();
+ const basis = { via: "declared", source: `${baseUrl}/.well-known/integrations.json` } as const;
+ const apiKey = {
+ id: "api-key",
+ mechanics: { source: "http", in: "header", headerName: "x-api-key" },
+ } as const;
+
+ return {
+ version: 3,
+ summary:
+ "Reactive Resume is a free and open-source resume builder. Agents can read and edit a user's resumes, cover letters and job applications through the REST API or the MCP server.",
+ credentials: {
+ "api-key": {
+ type: "api_key",
+ label: "Reactive Resume API key",
+ generateUrl: `${baseUrl}/dashboard/settings/ai`,
+ setup: [
+ "Open **Settings → AI & developer**, select **New key** in the **API keys** section, name it, choose when it expires, then copy it.",
+ "The key is shown only once and acts as you: anyone holding it can read and edit your documents. Revoke it from the same table when you no longer need it.",
+ "Send it in the `x-api-key` header.",
+ ].join("\n\n"),
+ },
+ oauth: {
+ type: "oauth2",
+ label: "Reactive Resume OAuth",
+ setup: [
+ `OAuth authorization-code flow with dynamic client registration (RFC 7591). Clients discover the authorization server from \`${baseUrl}/.well-known/oauth-protected-resource\` (issuer \`${authorizationServer()}\`).`,
+ "The user signs in to Reactive Resume and approves the client on the consent screen; the resulting access token is sent as `Authorization: Bearer <token>`.",
+ ].join("\n\n"),
+ },
+ },
+ surfaces: [
+ {
+ type: "http",
+ slug: "reactive-resume-api",
+ name: "Reactive Resume REST API",
+ docs: `${DOCS_URL}/guides/using-the-api`,
+ basis,
+ spec: `${baseUrl}/openapi.json`,
+ url: `${baseUrl}/api/openapi`,
+ auth: {
+ status: "required",
+ entries: [
+ { use: [apiKey], basis },
+ {
+ use: [
+ {
+ id: "oauth",
+ mechanics: { source: "http", in: "header", headerName: "Authorization", scheme: "Bearer" },
+ },
+ ],
+ basis,
+ },
+ ],
+ },
+ },
+ {
+ type: "mcp",
+ slug: "reactive-resume-mcp",
+ name: "Reactive Resume MCP server",
+ docs: `${DOCS_URL}/guides/using-the-mcp-server`,
+ basis,
+ url: `${baseUrl}/mcp`,
+ transports: ["streamable-http"],
+ auth: {
+ status: "required",
+ entries: [
+ { use: [{ id: "oauth", mechanics: { source: "well-known" } }], basis },
+ { use: [apiKey], basis },
+ ],
+ },
+ },
+ ],
+ };
+}
+
+export function handleIntegrations() {
+ return Response.json(buildIntegrations(), {
+ headers: { "Content-Type": "application/json", "Cache-Control": "public, max-age=3600" },
+ });
+}
+
+/** RFC 9727 API catalog: the REST API and MCP server, each with its description and documentation. */
+export function handleApiCatalog(options: { head?: boolean } = {}) {
+ const baseUrl = appUrl();
+ const linkset = {
+ linkset: [
+ {
+ anchor: `${baseUrl}/api/openapi`,
+ "service-desc": [{ href: `${baseUrl}/openapi.json`, type: "application/vnd.oai.openapi+json" }],
+ "service-doc": [{ href: `${DOCS_URL}/guides/using-the-api`, type: "text/html" }],
+ status: [{ href: `${baseUrl}/api/health`, type: "application/json" }],
+ },
+ {
+ anchor: `${baseUrl}/mcp`,
+ "service-desc": [{ href: `${baseUrl}/.well-known/mcp/server-card.json`, type: "application/json" }],
+ "service-doc": [{ href: `${DOCS_URL}/guides/using-the-mcp-server`, type: "text/html" }],
+ },
+ ],
+ };
+
+ return new Response(options.head ? null : JSON.stringify(linkset), {
+ headers: {
+ "Content-Type": 'application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727"',
+ "Cache-Control": "public, max-age=3600",
+ Link: `<${baseUrl}/.well-known/api-catalog>; rel="api-catalog"`,
+ },
+ });
+}
diff --git a/apps/server/src/static/agent-skills.test.ts b/apps/server/src/static/agent-skills.test.ts
new file mode 100644
index 000000000..9d983ed77
--- /dev/null
+++ b/apps/server/src/static/agent-skills.test.ts
@@ -0,0 +1,59 @@
+import { createHash } from "node:crypto";
+import { readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { gunzipSync } from "node:zlib";
+import { describe, expect, it } from "vitest";
+import { handleAgentSkillArchive, handleAgentSkillsIndex, loadAgentSkills } from "./agent-skills";
+
+const skillsRoot = fileURLToPath(new URL("../../../../plugins/reactive-resume/skills", import.meta.url));
+
+function listTarEntries(archive: Buffer) {
+ const tar = gunzipSync(archive);
+ const entries: string[] = [];
+ for (let offset = 0; offset + 512 <= tar.length;) {
+ const header = tar.subarray(offset, offset + 512);
+ const name = header.subarray(0, 100).toString("utf8").replace(/\0.*$/s, "");
+ if (!name) break;
+ const size = Number.parseInt(header.subarray(124, 136).toString("utf8").replace(/\0.*$/s, ""), 8);
+ entries.push(name);
+ offset += 512 + Math.ceil(size / 512) * 512;
+ }
+ return entries;
+}
+
+describe("agent skills discovery", () => {
+ it("lists every published skill as an archive whose digest matches the served bytes", async () => {
+ const response = handleAgentSkillsIndex();
+ const index = await response.json();
+
+ expect(response.headers.get("Content-Type")).toBe("application/json");
+ expect(index.$schema).toBe("https://schemas.agentskills.io/discovery/0.2.0/schema.json");
+ expect(index.skills.map((skill: { name: string }) => skill.name)).toEqual(readdirSync(skillsRoot).toSorted());
+
+ for (const skill of index.skills) {
+ expect(skill).toMatchObject({ type: "archive", url: `/.well-known/agent-skills/${skill.name}.tar.gz` });
+ expect(skill.description.length).toBeGreaterThan(0);
+ const archive = handleAgentSkillArchive(`${skill.name}.tar.gz`);
+ expect(archive.headers.get("Content-Type")).toBe("application/gzip");
+ const bytes = Buffer.from(await archive.arrayBuffer());
+ expect(`sha256:${createHash("sha256").update(bytes).digest("hex")}`).toBe(skill.digest);
+ }
+ });
+
+ it("places SKILL.md at the archive root and builds identical bytes each time", () => {
+ const [first] = loadAgentSkills(skillsRoot);
+ const [second] = loadAgentSkills(skillsRoot);
+
+ if (!first) throw new Error("No agent skills found");
+ const entries = listTarEntries(first.archive);
+ expect(entries).toContain("SKILL.md");
+ expect(entries.some((path) => path.startsWith("references/"))).toBe(true);
+ expect(entries.every((path) => !path.startsWith("/") && !path.includes(".."))).toBe(true);
+ expect(second?.digest).toBe(first.digest);
+ });
+
+ it("returns 404 for unknown archives", () => {
+ expect(handleAgentSkillArchive("missing.tar.gz").status).toBe(404);
+ expect(handleAgentSkillArchive("../SKILL.md").status).toBe(404);
+ });
+});
diff --git a/apps/server/src/static/agent-skills.ts b/apps/server/src/static/agent-skills.ts
new file mode 100644
index 000000000..82c16a60b
--- /dev/null
+++ b/apps/server/src/static/agent-skills.ts
@@ -0,0 +1,129 @@
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { gzipSync } from "node:zlib";
+
+const SCHEMA_URL = "https://schemas.agentskills.io/discovery/0.2.0/schema.json";
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const cacheControl = "public, max-age=3600";
+
+type AgentSkill = { name: string; description: string; archive: Buffer; digest: string };
+
+function resolveSkillsRoot() {
+ const candidates = [
+ // Bundled layout: apps/server/dist/*.mjs -> apps/server/dist/agent-skills (emitted by tsdown.config.ts)
+ fileURLToPath(new URL("./agent-skills", import.meta.url)),
+ // Source layout: apps/server/src/static/agent-skills.ts -> plugins/reactive-resume/skills
+ fileURLToPath(new URL("../../../../plugins/reactive-resume/skills", import.meta.url)),
+ ];
+
+ return candidates.find((candidate) => existsSync(candidate));
+}
+
+function listFiles(root: string, prefix = ""): string[] {
+ return readdirSync(join(root, prefix), { withFileTypes: true })
+ .toSorted((a, b) => a.name.localeCompare(b.name))
+ .flatMap((entry) => {
+ const path = prefix ? `${prefix}/${entry.name}` : entry.name;
+ if (entry.isDirectory()) return listFiles(root, path);
+ return entry.isFile() ? [path] : [];
+ });
+}
+
+function tarHeader(path: string, size: number) {
+ const header = Buffer.alloc(512);
+ const field = (value: string, offset: number, length: number) => header.write(value, offset, length, "utf8");
+ const octal = (value: number, offset: number, length: number) =>
+ field(`${value.toString(8).padStart(length - 1, "0")}\0`, offset, length);
+
+ if (Buffer.byteLength(path) > 100) throw new Error(`Agent skill path is too long for a tar header: ${path}`);
+ field(path, 0, 100);
+ octal(0o644, 100, 8);
+ octal(0, 108, 8);
+ octal(0, 116, 8);
+ octal(size, 124, 12);
+ // A fixed modification time keeps the archive, and so its published digest, stable across builds.
+ octal(0, 136, 12);
+ field(" ", 148, 8);
+ field("0", 156, 1);
+ field("ustar\0", 257, 6);
+ field("00", 263, 2);
+
+ const checksum = header.reduce((sum, byte) => sum + byte, 0);
+ field(`${checksum.toString(8).padStart(6, "0")}\0 `, 148, 8);
+ return header;
+}
+
+/** A gzipped ustar archive with the skill's files at its root, as the discovery RFC requires. */
+function buildArchive(directory: string) {
+ const blocks = listFiles(directory).flatMap((path) => {
+ const content = readFileSync(join(directory, path));
+ const padding = Buffer.alloc((512 - (content.length % 512)) % 512);
+ return [tarHeader(path, content.length), content, padding];
+ });
+
+ return gzipSync(Buffer.concat([...blocks, Buffer.alloc(1024)]), { level: 9 });
+}
+
+function readFrontmatterField(markdown: string, key: string) {
+ const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(markdown)?.[1] ?? "";
+ const line = frontmatter.split(/\r?\n/).find((entry) => entry.startsWith(`${key}:`));
+ return line?.slice(key.length + 1).trim();
+}
+
+let skills: AgentSkill[] | undefined;
+
+export function loadAgentSkills(root = resolveSkillsRoot()): AgentSkill[] {
+ if (!root) return [];
+
+ return readdirSync(root, { withFileTypes: true })
+ .filter((entry) => entry.isDirectory() && existsSync(join(root, entry.name, "SKILL.md")))
+ .toSorted((a, b) => a.name.localeCompare(b.name))
+ .flatMap((entry) => {
+ const directory = join(root, entry.name);
+ const markdown = readFileSync(join(directory, "SKILL.md"), "utf8");
+ const name = readFrontmatterField(markdown, "name");
+ const description = readFrontmatterField(markdown, "description");
+ if (!name || name !== entry.name || !SKILL_NAME.test(name) || !description) return [];
+
+ const archive = buildArchive(directory);
+ const digest = `sha256:${createHash("sha256").update(archive).digest("hex")}`;
+ return [{ name, description, archive, digest }];
+ });
+}
+
+function getAgentSkills() {
+ skills ??= loadAgentSkills();
+ return skills;
+}
+
+export function handleAgentSkillsIndex(options: { head?: boolean } = {}) {
+ const index = {
+ $schema: SCHEMA_URL,
+ skills: getAgentSkills().map(({ name, description, digest }) => ({
+ name,
+ type: "archive",
+ description,
+ url: `/.well-known/agent-skills/${name}.tar.gz`,
+ digest,
+ })),
+ };
+
+ return new Response(options.head ? null : JSON.stringify(index), {
+ headers: { "Content-Type": "application/json", "Cache-Control": cacheControl },
+ });
+}
+
+export function handleAgentSkillArchive(filename: string, options: { head?: boolean } = {}) {
+ const skill = getAgentSkills().find(({ name }) => `${name}.tar.gz` === filename);
+ if (!skill) return new Response("Not Found", { status: 404, headers: { "Cache-Control": "no-store" } });
+
+ return new Response(options.head ? null : new Uint8Array(skill.archive), {
+ headers: {
+ "Content-Type": "application/gzip",
+ "Content-Length": String(skill.archive.length),
+ "Cache-Control": cacheControl,
+ },
+ });
+}
diff --git a/apps/server/src/static/seo.ts b/apps/server/src/static/seo.ts
index fe06a21d0..c12b73425 100644
--- a/apps/server/src/static/seo.ts
+++ b/apps/server/src/static/seo.ts
@@ -27,6 +27,11 @@ export function handleRobots(options?: StaticSeoOptions) {
"Disallow: /api/auth",
"Disallow: /mcp",
"Disallow: /.well-known",
+ // Discovery documents meant for agents and API directories.
+ "Allow: /.well-known/integrations.json",
+ "Allow: /.well-known/api-catalog",
+ "Allow: /.well-known/mcp/server-card.json",
+ "Allow: /.well-known/agent-skills/",
"",
`Sitemap: ${baseUrl}/sitemap.xml`,
`Sitemap: ${DOCS_URL}/sitemap.xml`,
@@ -93,9 +98,11 @@ export function handleLlms(options?: StaticSeoOptions) {
`- [Documentation llms.txt](${DOCS_URL}/llms.txt)`,
`- [Self-hosting with Docker](${DOCS_URL}/self-hosting/docker)`,
`- [API reference](${DOCS_URL}/api-reference)`,
- `- [OpenAPI specification](${baseUrl}/api/openapi/spec.json)`,
+ `- [OpenAPI specification](${baseUrl}/openapi.json)`,
`- [Resume JSON schema](${baseUrl}/schema.json)`,
- `- [MCP server guide](${DOCS_URL}/guides/using-the-mcp-server)`,
+ `- [MCP server guide](${DOCS_URL}/guides/using-the-mcp-server): connect any MCP client to ${baseUrl}/mcp with OAuth or an API key.`,
+ `- [Agent skills](${DOCS_URL}/guides/using-agent-skills): eight job-search skills, also listed at ${baseUrl}/.well-known/agent-skills/index.json.`,
+ `- [Integrations](${baseUrl}/.well-known/integrations.json): every API and MCP surface with its authentication.`,
"",
"## Community",
"",
diff --git a/apps/server/tsdown.config.ts b/apps/server/tsdown.config.ts
index bd0141970..5ed083819 100644
--- a/apps/server/tsdown.config.ts
+++ b/apps/server/tsdown.config.ts
@@ -1,6 +1,6 @@
import type { TsdownPlugin } from "tsdown";
import { readdirSync, readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { defineConfig } from "tsdown";
@@ -80,6 +80,25 @@ const promptAssetsPlugin: TsdownPlugin = {
},
};
+const agentSkillsDir = resolve(dirname(fileURLToPath(import.meta.url)), "../../plugins/reactive-resume/skills");
+
+// Copies the published agent skills beside the bundle; src/static/agent-skills.ts archives them for discovery.
+const agentSkillAssetsPlugin: TsdownPlugin = {
+ name: "agent-skill-assets",
+ buildStart() {
+ for (const entry of readdirSync(agentSkillsDir, { recursive: true, withFileTypes: true })) {
+ if (!entry.isFile()) continue;
+ const path = join(entry.parentPath, entry.name);
+
+ this.emitFile({
+ type: "asset",
+ fileName: `agent-skills/${relative(agentSkillsDir, path).split("\\").join("/")}`,
+ source: readFileSync(path),
+ });
+ }
+ },
+};
+
export default defineConfig({
entry: {
index: "src/index.ts",
@@ -105,5 +124,5 @@ export default defineConfig({
alwaysBundle: shouldBundle,
neverBundle: shouldExternalizeThirdParty,
},
- plugins: [promptAssetsPlugin],
+ plugins: [promptAssetsPlugin, agentSkillAssetsPlugin],
});
diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
index 2aaa3e72f..a477daec1 100644
--- a/apps/web/vite.config.ts
+++ b/apps/web/vite.config.ts
@@ -63,7 +63,7 @@ async function prerenderPages() {
const linguiPlugin = () =>
lingui({ macroTransform: { parser: { syntax: "typescript", tsx: true, decorators: true } } });
-const serverPaths = ["/api", "/mcp", "/uploads", "/.well-known", "/schema.json"] as const;
+const serverPaths = ["/api", "/mcp", "/uploads", "/.well-known", "/schema.json", "/openapi.json"] as const;
const serverProxy = serverPaths.reduce(
(acc, path) => {
diff --git a/vercel.json b/vercel.json
index 859333f90..a4bb61813 100644
--- a/vercel.json
+++ b/vercel.json
@@ -17,7 +17,7 @@
"functions": {
"vercel.mjs": {
"maxDuration": 300,
- "includeFiles": "{apps/web/dist/index.html,apps/web/dist-prerender/**,apps/server/dist/prompts/**}"
+ "includeFiles": "{apps/web/dist/index.html,apps/web/dist-prerender/**,apps/server/dist/prompts/**,apps/server/dist/agent-skills/**}"
}
}
}
@@ -28,7 +28,7 @@
{ "source": "/mcp(/.*)?", "destination": { "service": "backend" } },
{ "source": "/\\.well-known(/.*)?", "destination": { "service": "backend" } },
{
- "source": "/(index\\.html|robots\\.txt|sitemap\\.xml|llms\\.txt|schema\\.json)",
+ "source": "/(index\\.html|robots\\.txt|sitemap\\.xml|llms\\.txt|schema\\.json|openapi\\.json)",
"destination": { "service": "backend" }
},
{ "source": "/(.*\\.[^/]+)", "destination": { "service": "frontend" } },