@render-harness/cap-search-exa 0.1.1

package/README.md

@@ -0,0 +1,18 @@
+## @render-harness/cap-search-exa
+
+Wires Exa web search into a Render harness entry. Drop into `render-harness.yaml`:
+
+```yaml
+capabilities:
+  - pack: "@render-harness/cap-search-exa"
+    config:
+      defaultMaxResults: 10
+```
+
+Set `EXA_API_KEY` in the entry's environment.
+
+The pack contributes:
+
+- An MCP server `cap-search-exa.exa` (HTTP transport) talking to Exa's hosted MCP.
+- A skill (`web-search-exa`) describing when to use Exa.
+- An `EXA_API_KEY` entry in the effective env schema.

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import * as _render_harness_registry from '@render-harness/registry';
+
+/**
+ * cap-search-exa — wires up Exa's hosted MCP server (https://exa.ai)
+ * for any harness entry that wants high-recall web search.
+ *
+ * Usage in render-harness.yaml:
+ *
+ *   capabilities:
+ *     - pack: "@render-harness/cap-search-exa"
+ *       version: "^0.1"
+ *       config:
+ *         defaultMaxResults: 10
+ *
+ * Surfaces:
+ *   - One MCP server (HTTP transport) named "exa" — namespaced by the
+ *     loader to "cap-search-exa.exa".
+ *   - One skill (skills/web-search-exa.md) explaining when to reach
+ *     for Exa vs other tools.
+ *   - envSchema entry for EXA_API_KEY.
+ *
+ * Config keys:
+ *   - `apiKeyEnv` (string, default "EXA_API_KEY") — env var name to
+ *     read for the bearer token. Override if the entry already has
+ *     another env var holding the key.
+ *   - `baseUrl` (string, default "https://mcp.exa.ai/mcp") — override
+ *     for self-hosted or staging Exa MCP endpoints.
+ *   - `defaultMaxResults` (number) — passed through to Exa's tool args
+ *     by way of an "Exa-Default-Max-Results" header. Optional.
+ */
+declare const pack: _render_harness_registry.CapabilityPack;
+
+export { pack as default };

package/dist/index.js

@@ -0,0 +1,65 @@
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { definePack } from '@render-harness/registry';
+
+// src/index.ts
+var HERE = dirname(fileURLToPath(import.meta.url));
+var SKILLS_DIR = join(HERE, "..", "skills");
+function readConfig(ctx) {
+  const cfg = ctx.config;
+  return {
+    apiKeyEnv: cfg.apiKeyEnv ?? "EXA_API_KEY",
+    baseUrl: cfg.baseUrl ?? "https://mcp.exa.ai/mcp",
+    ...cfg.defaultMaxResults !== void 0 ? { defaultMaxResults: cfg.defaultMaxResults } : {}
+  };
+}
+var pack = definePack({
+  name: "cap-search-exa",
+  version: "0.1.0",
+  envSchema: [
+    {
+      name: "EXA_API_KEY",
+      required: true,
+      secret: true,
+      description: "API key for Exa search (https://exa.ai). Used as a bearer token to the Exa MCP."
+    }
+  ],
+  mcpServers(ctx) {
+    const cfg = readConfig(ctx);
+    const apiKey = ctx.env(cfg.apiKeyEnv);
+    if (!apiKey) {
+      throw new Error(
+        `cap-search-exa: env var ${cfg.apiKeyEnv} is not set. Set it before building or starting the agent.`
+      );
+    }
+    const headers = {
+      Authorization: `Bearer ${apiKey}`
+    };
+    if (cfg.defaultMaxResults !== void 0) {
+      headers["Exa-Default-Max-Results"] = String(cfg.defaultMaxResults);
+    }
+    return [
+      {
+        name: "exa",
+        transport: "http",
+        url: cfg.baseUrl,
+        headers
+      }
+    ];
+  },
+  skills(_ctx) {
+    return [
+      {
+        name: "web-search-exa",
+        description: "Use Exa for high-recall, neural web search.",
+        whenToUse: "When you need fresh web context, comparison shopping, or to find specific facts not in your training data. Prefer this over fetch_url unless you already have a specific URL.",
+        contentPath: join(SKILLS_DIR, "web-search-exa.md")
+      }
+    ];
+  }
+});
+var src_default = pack;
+
+export { src_default as default };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;;;AAkCA,IAAM,IAAA,GAAO,OAAA,CAAQ,aAAA,CAAc,MAAA,CAAA,IAAA,CAAY,GAAG,CAAC,CAAA;AAEnD,IAAM,UAAA,GAAa,IAAA,CAAK,IAAA,EAAM,IAAA,EAAM,QAAQ,CAAA;AAQ5C,SAAS,WAAW,GAAA,EAAkF;AACpG,EAAA,MAAM,MAAM,GAAA,CAAI,MAAA;AAChB,EAAA,OAAO;AAAA,IACL,SAAA,EAAW,IAAI,SAAA,IAAa,aAAA;AAAA,IAC5B,OAAA,EAAS,IAAI,OAAA,IAAW,wBAAA;AAAA,IACxB,GAAI,IAAI,iBAAA,KAAsB,MAAA,GAAY,EAAE,iBAAA,EAAmB,GAAA,CAAI,iBAAA,EAAkB,GAAI;AAAC,GAC5F;AACF;AAEA,IAAM,OAAO,UAAA,CAAW;AAAA,EACtB,IAAA,EAAM,gBAAA;AAAA,EACN,OAAA,EAAS,OAAA;AAAA,EACT,SAAA,EAAW;AAAA,IACT;AAAA,MACE,IAAA,EAAM,aAAA;AAAA,MACN,QAAA,EAAU,IAAA;AAAA,MACV,MAAA,EAAQ,IAAA;AAAA,MACR,WAAA,EAAa;AAAA;AACf,GACF;AAAA,EACA,WAAW,GAAA,EAAqC;AAC9C,IAAA,MAAM,GAAA,GAAM,WAAW,GAAG,CAAA;AAC1B,IAAA,MAAM,MAAA,GAAS,GAAA,CAAI,GAAA,CAAI,GAAA,CAAI,SAAS,CAAA;AACpC,IAAA,IAAI,CAAC,MAAA,EAAQ;AAGX,MAAA,MAAM,IAAI,KAAA;AAAA,QACR,CAAA,wBAAA,EAA2B,IAAI,SAAS,CAAA,0DAAA;AAAA,OAC1C;AAAA,IACF;AACA,IAAA,MAAM,OAAA,GAAkC;AAAA,MACtC,aAAA,EAAe,UAAU,MAAM,CAAA;AAAA,KACjC;AACA,IAAA,IAAI,GAAA,CAAI,sBAAsB,MAAA,EAAW;AACvC,MAAA,OAAA,CAAQ,yBAAyB,CAAA,GAAI,MAAA,CAAO,GAAA,CAAI,iBAAiB,CAAA;AAAA,IACnE;AACA,IAAA,OAAO;AAAA,MACL;AAAA,QACE,IAAA,EAAM,KAAA;AAAA,QACN,SAAA,EAAW,MAAA;AAAA,QACX,KAAK,GAAA,CAAI,OAAA;AAAA,QACT;AAAA;AACF,KACF;AAAA,EACF,CAAA;AAAA,EACA,OAAO,IAAA,EAAoC;AACzC,IAAA,OAAO;AAAA,MACL;AAAA,QACE,IAAA,EAAM,gBAAA;AAAA,QACN,WAAA,EAAa,6CAAA;AAAA,QACb,SAAA,EACE,+KAAA;AAAA,QACF,WAAA,EAAa,IAAA,CAAK,UAAA,EAAY,mBAAmB;AAAA;AACnD,KACF;AAAA,EACF;AACF,CAAC,CAAA;AAED,IAAO,WAAA,GAAQ","file":"index.js","sourcesContent":["/**\n * cap-search-exa — wires up Exa's hosted MCP server (https://exa.ai)\n * for any harness entry that wants high-recall web search.\n *\n * Usage in render-harness.yaml:\n *\n *   capabilities:\n *     - pack: \"@render-harness/cap-search-exa\"\n *       version: \"^0.1\"\n *       config:\n *         defaultMaxResults: 10\n *\n * Surfaces:\n *   - One MCP server (HTTP transport) named \"exa\" — namespaced by the\n *     loader to \"cap-search-exa.exa\".\n *   - One skill (skills/web-search-exa.md) explaining when to reach\n *     for Exa vs other tools.\n *   - envSchema entry for EXA_API_KEY.\n *\n * Config keys:\n *   - `apiKeyEnv` (string, default \"EXA_API_KEY\") — env var name to\n *     read for the bearer token. Override if the entry already has\n *     another env var holding the key.\n *   - `baseUrl` (string, default \"https://mcp.exa.ai/mcp\") — override\n *     for self-hosted or staging Exa MCP endpoints.\n *   - `defaultMaxResults` (number) — passed through to Exa's tool args\n *     by way of an \"Exa-Default-Max-Results\" header. Optional.\n */\n\nimport { dirname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { definePack, type PackContext } from \"@render-harness/registry\";\nimport type { McpServerConfig, SkillMetadata } from \"@render-harness/core\";\n\nconst HERE = dirname(fileURLToPath(import.meta.url));\n// dist/ is one level under the package root, so skills/ is one above.\nconst SKILLS_DIR = join(HERE, \"..\", \"skills\");\n\ninterface ExaConfig {\n  apiKeyEnv?: string;\n  baseUrl?: string;\n  defaultMaxResults?: number;\n}\n\nfunction readConfig(ctx: PackContext): Required<Pick<ExaConfig, \"apiKeyEnv\" | \"baseUrl\">> & ExaConfig {\n  const cfg = ctx.config as ExaConfig;\n  return {\n    apiKeyEnv: cfg.apiKeyEnv ?? \"EXA_API_KEY\",\n    baseUrl: cfg.baseUrl ?? \"https://mcp.exa.ai/mcp\",\n    ...(cfg.defaultMaxResults !== undefined ? { defaultMaxResults: cfg.defaultMaxResults } : {}),\n  };\n}\n\nconst pack = definePack({\n  name: \"cap-search-exa\",\n  version: \"0.1.0\",\n  envSchema: [\n    {\n      name: \"EXA_API_KEY\",\n      required: true,\n      secret: true,\n      description: \"API key for Exa search (https://exa.ai). Used as a bearer token to the Exa MCP.\",\n    },\n  ],\n  mcpServers(ctx: PackContext): McpServerConfig[] {\n    const cfg = readConfig(ctx);\n    const apiKey = ctx.env(cfg.apiKeyEnv);\n    if (!apiKey) {\n      // Fail loud at build time / boot time so users notice immediately\n      // rather than getting a broken agent in production.\n      throw new Error(\n        `cap-search-exa: env var ${cfg.apiKeyEnv} is not set. Set it before building or starting the agent.`,\n      );\n    }\n    const headers: Record<string, string> = {\n      Authorization: `Bearer ${apiKey}`,\n    };\n    if (cfg.defaultMaxResults !== undefined) {\n      headers[\"Exa-Default-Max-Results\"] = String(cfg.defaultMaxResults);\n    }\n    return [\n      {\n        name: \"exa\",\n        transport: \"http\",\n        url: cfg.baseUrl,\n        headers,\n      },\n    ];\n  },\n  skills(_ctx: PackContext): SkillMetadata[] {\n    return [\n      {\n        name: \"web-search-exa\",\n        description: \"Use Exa for high-recall, neural web search.\",\n        whenToUse:\n          \"When you need fresh web context, comparison shopping, or to find specific facts not in your training data. Prefer this over fetch_url unless you already have a specific URL.\",\n        contentPath: join(SKILLS_DIR, \"web-search-exa.md\"),\n      },\n    ];\n  },\n});\n\nexport default pack;\n"]}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@render-harness/cap-search-exa",
+  "version": "0.1.1",
+  "description": "Exa web-search capability pack for the Render agent harness.",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "keywords": [
+    "render-harness-cap",
+    "render-harness",
+    "exa",
+    "search",
+    "mcp"
+  ],
+  "renderHarness": {
+    "gallery": {
+      "label": "Exa web search",
+      "envHint": "EXA_API_KEY"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "@render-harness/registry": "workspace:*"
+  },
+  "devDependencies": {
+    "@render-harness/core": "workspace:*",
+    "@types/node": "^25.6.2",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/web-search-exa.md

@@ -0,0 +1,30 @@
+---
+name: web-search-exa
+description: Use Exa for high-recall, neural web search.
+when_to_use: When you need fresh web context, comparison shopping, or to find specific facts not in your training data. Prefer this over fetch_url unless you already have a specific URL.
+---
+
+# Web search with Exa
+
+Exa is a neural search engine optimized for high-recall retrieval over the open web. The `cap-search-exa.exa` MCP exposes Exa's tool set; the most useful tools are:
+
+- `web_search_exa` — returns ranked results for a free-form query, with title, URL, and a relevance-scored snippet.
+- `crawl_url` — fetches the body of a single page.
+
+## When to use Exa
+
+- The user asks about something time-sensitive (current pricing, recent releases, announcements).
+- You need a citation or a quote from a specific source.
+- You're trying to find a project, library, or company by description.
+
+## When not to use Exa
+
+- The user is asking about their own Render account — use the Render MCP instead.
+- You already have the exact URL — use `crawl_url` directly.
+- The question is conceptual and doesn't need a fresh source.
+
+## Tips
+
+- Keep queries short and specific; Exa is neural, so concept-style queries work well.
+- If you want results from a specific time window, set the `startPublishedDate` argument.
+- Always cite the URL you used in your final answer.