@lynq/lynq 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 hogekai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,182 @@
+# 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)
+
+Lightweight MCP server framework. Tool visibility control through middleware.
+
+```ts
+import { createMCPServer } from "lynq";
+import { auth } from "lynq/auth";
+import { z } from "zod";
+
+const server = createMCPServer({ name: "my-server", version: "1.0.0" });
+
+// 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}` }] };
+});
+
+// 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) }] };
+});
+
+await server.stdio();
+```
+
+## Install
+
+```sh
+npm install lynq @modelcontextprotocol/sdk zod
+```
+
+## 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.
+
+```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.
+
+```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 }],
+}));
+```
+
+### `server.resource(uri, ...middlewares?, config, handler)`
+
+Register a resource. Same middleware pattern as `tool()`. Global middleware (`server.use()`) does not apply to resources.
+
+```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()),
+}));
+```
+
+### `server.use(middleware)`
+
+Apply middleware to all subsequently registered tools.
+
+```ts
+server.use(auth());
+```
+
+### Session
+
+Available in handlers and middleware via `ctx.session`:
+
+```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.
+
+```ts
+import { auth } from "lynq/auth";
+
+auth();                          // checks ctx.session.get("user")
+auth({ sessionKey: "token" });   // checks ctx.session.get("token")
+auth({ message: "Login first" }); // custom error message
+```
+
+## Testing
+
+lynq ships a test helper that eliminates MCP boilerplate. No manual `Client`/`InMemoryTransport` setup.
+
+```ts
+import { createTestClient } from "lynq/test";
+import { createMCPServer } from "lynq";
+import { auth } from "lynq/auth";
+import { z } from "zod";
+
+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" });
+
+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();
+```
+
+## License
+
+MIT

package/dist/adapters/express.d.ts

@@ -0,0 +1,14 @@
+import { Express } from 'express';
+import { M as MCPServer } from '../types-BqH9Me9B.js';
+import '@modelcontextprotocol/sdk/types.js';
+import 'zod';
+
+interface MountOptions {
+    /** Route path. Default: "/mcp" */
+    path?: string;
+    /** Allowed hostnames for DNS rebinding protection. Default: localhost variants. */
+    allowedHosts?: string[];
+}
+declare function mountLynq(app: Express, server: MCPServer, options?: MountOptions): void;
+
+export { type MountOptions, mountLynq };

package/dist/adapters/express.mjs

@@ -0,0 +1,2 @@
+import {b,a}from'../chunk-7C4A572Z.mjs';function u(e){let t=e.protocol||"http",s=e.headers.host||"localhost",o=`${t}://${s}${e.originalUrl}`,r=new Headers;for(let[a,n]of Object.entries(e.headers))n&&r.set(a,Array.isArray(n)?n.join(", "):n);let i={method:e.method,headers:r};return e.method!=="GET"&&e.method!=="HEAD"&&(i.body=JSON.stringify(e.body)),new Request(o,i)}async function h(e,t){if(e.status(t.status),t.headers.forEach((s,o)=>e.setHeader(o,s)),t.body){let s=t.body.getReader();try{for(;;){let{done:o,value:r}=await s.read();if(o)break;e.write(r);}}finally{e.end();}}else e.end();}function y(e,t,s){let o=s?.path??"/mcp",r=t.http(),i=s?.allowedHosts??[...b];e.use(o,(a$1,n,d)=>{if(!a(a$1.headers.host??null,i)){n.status(403).json({jsonrpc:"2.0",error:{code:-32e3,message:"Forbidden"},id:null});return}d();}),e.all(o,async(a,n)=>{let d=u(a),p=await r(d);await h(n,p);});}
+export{y as mountLynq};

package/dist/adapters/hono.d.ts

@@ -0,0 +1,14 @@
+import { Hono } from 'hono';
+import { M as MCPServer } from '../types-BqH9Me9B.js';
+import '@modelcontextprotocol/sdk/types.js';
+import 'zod';
+
+interface MountOptions {
+    /** Route path. Default: "/mcp" */
+    path?: string;
+    /** Allowed hostnames for DNS rebinding protection. Default: localhost variants. */
+    allowedHosts?: string[];
+}
+declare function mountLynq(app: Hono, server: MCPServer, options?: MountOptions): void;
+
+export { type MountOptions, mountLynq };

package/dist/adapters/hono.mjs

@@ -0,0 +1 @@
+import {b,a}from'../chunk-7C4A572Z.mjs';function m(t,a$1,e){let r=e?.path??"/mcp",l=a$1.http(),i=e?.allowedHosts??[...b];t.use(r,async(o,p)=>a(o.req.header("host")??null,i)?p():o.json({jsonrpc:"2.0",error:{code:-32e3,message:"Forbidden"},id:null},403)),t.all(r,o=>l(o.req.raw));}export{m as mountLynq};

package/dist/adapters/stdio.d.ts

@@ -0,0 +1 @@
+export { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

package/dist/adapters/stdio.mjs

@@ -0,0 +1 @@
+export{StdioServerTransport}from'@modelcontextprotocol/sdk/server/stdio.js';

package/dist/chunk-7C4A572Z.mjs

@@ -0,0 +1 @@
+function e(n,t){if(!n)return  false;let o=n.replace(/:\d+$/,"");return t.includes(o)}var l=["localhost","127.0.0.1","::1"];export{e as a,l as b};

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+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 '@modelcontextprotocol/sdk/types.js';
+import 'zod';
+
+declare function createMCPServer(info: {
+    name: string;
+    version: string;
+}): MCPServer;
+
+export { MCPServer, createMCPServer };

package/dist/index.mjs

@@ -0,0 +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};

package/dist/middleware/auth.d.ts

@@ -0,0 +1,13 @@
+import { u as ToolMiddleware } from '../types-BqH9Me9B.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;
+
+export { type AuthOptions, auth };

package/dist/middleware/auth.mjs

@@ -0,0 +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};

package/dist/test.d.ts

@@ -0,0 +1,39 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { m as Session, M as MCPServer } from './types-BqH9Me9B.js';
+import 'zod';
+
+interface TestClient {
+    /** List visible tool names. */
+    listTools(): Promise<string[]>;
+    /** Call a tool and return the full result. */
+    callTool(name: string, args?: Record<string, unknown>): Promise<CallToolResult>;
+    /** Call a tool and return the first text content. Throws if isError. */
+    callToolText(name: string, args?: Record<string, unknown>): Promise<string>;
+    /** List visible resource URIs (static only). */
+    listResources(): Promise<string[]>;
+    /** List visible resource template URIs. */
+    listResourceTemplates(): Promise<string[]>;
+    /** Read a resource and return its text content. */
+    readResource(uri: string): Promise<string>;
+    /** Authorize a middleware (enable tools/resources guarded by it). */
+    authorize(middlewareName: string): void;
+    /** Revoke a middleware authorization. */
+    revoke(middlewareName: string): void;
+    /** Direct session access for test setup. */
+    session: Session;
+    /** Close the test client and clean up. */
+    close(): Promise<void>;
+}
+declare function createTestClient(server: MCPServer): Promise<TestClient>;
+declare const matchers: {
+    toHaveTextContent(received: CallToolResult, expected: string): {
+        pass: boolean;
+        message: () => string;
+    };
+    toBeError(received: CallToolResult): {
+        pass: boolean;
+        message: () => "Expected result not to be an error" | "Expected result to be an error (isError: true)";
+    };
+};
+
+export { type TestClient, createTestClient, matchers };

package/dist/test.mjs

@@ -0,0 +1 @@
+async function d(n){let{Client:r}=await import('@modelcontextprotocol/sdk/client/index.js'),{InMemoryTransport:c}=await import('@modelcontextprotocol/sdk/inMemory.js'),[o,a]=c.createLinkedPair(),t=new r({name:"lynq-test",version:"1.0.0"},{capabilities:{tasks:{}}}),u=n;await Promise.all([u._server.connect(a),t.connect(o)]);let l=u._createSessionAPI("default");return {async listTools(){return (await t.listTools()).tools.map(s=>s.name)},async callTool(e,s={}){return t.callTool({name:e,arguments:s})},async callToolText(e,s={}){let i=await t.callTool({name:e,arguments:s});if(i.isError){let p=i.content.find(g=>g.type==="text")?.text??"Unknown error";throw new Error(p)}return i.content.find(m=>m.type==="text")?.text??""},async listResources(){return (await t.listResources()).resources.map(s=>s.uri)},async listResourceTemplates(){return (await t.listResourceTemplates()).resourceTemplates.map(s=>s.uriTemplate)},async readResource(e){return (await t.readResource({uri:e})).contents[0]?.text??""},authorize(e){l.authorize(e);},revoke(e){l.revoke(e);},session:l,async close(){await t.close();}}}var y={toHaveTextContent(n,r){let o=n.content.filter(t=>t.type==="text").map(t=>t.text??""),a=o.some(t=>t.includes(r));return {pass:a,message:()=>a?`Expected result not to contain "${r}"`:`Expected result to contain "${r}", got: ${o.join(", ")}`}},toBeError(n){let r=n.isError===true;return {pass:r,message:()=>r?"Expected result not to be an error":"Expected result to be an error (isError: true)"}}};export{d as createTestClient,y as matchers};

package/dist/types-BqH9Me9B.d.ts

@@ -0,0 +1,176 @@
+import { CreateMessageRequestParamsBase, CreateMessageResult, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+
+interface ServerInfo {
+    name: string;
+    version: string;
+}
+interface Session {
+    /** Get a session-scoped value. */
+    get<T = unknown>(key: string): T | undefined;
+    /** Set a session-scoped value. */
+    set(key: string, value: unknown): void;
+    /** Authorize a middleware by name, enabling all tools and resources guarded by it. */
+    authorize(middlewareName: string): void;
+    /** Revoke a middleware authorization, disabling all tools and resources guarded by it. */
+    revoke(middlewareName: string): void;
+    /** Enable specific tools by name. */
+    enableTools(...names: string[]): void;
+    /** Disable specific tools by name. */
+    disableTools(...names: string[]): void;
+    /** Enable specific resources by URI. */
+    enableResources(...uris: string[]): void;
+    /** 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 {
+    action: "accept" | "decline" | "cancel";
+    content: Record<string, string | number | boolean | string[]>;
+}
+interface ElicitUrlParams {
+    message: string;
+    url: string;
+}
+interface ElicitUrlResult {
+    action: "accept" | "decline" | "cancel";
+}
+interface Elicit {
+    /** Request structured data from the user via a form. */
+    form(params: ElicitFormParams): Promise<ElicitFormResult>;
+    /** Direct the user to an external URL. */
+    url(params: ElicitUrlParams): Promise<ElicitUrlResult>;
+}
+interface SampleOptions {
+    maxTokens?: number;
+    /** Model hint — the client makes the final decision. */
+    model?: string;
+    system?: string;
+    temperature?: number;
+    stopSequences?: string[];
+}
+type SampleRawParams = CreateMessageRequestParamsBase;
+type SampleRawResult = CreateMessageResult;
+interface Sample {
+    /** Send text, get text back. */
+    (prompt: string, options?: SampleOptions): Promise<string>;
+    /** Full SDK createMessage params and result. */
+    raw(params: SampleRawParams): Promise<SampleRawResult>;
+}
+interface RootInfo {
+    /** The root URI. Currently always `file://`. */
+    uri: string;
+    /** Optional human-readable name for the root. */
+    name?: string;
+}
+interface ToolContext {
+    /** The name of the tool being called. */
+    toolName: string;
+    /** Session-scoped state and visibility control. */
+    session: Session;
+    /** Abort signal from the client. */
+    signal: AbortSignal;
+    /** Session ID. */
+    sessionId: string;
+    /** Request information from the user. */
+    elicit: Elicit;
+    /** Query client-provided filesystem roots. */
+    roots: () => Promise<RootInfo[]>;
+    /** Request LLM inference from the client. */
+    sample: Sample;
+}
+interface ToolInfo {
+    name: string;
+    description?: string | undefined;
+    middlewares: readonly ToolMiddleware[];
+}
+interface ToolMiddleware {
+    /** Unique name for this middleware instance. Used for authorize()/revoke(). */
+    name: string;
+    /** 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>;
+    /** Called after the handler returns. Runs in reverse middleware order. */
+    onResult?(result: CallToolResult, ctx: 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>;
+/** @experimental */
+interface TaskConfig<TInput = unknown> {
+    description?: string;
+    input?: TInput;
+}
+/** @experimental */
+interface TaskControl {
+    /** Report progress. percentage: 0-100. message: optional status text. */
+    progress(percentage: number, message?: string): void;
+    /** True when the client has cancelled this task. */
+    readonly cancelled: boolean;
+}
+/** @experimental */
+interface TaskContext extends ToolContext {
+    task: TaskControl;
+}
+/** @experimental */
+type TaskHandler<TInput = unknown> = (args: InferInput<TInput>, ctx: TaskContext) => CallToolResult | Promise<CallToolResult>;
+interface ResourceConfig {
+    name: string;
+    description?: string;
+    mimeType?: string;
+}
+interface ResourceContent {
+    text?: string;
+    blob?: string;
+    mimeType?: string;
+}
+interface ResourceContext {
+    uri: string;
+    session: Session;
+    sessionId: string;
+    /** Query client-provided filesystem roots. */
+    roots: () => Promise<RootInfo[]>;
+}
+type ResourceHandler = (uri: string, ctx: ResourceContext) => ResourceContent | Promise<ResourceContent>;
+interface HttpAdapterOptions {
+    /** Disable session management. Default: false. */
+    sessionless?: boolean;
+    /** Custom session ID generator. Default: crypto.randomUUID(). */
+    sessionIdGenerator?: () => string;
+    /** Return JSON instead of SSE streams. Default: false. */
+    enableJsonResponse?: boolean;
+}
+interface MCPServer {
+    /** Register a global middleware applied to all subsequently registered tools. */
+    use(middleware: ToolMiddleware): void;
+    /** Register a tool with config and handler. */
+    tool<TInput>(name: string, config: ToolConfig<TInput>, handler: ToolHandler<TInput>): void;
+    /** Register a tool with per-tool middlewares, config, and handler. */
+    tool<TInput>(name: string, ...args: [...ToolMiddleware[], ToolConfig<TInput>, ToolHandler<TInput>]): void;
+    /** Register a resource with config and handler. */
+    resource(uri: string, config: ResourceConfig, handler: ResourceHandler): void;
+    /** Register a resource with per-resource middlewares, config, and handler. */
+    resource(uri: string, ...args: [...ToolMiddleware[], ResourceConfig, ResourceHandler]): void;
+    /** @experimental Register a task with config and handler. */
+    task<TInput>(name: string, config: TaskConfig<TInput>, handler: TaskHandler<TInput>): void;
+    /** @experimental Register a task with per-task middlewares, config, and handler. */
+    task<TInput>(name: string, ...args: [...ToolMiddleware[], TaskConfig<TInput>, TaskHandler<TInput>]): void;
+    /** Start stdio transport. */
+    stdio(): Promise<void>;
+    /** Start HTTP transport. Returns a Web Standard request handler. */
+    http(options?: HttpAdapterOptions): (req: Request) => Promise<Response>;
+}
+
+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 };

package/package.json

@@ -0,0 +1,103 @@
+{
+	"name": "@lynq/lynq",
+	"version": "0.1.0",
+	"description": "Lightweight MCP server framework. Tool visibility control through middleware.",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.mjs"
+		},
+		"./auth": {
+			"types": "./dist/middleware/auth.d.ts",
+			"import": "./dist/middleware/auth.mjs"
+		},
+		"./stdio": {
+			"types": "./dist/adapters/stdio.d.ts",
+			"import": "./dist/adapters/stdio.mjs"
+		},
+		"./hono": {
+			"types": "./dist/adapters/hono.d.ts",
+			"import": "./dist/adapters/hono.mjs"
+		},
+		"./express": {
+			"types": "./dist/adapters/express.d.ts",
+			"import": "./dist/adapters/express.mjs"
+		},
+		"./test": {
+			"types": "./dist/test.d.ts",
+			"import": "./dist/test.mjs"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"build": "tsup",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"lint": "biome check src tests",
+		"lint:fix": "biome check --write src tests",
+		"typecheck": "tsc --noEmit",
+		"prepublishOnly": "pnpm build"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^1.9.0",
+		"@modelcontextprotocol/sdk": "^1.27.0",
+		"@types/express": "^5.0.6",
+		"express": "^5.2.1",
+		"hono": "^4.12.5",
+		"tsup": "^8.0.0",
+		"typescript": "^5.6.0",
+		"vitest": "^2.0.0",
+		"zod": "^3.24.0"
+	},
+	"peerDependencies": {
+		"@modelcontextprotocol/sdk": "^1.27.0",
+		"express": "^5.0.0",
+		"hono": "^4.0.0",
+		"zod": "^3.0.0"
+	},
+	"peerDependenciesMeta": {
+		"zod": {
+			"optional": true
+		},
+		"hono": {
+			"optional": true
+		},
+		"express": {
+			"optional": true
+		}
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"keywords": [
+		"mcp",
+		"model-context-protocol",
+		"framework",
+		"middleware",
+		"ai",
+		"agent"
+	],
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/hogekai/lynq"
+	},
+	"bugs": {
+		"url": "https://github.com/hogekai/lynq/issues"
+	},
+	"homepage": "https://github.com/hogekai/lynq#readme",
+	"license": "MIT",
+	"engines": {
+		"node": ">=18"
+	},
+	"packageManager": "pnpm@10.30.1",
+	"pnpm": {
+		"onlyBuiltDependencies": [
+			"@biomejs/biome",
+			"esbuild"
+		]
+	}
+}