@rekog/mcp-nest 1.5.0-beta.1 → 1.5.1

package/.github/workflows/pipeline.yml

@@ -1,4 +1,4 @@
-name: Node.js CI and Publish
+name: Testing
 
 on:
   push:
@@ -15,12 +15,22 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+
       - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
           cache: 'npm'
+
       - name: Install dependencies
         run: npm ci
+
       - name: Run tests
         run: npm run test
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main' && matrix.node-version == '20.x'
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage/lcov.info

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

@@ -1,27 +1,30 @@
 # NestJS MCP Server Module
 
-<p align="center">
+<div align="center">
   <img src="https://raw.githubusercontent.com/rekog-labs/MCP-Nest/main/image.png" height="200">
-</p>
 
-<p align="center">
-  <a href="https://www.npmjs.com/package/@rekog/mcp-nest" target="_blank"><img alt="npm version" src="https://img.shields.io/npm/v/@rekog/mcp-nest" /></a>
-  <a href="https://www.npmjs.com/package/@rekog/mcp-nest" target="_blank"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@rekog/mcp-nest" /></a>
-  <a href="https://www.npmjs.com/package/@rekog/mcp-nest" target="_blank"><img alt="NPM" src="https://img.shields.io/npm/l/@rekog/mcp-nest" /></a>
-</p>
+[![CI][ci-image]][ci-url]
+[![Code Coverage][code-coverage-image]][code-coverage-url]
+[![NPM Version][npm-version-image]][npm-url]
+[![NPM Downloads][npm-downloads-image]][npm-url]
+[![NPM License][npm-license-image]][npm-url]
+
+</div>
 
 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 +117,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 project 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 +214,42 @@ 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:
-
-```typescript
-// app.module.ts
-import { Module } from '@nestjs/common';
-import { McpModule } from '@rekog/mcp-nest';
-
-@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)
-      },
-    }),
-  ],
-})
-export class AppModule {}
-```
+## 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`                                                               |
+
+<!-- Badges -->
+[ci-url]: https://github.com/rekog-labs/MCP-Nest/actions/workflows/pipeline.yml
+[ci-image]: https://github.com/rekog-labs/MCP-Nest/actions/workflows/pipeline.yml/badge.svg
+[npm-url]: https://www.npmjs.com/package/@rekog/mcp-nest
+[npm-version-image]: https://img.shields.io/npm/v/@rekog/mcp-nest
+[npm-downloads-image]: https://img.shields.io/npm/dm/@rekog/mcp-nest
+[npm-license-image]: https://img.shields.io/npm/l/@rekog/mcp-nest
+[code-coverage-url]: https://codecov.io/gh/rekog-labs/mcp-nest
+[code-coverage-image]: https://codecov.io/gh/rekog-labs/mcp-nest/branch/main/graph/badge.svg