@nestjs-mcp/server 0.1.0-alpha.4

package/examples/tools/main.ts

@@ -0,0 +1,11 @@
+import { NestFactory } from '@nestjs/core';
+
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  await app.listen(3000);
+  console.log('Resources example server running on http://localhost:3000');
+}
+
+void bootstrap();

package/examples/tools/tools.resolver.ts

@@ -0,0 +1,205 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types';
+import { randomInt, randomUUID } from 'crypto';
+import { z } from 'zod';
+
+import { Resolver, Tool } from '../../src';
+
+@Resolver('tools')
+export class ToolsResolver {
+  /**
+   * Simple tool with only a name
+   * Use case: Basic functionality that requires no parameters
+   */
+  @Tool({
+    name: 'server_health_check',
+  })
+  healthCheck(): CallToolResult {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'Server is operational. All systems running normally.',
+        },
+      ],
+    };
+  }
+
+  /**
+   * Tool with name and parameter schema
+   * Use case: When you need validated input parameters
+   */
+  @Tool({
+    name: 'calculate_discount',
+    paramSchema: {
+      price: z.number().positive().min(0.01),
+      discountPercentage: z.number().min(0).max(100),
+    },
+  })
+  calculateDiscount({
+    price,
+    discountPercentage,
+  }: {
+    price: number;
+    discountPercentage: number;
+  }): CallToolResult {
+    const discountAmount = price * (discountPercentage / 100);
+    const finalPrice = price - discountAmount;
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Original price: $${price.toFixed(2)}\nDiscount: $${discountAmount.toFixed(2)} (${discountPercentage}%)\nFinal price: $${finalPrice.toFixed(2)}`,
+        },
+      ],
+    };
+  }
+
+  /**
+   * Tool with name and description
+   * Use case: When additional context helps the user understand the tool's purpose
+   */
+  @Tool({
+    name: 'generate_unique_id',
+    description:
+      'Generates a cryptographically strong unique identifier suitable for database keys or session tokens',
+  })
+  generateUniqueId(): CallToolResult {
+    // Simple UUID v4 implementation for example purposes
+    const uuid = randomUUID();
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Generated ID: ${uuid}`,
+        },
+      ],
+    };
+  }
+
+  /**
+   * Comprehensive tool with all options
+   * Use case: Complex functionality requiring validated input and clear explanation
+   */
+  @Tool({
+    name: 'weather_forecast',
+    description:
+      'Retrieves weather forecast for a specified location and timeframe',
+    paramSchema: {
+      location: z.string().min(2).max(100),
+      days: z.number().int().min(1).max(7).default(3),
+      tempUnit: z.enum(['celsius', 'fahrenheit']).default('celsius'),
+    },
+  })
+  getWeatherForecast({
+    location,
+    days,
+    tempUnit,
+  }: {
+    location: string;
+    days: number;
+    tempUnit: 'celsius' | 'fahrenheit';
+  }): CallToolResult {
+    // Mock weather data for demonstration
+    const weatherTypes = [
+      'Sunny',
+      'Partly Cloudy',
+      'Cloudy',
+      'Rainy',
+      'Thunderstorms',
+    ];
+    const forecast = Array.from({ length: days }, (_, i) => {
+      const date = new Date();
+      date.setDate(date.getDate() + i);
+
+      // Generate mock temperature (60-85°F range or 15-30°C range)
+      let temp = Math.floor(Math.random() * 15) + 15; // celsius
+      if (tempUnit === 'fahrenheit') {
+        temp = Math.round((temp * 9) / 5 + 32);
+      }
+
+      return {
+        date: date.toDateString(),
+        condition:
+          weatherTypes[Math.floor(Math.random() * weatherTypes.length)],
+        temperature: temp,
+        unit: tempUnit === 'celsius' ? '°C' : '°F',
+      };
+    });
+
+    const formattedForecast = forecast
+      .map(
+        (day) => `${day.date}: ${day.condition}, ${day.temperature}${day.unit}`,
+      )
+      .join('\n');
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Weather forecast for ${location} (next ${days} days):\n\n${formattedForecast}`,
+        },
+      ],
+    };
+  }
+
+  /**
+   * Tool with complex schema validation
+   * Use case: When you need sophisticated input validation
+   */
+  @Tool({
+    name: 'register_user',
+    description: 'Registers a new user in the system with validation',
+    paramSchema: {
+      username: z
+        .string()
+        .min(3)
+        .max(20)
+        .regex(/^[a-zA-Z0-9_]+$/),
+      email: z.string().email(),
+      age: z.number().int().min(18).optional(),
+      preferences: z
+        .object({
+          theme: z.enum(['light', 'dark', 'system']).default('system'),
+          notifications: z.boolean().default(true),
+        })
+        .optional(),
+    },
+  })
+  registerUser({
+    username,
+    email,
+    age,
+    preferences,
+  }: {
+    username: string;
+    email: string;
+    age?: number;
+    preferences?: {
+      theme: 'light' | 'dark' | 'system';
+      notifications: boolean;
+    };
+  }): CallToolResult {
+    const userId = randomInt(10000, 100000);
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `User registered successfully!\n
+          User ID: ${userId}
+          Username: ${username}
+          Email: ${email}
+          ${age ? `Age: ${age}` : ''}
+          ${
+            preferences
+              ? `Theme: ${preferences.theme}
+                Notifications: ${preferences.notifications ? 'Enabled' : 'Disabled'}`
+              : ''
+          }`,
+        },
+      ],
+    };
+  }
+}

package/nest-cli.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true
+  }
+}

package/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "@nestjs-mcp/server",
+  "version": "0.1.0-alpha.4",
+  "description": "Modular library for building scalable MCP servers with NestJS, providing decorators and integration patterns as a wrapper for the official MCP TypeScript SDK.",
+  "author": "Adrián Darío Hidalgo Flores",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22",
+    "pnpm": ">=10"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/adrian-d-hidalgo/nestjs-mcp-server.git"
+  },
+  "homepage": "https://github.com/adrian-d-hidalgo/nestjs-mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/adrian-d-hidalgo/nestjs-mcp-server/issues"
+  },
+  "keywords": [
+    "decorators",
+    "integration",
+    "large-language-models",
+    "llm",
+    "mcp",
+    "model-context-protocol",
+    "module",
+    "nestjs",
+    "sdk",
+    "server",
+    "typescript"
+  ],
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.1",
+    "@nestjs/core": "^11.0.1",
+    "@nestjs/platform-express": "^11.0.1",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.2",
+    "zod": "^3.24.3"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.2.0",
+    "@eslint/js": "^9.18.0",
+    "@nestjs/cli": "^11.0.0",
+    "@nestjs/config": "^4.0.2",
+    "@nestjs/schematics": "^11.0.0",
+    "@nestjs/testing": "^11.0.1",
+    "@swc/cli": "^0.6.0",
+    "@swc/core": "^1.10.7",
+    "@types/express": "^5.0.0",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.10.7",
+    "@types/supertest": "^6.0.2",
+    "eslint": "^9.18.0",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-prettier": "^5.2.2",
+    "globals": "^16.0.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.4.2",
+    "source-map-support": "^0.5.21",
+    "supertest": "^7.0.0",
+    "ts-jest": "^29.2.5",
+    "ts-loader": "^9.5.2",
+    "ts-node": "^10.9.2",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.20.0"
+  },
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "rootDir": "src",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.(t|j)s$": "ts-jest"
+    },
+    "collectCoverageFrom": [
+      "**/*.(t|j)s"
+    ],
+    "coverageDirectory": "../coverage",
+    "testEnvironment": "node"
+  },
+  "scripts": {
+    "build": "nest build",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "start:example": "npx -y ts-node-dev --respawn examples/$EXAMPLE/main.ts",
+    "start:inspector": "npx -y @modelcontextprotocol/inspector",
+    "lint": "eslint \"{src,test,examples}/**/*.ts\" --fix",
+    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:cov": "jest --coverage",
+    "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
+    "test:e2e": "jest --config ./test/jest-e2e.json"
+  }
+}

package/scripts/npm-publish.js

@@ -0,0 +1,301 @@
+#!/usr/bin/env node
+
+/**
+ * npm-publish.js
+ *
+ * Smart publish script for MCP Server packages.
+ * - Detects branch and version
+ * - Enforces branch and versioning rules
+ * - Decides release type (alpha, beta, rc, release)
+ * - Runs build and appropriate publish command
+ * - Prints clear errors and exits non-zero on rule violation
+ *
+ * Usage: pnpm run publish
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+// --- CONFIGURABLE RULES ---
+const ALLOWED_BRANCHES = [/^release\//, /^fix\//];
+const RELEASE_BRANCH = /^release\//;
+const VERSION_REGEX = /^(\d+)\.(\d+)\.(\d+)(?:-(alpha|beta|rc)\.(\d+))?$/;
+
+function getCurrentBranch() {
+  try {
+    return execSync('git rev-parse --abbrev-ref HEAD').toString().trim();
+  } catch (e) {
+    console.error('Error: Not a git repository or git not installed.');
+    process.exit(1);
+  }
+}
+
+function getPackageJson() {
+  const pkgPath = path.resolve(process.cwd(), 'package.json');
+  if (!fs.existsSync(pkgPath)) {
+    console.error('Error: package.json not found.');
+    process.exit(1);
+  }
+  return JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+}
+
+function getReleaseType(version) {
+  const match = VERSION_REGEX.exec(version);
+  if (!match) return null;
+  return match[4] || 'release';
+}
+
+function checkAllowedBranch(branch) {
+  return ALLOWED_BRANCHES.some((re) => re.test(branch));
+}
+
+function checkReleaseBranch(branch) {
+  return RELEASE_BRANCH.test(branch);
+}
+
+function run(cmd, opts = {}) {
+  try {
+    execSync(cmd, { stdio: 'inherit', ...opts });
+  } catch (e) {
+    process.exit(e.status || 1);
+  }
+}
+
+function checkNpmAuth() {
+  try {
+    execSync('npm whoami', { stdio: 'ignore' });
+  } catch (e) {
+    console.error('Error: You are not authenticated with npm. Run `npm login` and try again.');
+    process.exit(1);
+  }
+}
+
+function checkBuildSuccess() {
+  const distPath = path.resolve(process.cwd(), 'dist');
+  if (!fs.existsSync(distPath) || fs.readdirSync(distPath).length === 0) {
+    console.error('Error: Build failed or dist/ directory is empty. Aborting publish.');
+    process.exit(1);
+  }
+}
+
+function checkNpmVersion(version) {
+  try {
+    const pkg = getPackageJson();
+    const name = pkg.name;
+    // Get all versions from npm
+    const result = execSync(`npm view ${name} versions --json`).toString();
+    const versions = JSON.parse(result);
+    if (versions.includes(version)) {
+      console.error(`Error: Version ${version} already exists on npm. Bump the version before publishing.`);
+      process.exit(1);
+    }
+  } catch (e) {
+    // If the package is not published yet, ignore
+    if (e.stderr && e.stderr.toString().includes('E404')) return;
+    console.error('Error checking npm registry:', e.message || e);
+    process.exit(1);
+  }
+}
+
+function getTagVersion() {
+  // Try to get tag from environment (e.g., GITHUB_REF) or from git
+  const envTag = process.env.GITHUB_REF;
+  if (envTag && envTag.startsWith('refs/tags/v')) {
+    return envTag.replace('refs/tags/v', '');
+  }
+  // Fallback: try to get latest tag from git
+  try {
+    const tag = execSync('git describe --tags --abbrev=0').toString().trim();
+    return tag.startsWith('v') ? tag.slice(1) : tag;
+  } catch (e) {
+    return null;
+  }
+}
+
+function getSemverMain(version) {
+  // Extracts major.minor.patch
+  const match = version.match(/^(\d+)\.(\d+)\.(\d+)/);
+  return match ? match[0] : null;
+}
+
+function validateTagStructure(tagVersion) {
+  // Accepts: 1.2.3, 1.2.3-alpha.0, 1.2.3-beta.1, 1.2.3-rc.2
+  const valid = /^\d+\.\d+\.\d+(-((alpha|beta|rc)\.(\d+)))?$/.test(tagVersion);
+  if (!valid) {
+    console.error(`Error: Tag version '${tagVersion}' does not match the required pattern: v<semver>[-<prerelease>.<number>]`);
+    process.exit(1);
+  }
+}
+
+function isProductiveTag(tagVersion) {
+  // Returns true if tag is X.Y.Z (no pre-release)
+  return /^\d+\.\d+\.\d+$/.test(tagVersion);
+}
+
+function getNpmTagFromVersion(version) {
+  // Extracts prerelease part (e.g., alpha.0, beta.1, rc.2) or returns 'latest' for final
+  const match = version.match(/^\d+\.\d+\.\d+-(alpha|beta|rc)\.(\d+)$/);
+  if (match) {
+    return `${match[1]}.${match[2]}`;
+  }
+  return 'latest';
+}
+
+function getNextPrereleaseTag(baseVersion, type) {
+  // Find all tags for this version and type, return next incremental tag
+  const tagPrefix = `v${baseVersion}-${type}.`;
+  let maxNum = -1;
+  try {
+    const allTags = execSync('git tag', { encoding: 'utf8' })
+      .split('\n')
+      .filter(Boolean);
+    allTags.forEach(tag => {
+      if (tag.startsWith(tagPrefix)) {
+        const match = tag.match(new RegExp(`^v${baseVersion}-${type}\.(\\d+)$`));
+        if (match) {
+          const num = parseInt(match[1], 10);
+          if (num > maxNum) maxNum = num;
+        }
+      }
+    });
+  } catch (e) {
+    // ignore
+  }
+  return `v${baseVersion}-${type}.${maxNum + 1}`;
+}
+
+function validateBaseTagFormat(tag) {
+  // Must be vX.Y.Z
+  if (!/^v\d+\.\d+\.\d+$/.test(tag)) {
+    console.error('Error: Tag must be in the format vX.Y.Z (e.g., v0.1.0)');
+    process.exit(1);
+  }
+}
+
+function checkNpmTagExists(pkgName, version) {
+  try {
+    const result = execSync(`npm view ${pkgName} versions --json`).toString();
+    const versions = JSON.parse(result);
+    if (versions.includes(version)) {
+      console.error(`Error: Version ${version} already exists on npm.`);
+      process.exit(1);
+    }
+  } catch (e) {
+    // If the package is not published yet, ignore
+    if (e.stderr && e.stderr.toString().includes('E404')) return;
+    console.error('Error checking npm registry:', e.message || e);
+    process.exit(1);
+  }
+}
+
+if (process.argv[2] === 'next-tag') {
+  // Usage: node scripts/npm-publish.js next-tag v0.1.0 beta
+  const baseTag = process.argv[3];
+  const type = process.argv[4];
+  validateBaseTagFormat(baseTag);
+  const baseVersion = baseTag.slice(1); // remove 'v'
+  if (!type || !['alpha', 'beta', 'rc'].includes(type)) {
+    console.error('Usage: node scripts/npm-publish.js next-tag vX.Y.Z <alpha|beta|rc>');
+    process.exit(1);
+  }
+  if (process.env.CI === 'true') {
+    // In CI, just return the base version and check npm
+    const pkg = getPackageJson();
+    checkNpmTagExists(pkg.name, baseVersion);
+    console.log(baseVersion);
+    process.exit(0);
+  }
+  // Local: suggest next pre-release tag
+  const nextTag = getNextPrereleaseTag(baseVersion, type);
+  console.log(nextTag);
+  process.exit(0);
+}
+
+function main() {
+  if (process.argv[2] === 'next-tag') {
+    // Usage: node scripts/npm-publish.js next-tag 0.1.0 alpha
+    const baseVersion = process.argv[3];
+    const type = process.argv[4];
+    if (!baseVersion || !type || !['alpha', 'beta', 'rc'].includes(type)) {
+      console.error('Usage: node scripts/npm-publish.js next-tag <baseVersion> <alpha|beta|rc>');
+      process.exit(1);
+    }
+    const nextTag = getNextPrereleaseTag(baseVersion, type);
+    console.log(nextTag);
+    process.exit(0);
+  }
+
+  const branch = getCurrentBranch();
+  const pkg = getPackageJson();
+  const version = pkg.version;
+  const releaseType = getReleaseType(version);
+
+  // --- Tag version validation (if running from a tag) ---
+  const tagVersion = getTagVersion();
+  if (tagVersion) {
+    validateTagStructure(tagVersion);
+    const tagSemver = getSemverMain(tagVersion);
+    const pkgSemver = getSemverMain(version);
+    if (tagSemver !== pkgSemver) {
+      console.error(`Error: Tag semver (${tagSemver}) does not match package.json semver (${pkgSemver}).`);
+      process.exit(1);
+    }
+  }
+
+  // Default to dry-run unless --no-dry-run is passed or CI is true
+  const isDryRun = !process.argv.includes('--no-dry-run') && process.env.CI !== 'true';
+
+  // --- Branch validation ---
+  if (!checkAllowedBranch(branch)) {
+    console.error(`\nError: Publishing is only allowed from release/* or fix/* branches. Current: ${branch}`);
+    process.exit(1);
+  }
+
+  // --- NPM authentication check ---
+  checkNpmAuth();
+
+  // --- Build before publish ---
+  run('pnpm run build');
+  checkBuildSuccess();
+
+  // --- NPM version check ---
+  checkNpmVersion(version);
+
+  // --- Restrict final releases to CI/CD only ---
+  if (releaseType === 'release' && process.env.CI !== 'true') {
+    console.error('Error: Final releases can only be published from CI/CD pipelines. Set CI=true in your environment.');
+    process.exit(1);
+  }
+
+  // --- Decide publish command ---
+  let publishCmd = 'npm publish';
+  if (isDryRun) {
+    publishCmd += ' --dry-run --no-git-checks';
+  }
+  const npmTag = getNpmTagFromVersion(version);
+  if (npmTag !== 'latest') {
+    publishCmd += ` --tag ${npmTag}`;
+    // For alpha/beta/rc, set access (alpha is restricted, others are public)
+    if (npmTag.startsWith('alpha')) {
+      publishCmd += ' --access=restricted';
+    } else {
+      publishCmd += ' --access=public';
+    }
+  } else {
+    if (!checkReleaseBranch(branch)) {
+      console.error('Error: Final releases can only be published from release/* branches.');
+      process.exit(1);
+    }
+    publishCmd += ' --access=public';
+  }
+
+  // --- Publish ---
+  console.log(`\nPublishing version ${version} as ${npmTag} from branch ${branch}...\n`);
+  if (isDryRun) {
+    console.log('Dry run enabled by default: No package will actually be published. Use --no-dry-run or set CI=true to publish for real.');
+  }
+  run(publishCmd);
+}
+
+main();

package/src/controllers/sse/index.ts

@@ -0,0 +1,2 @@
+export * from './sse.controller';
+export * from './sse.service';

package/src/controllers/sse/sse.controller.ts

@@ -0,0 +1,19 @@
+import { Controller, Get, Post, Req, Res } from '@nestjs/common';
+import { Request, Response } from 'express';
+
+import { SseService } from './sse.service';
+
+@Controller()
+export class SseController {
+  constructor(private readonly service: SseService) {}
+
+  @Get('sse')
+  async handleSse(@Req() req: Request, @Res() res: Response) {
+    await this.service.handleSse(req, res);
+  }
+
+  @Post('messages')
+  async handleMessages(@Req() req: Request, @Res() res: Response) {
+    await this.service.handleMessage(req, res);
+  }
+}