@rekog/mcp-nest 1.5.0-beta.0 → 1.5.0

package/.idea/codeStyles/Project.xml

@@ -0,0 +1,59 @@
+<component name="ProjectCodeStyleConfiguration">
+  <code_scheme name="Project" version="173">
+    <HTMLCodeStyleSettings>
+      <option name="HTML_SPACE_INSIDE_EMPTY_TAG" value="true" />
+    </HTMLCodeStyleSettings>
+    <JSCodeStyleSettings version="0">
+      <option name="FORCE_SEMICOLON_STYLE" value="true" />
+      <option name="SPACE_BEFORE_FUNCTION_LEFT_PARENTH" value="false" />
+      <option name="USE_DOUBLE_QUOTES" value="false" />
+      <option name="FORCE_QUOTE_STYlE" value="true" />
+      <option name="ENFORCE_TRAILING_COMMA" value="WhenMultiline" />
+      <option name="SPACES_WITHIN_OBJECT_LITERAL_BRACES" value="true" />
+      <option name="SPACES_WITHIN_IMPORTS" value="true" />
+    </JSCodeStyleSettings>
+    <TypeScriptCodeStyleSettings version="0">
+      <option name="FORCE_SEMICOLON_STYLE" value="true" />
+      <option name="SPACE_BEFORE_FUNCTION_LEFT_PARENTH" value="false" />
+      <option name="USE_DOUBLE_QUOTES" value="false" />
+      <option name="FORCE_QUOTE_STYlE" value="true" />
+      <option name="ENFORCE_TRAILING_COMMA" value="WhenMultiline" />
+      <option name="SPACES_WITHIN_OBJECT_LITERAL_BRACES" value="true" />
+      <option name="SPACES_WITHIN_IMPORTS" value="true" />
+    </TypeScriptCodeStyleSettings>
+    <VueCodeStyleSettings>
+      <option name="INTERPOLATION_NEW_LINE_AFTER_START_DELIMITER" value="false" />
+      <option name="INTERPOLATION_NEW_LINE_BEFORE_END_DELIMITER" value="false" />
+    </VueCodeStyleSettings>
+    <codeStyleSettings language="HTML">
+      <option name="SOFT_MARGINS" value="80" />
+      <indentOptions>
+        <option name="INDENT_SIZE" value="2" />
+        <option name="CONTINUATION_INDENT_SIZE" value="2" />
+        <option name="TAB_SIZE" value="2" />
+      </indentOptions>
+    </codeStyleSettings>
+    <codeStyleSettings language="JavaScript">
+      <option name="SOFT_MARGINS" value="80" />
+      <indentOptions>
+        <option name="INDENT_SIZE" value="2" />
+        <option name="CONTINUATION_INDENT_SIZE" value="2" />
+        <option name="TAB_SIZE" value="2" />
+      </indentOptions>
+    </codeStyleSettings>
+    <codeStyleSettings language="TypeScript">
+      <option name="SOFT_MARGINS" value="80" />
+      <indentOptions>
+        <option name="INDENT_SIZE" value="2" />
+        <option name="CONTINUATION_INDENT_SIZE" value="2" />
+        <option name="TAB_SIZE" value="2" />
+      </indentOptions>
+    </codeStyleSettings>
+    <codeStyleSettings language="Vue">
+      <option name="SOFT_MARGINS" value="80" />
+      <indentOptions>
+        <option name="CONTINUATION_INDENT_SIZE" value="2" />
+      </indentOptions>
+    </codeStyleSettings>
+  </code_scheme>
+</component>

package/.idea/codeStyles/codeStyleConfig.xml

@@ -0,0 +1,5 @@
+<component name="ProjectCodeStyleConfiguration">
+  <state>
+    <option name="USE_PER_PROJECT_SETTINGS" value="true" />
+  </state>
+</component>

package/.idea/inspectionProfiles/Project_Default.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+    <inspection_tool class="Eslint" enabled="true" level="WARNING" enabled_by_default="true" />
+  </profile>
+</component>

package/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/nest-mcp.iml" filepath="$PROJECT_DIR$/.idea/nest-mcp.iml" />
+    </modules>
+  </component>
+</project>

package/.idea/nest-mcp.iml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="WEB_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <excludeFolder url="file://$MODULE_DIR$/.tmp" />
+      <excludeFolder url="file://$MODULE_DIR$/temp" />
+      <excludeFolder url="file://$MODULE_DIR$/tmp" />
+    </content>
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

package/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

package/README.md

@@ -12,16 +12,18 @@
 
 A NestJS module to effortlessly expose tools, resources, and prompts for AI, from your NestJS applications using the **Model Context Protocol (MCP)**.
 
-`@rekog/mcp-nest` handles the complexity of setting up MCP servers. You define tools, resources, and prompts in a way that's familiar in NestJS and leverage the full power of dependency injection to utilize your existing services.
+with `@rekog/mcp-nest` you define tools, resources, and prompts in a way that's familiar in NestJS and leverage the full power of dependency injection to utilize your existing codebase in building complex enterprise ready MCP servers.
 
 ## Features
 
-- 🚀 HTTP+SSE and Streamable HTTP Transport
+- 🚀 Support for all Transport Types:
+  - Streamable HTTP
+  - HTTP+SSE
+  - STDIO
 - 🔍 Automatic `tool`, `resource`, and `prompt` discovery and registration
-- 💯 Zod-based request validation
+- 💯 Zod-based tool call validation
 - 📊 Progress notifications
 - 🔒 Guard-based authentication
-- ⏱️ Automatic SSE ping to maintain long connections
 
 ## Installation
 
@@ -114,17 +116,65 @@ export class GreetingTool {
 
 You are done!
 
+## Quick Start for STDIO
+
+The main difference is that you need to provide the `transport` option when importing the module.
+
+```typescript
+McpModule.forRoot({
+  name: 'playground-stdio-server',
+  version: '0.0.1',
+  transport: McpTransportType.STDIO,
+});
+```
+
+The rest is the same, you can define tools, resources, and prompts as usual. An example of a standalone NestJS application using the STDIO transport is the following:
+
+```typescript
+async function bootstrap() {
+  const app = await NestFactory.createApplicationContext(AppModule, {
+    logger: false,
+  });
+  return app.close();
+}
+
+void bootstrap();
+```
+
+Next, you can use the MCP server with an MCP Stdio Client ([see example](playground/clients/stdio-client.ts)), or after building your prject you can use it with the following MCP Client configuration:
+
+```json
+{
+  "mcpServers": {
+    "greeting": {
+      "command": "node",
+      "args": [
+        "<path to dist js file>",
+      ]
+    }
+  }
+}
+```
+
 ## API Endpoints
 
+HTTP+SSE transport exposes two endpoints:
+
 - `GET /sse`: SSE connection endpoint (Protected by guards if configured)
 - `POST /messages`: Tool execution endpoint (Protected by guards if configured)
 
+Streamable HTTP transport exposes the following endpoints:
+
+- `POST /mcp`: Main endpoint for all MCP operations (tool execution, resource access, etc.). In stateful mode, this creates and maintains sessions.
+- `GET /mcp`: Establishes Server-Sent Events (SSE) streams for real-time updates and progress notifications. **Only available in stateful mode.**
+- `DELETE /mcp`: Terminates MCP sessions. **Only available in stateful mode.**
+
 ### Tips
 
 It's possible to use the module with global prefix, but the recommended way is to exclude those endpoints with:
 
 ```typescript
-app.setGlobalPrefix('/api', { exclude: ['sse', 'messages'] });
+app.setGlobalPrefix('/api', { exclude: ['sse', 'messages', 'mcp'] });
 ```
 
 ## Authentication
@@ -163,30 +213,62 @@ export class AppModule {}
 
 That's it! The rest is the same as NestJS Guards.
 
-## SSE Ping Service
-
-The module includes an SSE ping service that helps maintain long-lived SSE connections by preventing browser/client timeouts. This is especially useful for clients such as IDE's using your MCP server remotely.
-
-### Configuration
-
-You can configure the SSE ping behavior when importing the module:
+## Playground
+
+The `playground` directory contains examples to quickly test MCP and `@rekog/mcp-nest` features.
+Refer to the [`playground/README.md`](playground/README.md) for more details.
+
+## Configuration
+
+The `McpModule.forRoot()` method accepts an `McpOptions` object to configure the server. Here are the available options:
+
+| Option             | Description                                                                                                                               | Default                                                              |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `name`             | **Required.** The name of your MCP server.                                                                                                | -                                                                    |
+| `version`          | **Required.** The version of your MCP server.                                                                                             | -                                                                    |
+| `capabilities`     | Optional MCP server capabilities to advertise. See [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk). | `undefined`                                                          |
+| `instructions`     | Optional instructions for the client on how to interact with the server.                                                                    | `undefined`                                                          |
+| `transport`        | Specifies the transport type(s) to enable.                                                                                                | `[McpTransportType.SSE, McpTransportType.STREAMABLE_HTTP, McpTransportType.STDIO]` |
+| `sseEndpoint`      | The endpoint path for the SSE connection (used with `SSE` transport).                                                                     | `'sse'`                                                              |
+| `messagesEndpoint` | The endpoint path for sending messages (used with `SSE` transport).                                                                       | `'messages'`                                                         |
+| `mcpEndpoint`      | The base endpoint path for MCP operations (used with `STREAMABLE_HTTP` transport).                                                        | `'mcp'`                                                              |
+| `globalApiPrefix`  | A global prefix for all MCP endpoints. Useful if integrating into an existing application.                                                | `''`                                                                 |
+| `guards`           | An array of NestJS Guards to apply to the MCP endpoints for authentication/authorization.                                                   | `[]`                                                                 |
+| `decorators`       | An array of NestJS Class Decorators to apply to the generated MCP controllers.                                                            | `[]`                                                                 |
+| `sse`              | Configuration specific to the `SSE` transport.                                                                                            | `{ pingEnabled: true, pingIntervalMs: 30000 }`                       |
+| `sse.pingEnabled`  | Whether to enable periodic SSE ping messages to keep the connection alive.                                                                | `true`                                                               |
+| `sse.pingIntervalMs` | The interval (in milliseconds) for sending SSE ping messages.                                                                             | `30000`                                                              |
+| `streamableHttp`   | Configuration specific to the `STREAMABLE_HTTP` transport.                                                                                | `{ enableJsonResponse: true, sessionIdGenerator: undefined, statelessMode: true }` |
+| `streamableHttp.enableJsonResponse` | If `true`, allows the `/mcp` endpoint to return JSON responses for non-streaming requests (like `listTools`).                             | `true`                                                               |
+| `streamableHttp.sessionIdGenerator` | A function to generate unique session IDs when running in stateful mode. Required if `statelessMode` is `false`.                            | `undefined`                                                          |
+| `streamableHttp.statelessMode` | If `true`, the `STREAMABLE_HTTP` transport operates statelessly (no sessions). If `false`, it operates statefully, requiring a `sessionIdGenerator`. | `true`                                                               |
+
+**Example:**
 
 ```typescript
 // app.module.ts
 import { Module } from '@nestjs/common';
-import { McpModule } from '@rekog/mcp-nest';
+import { McpModule, McpTransportType } from '@rekog/mcp-nest';
+import { GreetingTool } from './greeting.tool';
+import { AuthGuard } from './auth.guard'; // Your custom guard
+import { randomUUID } from 'crypto';
 
 @Module({
   imports: [
     McpModule.forRoot({
-      name: 'my-mcp-server',
-      version: '1.0.0',
-      sse: {
-        pingEnabled: true,        // Default is true
-        pingIntervalMs: 30000,    // Default is 30 seconds (30000ms)
+      name: 'my-stateful-mcp-server',
+      version: '2.1.0',
+      transport: McpTransportType.STREAMABLE_HTTP, // Only enable Streamable HTTP
+      mcpEndpoint: 'api/mcp', // Custom endpoint
+      guards: [AuthGuard], // Apply authentication
+      streamableHttp: {
+        statelessMode: false, // Enable stateful mode
+        sessionIdGenerator: () => randomUUID(), // Provide a session ID generator
+        enableJsonResponse: false, // Disable JSON responses for non-streaming requests
       },
     }),
   ],
+  providers: [GreetingTool, AuthGuard],
 })
 export class AppModule {}
 ```