@lynq/lynq 0.2.0 → 0.4.0

package/README.md

@@ -1,181 +1,121 @@
 # lynq
 
 [![CI](https://github.com/hogekai/lynq/actions/workflows/ci.yml/badge.svg)](https://github.com/hogekai/lynq/actions/workflows/ci.yml)
-[![npm](https://img.shields.io/npm/v/lynq)](https://www.npmjs.com/package/lynq)
+[![npm](https://img.shields.io/npm/v/@lynq/lynq)](https://www.npmjs.com/package/@lynq/lynq)
 
-Lightweight MCP server framework. Tool visibility control through middleware.
+MCP servers are stateless by default. lynq makes them session-aware.
 
-```ts
-import { createMCPServer } from "lynq";
-import { auth } from "lynq/auth";
-import { z } from "zod";
+## The Problem
 
-const server = createMCPServer({ name: "my-server", version: "1.0.0" });
+With the official SDK, adding session-aware tool visibility requires manual plumbing:
 
-// Login tool — always visible
-server.tool("login", {
-  input: z.object({ username: z.string(), password: z.string() }),
-}, async (args, ctx) => {
-  const user = await authenticate(args.username, args.password);
-  ctx.session.set("user", user);
-  ctx.session.authorize("auth");
-  return { content: [{ type: "text", text: `Welcome, ${user.name}` }] };
+```ts
+// Without lynq — manual session tracking, manual notifications
+const sessions = new Map();
+
+server.setRequestHandler(ListToolsRequestSchema, (req, extra) => {
+  const session = sessions.get(extra.sessionId);
+  const tools = [loginTool];
+  if (session?.authorized) tools.push(weatherTool); // manual filtering
+  return { tools };
 });
 
-// Weather tool — hidden until authenticated
-server.tool("weather", auth(), {
-  description: "Get weather for a city",
-  input: z.object({ city: z.string() }),
-}, async (args) => {
-  const data = await fetchWeather(args.city);
-  return { content: [{ type: "text", text: JSON.stringify(data) }] };
+server.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
+  if (req.params.name === "login") {
+    sessions.set(extra.sessionId, { authorized: true });
+    server.sendToolListChanged(); // manual notification
+  }
+  // ...
 });
+```
 
-await server.stdio();
+## The Solution
+
+```ts
+// With lynq — one line
+server.tool("weather", guard(), config, handler);
+// Client gets notified automatically. No manual wiring.
 ```
 
 ## Install
 
 ```sh
-npm install lynq @modelcontextprotocol/sdk zod
+npm install @lynq/lynq
 ```
 
-## Why lynq
-
-When you build an MCP server, you often need to show different tools depending on session state — hide admin tools from unauthenticated users, reveal features after onboarding, etc. The MCP protocol supports this via bidirectional tool list notifications, but wiring it by hand means managing visibility sets, diffing tool lists, and calling `sendToolListChanged` at the right time. lynq lets you declare visibility as middleware and handles the rest.
-
-## API
-
-### `createMCPServer(info)`
-
-Creates a server instance.
+## Quick Start
 
 ```ts
-const server = createMCPServer({ name: "my-server", version: "1.0.0" });
-```
-
-### `server.tool(name, ...middlewares?, config, handler)`
-
-Register a tool. Middlewares are optional, config holds `description` and `input` schema.
+import { createMCPServer } from "@lynq/lynq";
+import { guard } from "@lynq/lynq/guard";
+import { z } from "zod";
 
-```ts
-server.tool("greet", {
-  description: "Greet someone",
-  input: z.object({ name: z.string() }),
-}, async (args) => ({
-  content: [{ type: "text", text: `Hello ${args.name}` }],
-}));
-
-server.tool("secret", auth(), {
-  input: z.object({ query: z.string() }),
-}, async (args) => ({
-  content: [{ type: "text", text: args.query }],
-}));
-```
+const server = createMCPServer({ name: "my-server", version: "1.0.0" });
 
-### `server.resource(uri, ...middlewares?, config, handler)`
+server.tool("login", {
+  input: z.object({ username: z.string(), password: z.string() }),
+}, async (args, c) => {
+  const user = await authenticate(args.username, args.password);
+  c.session.set("user", user);
+  c.session.authorize("guard");
+  return c.text(`Welcome, ${user.name}`);
+});
 
-Register a resource. Same middleware pattern as `tool()`. Global middleware (`server.use()`) does not apply to resources.
+server.tool("weather", guard(), {
+  description: "Get weather for a city",
+  input: z.object({ city: z.string() }),
+}, async (args, c) => {
+  return c.text(JSON.stringify(await fetchWeather(args.city)));
+});
 
-```ts
-server.resource("config://settings", {
-  name: "App Settings",
-  mimeType: "application/json",
-}, async (uri) => ({
-  text: JSON.stringify(config),
-}));
-
-server.resource("data://users", auth(), {
-  name: "User Database",
-  mimeType: "application/json",
-}, async (uri, ctx) => ({
-  text: JSON.stringify(await db.getUsers()),
-}));
+await server.stdio();
 ```
 
-### `server.use(middleware)`
-
-Apply middleware to all subsequently registered tools.
-
-```ts
-server.use(auth());
+```sh
+npx tsx server.ts
 ```
 
-### Session
+## Features
 
-Available in handlers and middleware via `ctx.session`:
+- **Session-Scoped Visibility** — `authorize()` shows tools, `revoke()` hides them. Client notification is automatic.
+- **Hono-Style Middleware** — Global via `server.use()`, per-tool inline. Three hooks: `onRegister`, `onCall`, `onResult`.
+- **Built-in Middleware** — `guard()` `rateLimit()` `logger()` `truncate()` `credentials()` `some()` `every()` `except()`
+- **Response Helpers** — `c.text()` `c.json()` `c.error()` `c.image()` — chainable: `c.text("done").json({ id: 1 })`
+- **Elicitation** — `c.elicit.form(message, zodSchema)` for structured user input. `c.elicit.url()` for external flows.
+- **Framework Adapters** — `server.http()` returns `(Request) => Response`. Mount in Hono, Express, Deno, Workers.
+- **Test Helpers** — `createTestClient()` for in-memory testing. No transport setup.
+- **Tiny Core** — One dependency. ESM only. No config files, no magic.
 
-```ts
-ctx.session.set("key", value);
-ctx.session.get("key");
-ctx.session.authorize("auth"); // Enable tools guarded by "auth" middleware
-```
-
-### `auth(options?)`
-
-Middleware that hides tools until authenticated.
+## Middleware Composition
 
 ```ts
-import { auth } from "lynq/auth";
+import { guard } from "@lynq/lynq/guard";
+import { rateLimit } from "@lynq/lynq/rate-limit";
+import { logger } from "@lynq/lynq/logger";
 
-auth();                          // checks ctx.session.get("user")
-auth({ sessionKey: "token" });   // checks ctx.session.get("token")
-auth({ message: "Login first" }); // custom error message
+server.use(logger());                                              // global
+server.tool("search", guard(), rateLimit({ max: 10 }), config, handler);  // per-tool stack
 ```
 
-## Testing
+## Comparison
 
-lynq ships a test helper that eliminates MCP boilerplate. No manual `Client`/`InMemoryTransport` setup.
+| | lynq | FastMCP | Official SDK |
+|---|---|---|---|
+| Per-tool middleware | Yes | No | No |
+| Session-scoped visibility | Auto-notify | Manual | Manual |
+| onResult hook | Yes | No | No |
+| Response helpers | Chainable | Basic | No |
+| Test helpers | Yes | No | No |
+| HTTP server built-in | No (you choose) | Yes (opinionated) | No |
 
-```ts
-import { createTestClient } from "lynq/test";
-import { createMCPServer } from "lynq";
-import { auth } from "lynq/auth";
-import { z } from "zod";
+## Documentation
 
-const server = createMCPServer({ name: "my-server", version: "1.0.0" });
-server.tool("weather", auth(), {
-  input: z.object({ city: z.string() }),
-}, async (args) => ({
-  content: [{ type: "text", text: `Sunny in ${args.city}` }],
-}));
-
-const t = await createTestClient(server);
-
-// Tool visibility
-const tools = await t.listTools();     // string[]
-expect(tools).not.toContain("weather");
-
-// Authorize and call
-t.authorize("auth");
-const text = await t.callToolText("weather", { city: "Tokyo" });
-expect(text).toContain("Sunny");
-
-// Full result access
-const result = await t.callTool("weather", { city: "Tokyo" });
-
-// Resources
-const uris = await t.listResources();
-const content = await t.readResource("config://settings");
-
-// Session access
-t.session.set("user", { name: "alice" });
+[https://hogekai.github.io/lynq/](https://hogekai.github.io/lynq/)
 
-await t.close();
-```
-
-### Custom matchers
-
-Optional vitest/jest matchers for more expressive assertions:
-
-```ts
-import { matchers } from "lynq/test";
-expect.extend(matchers);
-
-const result = await t.callTool("weather", { city: "Tokyo" });
-expect(result).toHaveTextContent("Sunny");
-expect(result).not.toBeError();
-```
+- [Quick Start](https://hogekai.github.io/lynq/getting-started/quick-start)
+- [Middleware Concepts](https://hogekai.github.io/lynq/concepts/middleware)
+- [Why lynq](https://hogekai.github.io/lynq/why-lynq)
+- [API Reference](https://hogekai.github.io/lynq/api-reference/)
 
 ## License
 

package/dist/adapters/express.d.ts

@@ -1,5 +1,5 @@
 import { Express } from 'express';
-import { M as MCPServer } from '../types-BqH9Me9B.js';
+import { M as MCPServer } from '../types-CqT2idkd.js';
 import '@modelcontextprotocol/sdk/types.js';
 import 'zod';
 

package/dist/adapters/hono.d.ts

@@ -1,5 +1,5 @@
 import { Hono } from 'hono';
-import { M as MCPServer } from '../types-BqH9Me9B.js';
+import { M as MCPServer } from '../types-CqT2idkd.js';
 import '@modelcontextprotocol/sdk/types.js';
 import 'zod';
 

package/dist/chunk-2KEVF6YL.mjs

@@ -0,0 +1 @@
+import {a}from'./chunk-STWVQGX5.mjs';function n(e){let t={name:e.name??"oauth",sessionKey:e.sessionKey??"user",message:e.message??"Please sign in to continue.",buildUrl:e.buildUrl,declineMessage:"Authentication cancelled."};return e.timeout!==void 0&&(t.timeout=e.timeout),a(t)}export{n as a};

package/dist/chunk-L7SD7KKW.mjs

@@ -0,0 +1 @@
+import {c}from'./chunk-VAAZWX4U.mjs';function g(e){let s=e?.name??"guard",n=e?.sessionKey??"user",t=e?.message??"Authorization required.";return {name:s,onRegister(){return  false},async onCall(o,a){return o.session.get(n)?a():c(t)}}}export{g as a};

package/dist/chunk-STWVQGX5.mjs

@@ -0,0 +1 @@
+import {c}from'./chunk-VAAZWX4U.mjs';function m(e){let n=e.name??"url-action",i=e.sessionKey??"user",l=e.timeout??3e5,a=e.declineMessage??"Action cancelled.";return {name:n,onRegister(){return  false},async onCall(s,r){if(s.session.get(i))return r();let o=crypto.randomUUID(),c$1=e.buildUrl({sessionId:s.sessionId,elicitationId:o});return (await s.elicit.url(e.message,c$1,{elicitationId:o,waitForCompletion:true,timeout:l})).action!=="accept"?c(a):s.session.get(i)?(s.session.authorize(n),r()):c("Action was not completed.")}}}export{m as a};

package/dist/chunk-VAAZWX4U.mjs

@@ -0,0 +1 @@
+function t(e,n){return {content:e,...n?{isError:true}:{},text(o){return t([...e,{type:"text",text:o}],n)},json(o){return t([...e,{type:"text",text:JSON.stringify(o,null,2)}],n)},error(o){return t([...e,{type:"text",text:o}],true)},image(o,r){return t([...e,{type:"image",data:o,mimeType:r}],n)}}}function s(e){return t([{type:"text",text:e}])}function l(e){return t([{type:"text",text:JSON.stringify(e,null,2)}])}function p(e){return t([{type:"text",text:e}],true)}function i(e,n){return t([{type:"image",data:e,mimeType:n}])}export{s as a,l as b,p as c,i as d};

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { M as MCPServer } from './types-BqH9Me9B.js';
-export { E as Elicit, a as ElicitFormParams, b as ElicitFormResult, c as ElicitUrlParams, d as ElicitUrlResult, H as HttpAdapterOptions, R as ResourceConfig, e as ResourceContent, f as ResourceContext, g as ResourceHandler, h as RootInfo, S as Sample, i as SampleOptions, j as SampleRawParams, k as SampleRawResult, l as ServerInfo, m as Session, T as TaskConfig, n as TaskContext, o as TaskControl, p as TaskHandler, q as ToolConfig, r as ToolContext, s as ToolHandler, t as ToolInfo, u as ToolMiddleware } from './types-BqH9Me9B.js';
+import { M as MCPServer } from './types-CqT2idkd.js';
+export { E as Elicit, a as ElicitFormResult, b as ElicitUrlOptions, c as ElicitUrlResult, H as HttpAdapterOptions, R as ResourceConfig, d as ResourceContent, e as ResourceContext, f as ResourceHandler, g as RootInfo, S as Sample, h as SampleOptions, i as SampleRawParams, j as SampleRawResult, k as ServerInfo, l as Session, T as TaskConfig, m as TaskContext, n as TaskControl, o as TaskHandler, p as ToolConfig, q as ToolContext, r as ToolHandler, s as ToolInfo, t as ToolMiddleware, u as ToolResponse, v as error, w as image, x as json, y as text } from './types-CqT2idkd.js';
 import '@modelcontextprotocol/sdk/types.js';
 import 'zod';
 

package/dist/index.mjs

@@ -1 +1 @@
-import {InMemoryTaskStore}from'@modelcontextprotocol/sdk/experimental/tasks';import {Server}from'@modelcontextprotocol/sdk/server/index.js';import {ListToolsRequestSchema,CallToolRequestSchema,ListResourcesRequestSchema,ListResourceTemplatesRequestSchema,ReadResourceRequestSchema}from'@modelcontextprotocol/sdk/types.js';import {normalizeObjectSchema}from'@modelcontextprotocol/sdk/server/zod-compat.js';import {toJsonSchemaCompat}from'@modelcontextprotocol/sdk/server/zod-json-schema-compat.js';function ne(a){return {async form({message:l,schema:c}){let i=await a.elicitInput({message:l,requestedSchema:{type:"object",properties:c}});return {action:i.action,content:i.content??{}}},async url({message:l,url:c}){return {action:(await a.elicitInput({mode:"url",message:l,url:c,elicitationId:crypto.randomUUID()})).action}}}}function A(a){return async()=>{try{return (await a.listRoots()).roots.map(c=>{let i={uri:c.uri};return c.name!==void 0&&(i.name=c.name),i})}catch{return []}}}function se(a){async function l(i,u){let p={messages:[{role:"user",content:{type:"text",text:i}}],maxTokens:u?.maxTokens??1024};u?.model!==void 0&&(p.modelPreferences={hints:[{name:u.model}]}),u?.system!==void 0&&(p.systemPrompt=u.system),u?.temperature!==void 0&&(p.temperature=u.temperature),u?.stopSequences!==void 0&&(p.stopSequences=u.stopSequences);let f=(await a.createMessage(p)).content;return f.type==="text"?f.text:""}async function c(i){return a.createMessage(i)}return Object.assign(l,{raw:c})}function q(a,l,c,i,u){return {toolName:i,session:c,signal:u,sessionId:l,elicit:ne(a),roots:A(a),sample:se(a)}}function B(a){if(a==null)return {type:"object"};let l=normalizeObjectSchema(a);return l?toJsonSchemaCompat(l):a}function H(a,l){let c=l[l.length-1];if(typeof c!="function")throw new TypeError(`${a}: last argument must be a handler function`);let i=l[l.length-2];if(i==null||typeof i!="object"||Array.isArray(i))throw new TypeError(`${a}: second-to-last argument must be a config object`);let u=l.slice(0,-2);for(let p of u)if(!p||typeof p!="object"||typeof p.name!="string")throw new TypeError(`${a}: each middleware must have a "name" property`);return {middlewares:u,config:i,handler:c}}function j(a,l){let c=[];for(let i of l)i.onRegister?.(a)===false&&c.push(i.name);return c}function L(a){let c=a.split(/\{[^}]+\}/).map(i=>i.replace(/[.*+?^$|()[\]\\]/g,"\\$&"));return new RegExp(`^${c.join("(.+)")}$`)}function E(a,l,c,i){let u=c.get(l);if(u==="disabled")return  false;if(u==="enabled")return  true;for(let p of a)if(!i.has(p))return  false;return  true}function z(a,l){let c=a.get(l);if(c)return c;for(let i of a.values())if(i.isTemplate&&i.uriPattern?.test(l))return i}function $(a,l,c){let i=a.filter(f=>f.onCall),u=a.filter(f=>f.onResult).reverse(),p=0,y=async()=>{if(p>=i.length){let b=await c();for(let C of u)b=await C.onResult(b,l);return b}return i[p++].onCall(l,y)};return y}function pe(a){let l=[],c=new Map,i=new Map,u=new Map,p=new Map,y=new Map,f=new Set,b=new InMemoryTaskStore,C=new Proxy(b,{get(e,n,t){return n==="updateTaskStatus"?async(s,r,...o)=>(r==="cancelled"&&f.add(s),e.updateTaskStatus.call(e,s,r,...o)):Reflect.get(e,n,t)}}),h=new Server(a,{capabilities:{tools:{listChanged:true},resources:{listChanged:true},tasks:{list:{},cancel:{},requests:{tools:{call:{}}}}},taskStore:C});function S(e){let n=p.get(e);return n||(n={data:new Map,grants:new Set,toolOverrides:new Map,resourceOverrides:new Map},p.set(e,n)),n}function O(e,n){let t=S(n);return E(e.hiddenByMiddlewares,e.name,t.toolOverrides,t.grants)}function k(e,n){let t=S(n);return E(e.hiddenByMiddlewares,e.uri,t.resourceOverrides,t.grants)}function _(e,n){let t=S(n);return E(e.hiddenByMiddlewares,e.name,t.toolOverrides,t.grants)}function M(e){(e&&y.get(e)||h).sendToolListChanged().catch(()=>{});}function x(e){(e&&y.get(e)||h).sendResourceListChanged().catch(()=>{});}function I(e){let n=S(e);return {get(t){return n.data.get(t)},set(t,s){n.data.set(t,s);},authorize(t){n.grants.add(t),M(e),x(e);},revoke(t){n.grants.delete(t),M(e),x(e);},enableTools(...t){for(let s of t)n.toolOverrides.set(s,"enabled");M(e);},disableTools(...t){for(let s of t)n.toolOverrides.set(s,"disabled");M(e);},enableResources(...t){for(let s of t)n.resourceOverrides.set(s,"enabled");x(e);},disableResources(...t){for(let s of t)n.resourceOverrides.set(s,"disabled");x(e);}}}function V(e){e.setRequestHandler(ListToolsRequestSchema,(n,t)=>{let s=t.sessionId??"default",r=[];for(let o of c.values())O(o,s)&&r.push({name:o.name,description:o.description,inputSchema:B(o.input)});for(let o of u.values())_(o,s)&&r.push({name:o.name,description:o.description,inputSchema:B(o.input),execution:{taskSupport:"required"}});return {tools:r}}),e.setRequestHandler(CallToolRequestSchema,async(n,t)=>{let{name:s,arguments:r}=n.params,o=t.sessionId??"default",w=d=>({content:[{type:"text",text:d}],isError:true}),g=c.get(s);if(g){if(!O(g,o))return w(`Tool not available: ${s}`);let d=q(e,o,I(o),s,t.signal),v=()=>Promise.resolve(g.handler(r??{},d));return $(g.middlewares,d,v)()}let T=u.get(s);if(T){if(!_(T,o))return w(`Tool not available: ${s}`);let d=t.taskStore;if(!d)return w("Task store not available");let v=await d.createTask({pollInterval:1e3}),m=v.taskId,Y={progress(R,P){if(f.has(m))return;let te=P?`${R}% ${P}`:`${R}%`;d.updateTaskStatus(m,"working",te).catch(()=>{});},get cancelled(){return f.has(m)}},J={...q(e,o,I(o),s,t.signal),task:Y},ee=async()=>((async()=>{try{let R=await T.handler(r??{},J);f.has(m)||await d.storeTaskResult(m,"completed",R);}catch(R){if(!f.has(m)){let P=R instanceof Error?R.message:String(R);await d.storeTaskResult(m,"failed",{content:[{type:"text",text:P}],isError:true}).catch(()=>{});}}})(),{task:v});return $(T.middlewares,J,ee)()}return w(`Unknown tool: ${s}`)}),e.setRequestHandler(ListResourcesRequestSchema,(n,t)=>{let s=t.sessionId??"default",r=[];for(let o of i.values())!o.isTemplate&&k(o,s)&&r.push({uri:o.uri,name:o.name,description:o.description,mimeType:o.mimeType});return {resources:r}}),e.setRequestHandler(ListResourceTemplatesRequestSchema,(n,t)=>{let s=t.sessionId??"default",r=[];for(let o of i.values())o.isTemplate&&k(o,s)&&r.push({uriTemplate:o.uri,name:o.name,description:o.description,mimeType:o.mimeType});return {resourceTemplates:r}}),e.setRequestHandler(ReadResourceRequestSchema,async(n,t)=>{let{uri:s}=n.params,r=z(i,s);if(!r)throw new Error(`Unknown resource: ${s}`);let o=t.sessionId??"default";if(!k(r,o))throw new Error(`Resource not available: ${s}`);let w=I(o),g={uri:s,session:w,sessionId:o,roots:A(e)},T=q(e,o,w,r.uri,t.signal),d=async()=>{let m=await r.handler(s,g);return {contents:[{uri:s,mimeType:m.mimeType??r.mimeType,...m.text!=null?{text:m.text}:{},...m.blob!=null?{blob:m.blob}:{}}]}};return $(r.middlewares,T,d)()});}V(h);function F(e){l.push(e);}function G(...e){let n=e[0],t=H(`tool("${n}")`,e.slice(1));if(typeof t.config.name=="string")throw new TypeError(`tool("${n}"): second-to-last argument must be a config object`);let s=t.config,r=[...l,...t.middlewares],o={name:n,description:s.description,middlewares:r};c.set(n,{name:n,description:s.description,input:s.input,handler:t.handler,middlewares:r,hiddenByMiddlewares:j(o,r)});}function D(...e){let n=e[0],t=H(`resource("${n}")`,e.slice(1));if(typeof t.config.name!="string")throw new TypeError(`resource("${n}"): second-to-last argument must be a config object with a "name" property`);let s=t.config,r={name:s.name,description:s.description,middlewares:t.middlewares},o=n.includes("{");i.set(n,{uri:n,isTemplate:o,uriPattern:o?L(n):null,name:s.name,description:s.description,mimeType:s.mimeType,handler:t.handler,middlewares:t.middlewares,hiddenByMiddlewares:j(r,t.middlewares)});}function W(...e){let n=e[0],t=H(`task("${n}")`,e.slice(1));if(typeof t.config.name=="string")throw new TypeError(`task("${n}"): second-to-last argument must be a config object`);let s=t.config,r=[...l,...t.middlewares],o={name:n,description:s.description,middlewares:r};u.set(n,{name:n,description:s.description,input:s.input,handler:t.handler,middlewares:r,hiddenByMiddlewares:j(o,r)});}async function Z(){let{StdioServerTransport:e}=await import('@modelcontextprotocol/sdk/server/stdio.js'),n=new e;await h.connect(n);}async function K(e){await h.connect(e);}let Q={tools:{listChanged:true},resources:{listChanged:true},tasks:{list:{},cancel:{},requests:{tools:{call:{}}}}};function U(){let e=new Server(a,{capabilities:Q,taskStore:C});return V(e),e}function X(e){let n=null;async function t(){return n||(n=(await import('@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js')).WebStandardStreamableHTTPServerTransport),n}if(e?.sessionless)return async r=>{let o=await t(),w=U(),g=new o({sessionIdGenerator:void 0,enableJsonResponse:e?.enableJsonResponse});return await w.connect(g),g.handleRequest(r)};let s=new Map;return async r=>{let o=await t(),w=r.headers.get("mcp-session-id");if(w){let d=s.get(w);return d?d.transport.handleRequest(r):new Response(JSON.stringify({jsonrpc:"2.0",error:{code:-32e3,message:"Session not found"}}),{status:404,headers:{"Content-Type":"application/json"}})}let g=U(),T=new o({sessionIdGenerator:e?.sessionIdGenerator??(()=>crypto.randomUUID()),enableJsonResponse:e?.enableJsonResponse,onsessioninitialized:d=>{s.set(d,{server:g,transport:T}),y.set(d,g);},onsessionclosed:d=>{s.delete(d),y.delete(d);}});return await g.connect(T),T.handleRequest(r)}}return {use:F,tool:G,resource:D,task:W,stdio:Z,http:X,connect:K,_server:h,_getSession:S,_isToolVisible(e,n){let t=c.get(e);return t?O(t,n):false},_isResourceVisible(e,n){let t=i.get(e);return t?k(t,n):false},_isTaskVisible(e,n){let t=u.get(e);return t?_(t,n):false},_createSessionAPI:I}}export{pe as createMCPServer};
+import {c,d,b,a}from'./chunk-VAAZWX4U.mjs';export{c as error,d as image,b as json,a as text}from'./chunk-VAAZWX4U.mjs';import {InMemoryTaskStore}from'@modelcontextprotocol/sdk/experimental/tasks';import {Server}from'@modelcontextprotocol/sdk/server/index.js';import {ListToolsRequestSchema,CallToolRequestSchema,ListResourcesRequestSchema,ListResourceTemplatesRequestSchema,ReadResourceRequestSchema}from'@modelcontextprotocol/sdk/types.js';import {normalizeObjectSchema}from'@modelcontextprotocol/sdk/server/zod-compat.js';import {toJsonSchemaCompat}from'@modelcontextprotocol/sdk/server/zod-json-schema-compat.js';function j(a){if(a==null)return {type:"object"};let l=normalizeObjectSchema(a);return l?toJsonSchemaCompat(l):a}function $(a,l){let c=l[l.length-1];if(typeof c!="function")throw new TypeError(`${a}: last argument must be a handler function`);let i=l[l.length-2];if(i==null||typeof i!="object"||Array.isArray(i))throw new TypeError(`${a}: second-to-last argument must be a config object`);let d=l.slice(0,-2);for(let u of d)if(!u||typeof u!="object"||typeof u.name!="string")throw new TypeError(`${a}: each middleware must have a "name" property`);return {middlewares:d,config:i,handler:c}}function A(a,l){let c=[];for(let i of l)i.onRegister?.(a)===false&&c.push(i.name);return c}function Q(a){let c=a.split(/\{[^}]+\}/).map(i=>i.replace(/[.*+?^$|()[\]\\]/g,"\\$&"));return new RegExp(`^${c.join("(.+)")}$`)}function B(a,l,c,i){let d=c.get(l);if(d==="disabled")return  false;if(d==="enabled")return  true;for(let u of a)if(!i.has(u))return  false;return  true}function X(a,l){let c=a.get(l);if(c)return c;for(let i of a.values())if(i.isTemplate&&i.uriPattern?.test(l))return i}function U(a,l,c){let i=a.filter(m=>m.onCall),d=a.filter(m=>m.onResult).reverse(),u=0,p=async()=>{if(u>=i.length){let S=await c();for(let C of d)S=await C.onResult(S,l);return S}return i[u++].onCall(l,p)};return p}function pe(a,l,c){return {async form(i,d){let u=j(d),p=await a.elicitInput({message:i,requestedSchema:u});return {action:p.action,content:p.content??{}}},async url(i,d,u){let p=u?.elicitationId??crypto.randomUUID(),m;u?.waitForCompletion&&l&&(m=l(p,a));let S=await a.elicitInput({mode:"url",message:i,url:d,elicitationId:p});if(S.action==="accept"&&m){let C=u?.timeout??3e5,x=new Promise((G,I)=>{setTimeout(()=>I(new Error("Elicitation timed out")),C);});await Promise.race([m,x]);}else m&&c&&c(p);return {action:S.action}}}}function F(a){return async()=>{try{return (await a.listRoots()).roots.map(c=>{let i={uri:c.uri};return c.name!==void 0&&(i.name=c.name),i})}catch{return []}}}function fe(a){async function l(i,d){let u={messages:[{role:"user",content:{type:"text",text:i}}],maxTokens:d?.maxTokens??1024};d?.model!==void 0&&(u.modelPreferences={hints:[{name:d.model}]}),d?.system!==void 0&&(u.systemPrompt=d.system),d?.temperature!==void 0&&(u.temperature=d.temperature),d?.stopSequences!==void 0&&(u.stopSequences=d.stopSequences);let m=(await a.createMessage(u)).content;return m.type==="text"?m.text:""}async function c(i){return a.createMessage(i)}return Object.assign(l,{raw:c})}function N(a$1,l,c$1,i,d$1,u,p){return {toolName:i,session:c$1,signal:d$1,sessionId:l,elicit:pe(a$1,u,p),roots:F(a$1),sample:fe(a$1),text:a,json:b,error:c,image:d}}function ve(a){let l=[],c$1=new Map,i=new Map,d=new Map,u=new Map,p=new Map,m=new Map,S=36e5;function C(){let e=Date.now();for(let[t,n]of m)e-n.createdAt>S&&m.delete(t);}function x(e,t,n){return C(),new Promise(o=>{let r;try{r=n.createElicitationCompletionNotifier(e);}catch{}m.set(e,{resolver:o,completionNotifier:r,createdAt:Date.now()});})}function G(e){C();let t=m.get(e);t&&(m.delete(e),t.completionNotifier&&t.completionNotifier().catch(()=>{}),t.resolver());}function I(e){let t=m.get(e);t&&(m.delete(e),t.resolver());}let q=new Set,ee=new InMemoryTaskStore,W=new Proxy(ee,{get(e,t,n){return t==="updateTaskStatus"?async(o,r,...s)=>(r==="cancelled"&&q.add(o),e.updateTaskStatus.call(e,o,r,...s)):Reflect.get(e,t,n)}}),k=new Server(a,{capabilities:{tools:{listChanged:true},resources:{listChanged:true},tasks:{list:{},cancel:{},requests:{tools:{call:{}}}}},taskStore:W});function E(e){let t=u.get(e);return t||(t={data:new Map,grants:new Set,toolOverrides:new Map,resourceOverrides:new Map},u.set(e,t)),t}function V(e,t){let n=E(t);return B(e.hiddenByMiddlewares,e.name,n.toolOverrides,n.grants)}function H(e,t){let n=E(t);return B(e.hiddenByMiddlewares,e.uri,n.resourceOverrides,n.grants)}function J(e,t){let n=E(t);return B(e.hiddenByMiddlewares,e.name,n.toolOverrides,n.grants)}function O(e){(e&&p.get(e)||k).sendToolListChanged().catch(()=>{});}function _(e){(e&&p.get(e)||k).sendResourceListChanged().catch(()=>{});}function b(e){let t=E(e);return {get(n){return t.data.get(n)},set(n,o){t.data.set(n,o);},authorize(n){t.grants.add(n),O(e),_(e);},revoke(n){t.grants.delete(n),O(e),_(e);},enableTools(...n){for(let o of n)t.toolOverrides.set(o,"enabled");O(e);},disableTools(...n){for(let o of n)t.toolOverrides.set(o,"disabled");O(e);},enableResources(...n){for(let o of n)t.resourceOverrides.set(o,"enabled");_(e);},disableResources(...n){for(let o of n)t.resourceOverrides.set(o,"disabled");_(e);}}}function Z(e){e.setRequestHandler(ListToolsRequestSchema,(t,n)=>{let o=n.sessionId??"default",r=[];for(let s of c$1.values())V(s,o)&&r.push({name:s.name,description:s.description,inputSchema:j(s.input)});for(let s of d.values())J(s,o)&&r.push({name:s.name,description:s.description,inputSchema:j(s.input),execution:{taskSupport:"required"}});return {tools:r}}),e.setRequestHandler(CallToolRequestSchema,async(t,n)=>{let{name:o,arguments:r}=t.params,s=n.sessionId??"default",g=c$1.get(o);if(g){if(!V(g,s))return c(`Tool not available: ${o}`);let w=N(e,s,b(s),o,n.signal,(R,M)=>x(R,s,M),I),f=()=>Promise.resolve(g.handler(r??{},w));return U(g.middlewares,w,f)()}let T=d.get(o);if(T){if(!J(T,s))return c(`Tool not available: ${o}`);let w=n.taskStore;if(!w)return c("Task store not available");let f=await w.createTask({pollInterval:1e3}),h=f.taskId,R={progress(y,P){if(q.has(h))return;let de=P?`${y}% ${P}`:`${y}%`;w.updateTaskStatus(h,"working",de).catch(()=>{});},get cancelled(){return q.has(h)}},M={...N(e,s,b(s),o,n.signal,(y,P)=>x(y,s,P),I),task:R},ce=async()=>((async()=>{try{let y=await T.handler(r??{},M);q.has(h)||await w.storeTaskResult(h,"completed",y);}catch(y){if(!q.has(h)){let P=y instanceof Error?y.message:String(y);await w.storeTaskResult(h,"failed",c(P)).catch(()=>{});}}})(),{task:f});return U(T.middlewares,M,ce)()}return c(`Unknown tool: ${o}`)}),e.setRequestHandler(ListResourcesRequestSchema,(t,n)=>{let o=n.sessionId??"default",r=[];for(let s of i.values())!s.isTemplate&&H(s,o)&&r.push({uri:s.uri,name:s.name,description:s.description,mimeType:s.mimeType});return {resources:r}}),e.setRequestHandler(ListResourceTemplatesRequestSchema,(t,n)=>{let o=n.sessionId??"default",r=[];for(let s of i.values())s.isTemplate&&H(s,o)&&r.push({uriTemplate:s.uri,name:s.name,description:s.description,mimeType:s.mimeType});return {resourceTemplates:r}}),e.setRequestHandler(ReadResourceRequestSchema,async(t,n)=>{let{uri:o}=t.params,r=X(i,o);if(!r)throw new Error(`Unknown resource: ${o}`);let s=n.sessionId??"default";if(!H(r,s))throw new Error(`Resource not available: ${o}`);let g=b(s),T={uri:o,session:g,sessionId:s,roots:F(e)},w=N(e,s,g,r.uri,n.signal,(R,M)=>x(R,s,M),I),f=async()=>{let R=await r.handler(o,T);return {contents:[{uri:o,mimeType:R.mimeType??r.mimeType,...R.text!=null?{text:R.text}:{},...R.blob!=null?{blob:R.blob}:{}}]}};return U(r.middlewares,w,f)()});}Z(k);function te(e){l.push(e);}function ne(...e){let t=e[0],n=$(`tool("${t}")`,e.slice(1));if(typeof n.config.name=="string")throw new TypeError(`tool("${t}"): second-to-last argument must be a config object`);let o=n.config,r=[...l,...n.middlewares],s={name:t,description:o.description,middlewares:r};c$1.set(t,{name:t,description:o.description,input:o.input,handler:n.handler,middlewares:r,hiddenByMiddlewares:A(s,r)});}function oe(...e){let t=e[0],n=$(`resource("${t}")`,e.slice(1));if(typeof n.config.name!="string")throw new TypeError(`resource("${t}"): second-to-last argument must be a config object with a "name" property`);let o=n.config,r={name:o.name,description:o.description,middlewares:n.middlewares},s=t.includes("{");i.set(t,{uri:t,isTemplate:s,uriPattern:s?Q(t):null,name:o.name,description:o.description,mimeType:o.mimeType,handler:n.handler,middlewares:n.middlewares,hiddenByMiddlewares:A(r,n.middlewares)});}function se(...e){let t=e[0],n=$(`task("${t}")`,e.slice(1));if(typeof n.config.name=="string")throw new TypeError(`task("${t}"): second-to-last argument must be a config object`);let o=n.config,r=[...l,...n.middlewares],s={name:t,description:o.description,middlewares:r};d.set(t,{name:t,description:o.description,input:o.input,handler:n.handler,middlewares:r,hiddenByMiddlewares:A(s,r)});}async function re(){let{StdioServerTransport:e}=await import('@modelcontextprotocol/sdk/server/stdio.js'),t=new e;await k.connect(t);}async function ie(e){await k.connect(e);}let ae={tools:{listChanged:true},resources:{listChanged:true},tasks:{list:{},cancel:{},requests:{tools:{call:{}}}}};function K(){let e=new Server(a,{capabilities:ae,taskStore:W});return Z(e),e}function le(e){let t=null;async function n(){return t||(t=(await import('@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js')).WebStandardStreamableHTTPServerTransport),t}if(e?.sessionless)return async r=>{let s=await n(),g=K(),T=new s({sessionIdGenerator:void 0,enableJsonResponse:e?.enableJsonResponse});return await g.connect(T),T.handleRequest(r)};let o=new Map;return async r=>{let s=await n(),g=r.headers.get("mcp-session-id");if(g){let f=o.get(g);return f?(e?.onRequest&&await e.onRequest(r,g,b(g)),f.transport.handleRequest(r)):new Response(JSON.stringify({jsonrpc:"2.0",error:{code:-32e3,message:"Session not found"}}),{status:404,headers:{"Content-Type":"application/json"}})}let T=K(),w=new s({sessionIdGenerator:e?.sessionIdGenerator??(()=>crypto.randomUUID()),enableJsonResponse:e?.enableJsonResponse,onsessioninitialized:f=>{o.set(f,{server:T,transport:w}),p.set(f,T),e?.onRequest&&e.onRequest(r,f,b(f));},onsessionclosed:f=>{o.delete(f),p.delete(f);}});return await T.connect(w),w.handleRequest(r)}}return {use:te,tool:ne,resource:oe,task:se,stdio:re,http:le,session:b,completeElicitation:G,connect:ie,_server:k,_getSession:E,_isToolVisible(e,t){let n=c$1.get(e);return n?V(n,t):false},_isResourceVisible(e,t){let n=i.get(e);return n?H(n,t):false},_isTaskVisible(e,t){let n=d.get(e);return n?J(n,t):false},_createSessionAPI:b}}export{ve as createMCPServer};

package/dist/middleware/auth.d.ts

@@ -1,13 +1,11 @@
-import { u as ToolMiddleware } from '../types-BqH9Me9B.js';
+import { t as ToolMiddleware } from '../types-CqT2idkd.js';
+import { GuardOptions } from './guard.js';
 import '@modelcontextprotocol/sdk/types.js';
 import 'zod';
 
-interface AuthOptions {
-    /** Session key to check for authentication. Default: "user" */
-    sessionKey?: string;
-    /** Error message when not authenticated. */
-    message?: string;
-}
-declare function auth(options?: AuthOptions): ToolMiddleware;
+/** @deprecated Use `GuardOptions` from `@lynq/lynq/guard` instead. */
+type AuthOptions = GuardOptions;
+/** @deprecated Use `guard()` from `@lynq/lynq/guard` instead. */
+declare function auth(options?: GuardOptions): ToolMiddleware;
 
 export { type AuthOptions, auth };

package/dist/middleware/auth.mjs

@@ -1 +1 @@
-function i(e){let t=e?.sessionKey??"user",s=e?.message??"Authentication required. Please login first.";return {name:"auth",onRegister(){return  false},async onCall(n,r){return n.session.get(t)?r():{content:[{type:"text",text:s}],isError:true}}}}export{i as auth};
+import {a}from'../chunk-L7SD7KKW.mjs';import'../chunk-VAAZWX4U.mjs';function e(o){return a({name:"auth",...o})}export{e as auth};

package/dist/middleware/bearer.d.ts

@@ -0,0 +1,19 @@
+import { t as ToolMiddleware } from '../types-CqT2idkd.js';
+import '@modelcontextprotocol/sdk/types.js';
+import 'zod';
+
+interface BearerOptions {
+    /** Middleware name. Default: "bearer" */
+    name?: string;
+    /** Session key where the raw token is stored. Default: "token" */
+    tokenKey?: string;
+    /** Session key to store verified user. Default: "user" */
+    sessionKey?: string;
+    /** Verify the token. Return user data or null/throw on failure. */
+    verify: (token: string) => Promise<unknown | null>;
+    /** Error message. Default: "Invalid or missing token." */
+    message?: string;
+}
+declare function bearer(options: BearerOptions): ToolMiddleware;
+
+export { type BearerOptions, bearer };

package/dist/middleware/bearer.mjs

@@ -0,0 +1 @@
+import {c}from'../chunk-VAAZWX4U.mjs';function y(e){let n=e.name??"bearer",m=e.tokenKey??"token",t=e.sessionKey??"user",o=e.message??"Invalid or missing token.";return {name:n,onRegister(){return  false},async onCall(s,i){if(s.session.get(t))return i();let a=s.session.get(m);if(!a)return c(o);let g=await e.verify(a);return g?(s.session.set(t,g),s.session.authorize(n),i()):c(o)}}}export{y as bearer};

package/dist/middleware/combine.d.ts

@@ -0,0 +1,12 @@
+import { t as ToolMiddleware, q as ToolContext } from '../types-CqT2idkd.js';
+import '@modelcontextprotocol/sdk/types.js';
+import 'zod';
+
+/** Run the first middleware that doesn't short-circuit. */
+declare function some(...middlewares: ToolMiddleware[]): ToolMiddleware;
+/** Run all middlewares. Stop if any short-circuits. */
+declare function every(...middlewares: ToolMiddleware[]): ToolMiddleware;
+/** Run middleware only when the condition is false. */
+declare function except(condition: (c: ToolContext) => boolean, middleware: ToolMiddleware): ToolMiddleware;
+
+export { every, except, some };

package/dist/middleware/combine.mjs

@@ -0,0 +1 @@
+function f(...n){return {name:`some(${n.map(e=>e.name).join(",")})`,onRegister(e){for(let o of n)if(o.onRegister?.(e)===false)return  false},async onCall(e,o){let t,r;for(let s of n){if(!s.onCall){t=s;break}let u=false,a=async()=>(u=true,o()),i=await s.onCall(e,a);if(u)return t=s,i;r=i;}return t?o():r},onResult(e){return e}}}function c(...n){let l=n.map(o=>o.name),e=n.filter(o=>o.onResult).reverse();return {name:`every(${l.join(",")})`,onRegister(o){for(let t of n)if(t.onRegister?.(o)===false)return  false},async onCall(o,t){let r=n.filter(a=>a.onCall),s=0,u=async()=>s>=r.length?t():r[s++].onCall(o,u);return u()},onResult(o,t){let r=o;for(let s of e){let u=s.onResult(r,t);u instanceof Promise||(r=u);}return r}}}function T(n,l){return {name:`except(${l.name})`,onRegister(e){return l.onRegister?.(e)},async onCall(e,o){return n(e)?o():l.onCall?l.onCall(e,o):o()},onResult(e,o){return l.onResult?l.onResult(e,o):e}}}export{c as every,T as except,f as some};

package/dist/middleware/credentials.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+import { t as ToolMiddleware } from '../types-CqT2idkd.js';
+import '@modelcontextprotocol/sdk/types.js';
+
+interface CredentialsOptions<T extends z.ZodObject<z.ZodRawShape>> {
+    /** Middleware name. Default: "credentials" */
+    name?: string;
+    /** Message shown to the user. */
+    message: string;
+    /** Zod schema for the form fields. */
+    schema: T;
+    /** Verify the submitted credentials. Return user data or null. */
+    verify: (fields: z.infer<T>) => Promise<unknown | null>;
+    /** Session key to store verified user. Default: "user" */
+    sessionKey?: string;
+}
+declare function credentials<T extends z.ZodObject<z.ZodRawShape>>(options: CredentialsOptions<T>): ToolMiddleware;
+
+export { type CredentialsOptions, credentials };

package/dist/middleware/credentials.mjs

@@ -0,0 +1 @@
+import {c as c$1}from'../chunk-VAAZWX4U.mjs';function c(e){let r=e.name??"credentials",t=e.sessionKey??"user";return {name:r,onRegister(){return  false},async onCall(s,i){if(s.session.get(t))return i();let a=await s.elicit.form(e.message,e.schema);if(a.action!=="accept")return c$1("Authentication cancelled.");let o=await e.verify(a.content);return o?(s.session.set(t,o),s.session.authorize(r),i()):c$1("Invalid credentials.")}}}export{c as credentials};

package/dist/middleware/github-oauth.d.ts

@@ -0,0 +1,42 @@
+import { t as ToolMiddleware, M as MCPServer } from '../types-CqT2idkd.js';
+import '@modelcontextprotocol/sdk/types.js';
+import 'zod';
+
+interface GitHubOAuthOptions {
+    /** Middleware name. Default: "github-oauth" */
+    name?: string;
+    /** GitHub OAuth App client ID. */
+    clientId: string;
+    /** GitHub OAuth App client secret. */
+    clientSecret: string;
+    /** OAuth callback URL (your server's callback endpoint). */
+    redirectUri: string;
+    /** GitHub OAuth scopes. Default: [] */
+    scopes?: string[];
+    /** Session key for user data. Default: "user" */
+    sessionKey?: string;
+    /** Message shown to the user. Default: "Please sign in with GitHub to continue." */
+    message?: string;
+    /** Timeout in ms. Default: 300000 */
+    timeout?: number;
+}
+declare function githubOAuth(options: GitHubOAuthOptions): ToolMiddleware;
+interface HandleGitHubCallbackOptions {
+    clientId: string;
+    clientSecret: string;
+    /** Session key for user data. Default: "user" */
+    sessionKey?: string;
+}
+/**
+ * Handle GitHub OAuth callback. Call from your HTTP callback route.
+ * Exchanges code for token, fetches user info, stores in session, and completes elicitation.
+ */
+declare function handleGitHubCallback(server: MCPServer, params: {
+    code: string;
+    state: string;
+}, options: HandleGitHubCallbackOptions): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+
+export { type GitHubOAuthOptions, type HandleGitHubCallbackOptions, githubOAuth, handleGitHubCallback };

package/dist/middleware/github-oauth.mjs

@@ -0,0 +1,2 @@
+import {a}from'../chunk-2KEVF6YL.mjs';import'../chunk-STWVQGX5.mjs';import'../chunk-VAAZWX4U.mjs';function h(e){let s=e.scopes??[],t={name:e.name??"github-oauth",sessionKey:e.sessionKey??"user",message:e.message??"Please sign in with GitHub to continue.",buildUrl({sessionId:c,elicitationId:n}){let r=new URLSearchParams({client_id:e.clientId,redirect_uri:e.redirectUri,state:`${c}:${n}`});return s.length>0&&r.set("scope",s.join(" ")),`https://github.com/login/oauth/authorize?${r}`}};return e.timeout!==void 0&&(t.timeout=e.timeout),a(t)}async function m(e,s,t){let c=t.sessionKey??"user",[n,r]=s.state.split(":");if(!n||!r)return {success:false,error:"Invalid state parameter"};try{let i=await(await fetch("https://github.com/login/oauth/access_token",{method:"POST",headers:{"Content-Type":"application/json",Accept:"application/json"},body:JSON.stringify({client_id:t.clientId,client_secret:t.clientSecret,code:s.code})})).json();if(!i.access_token)return {success:!1,error:i.error_description??i.error??"Token exchange failed"};let l=await(await fetch("https://api.github.com/user",{headers:{Authorization:`Bearer ${i.access_token}`}})).json(),a=e.session(n);return a.set(c,l),a.set("accessToken",i.access_token),e.completeElicitation(r),{success:!0}}catch(o){return {success:false,error:o instanceof Error?o.message:String(o)}}}
+export{h as githubOAuth,m as handleGitHubCallback};

package/dist/middleware/google-oauth.d.ts

@@ -0,0 +1,43 @@
+import { t as ToolMiddleware, M as MCPServer } from '../types-CqT2idkd.js';
+import '@modelcontextprotocol/sdk/types.js';
+import 'zod';
+
+interface GoogleOAuthOptions {
+    /** Middleware name. Default: "google-oauth" */
+    name?: string;
+    /** Google OAuth client ID. */
+    clientId: string;
+    /** Google OAuth client secret. */
+    clientSecret: string;
+    /** OAuth callback URL (your server's callback endpoint). */
+    redirectUri: string;
+    /** OAuth scopes. Default: ["openid", "profile", "email"] */
+    scopes?: string[];
+    /** Session key for user data. Default: "user" */
+    sessionKey?: string;
+    /** Message shown to the user. Default: "Please sign in with Google to continue." */
+    message?: string;
+    /** Timeout in ms. Default: 300000 */
+    timeout?: number;
+}
+declare function googleOAuth(options: GoogleOAuthOptions): ToolMiddleware;
+interface HandleGoogleCallbackOptions {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    /** Session key for user data. Default: "user" */
+    sessionKey?: string;
+}
+/**
+ * Handle Google OAuth callback. Call from your HTTP callback route.
+ * Exchanges code for tokens, fetches user info, stores in session, and completes elicitation.
+ */
+declare function handleGoogleCallback(server: MCPServer, params: {
+    code: string;
+    state: string;
+}, options: HandleGoogleCallbackOptions): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+
+export { type GoogleOAuthOptions, type HandleGoogleCallbackOptions, googleOAuth, handleGoogleCallback };

package/dist/middleware/google-oauth.mjs

@@ -0,0 +1,2 @@
+import {a}from'../chunk-2KEVF6YL.mjs';import'../chunk-STWVQGX5.mjs';import'../chunk-VAAZWX4U.mjs';function m(e){let r=e.scopes??["openid","profile","email"],t={name:e.name??"google-oauth",sessionKey:e.sessionKey??"user",message:e.message??"Please sign in with Google to continue.",buildUrl({sessionId:i,elicitationId:o}){return `https://accounts.google.com/o/oauth2/v2/auth?${new URLSearchParams({client_id:e.clientId,redirect_uri:e.redirectUri,response_type:"code",scope:r.join(" "),state:`${i}:${o}`,access_type:"offline"})}`}};return e.timeout!==void 0&&(t.timeout=e.timeout),a(t)}async function p(e,r,t){let i=t.sessionKey??"user",[o,c]=r.state.split(":");if(!o||!c)return {success:false,error:"Invalid state parameter"};try{let s=await(await fetch("https://oauth2.googleapis.com/token",{method:"POST",headers:{"Content-Type":"application/x-www-form-urlencoded"},body:new URLSearchParams({code:r.code,client_id:t.clientId,client_secret:t.clientSecret,redirect_uri:t.redirectUri,grant_type:"authorization_code"})})).json();if(!s.access_token)return {success:!1,error:s.error_description??s.error??"Token exchange failed"};let d=await(await fetch("https://www.googleapis.com/oauth2/v2/userinfo",{headers:{Authorization:`Bearer ${s.access_token}`}})).json(),a=e.session(o);return a.set(i,d),a.set("accessToken",s.access_token),s.id_token&&a.set("idToken",s.id_token),e.completeElicitation(c),{success:!0}}catch(n){return {success:false,error:n instanceof Error?n.message:String(n)}}}
+export{m as googleOAuth,p as handleGoogleCallback};

package/dist/middleware/guard.d.ts

@@ -0,0 +1,15 @@
+import { t as ToolMiddleware } from '../types-CqT2idkd.js';
+import '@modelcontextprotocol/sdk/types.js';
+import 'zod';
+
+interface GuardOptions {
+    /** Middleware name. Used for authorize()/revoke(). Default: "guard" */
+    name?: string;
+    /** Session key to check. Default: "user" */
+    sessionKey?: string;
+    /** Error message when not authorized. */
+    message?: string;
+}
+declare function guard(options?: GuardOptions): ToolMiddleware;
+
+export { type GuardOptions, guard };

package/dist/middleware/guard.mjs

@@ -0,0 +1 @@
+export{a as guard}from'../chunk-L7SD7KKW.mjs';import'../chunk-VAAZWX4U.mjs';

package/dist/middleware/jwt.d.ts

@@ -0,0 +1,27 @@
+import { t as ToolMiddleware } from '../types-CqT2idkd.js';
+import '@modelcontextprotocol/sdk/types.js';
+import 'zod';
+
+interface JwtOptions {
+    /** Middleware name. Default: "jwt" */
+    name?: string;
+    /** Session key where the raw token is stored. Default: "token" */
+    tokenKey?: string;
+    /** Session key to store decoded payload. Default: "user" */
+    sessionKey?: string;
+    /** Symmetric secret for HMAC verification. */
+    secret?: string;
+    /** JWKS URI for remote key fetching. */
+    jwksUri?: string;
+    /** Expected issuer claim. */
+    issuer?: string;
+    /** Expected audience claim. */
+    audience?: string;
+    /** Additional validation on the decoded payload. Return user data or null. */
+    validate?: (payload: Record<string, unknown>) => unknown | null | Promise<unknown | null>;
+    /** Error message. Default: "Invalid or expired JWT." */
+    message?: string;
+}
+declare function jwt(options: JwtOptions): ToolMiddleware;
+
+export { type JwtOptions, jwt };

package/dist/middleware/jwt.mjs

@@ -0,0 +1 @@
+import {c}from'../chunk-VAAZWX4U.mjs';function j(e){let u=e.name??"jwt",y=e.tokenKey??"token",l=e.sessionKey??"user",d=e.message??"Invalid or expired JWT.",s=null;function m(){return s||(s=import('jose').catch(()=>(s=null,null))),s}return {name:u,onRegister(){return  false},async onCall(n,c$1){if(n.session.get(l))return c$1();let a=n.session.get(y);if(!a)return c("JWT required.");let t=await m();if(!t)return c("jose library is required for JWT middleware. Install it: pnpm add jose");try{let i;if(e.jwksUri){let o=t.createRemoteJWKSet(new URL(e.jwksUri));i=(await t.jwtVerify(a,o,{issuer:e.issuer,audience:e.audience})).payload;}else if(e.secret){let o=new TextEncoder().encode(e.secret);i=(await t.jwtVerify(a,o,{issuer:e.issuer,audience:e.audience})).payload;}else return c("JWT middleware misconfigured: provide secret or jwksUri.");let w=e.validate?await e.validate(i):i;return w?(n.session.set(l,w),n.session.authorize(u),c$1()):c(d)}catch{return c(d)}}}}export{j as jwt};

package/dist/middleware/logger.d.ts

@@ -0,0 +1,11 @@
+import { t as ToolMiddleware } from '../types-CqT2idkd.js';
+import '@modelcontextprotocol/sdk/types.js';
+import 'zod';
+
+interface LoggerOptions {
+    /** Custom log function. Default: console.log */
+    log?: (message: string) => void;
+}
+declare function logger(options?: LoggerOptions): ToolMiddleware;
+
+export { type LoggerOptions, logger };

package/dist/middleware/logger.mjs

@@ -0,0 +1 @@
+function a(s){let e=s?.log??console.log;return {name:"logger",async onCall(o,t){let n=performance.now();e(`[${o.toolName}] called (session: ${o.sessionId})`);let r=await t(),l=(performance.now()-n).toFixed(1);return e(`[${o.toolName}] ${l}ms${r.isError?" ERROR":""}`),r}}}export{a as logger};

package/dist/middleware/oauth.d.ts

@@ -0,0 +1,22 @@
+import { t as ToolMiddleware } from '../types-CqT2idkd.js';
+import '@modelcontextprotocol/sdk/types.js';
+import 'zod';
+
+interface OAuthOptions {
+    /** Middleware name. Default: "oauth" */
+    name?: string;
+    /** Session key for storing tokens. Default: "user" */
+    sessionKey?: string;
+    /** Message shown to the user. Default: "Please sign in to continue." */
+    message?: string;
+    /** Build the OAuth authorization URL. */
+    buildUrl: (params: {
+        sessionId: string;
+        elicitationId: string;
+    }) => string;
+    /** Timeout in ms. Default: 300000 */
+    timeout?: number;
+}
+declare function oauth(options: OAuthOptions): ToolMiddleware;
+
+export { type OAuthOptions, oauth };

package/dist/middleware/oauth.mjs

@@ -0,0 +1 @@
+export{a as oauth}from'../chunk-2KEVF6YL.mjs';import'../chunk-STWVQGX5.mjs';import'../chunk-VAAZWX4U.mjs';

package/dist/middleware/payment.d.ts

@@ -0,0 +1,22 @@
+import { t as ToolMiddleware } from '../types-CqT2idkd.js';
+import '@modelcontextprotocol/sdk/types.js';
+import 'zod';
+
+interface PaymentOptions {
+    /** Middleware name. Default: "payment" */
+    name?: string;
+    /** Session key for storing payment confirmation. Default: "payment" */
+    sessionKey?: string;
+    /** Message shown to the user. Default: "Please complete payment to continue." */
+    message?: string;
+    /** Build the payment page URL. */
+    buildUrl: (params: {
+        sessionId: string;
+        elicitationId: string;
+    }) => string;
+    /** Timeout in ms. Default: 300000 */
+    timeout?: number;
+}
+declare function payment(options: PaymentOptions): ToolMiddleware;
+
+export { type PaymentOptions, payment };

package/dist/middleware/payment.mjs

@@ -0,0 +1 @@
+import {a}from'../chunk-STWVQGX5.mjs';import'../chunk-VAAZWX4U.mjs';function i(e){let t={name:e.name??"payment",sessionKey:e.sessionKey??"payment",message:e.message??"Please complete payment to continue.",buildUrl:e.buildUrl,declineMessage:"Payment cancelled."};return e.timeout!==void 0&&(t.timeout=e.timeout),a(t)}export{i as payment};

package/dist/middleware/rate-limit.d.ts

@@ -0,0 +1,15 @@
+import { t as ToolMiddleware } from '../types-CqT2idkd.js';
+import '@modelcontextprotocol/sdk/types.js';
+import 'zod';
+
+interface RateLimitOptions {
+    /** Maximum calls per window. */
+    max: number;
+    /** Window duration in milliseconds. Default: 60000 (1 minute) */
+    windowMs?: number;
+    /** Error message. */
+    message?: string;
+}
+declare function rateLimit(options: RateLimitOptions): ToolMiddleware;
+
+export { type RateLimitOptions, rateLimit };

package/dist/middleware/rate-limit.mjs

@@ -0,0 +1 @@
+import {c}from'../chunk-VAAZWX4U.mjs';function l(n){let{max:o,windowMs:r=6e4}=n,u=n.message??`Rate limit exceeded. Max ${o} calls per ${r/1e3}s.`;return {name:"rateLimit",async onCall(t,i){let s=`rateLimit:${t.toolName}`,e=t.session.get(s),a=Date.now();return !e||a>=e.resetAt?(t.session.set(s,{count:1,resetAt:a+r}),i()):e.count>=o?c(u):(t.session.set(s,{...e,count:e.count+1}),i())}}}export{l as rateLimit};

package/dist/middleware/truncate.d.ts

@@ -0,0 +1,13 @@
+import { t as ToolMiddleware } from '../types-CqT2idkd.js';
+import '@modelcontextprotocol/sdk/types.js';
+import 'zod';
+
+interface TruncateOptions {
+    /** Maximum characters per text content block. */
+    maxChars: number;
+    /** Suffix appended when truncated. Default: "..." */
+    suffix?: string;
+}
+declare function truncate(options: TruncateOptions): ToolMiddleware;
+
+export { type TruncateOptions, truncate };

package/dist/middleware/truncate.mjs

@@ -0,0 +1 @@
+function a(e){let{maxChars:r}=e,n=e.suffix??"...";return {name:"truncate",onResult(s){return {...s,content:s.content.map(t=>t.type==="text"&&t.text&&t.text.length>r?{...t,text:t.text.slice(0,r-n.length)+n}:t)}}}}export{a as truncate};

package/dist/middleware/url-action.d.ts

@@ -0,0 +1,24 @@
+import { t as ToolMiddleware } from '../types-CqT2idkd.js';
+import '@modelcontextprotocol/sdk/types.js';
+import 'zod';
+
+interface UrlActionOptions {
+    /** Middleware name. Default: "url-action" */
+    name?: string;
+    /** Session key to check/store result. Default: "user" */
+    sessionKey?: string;
+    /** Message shown to the user in the elicitation. */
+    message: string;
+    /** Build the URL. Receives sessionId and elicitationId for callback routing. */
+    buildUrl: (params: {
+        sessionId: string;
+        elicitationId: string;
+    }) => string;
+    /** Timeout in ms for waiting for external callback. Default: 300000 (5 min). */
+    timeout?: number;
+    /** Error message when user declines. Default: "Action cancelled." */
+    declineMessage?: string;
+}
+declare function urlAction(options: UrlActionOptions): ToolMiddleware;
+
+export { type UrlActionOptions, urlAction };

package/dist/middleware/url-action.mjs

@@ -0,0 +1 @@
+export{a as urlAction}from'../chunk-STWVQGX5.mjs';import'../chunk-VAAZWX4U.mjs';

package/dist/test.d.ts

@@ -1,5 +1,5 @@
 import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
-import { m as Session, M as MCPServer } from './types-BqH9Me9B.js';
+import { l as Session, M as MCPServer } from './types-CqT2idkd.js';
 import 'zod';
 
 interface TestClient {

package/dist/{types-BqH9Me9B.d.ts → types-CqT2idkd.d.ts}

@@ -1,6 +1,21 @@
-import { CreateMessageRequestParamsBase, CreateMessageResult, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolResult, CreateMessageRequestParamsBase, CreateMessageResult } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 
+interface ToolResponse extends CallToolResult {
+    text(value: string): ToolResponse;
+    json(value: unknown): ToolResponse;
+    error(message: string): ToolResponse;
+    image(data: string, mimeType: string): ToolResponse;
+}
+/** Create a text response. Chainable. */
+declare function text(value: string): ToolResponse;
+/** Create a JSON response (serialized to text). Chainable. */
+declare function json(value: unknown): ToolResponse;
+/** Create an error response. Chainable. */
+declare function error(message: string): ToolResponse;
+/** Create an image response. Chainable. */
+declare function image(data: string, mimeType: string): ToolResponse;
+
 interface ServerInfo {
     name: string;
     version: string;
@@ -23,31 +38,26 @@ interface Session {
     /** Disable specific resources by URI. */
     disableResources(...uris: string[]): void;
 }
-interface ElicitFormParams {
-    message: string;
-    schema: Record<string, {
-        type: "string" | "number" | "boolean";
-        description?: string;
-        enum?: string[];
-        default?: unknown;
-    }>;
-}
-interface ElicitFormResult {
+interface ElicitFormResult<T = Record<string, string | number | boolean | string[]>> {
     action: "accept" | "decline" | "cancel";
-    content: Record<string, string | number | boolean | string[]>;
-}
-interface ElicitUrlParams {
-    message: string;
-    url: string;
+    content: T;
 }
 interface ElicitUrlResult {
     action: "accept" | "decline" | "cancel";
 }
+interface ElicitUrlOptions {
+    /** Pre-generated elicitation ID. If omitted, a random UUID is used. */
+    elicitationId?: string;
+    /** If true, wait for completeElicitation() before resolving. Default: false. */
+    waitForCompletion?: boolean;
+    /** Timeout in ms for waiting. Default: 300000 (5 minutes). */
+    timeout?: number;
+}
 interface Elicit {
     /** Request structured data from the user via a form. */
-    form(params: ElicitFormParams): Promise<ElicitFormResult>;
+    form<T extends z.ZodObject<z.ZodRawShape>>(message: string, schema: T): Promise<ElicitFormResult<z.infer<T>>>;
     /** Direct the user to an external URL. */
-    url(params: ElicitUrlParams): Promise<ElicitUrlResult>;
+    url(message: string, url: string, options?: ElicitUrlOptions): Promise<ElicitUrlResult>;
 }
 interface SampleOptions {
     maxTokens?: number;
@@ -86,6 +96,14 @@ interface ToolContext {
     roots: () => Promise<RootInfo[]>;
     /** Request LLM inference from the client. */
     sample: Sample;
+    /** Create a text response. Chainable. */
+    text(value: string): ToolResponse;
+    /** Create a JSON response. Chainable. */
+    json(value: unknown): ToolResponse;
+    /** Create an error response. Chainable. */
+    error(message: string): ToolResponse;
+    /** Create an image response. Chainable. */
+    image(data: string, mimeType: string): ToolResponse;
 }
 interface ToolInfo {
     name: string;
@@ -98,16 +116,16 @@ interface ToolMiddleware {
     /** Called when a tool is registered. Return false to hide the tool initially. */
     onRegister?(tool: ToolInfo): boolean | undefined;
     /** Called when a tool is invoked. Must call next() to continue the chain. */
-    onCall?(ctx: ToolContext, next: () => Promise<CallToolResult>): Promise<CallToolResult>;
+    onCall?(c: ToolContext, next: () => Promise<CallToolResult>): Promise<CallToolResult>;
     /** Called after the handler returns. Runs in reverse middleware order. */
-    onResult?(result: CallToolResult, ctx: ToolContext): CallToolResult | Promise<CallToolResult>;
+    onResult?(result: CallToolResult, c: ToolContext): CallToolResult | Promise<CallToolResult>;
 }
 type InferInput<T> = T extends z.ZodTypeAny ? z.output<T> : Record<string, unknown>;
 interface ToolConfig<TInput = unknown> {
     description?: string;
     input?: TInput;
 }
-type ToolHandler<TInput = unknown> = (args: InferInput<TInput>, ctx: ToolContext) => CallToolResult | Promise<CallToolResult>;
+type ToolHandler<TInput = unknown> = (args: InferInput<TInput>, c: ToolContext) => CallToolResult | Promise<CallToolResult>;
 /** @experimental */
 interface TaskConfig<TInput = unknown> {
     description?: string;
@@ -125,7 +143,7 @@ interface TaskContext extends ToolContext {
     task: TaskControl;
 }
 /** @experimental */
-type TaskHandler<TInput = unknown> = (args: InferInput<TInput>, ctx: TaskContext) => CallToolResult | Promise<CallToolResult>;
+type TaskHandler<TInput = unknown> = (args: InferInput<TInput>, c: TaskContext) => CallToolResult | Promise<CallToolResult>;
 interface ResourceConfig {
     name: string;
     description?: string;
@@ -143,7 +161,7 @@ interface ResourceContext {
     /** Query client-provided filesystem roots. */
     roots: () => Promise<RootInfo[]>;
 }
-type ResourceHandler = (uri: string, ctx: ResourceContext) => ResourceContent | Promise<ResourceContent>;
+type ResourceHandler = (uri: string, c: ResourceContext) => ResourceContent | Promise<ResourceContent>;
 interface HttpAdapterOptions {
     /** Disable session management. Default: false. */
     sessionless?: boolean;
@@ -151,6 +169,8 @@ interface HttpAdapterOptions {
     sessionIdGenerator?: () => string;
     /** Return JSON instead of SSE streams. Default: false. */
     enableJsonResponse?: boolean;
+    /** Called on each HTTP request after session is resolved. Use to inject auth headers into sessions. */
+    onRequest?: (req: Request, sessionId: string, session: Session) => void | Promise<void>;
 }
 interface MCPServer {
     /** Register a global middleware applied to all subsequently registered tools. */
@@ -171,6 +191,10 @@ interface MCPServer {
     stdio(): Promise<void>;
     /** Start HTTP transport. Returns a Web Standard request handler. */
     http(options?: HttpAdapterOptions): (req: Request) => Promise<Response>;
+    /** Access a session by ID (for external HTTP callback routes). Stateful mode only. */
+    session(sessionId: string): Session;
+    /** Complete a pending URL elicitation (called from external HTTP callback). */
+    completeElicitation(elicitationId: string): void;
 }
 
-export type { Elicit as E, HttpAdapterOptions as H, MCPServer as M, ResourceConfig as R, Sample as S, TaskConfig as T, ElicitFormParams as a, ElicitFormResult as b, ElicitUrlParams as c, ElicitUrlResult as d, ResourceContent as e, ResourceContext as f, ResourceHandler as g, RootInfo as h, SampleOptions as i, SampleRawParams as j, SampleRawResult as k, ServerInfo as l, Session as m, TaskContext as n, TaskControl as o, TaskHandler as p, ToolConfig as q, ToolContext as r, ToolHandler as s, ToolInfo as t, ToolMiddleware as u };
+export { type Elicit as E, type HttpAdapterOptions as H, type MCPServer as M, type ResourceConfig as R, type Sample as S, type TaskConfig as T, type ElicitFormResult as a, type ElicitUrlOptions as b, type ElicitUrlResult as c, type ResourceContent as d, type ResourceContext as e, type ResourceHandler as f, type RootInfo as g, type SampleOptions as h, type SampleRawParams as i, type SampleRawResult as j, type ServerInfo as k, type Session as l, type TaskContext as m, type TaskControl as n, type TaskHandler as o, type ToolConfig as p, type ToolContext as q, type ToolHandler as r, type ToolInfo as s, type ToolMiddleware as t, type ToolResponse as u, error as v, image as w, json as x, text as y };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lynq/lynq",
-	"version": "0.2.0",
+	"version": "0.4.0",
 	"description": "Lightweight MCP server framework. Tool visibility control through middleware.",
 	"type": "module",
 	"exports": {
@@ -27,6 +27,58 @@
 		"./test": {
 			"types": "./dist/test.d.ts",
 			"import": "./dist/test.mjs"
+		},
+		"./guard": {
+			"types": "./dist/middleware/guard.d.ts",
+			"import": "./dist/middleware/guard.mjs"
+		},
+		"./logger": {
+			"types": "./dist/middleware/logger.d.ts",
+			"import": "./dist/middleware/logger.mjs"
+		},
+		"./rate-limit": {
+			"types": "./dist/middleware/rate-limit.d.ts",
+			"import": "./dist/middleware/rate-limit.mjs"
+		},
+		"./truncate": {
+			"types": "./dist/middleware/truncate.d.ts",
+			"import": "./dist/middleware/truncate.mjs"
+		},
+		"./combine": {
+			"types": "./dist/middleware/combine.d.ts",
+			"import": "./dist/middleware/combine.mjs"
+		},
+		"./credentials": {
+			"types": "./dist/middleware/credentials.d.ts",
+			"import": "./dist/middleware/credentials.mjs"
+		},
+		"./url-action": {
+			"types": "./dist/middleware/url-action.d.ts",
+			"import": "./dist/middleware/url-action.mjs"
+		},
+		"./oauth": {
+			"types": "./dist/middleware/oauth.d.ts",
+			"import": "./dist/middleware/oauth.mjs"
+		},
+		"./payment": {
+			"types": "./dist/middleware/payment.d.ts",
+			"import": "./dist/middleware/payment.mjs"
+		},
+		"./bearer": {
+			"types": "./dist/middleware/bearer.d.ts",
+			"import": "./dist/middleware/bearer.mjs"
+		},
+		"./jwt": {
+			"types": "./dist/middleware/jwt.d.ts",
+			"import": "./dist/middleware/jwt.mjs"
+		},
+		"./github-oauth": {
+			"types": "./dist/middleware/github-oauth.d.ts",
+			"import": "./dist/middleware/github-oauth.mjs"
+		},
+		"./google-oauth": {
+			"types": "./dist/middleware/google-oauth.d.ts",
+			"import": "./dist/middleware/google-oauth.mjs"
 		}
 	},
 	"files": [
@@ -46,12 +98,15 @@
 		"docs:preview": "vitepress preview docs",
 		"prepublishOnly": "pnpm build"
 	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.27.0"
+	},
 	"devDependencies": {
 		"@biomejs/biome": "^1.9.0",
-		"@modelcontextprotocol/sdk": "^1.27.0",
 		"@types/express": "^5.0.6",
 		"express": "^5.2.1",
 		"hono": "^4.12.5",
+		"jose": "^6.2.1",
 		"tsup": "^8.0.0",
 		"typedoc": "^0.28.17",
 		"typedoc-plugin-markdown": "^4.10.0",
@@ -61,9 +116,9 @@
 		"zod": "^3.24.0"
 	},
 	"peerDependencies": {
-		"@modelcontextprotocol/sdk": "^1.27.0",
 		"express": "^5.0.0",
 		"hono": "^4.0.0",
+		"jose": "^6.0.0",
 		"zod": "^3.0.0"
 	},
 	"peerDependenciesMeta": {
@@ -75,6 +130,9 @@
 		},
 		"express": {
 			"optional": true
+		},
+		"jose": {
+			"optional": true
 		}
 	},
 	"publishConfig": {