@exposify/express 0.3.2 → 0.3.3

package/README.md

@@ -0,0 +1,94 @@
+# @exposify/express — setup guide
+
+Turn an existing Express app into an MCP server in one line: an
+auto-generated **MCP endpoint** at `/mcp` lets AI agents (Claude, Cursor,
+ChatGPT, or anything else speaking MCP) call your routes as tools, and an
+embedded **knowledge base** built from your README/docs lets them understand
+your product. No external services, no build step.
+
+```ts
+import { aiReady } from "@exposify/express";
+
+app.use(aiReady()); // MCP endpoint live at /mcp
+```
+
+Auth is **passthrough**: every tool call carries exactly the caller's own
+credentials (`Authorization`/`Cookie`), forwarded to your routes unchanged.
+There is no separate authorization layer to configure or get wrong — an
+agent can do exactly what the person it's acting for could already do.
+
+## Exposure policy
+
+- **Reads (GET/HEAD) are exposed automatically.** Writes are hidden by
+  default — opt them in explicitly, right where the route is defined:
+
+```ts
+import { aiReady, exposed, describe } from "@exposify/express";
+import { z } from "zod";
+
+app.post("/orders", exposed(createOrder));
+
+// Or opt in while also enriching the tool's name/description/input schema:
+app.post("/orders/:id/refund", describe(refundOrder, {
+  name: "refund_order",
+  description: "Refund an order. Reversible within 30 days.",
+  input: { id: z.string(), body: z.object({ reason: z.string() }) },
+}));
+```
+
+- **`describe()`'s `input` envelope contract:** `input` is a flat Zod shape.
+  At call time, each top-level key is routed by name — a key matching one of
+  the route's `:param` segments becomes a path substitution, `query`
+  (expected to be an object) becomes the query string, `body` becomes the
+  JSON request body. Any other top-level key is silently dropped and never
+  reaches the route (a one-time warning is logged per tool at registration
+  if this happens) — nest fields under `body` or `query` instead of putting
+  them at the top level.
+
+## Mounted routers
+
+Routers mounted with `app.use(path, router)` **after** `aiReady()` (the
+standard layout above) are discovered automatically on both Express 4 and 5.
+Anything mounted *before* `aiReady()`, or a sub-app (Express can't
+distinguish a sub-app from arbitrary middleware), needs an explicit entry:
+
+```ts
+app.use(aiReady({ mounts: { "/legacy": legacyRouter } }));
+```
+
+## Options
+
+```ts
+aiReady({
+  auth?: "passthrough" | "none",        // default "passthrough"
+  docs?: string[],                       // default ["README.md", "docs/**/*.md"]
+  expose?: string[] | "*",               // e.g. ["GET /trends"]; default unset
+  exclude?: string[],                    // picomatch globs against the route path
+  docsAuth?: "public" | "required",      // default "public"
+  embedder?: (texts: string[]) => Promise<number[][]>,
+  telemetry?: { enabled: boolean; sink?(event): void; capturePayloads?: boolean },
+  cwd?: string,                          // default process.cwd()
+  mounts?: Record<string, unknown>,      // explicit router/sub-app overrides
+});
+```
+
+Exposure precedence: an `exposed()`/`hidden()`/`describe()` marker on a
+route always wins, then `exclude`, then `expose`, then the read/write
+default above.
+
+## Known limitations
+
+- **Sub-apps** (`app.use(path, subApp)`) are never auto-detected on any
+  Express version — always list them in `mounts` explicitly.
+- **Express 5** can't reflect a mounted router's own path, so auto-discovery
+  only works when `aiReady()` is registered *before* the mount. A router
+  mounted both before and after `aiReady()` ("straddle" mount) resolves
+  correctly on Express 4 but silently drops the earlier prefix on Express 5.
+- In-process dispatch uses `light-my-request`, which splices Express's
+  process-wide request/response prototypes for the duration of each
+  dispatch — a narrow concurrency window under real concurrent traffic, a
+  known tradeoff tracked in `packages/express/src/surface.ts`.
+
+See the [repo README](https://github.com/ayadagain/agentready#readme) for
+the full picture across all `@exposify/*` packages, including
+`@exposify/supabase`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exposify/express",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -23,7 +23,7 @@
     "prepack": "yarn build"
   },
   "dependencies": {
-    "@exposify/core": "0.3.2",
+    "@exposify/core": "1.0.0",
     "light-my-request": "^6.0.0"
   },
   "peerDependencies": {
@@ -52,9 +52,13 @@
   "bugs": {
     "url": "https://github.com/ayadagain/agentready/issues"
   },
-  "description": "test",
+  "description": "Turn an Express app into an MCP server in one line: routes become AI agent tools automatically, writes are opt-in, and the caller's own credentials pass straight through.",
   "author": "Exposify",
   "keywords": [
-    "aa"
+    "mcp",
+    "model-context-protocol",
+    "express",
+    "ai-agents",
+    "llm-tools"
   ]
 }