feat((versioning): Implemented versioned route apps (#63)

* feat: Implement API versioning in minimal example with enhanced greet tools

- Updated README to reflect versioning support and added API endpoint details.
- Refactored index.ts to define separate greet tools for v1 (name only) and v2 (name + surname).
- Removed deprecated GreetingWidget component and created version-specific UI components.
- Enhanced styles.css to support version badges and improved UI layout.
- Updated core to support multi-version app configurations and validation.

* docs: Update README and improve code formatting for clarity

- Enhanced README with clearer API endpoint descriptions and input/output specifications.
- Improved formatting in GreetingWidget components for better readability.
- Refactored createApp.ts and server/index.ts for consistent code style and lazy initialization of JWKS client.
- Updated OAuth middleware to support JWKS client as a getter function.

* feat: Add configuration support for protocol in minimal example app

- Introduced a new configuration option for the app to specify the protocol as "openai".
- Updated createApp.ts to manage a shared HTTP server for multi-version applications, enhancing server instance accessibility.
- Improved comments for clarity regarding server instance handling and debug logger configuration.

* docs: Enhance README with API versioning details and examples

- Added a new section on API versioning, explaining how to expose multiple versions from a single app.
- Included code examples demonstrating version-specific tools, configuration overrides, and middleware.
- Updated existing examples to reflect API versioning capabilities.

* docs: Update README and core documentation for improved clarity and formatting

- Added blank lines for better readability in README and core documentation.
- Reformatted tool definitions in the core README for consistency.
- Ensured consistent code style across examples in the documentation.

* refactor: Simplify GreetingWidgetV2 input handling and improve createApp comments

- Removed unnecessary surname check in GreetingWidgetV2 onKeyDown event.
- Updated comments in createApp.ts for clarity on version-specific config merging and server instance handling.
- Cleaned up versioning test file by removing unused server cleanup logic.

* feat: Add health check and OpenAI domain challenge endpoints to createApp

- Implemented a health check endpoint that returns the app status and available versions.
- Added support for handling OpenAI domain verification challenge requests.
- Updated routing logic to return 404 for unmatched routes, ensuring consistency with Express behavior.
- Enhanced comments for clarity on event handling and memory management in the request processing flow.

* feat: Enhance configuration validation and deep merge functionality

- Updated `validateGlobalConfig` to accept `VersionSpecificConfig`, allowing null values to disable properties.
- Introduced `deepMerge` function for recursively merging global and version-specific configurations, with support for null to remove properties.
- Updated `mergeVersionConfig` to utilize deep merging for nested objects, ensuring proper handling of undefined and null values.
- Added tests for deep merging behavior, including scenarios for overriding, disabling, and inheriting configurations.
- Enhanced type definitions for better clarity on configuration structures.

* docs: Remove example curl commands from index.ts for cleaner documentation

- Eliminated example curl commands from the index.ts file to streamline the documentation.
- Focused on providing a clearer overview of available endpoints without cluttering the content.

* refactor: Improve readability and consistency in createApp.ts

- Reformatted conditional checks in validateGlobalConfig for better clarity.
- Updated mergeVersionConfig to enhance readability by using parentheses for nested expressions.
- Ensured consistent handling of null and undefined values in configuration merging logic.

* refactor: Improve deep merge logic in createApp.ts for better property handling

- Updated deepMerge function to build the result object without null properties.
- Replaced direct property deletion with Reflect.deleteProperty to comply with ESLint rules.
- Enhanced comments for clarity on the merging process and runtime validation in versioning tests.

Author: gabrypavanello

README.md

@@ -62,6 +62,7 @@ This project may be a poor fit if you:
 ## Features
 
 - Single `createApp()` entry point to define tools and UI once
+- **API Versioning**: Expose multiple API versions from a single app (e.g., `/v1/mcp`, `/v2/mcp`)
 - Type-safe tool bindings with full TypeScript inference for inputs, outputs, and UI access
 - Protocol abstraction so UI code works identically on both platforms
 - OAuth 2.1 security with JWT validation and JWKS discovery (RFC 6750, RFC 8414)
@@ -181,6 +182,70 @@ export type AppTools = typeof app.tools;
 export type AppClientTools = ClientToolsFromCore<AppTools>;
 ```
 
+### API Versioning
+
+Expose multiple API versions from a single application, each with its own tools and UI:
+
+```typescript
+const app = createApp({
+  name: "my-app",
+
+  // Shared config across all versions
+  config: {
+    cors: { origin: true },
+    oauth: { authorizationServer: "https://auth.example.com" },
+  },
+
+  // Version-specific tools and config
+  versions: {
+    v1: {
+      version: "1.0.0",
+      tools: {
+        greet: defineTool({
+          description: "Greet v1",
+          input: z.object({ name: z.string() }),
+          output: z.object({ message: z.string() }),
+          handler: async ({ name }) => ({ message: `Hello, ${name}!` }),
+        }),
+      },
+    },
+    v2: {
+      version: "2.0.0",
+      tools: {
+        greet: defineTool({
+          description: "Greet v2",
+          input: z.object({ name: z.string(), surname: z.string().optional() }),
+          output: z.object({ message: z.string() }),
+          handler: async ({ name, surname }) => ({
+            message: `Hello, ${name} ${surname || ""}!`.trim(),
+          }),
+        }),
+      },
+      // Version-specific config overrides global config
+      config: {
+        protocol: "openai",
+      },
+    },
+  },
+});
+
+// Access version info programmatically
+console.log(app.getVersions()); // ["v1", "v2"]
+const v2App = app.getVersion("v2");
+
+// Each version is exposed at its dedicated route
+// - v1: http://localhost:3000/v1/mcp
+// - v2: http://localhost:3000/v2/mcp
+```
+
+Each version can have:
+
+- Different tools and tool schemas
+- Version-specific UI components
+- Config overrides (merged with global config)
+- Version-specific plugins (merged with global plugins)
+- Shared middleware and OAuth configuration
+
 ### UI Setup (React)
 
 ```typescript
@@ -455,7 +520,7 @@ npm run dev
 
 Local examples:
 
-- [examples/minimal](examples/minimal/) - minimal server and UI widget
+- [examples/minimal](examples/minimal/) - minimal server with API versioning (v1 and v2)
 - [examples/restaurant-finder](examples/restaurant-finder/) - end-to-end app with search functionality
 
 ## API

examples/minimal/README.md

@@ -1,12 +1,15 @@
-# Minimal Example
+# Minimal Example with Versioning
 
-A simple "hello world" example demonstrating basic @mcp-apps-kit/core usage.
+A simple example demonstrating @mcp-apps-kit/core versioning support - exposing multiple API versions from a single application.
 
 ## Features
 
-- Single tool definition with Zod schema validation
-- Simple UI widget showing greeting messages
-- Basic server setup
+- **API Versioning**: Two API versions exposed at different routes
+  - `v1`: Simple greet tool (name only)
+  - `v2`: Enhanced greet tool (name + optional surname)
+- **Shared Configuration**: CORS, debug settings shared across versions
+- **Type-Safe Tools**: Full TypeScript support for each version's tools
+- **React UI Widgets**: Version-specific UI components
 
 ## Quick Start
 
@@ -22,16 +25,42 @@ pnpm build
 pnpm start
 ```
 
+## API Endpoints
+
+Once running, the server exposes:
+
+| Endpoint       | Description                 |
+| -------------- | --------------------------- |
+| `GET /health`  | Health check                |
+| `POST /v1/mcp` | MCP v1 API (name only)      |
+| `POST /v2/mcp` | MCP v2 API (name + surname) |
+
+## Testing the API
+
+```bash
+# v1: Greet with name only
+curl -X POST http://localhost:3000/v1/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"greet","arguments":{"name":"World"}},"id":1}'
+
+# v2: Greet with name and surname
+curl -X POST http://localhost:3000/v2/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"greet","arguments":{"name":"John","surname":"Doe"}},"id":1}'
+```
+
 ## Connecting to Claude Desktop
 
 Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 
 ```json
 {
   "mcpServers": {
-    "minimal-app": {
-      "command": "npx",
-      "args": ["tsx", "path/to/examples/minimal/src/index.ts"]
+    "minimal-app-v1": {
+      "url": "http://localhost:3000/v1/mcp"
+    },
+    "minimal-app-v2": {
+      "url": "http://localhost:3000/v2/mcp"
     }
   }
 }
@@ -42,18 +71,20 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
 ```
 minimal/
   src/
-    index.ts       # Server with tool definition
+    index.ts                  # Server with versioned app setup
     ui/
-      index.html   # Widget HTML entry
-      main.ts      # Widget TypeScript
+      GreetingWidgetV1.tsx    # V1 UI widget (name only)
+      GreetingWidgetV2.tsx    # V2 UI widget (name + surname)
+      styles.css              # Shared styles
+      dist/                   # Built UI HTML files
   package.json
   tsconfig.json
   vite.config.ts
 ```
 
-## Tool
+## Tools
 
-### `greet`
+### V1: `greet`
 
 Greet someone by name.
 
@@ -65,3 +96,50 @@ Greet someone by name.
 
 - `message` (string): Greeting message
 - `timestamp` (string): ISO timestamp
+
+### V2: `greet`
+
+Greet someone by name and optional surname.
+
+**Input:**
+
+- `name` (string): First name to greet
+- `surname` (string, optional): Surname
+
+**Output:**
+
+- `message` (string): Greeting message
+- `fullName` (string): The full name used in greeting
+- `timestamp` (string): ISO timestamp
+
+## Versioning Configuration
+
+The app uses the `createApp` versioning feature:
+
+```typescript
+const app = createApp({
+  name: "minimal-app",
+
+  // Shared config across all versions
+  config: {
+    cors: { origin: true },
+    debug: { logTool: true, level: "info" },
+  },
+
+  // Version-specific tools and config
+  versions: {
+    v1: {
+      version: "1.0.0",
+      tools: { greet: greetToolV1 },
+    },
+    v2: {
+      version: "2.0.0",
+      tools: { greet: greetToolV2 },
+    },
+  },
+});
+
+// Access version info programmatically
+console.log(app.getVersions()); // ["v1", "v2"]
+const v2App = app.getVersion("v2");
+```