spiceflow 1.1.18 → 1.3.0

package/README.md

@@ -5,7 +5,6 @@
     <h3>spiceflow</h3>
     <br/>
     <p>fast, simple and type safe API framework</p>
-    <p>still in beata</p>
     <br/>
     <br/>
 </div>
@@ -16,12 +15,14 @@ Spiceflow is a lightweight, type-safe API framework for building web services us
 
 ## Features
 
-- Type safety
-- OpenAPI compatibility
-- RPC client generation
+- Type safe schema based validation via Zod
+- Can easily generate OpenAPI document based on your routes
+- Native support for [Fern](https://github.com/fern-api/fern) to generate docs and SDKs (see example docs [here](https://remorses.docs.buildwithfern.com))
+- Support for [Model Context Protocol](https://modelcontextprotocol.io/) to easily wire your app with LLMs
+- Type safe RPC client generation
 - Simple and intuitive API
 - Uses web standards for requests and responses
-- Supports async generators for streaming
+- Supports async generators for streaming via server sent events
 - Modular design with `.use()` for mounting sub-apps
 - Base path support
 
@@ -33,6 +34,8 @@ npm install spiceflow
 
 ## Basic Usage
 
+Objects returned from route handlers are automatically serialized to JSON
+
 ```ts
 import { Spiceflow } from 'spiceflow'
 
@@ -40,20 +43,20 @@ const app = new Spiceflow()
   .get('/hello', () => 'Hello, World!')
   .post('/echo', async ({ request }) => {
     const body = await request.json()
-    return body
+    return { echo: body }
   })
 
 app.listen(3000)
 ```
 
-> Notice that you should never declare app separately and add routes later, that way you lose the type safety. Instead always declare all routes in one place.
+> Never declare app and add routes separately, that way you lose the type safety. Instead always append routes with .post and .get in a single expression.
 
 ```ts
 // This is an example of what NOT to do when using Spiceflow
 
 import { Spiceflow } from 'spiceflow'
 
-// Do NOT declare the app separately and add routes later
+// DO NOT declare the app separately and add routes later
 const app = new Spiceflow()
 
 // Do NOT do this! Adding routes separately like this will lose type safety
@@ -62,7 +65,6 @@ app.post('/echo', async ({ request }) => {
   const body = await request.json()
   return body
 })
-
 ```
 
 ## Requests and Responses
@@ -91,7 +93,6 @@ new Spiceflow().post(
 > Notice that to get the body of the request, you need to call `request.json()` to parse the body as JSON.
 > Spiceflow does not parse the Body automatically, there is no body field in the Spiceflow route argument, instead you call either `request.json()` or `request.formData()` to get the body and validate it at the same time. This works by wrapping the request in a `SpiceflowRequest` instance, which has a `json()` and `formData()` method that parse the body and validate it. The returned data will have the correct schema type instead of `any`.
 
-
 ### Response Schema
 
 ```ts
@@ -282,6 +283,88 @@ new Spiceflow().use(({ request }) => {
 })
 ```
 
+## How errors are handled in Spiceflow client
+
+The Spiceflow client provides type-safe error handling by returning either a `data` or `error` property. When using the client:
+
+- Thrown errors appear in the `error` field
+- Response objects can be thrown or returned
+- Responses with status codes 200-299 appear in the `data` field
+- Responses with status codes <200 or ≥300 appear in the `error` field
+
+The example below demonstrates handling different types of responses:
+
+```ts
+import { Spiceflow } from 'spiceflow'
+import { createSpiceflowClient } from 'spiceflow/client'
+
+const app = new Spiceflow()
+  .get('/error', () => {
+    throw new Error('Something went wrong')
+  })
+  .get('/unauthorized', () => {
+    return new Response('Unauthorized access', { status: 401 })
+  })
+  .get('/success', () => {
+    throw new Response('Success message', { status: 200 })
+    return ''
+  })
+
+const client = createSpiceflowClient<typeof app>('http://localhost:3000')
+
+async function handleErrors() {
+  const errorResponse = await client.error.get()
+  console.log('Calling error endpoint...')
+  // Logs: Error occurred: Something went wrong
+  if (errorResponse.error) {
+    console.error('Error occurred:', errorResponse.error)
+  }
+
+  const unauthorizedResponse = await client.unauthorized.get()
+  console.log('Calling unauthorized endpoint...')
+  // Logs: Unauthorized: Unauthorized access (Status: 401)
+  if (unauthorizedResponse.error) {
+    console.error('Unauthorized:', unauthorizedResponse.error)
+  }
+
+  const successResponse = await client.success.get()
+  console.log('Calling success endpoint...')
+  // Logs: Success: Success message
+  if (successResponse.data) {
+    console.log('Success:', successResponse.data)
+  }
+}
+```
+
+## Using the client server side, without network requests
+
+When using the client server-side, you can pass the Spiceflow app instance directly to `createSpiceflowClient()` instead of providing a URL. This allows you to make "virtual" requests that are handled directly by the app without making actual network requests. This is useful for testing, generating documentation, or any other scenario where you want to interact with your API endpoints programmatically without setting up a server.
+
+Here's an example:
+
+```tsx
+import { Spiceflow } from 'spiceflow'
+import { createSpiceflowClient } from 'spiceflow/client'
+import { openapi } from 'spiceflow/openapi'
+import { writeFile } from 'node:fs/promises'
+
+const app = new Spiceflow()
+  .use(openapi({ path: '/openapi' }))
+  .get('/users', () => [
+    { id: 1, name: 'John' },
+    { id: 2, name: 'Jane' },
+  ])
+  .post('/users', ({ request }) => request.json())
+
+// Create client by passing app instance directly
+const client = createSpiceflowClient(app)
+
+// Get OpenAPI schema and write to disk
+const { data } = await client.openapi.get()
+await writeFile('openapi.json', JSON.stringify(data, null, 2))
+console.log('OpenAPI schema saved to openapi.json')
+```
+
 ## Modifying Response with Middleware
 
 Middleware in Spiceflow can be used to modify the response before it's sent to the client. This is useful for adding headers, transforming the response body, or performing any other operations on the response.
@@ -434,3 +517,155 @@ new Spiceflow()
     return { ok: true }
   })
 ```
+
+## Model Context Protocol (MCP)
+
+Spiceflow includes a Model Context Protocol (MCP) plugin that exposes your API routes as tools and resources that can be used by AI language models like Claude. The MCP plugin makes it easy to let AI assistants interact with your API endpoints in a controlled way.
+
+When you mount the MCP plugin (default path is `/mcp`), it automatically:
+
+- Exposes all your routes as callable tools with proper input validation
+- Exposes GET routes without query/path parameters as `resources`
+- Provides an SSE-based transport for real-time communication
+- Handles serialization of requests and responses
+
+This makes it simple to let AI models like Claude discover and call your API endpoints programmatically. Here's an example:
+
+```tsx
+// Import the MCP plugin and client
+import { mcp } from 'spiceflow/mcp'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js'
+import { Spiceflow } from 'spiceflow'
+import {
+  ListToolsResultSchema,
+  CallToolResultSchema,
+  ListResourcesResultSchema,
+} from '@modelcontextprotocol/sdk/types.js'
+
+// Create a new app with some example routes
+const app = new Spiceflow()
+  // Mount the MCP plugin at /mcp (default path)
+  .use(mcp())
+  // These routes will be available as tools
+  .get('/hello', () => 'Hello World')
+  .get('/users/:id', ({ params }) => ({ id: params.id }))
+  .post('/echo', async ({ request }) => {
+    const body = await request.json()
+    return body
+  })
+
+// Start the server
+app.listen(3000)
+
+// Example client usage:
+const transport = new SSEClientTransport(new URL('http://localhost:3000/mcp'))
+
+const client = new Client(
+  { name: 'example-client', version: '1.0.0' },
+  { capabilities: {} },
+)
+
+await client.connect(transport)
+
+// List available tools
+const tools = await client.request(
+  { method: 'tools/list' },
+  ListToolsResultSchema,
+)
+
+// Call a tool
+const result = await client.request(
+  {
+    method: 'tools/call',
+    params: {
+      name: 'GET /hello',
+      arguments: {},
+    },
+  },
+  CallToolResultSchema,
+)
+
+// List available resources (only GET /hello is exposed since it has no params)
+const resources = await client.request(
+  { method: 'resources/list' },
+  ListResourcesResultSchema,
+)
+```
+
+## Generating Fern docs and SDK
+
+Spiceflow has native support for Fern docs and SDK generation using openapi plugin.
+
+The openapi types also have additional types for `x-fern` extensions to help you customize your docs and SDK.
+
+Here is an example script to help you generate an openapi.yml file that you can then use with Fern:
+
+```ts
+import fs from 'fs'
+import path from 'path'
+import yaml from 'js-yaml'
+import { Spiceflow } from 'spiceflow'
+import { openapi } from 'spiceflow/openapi'
+import { createSpiceflowClient } from 'spiceflow/client'
+
+const app = new Spiceflow()
+  .use(openapi({ path: '/openapi' }))
+  .get('/hello', () => 'Hello World')
+
+async function main() {
+  console.log('Creating Spiceflow client...')
+  const client = createSpiceflowClient(app)
+
+  console.log('Fetching OpenAPI spec...')
+  const { data: openapiJson, error } = await client.openapi.get()
+  if (error) {
+    console.error('Failed to fetch OpenAPI spec:', error)
+    throw error
+  }
+
+  const outputPath = path.resolve('./openapi.yml')
+  console.log('Writing OpenAPI spec to', outputPath)
+  fs.writeFileSync(
+    outputPath,
+    yaml.dump(openapiJson, {
+      indent: 2,
+      lineWidth: -1,
+    }),
+  )
+  console.log('Successfully wrote OpenAPI spec')
+}
+
+main().catch((e) => {
+  console.error('Failed to generate OpenAPI spec:', e)
+  process.exit(1)
+})
+```
+
+Then follow Fern docs to generate the SDK and docs. You will need to create some Fern yml config files.
+
+You can take a look at the [`scripts/example-app.ts`](spiceflow/scripts/example-app.ts) file for an example app that generates the docs and SDK.
+
+## Fern SDK streaming support
+
+When you use an async generator in your app, Spiceflow will automatically add the required `x-fern` extensions to the OpenAPI spec to support streaming.
+
+Here is what streaming looks like in the Fern generated SDK:
+
+```ts
+import { ExampleSdkClient } from './sdk-typescript'
+
+const sdk = new ExampleSdkClient({
+  environment: 'http://localhost:3000',
+})
+
+// Get stream data
+const stream = await sdk.getStream()
+for await (const data of stream) {
+  console.log('Stream data:', data)
+}
+
+// Simple GET request
+const response = await sdk.getUsers()
+console.log('Users:', response)
+```

package/dist/cors.d.ts

@@ -16,6 +16,8 @@ type CORSOptions = {
     credentials?: boolean;
     /** Configures the Access-Control-Expose-Headers CORS header */
     exposeHeaders?: string[];
+    /** Configures browser and CDN caching duration for CORS preflight requests in seconds. Set to 0 to disable. */
+    cacheAge?: number;
 };
 export declare const cors: (options?: CORSOptions) => MiddlewareHandler;
 export {};

package/dist/cors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../src/cors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAC9C;;;GAGG;AACH,KAAK,WAAW,GAAG;IACjB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACzB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,kEAAkE;IAClE,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;CACzB,CAAA;AAED,eAAO,MAAM,IAAI,aAAc,WAAW,KAAG,iBAyF5C,CAAA"}
+{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../src/cors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAC9C;;;GAGG;AACH,KAAK,WAAW,GAAG;IACjB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACzB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,kEAAkE;IAClE,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB,+GAA+G;IAC/G,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,eAAO,MAAM,IAAI,aAAc,WAAW,KAAG,iBAmG5C,CAAA"}

package/dist/cors.js

@@ -4,6 +4,7 @@ export const cors = (options) => {
         allowMethods: ['GET', 'HEAD', 'PUT', 'POST', 'DELETE', 'PATCH'],
         allowHeaders: [],
         exposeHeaders: [],
+        cacheAge: 21600 // 6 hours default
     };
     const opts = Object.assign(Object.assign({}, defaults), options);
     const findAllowOrigin = ((optsOrigin) => {
@@ -45,8 +46,15 @@ export const cors = (options) => {
             set('Access-Control-Expose-Headers', opts.exposeHeaders.join(','));
         }
         if (c.request.method === 'OPTIONS') {
-            if (opts.maxAge != null) {
-                set('Access-Control-Max-Age', opts.maxAge.toString());
+            // Set CORS caching headers if enabled
+            if (opts.cacheAge && opts.cacheAge > 0) {
+                // CORS preflight cache
+                set('Access-Control-Max-Age', opts.cacheAge.toString());
+                // Browser cache and CDN cache
+                set('Cache-Control', `public, max-age=${opts.cacheAge}, s-maxage=${opts.cacheAge}`);
+                // Additional CDN-specific headers
+                set('CDN-Cache-Control', `public, s-maxage=${opts.cacheAge}`);
+                set('Cloudflare-CDN-Cache-Control', `public, s-maxage=${opts.cacheAge}`);
             }
             if ((_b = opts.allowMethods) === null || _b === void 0 ? void 0 : _b.length) {
                 set('Access-Control-Allow-Methods', opts.allowMethods.join(','));

package/dist/cors.js.map

@@ -1 +1 @@
-{"version":3,"file":"cors.js","sourceRoot":"","sources":["../src/cors.ts"],"names":[],"mappings":"AAoBA,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,OAAqB,EAAqB,EAAE;IAC/D,MAAM,QAAQ,GAAgB;QAC5B,MAAM,EAAE,GAAG;QACX,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC;QAC/D,YAAY,EAAE,EAAE;QAChB,aAAa,EAAE,EAAE;KAClB,CAAA;IACD,MAAM,IAAI,mCACL,QAAQ,GACR,OAAO,CACX,CAAA;IAED,MAAM,eAAe,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE;QACtC,IAAI,OAAO,UAAU,KAAK,QAAQ,EAAE,CAAC;YACnC,OAAO,GAAG,EAAE,CAAC,UAAU,CAAA;QACzB,CAAC;aAAM,IAAI,OAAO,UAAU,KAAK,UAAU,EAAE,CAAC;YAC5C,OAAO,UAAU,CAAA;QACnB,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,MAAc,EAAE,EAAE,CACxB,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAA;QACxD,CAAC;IACH,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IAEf,OAAO,KAAK,UAAU,IAAI,CAAC,CAAC,EAAE,IAAI;;QAChC,IAAI,QAAQ,GAAG,MAAM,IAAI,EAAE,CAAA;QAE3B,SAAS,GAAG,CAAC,GAAW,EAAE,KAAa;YACrC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;QAClC,CAAC;QAED,MAAM,WAAW,GAAG,eAAe,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAA;QAC1E,IAAI,WAAW,EAAE,CAAC;YAChB,GAAG,CAAC,6BAA6B,EAAE,WAAW,CAAC,CAAA;QACjD,CAAC;QAED,wIAAwI;QACxI,wFAAwF;QACxF,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACxB,MAAM,YAAY,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;YAElD,IAAI,YAAY,EAAE,CAAC;gBACjB,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;YAC3B,CAAC;iBAAM,CAAC;gBACN,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;YACvB,CAAC;QACH,CAAC;QAED,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,GAAG,CAAC,kCAAkC,EAAE,MAAM,CAAC,CAAA;QACjD,CAAC;QAED,IAAI,MAAA,IAAI,CAAC,aAAa,0CAAE,MAAM,EAAE,CAAC;YAC/B,GAAG,CAAC,+BAA+B,EAAE,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;QACpE,CAAC;QAED,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACnC,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;gBACxB,GAAG,CAAC,wBAAwB,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAA;YACvD,CAAC;YAED,IAAI,MAAA,IAAI,CAAC,YAAY,0CAAE,MAAM,EAAE,CAAC;gBAC9B,GAAG,CAAC,8BAA8B,EAAE,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;YAClE,CAAC;YAED,IAAI,OAAO,GAAG,IAAI,CAAC,YAAY,CAAA;YAC/B,IAAI,CAAC,CAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM,CAAA,EAAE,CAAC;gBACrB,MAAM,cAAc,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAC1C,gCAAgC,CACjC,CAAA;gBACD,IAAI,cAAc,EAAE,CAAC;oBACnB,OAAO,GAAG,cAAc,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;gBAC3C,CAAC;YACH,CAAC;YACD,IAAI,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM,EAAE,CAAC;gBACpB,GAAG,CAAC,8BAA8B,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;gBACtD,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,gCAAgC,CAAC,CAAA;YACpE,CAAC;YAED,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAA;YACzC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAA;YAEvC,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE;gBACxB,OAAO,EAAE,QAAQ,CAAC,OAAO;gBACzB,MAAM,EAAE,GAAG;gBACX,UAAU,EAAE,QAAQ,CAAC,UAAU;aAChC,CAAC,CAAA;QACJ,CAAC;QACD,OAAO,QAAQ,CAAA;IACjB,CAAC,CAAA;AACH,CAAC,CAAA"}
+{"version":3,"file":"cors.js","sourceRoot":"","sources":["../src/cors.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
-export { Spiceflow, AnySpiceflow } from './spiceflow.js';
+export { Spiceflow } from './spiceflow.js';
+export type { AnySpiceflow } from './spiceflow.js';
 export { InternalServerError, ParseError, ValidationError } from './error.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AACxD,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAClD,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAgB,MAAM,gBAAgB,CAAA;AACxD,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE1C,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA"}

package/dist/mcp-transport.d.ts

@@ -0,0 +1,45 @@
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Server transport for SSE: this will send messages over an SSE connection and receive messages from HTTP POST requests.
+ *
+ * This transport is only available in Node.js environments.
+ */
+export declare class SSEServerTransportSpiceflow implements Transport {
+    private _sessionId;
+    private _endpoint;
+    private _writableStream?;
+    response?: Response;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: (message: JSONRPCMessage) => void;
+    /**
+     * Creates a new SSE server transport, which will direct the client to POST messages to the relative or absolute URL identified by `_endpoint`.
+     */
+    constructor(endpoint: string);
+    /**
+     * Handles the initial SSE connection request.
+     *
+     * This should be called when a GET request is made to establish the SSE stream.
+     */
+    start(): Promise<void>;
+    /**
+     * Handles incoming POST messages.
+     *
+     * This should be called when a POST request is made to send a message to the server.
+     */
+    handlePostMessage(req: Request, parsedBody?: unknown): Promise<Response>;
+    /**
+     * Handle a client message, regardless of how it arrived. This can be used to inform the server of messages that arrive via a means different than HTTP POST.
+     */
+    handleMessage(message: unknown): Promise<void>;
+    close(): Promise<void>;
+    send(message: JSONRPCMessage): Promise<void>;
+    /**
+     * Returns the session ID for this transport.
+     *
+     * This can be used to route incoming POST requests.
+     */
+    get sessionId(): string;
+}
+//# sourceMappingURL=mcp-transport.d.ts.map

package/dist/mcp-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-transport.d.ts","sourceRoot":"","sources":["../src/mcp-transport.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAA;AACzE,OAAO,EACL,cAAc,EAEf,MAAM,oCAAoC,CAAA;AAG3C;;;;GAIG;AACH,qBAAa,2BAA4B,YAAW,SAAS;IAC3D,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,eAAe,CAAC,CAAyC;IACjE,QAAQ,CAAC,EAAE,QAAQ,CAAA;IAEnB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;IAChC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAA;IAE7C;;OAEG;gBACS,QAAQ,EAAE,MAAM;IAK5B;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAuC5B;;;;OAIG;IACG,iBAAiB,CACrB,GAAG,EAAE,OAAO,EACZ,UAAU,CAAC,EAAE,OAAO,GACnB,OAAO,CAAC,QAAQ,CAAC;IAmBpB;;OAEG;IACG,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAY9C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAalD;;;;OAIG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;CACF"}

package/dist/mcp-transport.js

@@ -0,0 +1,107 @@
+import { JSONRPCMessageSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { randomUUID } from 'node:crypto';
+/**
+ * Server transport for SSE: this will send messages over an SSE connection and receive messages from HTTP POST requests.
+ *
+ * This transport is only available in Node.js environments.
+ */
+export class SSEServerTransportSpiceflow {
+    /**
+     * Creates a new SSE server transport, which will direct the client to POST messages to the relative or absolute URL identified by `_endpoint`.
+     */
+    constructor(endpoint) {
+        this._sessionId = randomUUID();
+        this._endpoint = endpoint;
+    }
+    /**
+     * Handles the initial SSE connection request.
+     *
+     * This should be called when a GET request is made to establish the SSE stream.
+     */
+    async start() {
+        var _a;
+        if (this.response) {
+            throw new Error('SSEServerTransport already started! If using Server class, note that connect() calls start() automatically.');
+        }
+        const headers = new Headers({
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            // https://github.com/vercel/next.js/issues/9965
+            'content-encoding': 'none',
+            Connection: 'keep-alive',
+        });
+        // Create a TransformStream
+        const transformStream = new TransformStream();
+        const { readable, writable } = transformStream;
+        // Create the Response from the readable side
+        this.response = new Response(readable, { headers });
+        // Obtain a writer from the writable end
+        this._writableStream = writable.getWriter();
+        (_a = this._writableStream) === null || _a === void 0 ? void 0 : _a.write(new TextEncoder().encode(`event: endpoint\ndata: ${encodeURI(this._endpoint)}?sessionId=${this._sessionId}\n\n`));
+        // readable.getReader().closed.then(() => {
+        //   this.response = undefined
+        //   this._writableStream = undefined
+        //   this.onclose?.()
+        // })
+    }
+    /**
+     * Handles incoming POST messages.
+     *
+     * This should be called when a POST request is made to send a message to the server.
+     */
+    async handlePostMessage(req, parsedBody) {
+        if (!this.response) {
+            const message = 'SSE connection not established';
+            throw new Error(message);
+        }
+        let body = await req.json();
+        try {
+            await this.handleMessage(typeof body === 'string' ? JSON.parse(body) : body);
+        }
+        catch (_a) {
+            return new Response(`Invalid message: ${body}`, { status: 400 });
+        }
+        return new Response('Accepted', { status: 202 });
+    }
+    /**
+     * Handle a client message, regardless of how it arrived. This can be used to inform the server of messages that arrive via a means different than HTTP POST.
+     */
+    async handleMessage(message) {
+        var _a, _b;
+        let parsedMessage;
+        try {
+            parsedMessage = JSONRPCMessageSchema.parse(message);
+        }
+        catch (error) {
+            (_a = this.onerror) === null || _a === void 0 ? void 0 : _a.call(this, error);
+            throw error;
+        }
+        (_b = this.onmessage) === null || _b === void 0 ? void 0 : _b.call(this, parsedMessage);
+    }
+    async close() {
+        var _a;
+        if (this._writableStream) {
+            await this._writableStream.close();
+        }
+        this.response = undefined;
+        this._writableStream = undefined;
+        (_a = this.onclose) === null || _a === void 0 ? void 0 : _a.call(this);
+    }
+    async send(message) {
+        if (!this._writableStream) {
+            throw new Error('Not connected');
+        }
+        const encoder = new TextEncoder();
+        const data = encoder.encode(`event: message\ndata: ${JSON.stringify(message)}\n\n`);
+        await this._writableStream.write(data);
+    }
+    /**
+     * Returns the session ID for this transport.
+     *
+     * This can be used to route incoming POST requests.
+     */
+    get sessionId() {
+        return this._sessionId;
+    }
+}
+//# sourceMappingURL=mcp-transport.js.map

package/dist/mcp-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-transport.js","sourceRoot":"","sources":["../src/mcp-transport.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,oBAAoB,GACrB,MAAM,oCAAoC,CAAA;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC;;;;GAIG;AACH,MAAM,OAAO,2BAA2B;IAUtC;;OAEG;IACH,YAAY,QAAgB;QAC1B,IAAI,CAAC,UAAU,GAAG,UAAU,EAAE,CAAA;QAC9B,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAA;IAC3B,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK;;QACT,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CACb,6GAA6G,CAC9G,CAAA;QACH,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC;YAC1B,cAAc,EAAE,mBAAmB;YACnC,eAAe,EAAE,UAAU;YAC3B,gDAAgD;YAChD,kBAAkB,EAAE,MAAM;YAC1B,UAAU,EAAE,YAAY;SACzB,CAAC,CAAA;QAEF,2BAA2B;QAC3B,MAAM,eAAe,GAAG,IAAI,eAAe,EAAE,CAAA;QAC7C,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,eAAe,CAAA;QAE9C,6CAA6C;QAC7C,IAAI,CAAC,QAAQ,GAAG,IAAI,QAAQ,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,CAAC,CAAA;QAEnD,wCAAwC;QACxC,IAAI,CAAC,eAAe,GAAG,QAAQ,CAAC,SAAS,EAAE,CAAA;QAC3C,MAAA,IAAI,CAAC,eAAe,0CAAE,KAAK,CACzB,IAAI,WAAW,EAAE,CAAC,MAAM,CACtB,0BAA0B,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,cACjD,IAAI,CAAC,UACP,MAAM,CACP,CACF,CAAA;QAED,2CAA2C;QAC3C,8BAA8B;QAC9B,qCAAqC;QACrC,qBAAqB;QACrB,KAAK;IACP,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,iBAAiB,CACrB,GAAY,EACZ,UAAoB;QAEpB,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,MAAM,OAAO,GAAG,gCAAgC,CAAA;YAChD,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,CAAA;QAC1B,CAAC;QAED,IAAI,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAA;QAE3B,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,aAAa,CACtB,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CACnD,CAAA;QACH,CAAC;QAAC,WAAM,CAAC;YACP,OAAO,IAAI,QAAQ,CAAC,oBAAoB,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAA;QAClE,CAAC;QAED,OAAO,IAAI,QAAQ,CAAC,UAAU,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAA;IAClD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,aAAa,CAAC,OAAgB;;QAClC,IAAI,aAA6B,CAAA;QACjC,IAAI,CAAC;YACH,aAAa,GAAG,oBAAoB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QACrD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAA,IAAI,CAAC,OAAO,qDAAG,KAAc,CAAC,CAAA;YAC9B,MAAM,KAAK,CAAA;QACb,CAAC;QAED,MAAA,IAAI,CAAC,SAAS,qDAAG,aAAa,CAAC,CAAA;IACjC,CAAC;IAED,KAAK,CAAC,KAAK;;QACT,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,MAAM,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAA;QACpC,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAA;QACzB,IAAI,CAAC,eAAe,GAAG,SAAS,CAAA;QAChC,MAAA,IAAI,CAAC,OAAO,oDAAI,CAAA;IAClB,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,OAAuB;QAChC,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAA;QAClC,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAA;QACjC,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CACzB,yBAAyB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CACvD,CAAA;QAED,MAAM,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IACxC,CAAC;IAED;;;;OAIG;IACH,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,UAAU,CAAA;IACxB,CAAC;CACF"}

package/dist/mcp.d.ts

@@ -0,0 +1,36 @@
+import { Spiceflow } from './spiceflow.js';
+export declare const mcp: <Path extends string = "/mcp">({ path, name, version, }?: {
+    path?: Path | undefined;
+    name?: string | undefined;
+    version?: string | undefined;
+}) => Spiceflow<"", true, {
+    state: {};
+}, {
+    type: {};
+    error: {};
+}, {
+    schema: {};
+    macro: {};
+    macroFn: {};
+}, {
+    [x: string]: {
+        post: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            response: {
+                200: Response | "ok";
+            };
+        };
+    };
+} & import("./types.js").CreateClient<`${Path extends "/" ? "/index" : Path extends "" ? Path : Path extends `/${string}` ? Path : Path}`, {
+    get: {
+        body: unknown;
+        params: { [Param in import("./types.js").GetPathParameter<Path> as Param extends `${string}?` ? never : Param]: string; } & { [Param_1 in import("./types.js").GetPathParameter<Path> as Param_1 extends `${infer OptionalParam}?` ? OptionalParam : never]?: string | undefined; } extends infer T ? { [K in keyof T]: ({ [Param in import("./types.js").GetPathParameter<Path> as Param extends `${string}?` ? never : Param]: string; } & { [Param_1 in import("./types.js").GetPathParameter<Path> as Param_1 extends `${infer OptionalParam}?` ? OptionalParam : never]?: string | undefined; })[K]; } : never;
+        query: unknown;
+        response: {
+            200: Response | undefined;
+        };
+    };
+}>>;
+//# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAUA,OAAO,EAAe,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAUvD,eAAO,MAAM,GAAG,GAAI,IAAI,SAAS,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkOtC,CAAA"}