@mcp-weave/nestjs 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,287 @@
+# @mcp-weave/nestjs
+
+NestJS-style decorators for building Model Context Protocol (MCP) servers with TypeScript.
+
+## Installation
+
+```bash
+npm install @mcp-weave/nestjs reflect-metadata
+# or
+pnpm add @mcp-weave/nestjs reflect-metadata
+```
+
+**Important:** Enable decorators in your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
+
+## Features
+
+- **Class Decorators** - `@McpServer` to define MCP servers
+- **Method Decorators** - `@McpTool`, `@McpResource`, `@McpPrompt`
+- **Parameter Decorators** - `@McpInput`, `@McpParam`, `@McpPromptArg`
+- **Runtime Server** - Start MCP servers from decorated classes
+- **Multiple Transports** - Stdio (default) and SSE (Server-Sent Events)
+
+## Quick Start
+
+```typescript
+import 'reflect-metadata';
+import {
+  McpServer,
+  McpTool,
+  McpResource,
+  McpPrompt,
+  McpInput,
+  McpParam,
+  McpPromptArg,
+  createMcpServer,
+} from '@mcp-weave/nestjs';
+
+@McpServer({
+  name: 'my-server',
+  version: '1.0.0',
+  description: 'My MCP server',
+})
+class MyServer {
+  @McpTool({
+    name: 'greet',
+    description: 'Greets a user',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Name to greet' },
+      },
+      required: ['name'],
+    },
+  })
+  greet(@McpInput() input: { name: string }) {
+    return `Hello, ${input.name}!`;
+  }
+
+  @McpResource({
+    uri: 'config://settings',
+    name: 'Settings',
+    description: 'Application settings',
+  })
+  getSettings() {
+    return {
+      contents: [
+        {
+          uri: 'config://settings',
+          mimeType: 'application/json',
+          text: JSON.stringify({ theme: 'dark' }),
+        },
+      ],
+    };
+  }
+
+  @McpPrompt({
+    name: 'welcome',
+    description: 'Welcome message prompt',
+    arguments: [{ name: 'username', description: 'User name', required: true }],
+  })
+  welcomePrompt(@McpPromptArg('username') username: string) {
+    return {
+      messages: [
+        {
+          role: 'user',
+          content: { type: 'text', text: `Welcome ${username} to our service!` },
+        },
+      ],
+    };
+  }
+}
+
+// Start the server
+createMcpServer(MyServer);
+```
+
+## Decorators
+
+### @McpServer
+
+Marks a class as an MCP server.
+
+```typescript
+@McpServer({
+  name: 'server-name',
+  version: '1.0.0',
+  description: 'Optional description',
+})
+class MyServer {}
+```
+
+### @McpTool
+
+Defines an MCP tool (callable function).
+
+```typescript
+@McpTool({
+  name: 'tool_name',
+  description: 'What the tool does',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      param1: { type: 'string' },
+      param2: { type: 'number' },
+    },
+    required: ['param1'],
+  },
+})
+myTool(@McpInput() input: ToolInput) {
+  return result;
+}
+```
+
+### @McpResource
+
+Defines an MCP resource (readable data).
+
+```typescript
+@McpResource({
+  uri: 'resource://path/{id}',
+  name: 'Resource Name',
+  description: 'Resource description',
+  mimeType: 'application/json',
+})
+getResource(@McpParam('id') id: string) {
+  return {
+    contents: [{ uri: `resource://path/${id}`, text: 'content' }],
+  };
+}
+```
+
+### @McpPrompt
+
+Defines an MCP prompt template.
+
+```typescript
+@McpPrompt({
+  name: 'prompt_name',
+  description: 'Prompt description',
+  arguments: [
+    { name: 'arg1', description: 'Argument 1', required: true },
+    { name: 'arg2', description: 'Argument 2', required: false },
+  ],
+})
+myPrompt(
+  @McpPromptArg('arg1') arg1: string,
+  @McpPromptArg('arg2') arg2?: string
+) {
+  return {
+    messages: [{ role: 'user', content: { type: 'text', text: `...` } }],
+  };
+}
+```
+
+## Parameter Decorators
+
+| Decorator             | Use Case               |
+| --------------------- | ---------------------- |
+| `@McpInput()`         | Tool input object      |
+| `@McpParam(name)`     | Resource URI parameter |
+| `@McpPromptArg(name)` | Prompt argument        |
+
+## Runtime Server
+
+### createMcpServer
+
+Creates and starts an MCP server from a decorated class.
+
+```typescript
+import { createMcpServer } from '@mcp-weave/nestjs';
+
+// Starts server on stdio transport
+await createMcpServer(MyServer);
+```
+
+### McpRuntimeServer
+
+For more control, use the class directly:
+
+```typescript
+import { McpRuntimeServer } from '@mcp-weave/nestjs';
+
+const server = new McpRuntimeServer(MyServer, {
+  transport: 'stdio',
+});
+
+await server.start();
+```
+
+### SSE Transport (Server-Sent Events)
+
+For web-based integrations, use the SSE transport:
+
+```typescript
+import { McpRuntimeServer } from '@mcp-weave/nestjs';
+
+const server = new McpRuntimeServer(MyServer, {
+  transport: 'sse',
+  port: 3000,
+  endpoint: '/sse',
+});
+
+// Starts HTTP server with SSE endpoint
+const httpServer = await server.start();
+
+// Server available at:
+// - SSE endpoint: http://localhost:3000/sse
+// - Health check: http://localhost:3000/health
+```
+
+Or use the `startSSE` method directly:
+
+```typescript
+const server = new McpRuntimeServer(MyServer);
+
+// Start with SSE transport
+const httpServer = await server.startSSE({
+  port: 8080,
+  endpoint: '/mcp',
+});
+```
+
+**SSE Features:**
+
+- CORS enabled by default
+- Health check endpoint at `/health`
+- Session management for multiple clients
+- Automatic cleanup on connection close
+
+## Metadata Extraction
+
+Extract metadata from decorated classes for code generation:
+
+```typescript
+import { extractMetadata, getServerMetadata, getToolsMetadata } from '@mcp-weave/nestjs';
+
+const metadata = extractMetadata(MyServer);
+console.log(metadata.server);
+console.log(metadata.tools);
+console.log(metadata.resources);
+console.log(metadata.prompts);
+```
+
+## Requirements
+
+- Node.js >= 18
+- TypeScript >= 5.0
+- `reflect-metadata` package
+
+## Related Packages
+
+- [`@mcp-weave/core`](https://www.npmjs.com/package/@mcp-weave/core) - Core types and utilities
+- [`@mcp-weave/testing`](https://www.npmjs.com/package/@mcp-weave/testing) - Testing utilities
+- [`@mcp-weave/cli`](https://www.npmjs.com/package/@mcp-weave/cli) - Command-line interface
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 import { ToolInputSchema, PromptArgument, McpParamMetadata, McpPromptMetadata, McpResourceMetadata, McpServerMetadata, McpToolMetadata } from '@mcp-weave/core';
 export { METADATA_KEYS, McpParamMetadata, McpPromptMetadata, McpResourceMetadata, McpServerMetadata, McpToolMetadata, ScannedMetadata, extractMetadata } from '@mcp-weave/core';
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { Server as Server$1 } from '@modelcontextprotocol/sdk/server/index.js';
+import { Server } from 'http';
 
 /**
  * Options for @McpServer decorator
@@ -209,9 +210,17 @@ declare function getParamsMetadata(target: Function): McpParamMetadata[];
  */
 interface McpRuntimeOptions {
     /**
-     * Transport type
+     * Transport type: 'stdio' (default), 'sse', or 'websocket'
      */
-    transport?: 'stdio' | 'sse';
+    transport?: 'stdio' | 'sse' | 'websocket';
+    /**
+     * Port for SSE/WebSocket transport (default: 3000)
+     */
+    port?: number;
+    /**
+     * Endpoint path for SSE/WebSocket (default: '/sse' or '/ws')
+     */
+    endpoint?: string;
 }
 /**
  * Runtime MCP server that wraps a decorated class
@@ -230,16 +239,46 @@ declare class McpRuntimeServer {
     private resolvePromptArgs;
     private extractUriParams;
     /**
-     * Start the MCP server
+     * Start the MCP server with stdio transport
      */
     start(): Promise<void>;
+    /**
+     * Start the MCP server with SSE transport
+     */
+    startSSE(options?: {
+        port?: number;
+        endpoint?: string;
+    }): Promise<Server>;
     /**
      * Get the underlying MCP server instance
      */
-    getServer(): Server;
+    getServer(): Server$1;
+    /**
+     * Start the MCP server with WebSocket transport
+     */
+    startWebSocket(options?: {
+        port?: number;
+        endpoint?: string;
+    }): Promise<Server>;
+    /**
+     * Handle WebSocket JSON-RPC messages
+     */
+    private handleWebSocketMessage;
 }
 /**
  * Create and start an MCP server from a decorated class
+ *
+ * @example
+ * // Stdio transport (default)
+ * await createMcpServer(MyServer);
+ *
+ * @example
+ * // SSE transport
+ * await createMcpServer(MyServer, { transport: 'sse', port: 3000 });
+ *
+ * @example
+ * // WebSocket transport
+ * await createMcpServer(MyServer, { transport: 'websocket', port: 8080 });
  */
 declare function createMcpServer(target: Function, options?: McpRuntimeOptions): Promise<McpRuntimeServer>;
 

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { ToolInputSchema, PromptArgument, McpParamMetadata, McpPromptMetadata, McpResourceMetadata, McpServerMetadata, McpToolMetadata } from '@mcp-weave/core';
 export { METADATA_KEYS, McpParamMetadata, McpPromptMetadata, McpResourceMetadata, McpServerMetadata, McpToolMetadata, ScannedMetadata, extractMetadata } from '@mcp-weave/core';
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { Server as Server$1 } from '@modelcontextprotocol/sdk/server/index.js';
+import { Server } from 'http';
 
 /**
  * Options for @McpServer decorator
@@ -209,9 +210,17 @@ declare function getParamsMetadata(target: Function): McpParamMetadata[];
  */
 interface McpRuntimeOptions {
     /**
-     * Transport type
+     * Transport type: 'stdio' (default), 'sse', or 'websocket'
      */
-    transport?: 'stdio' | 'sse';
+    transport?: 'stdio' | 'sse' | 'websocket';
+    /**
+     * Port for SSE/WebSocket transport (default: 3000)
+     */
+    port?: number;
+    /**
+     * Endpoint path for SSE/WebSocket (default: '/sse' or '/ws')
+     */
+    endpoint?: string;
 }
 /**
  * Runtime MCP server that wraps a decorated class
@@ -230,16 +239,46 @@ declare class McpRuntimeServer {
     private resolvePromptArgs;
     private extractUriParams;
     /**
-     * Start the MCP server
+     * Start the MCP server with stdio transport
      */
     start(): Promise<void>;
+    /**
+     * Start the MCP server with SSE transport
+     */
+    startSSE(options?: {
+        port?: number;
+        endpoint?: string;
+    }): Promise<Server>;
     /**
      * Get the underlying MCP server instance
      */
-    getServer(): Server;
+    getServer(): Server$1;
+    /**
+     * Start the MCP server with WebSocket transport
+     */
+    startWebSocket(options?: {
+        port?: number;
+        endpoint?: string;
+    }): Promise<Server>;
+    /**
+     * Handle WebSocket JSON-RPC messages
+     */
+    private handleWebSocketMessage;
 }
 /**
  * Create and start an MCP server from a decorated class
+ *
+ * @example
+ * // Stdio transport (default)
+ * await createMcpServer(MyServer);
+ *
+ * @example
+ * // SSE transport
+ * await createMcpServer(MyServer, { transport: 'sse', port: 3000 });
+ *
+ * @example
+ * // WebSocket transport
+ * await createMcpServer(MyServer, { transport: 'websocket', port: 8080 });
  */
 declare function createMcpServer(target: Function, options?: McpRuntimeOptions): Promise<McpRuntimeServer>;