@dangao/bun-server 1.12.1 → 2.0.0

package/src/mcp/mcp-module.ts

@@ -0,0 +1,58 @@
+import { Module, MODULE_METADATA_KEY } from '../di/module';
+import type { ModuleProvider } from '../di/module';
+import { McpServer } from './server';
+import { McpRegistry } from './registry';
+import { MCP_SERVER_TOKEN, MCP_OPTIONS_TOKEN, type McpModuleOptions } from './types';
+
+@Module({ providers: [] })
+export class McpModule {
+  /**
+   * Configure the MCP module.
+   *
+   * @example
+   * ```typescript
+   * McpModule.forRoot({
+   *   transport: 'sse',
+   *   path: '/mcp',
+   *   serverInfo: { name: 'my-api', version: '1.0.0' },
+   * });
+   *
+   * // Register tools by scanning instances:
+   * const registry = container.resolve<McpRegistry>(MCP_SERVER_TOKEN);
+   * registry.scan(myServiceInstance);
+   * ```
+   */
+  public static forRoot(options: McpModuleOptions): typeof McpModule {
+    const registry = new McpRegistry();
+    const server = new McpServer(registry, options.serverInfo);
+
+    const resolvedOptions: McpModuleOptions = {
+      transport: 'sse',
+      path: '/mcp',
+      ...options,
+    };
+
+    const providers: ModuleProvider[] = [
+      { provide: MCP_OPTIONS_TOKEN, useValue: resolvedOptions },
+      { provide: MCP_SERVER_TOKEN, useValue: server },
+      { provide: McpRegistry, useValue: registry },
+    ];
+
+    const existing = Reflect.getMetadata(MODULE_METADATA_KEY, McpModule) || {};
+    Reflect.defineMetadata(MODULE_METADATA_KEY, {
+      ...existing,
+      providers: [...(existing.providers || []), ...providers],
+      exports: [
+        ...(existing.exports || []),
+        MCP_SERVER_TOKEN,
+        McpRegistry,
+      ],
+    }, McpModule);
+
+    return McpModule;
+  }
+
+  public static reset(): void {
+    Reflect.deleteMetadata(MODULE_METADATA_KEY, McpModule);
+  }
+}

package/src/mcp/registry.ts

@@ -0,0 +1,72 @@
+import type { McpToolDefinition, McpResourceDefinition } from './types';
+import { MCP_TOOL_METADATA_KEY, MCP_RESOURCE_METADATA_KEY } from './types';
+
+export interface RegisteredMcpTool extends McpToolDefinition {
+  execute(args: Record<string, unknown>): Promise<unknown>;
+}
+
+export interface RegisteredMcpResource extends McpResourceDefinition {
+  read(uriParams: Record<string, string>): Promise<unknown>;
+}
+
+/**
+ * Registry for MCP tools and resources discovered via decorators.
+ */
+export class McpRegistry {
+  private readonly tools = new Map<string, RegisteredMcpTool>();
+  private readonly resources = new Map<string, RegisteredMcpResource>();
+
+  /**
+   * Scan an object instance for @McpTool() and @McpResource() decorated methods
+   */
+  public scan(instance: object): void {
+    const proto = Object.getPrototypeOf(instance);
+    const methodNames = Object.getOwnPropertyNames(proto).filter(
+      (key) => key !== 'constructor',
+    );
+
+    for (const methodName of methodNames) {
+      const toolDef: McpToolDefinition | undefined = Reflect.getMetadata(
+        MCP_TOOL_METADATA_KEY,
+        proto,
+        methodName,
+      );
+      if (toolDef) {
+        const method = (instance as Record<string, unknown>)[methodName] as (args: unknown) => Promise<unknown>;
+        this.tools.set(toolDef.name, {
+          ...toolDef,
+          execute: (args) => method.call(instance, args),
+        });
+      }
+
+      const resourceDef: McpResourceDefinition | undefined = Reflect.getMetadata(
+        MCP_RESOURCE_METADATA_KEY,
+        proto,
+        methodName,
+      );
+      if (resourceDef) {
+        const method = (instance as Record<string, unknown>)[methodName] as (params: unknown) => Promise<unknown>;
+        this.resources.set(resourceDef.uri, {
+          ...resourceDef,
+          read: (params) => method.call(instance, params),
+        });
+      }
+    }
+  }
+
+  public getTools(): RegisteredMcpTool[] {
+    return Array.from(this.tools.values());
+  }
+
+  public getResources(): RegisteredMcpResource[] {
+    return Array.from(this.resources.values());
+  }
+
+  public getTool(name: string): RegisteredMcpTool | undefined {
+    return this.tools.get(name);
+  }
+
+  public getResource(uri: string): RegisteredMcpResource | undefined {
+    return this.resources.get(uri);
+  }
+}

package/src/mcp/server.ts

@@ -0,0 +1,164 @@
+import type { McpServerInfo, JsonRpcRequest, JsonRpcResponse } from './types';
+import type { McpRegistry } from './registry';
+
+/**
+ * MCP protocol server — handles JSON-RPC 2.0 requests from MCP clients.
+ * Supports SSE transport (HTTP) and stdio transport.
+ *
+ * Implements MCP specification 2024-11-05.
+ */
+export class McpServer {
+  private readonly registry: McpRegistry;
+  private readonly serverInfo: McpServerInfo;
+
+  public constructor(registry: McpRegistry, serverInfo: McpServerInfo) {
+    this.registry = registry;
+    this.serverInfo = serverInfo;
+  }
+
+  /**
+   * Handle an incoming JSON-RPC request and return a response
+   */
+  public async handle(request: JsonRpcRequest): Promise<JsonRpcResponse> {
+    try {
+      const result = await this.dispatch(request.method, request.params);
+      return { jsonrpc: '2.0', id: request.id ?? null, result };
+    } catch (err) {
+      return {
+        jsonrpc: '2.0',
+        id: request.id ?? null,
+        error: {
+          code: err instanceof McpError ? err.code : -32603,
+          message: err instanceof Error ? err.message : 'Internal error',
+        },
+      };
+    }
+  }
+
+  /**
+   * Handle a raw HTTP request body (JSON-RPC over HTTP)
+   * Returns a Response suitable for Bun's serve()
+   */
+  public async handleHttp(req: Request): Promise<Response> {
+    const body = await req.json() as JsonRpcRequest;
+    const response = await this.handle(body);
+    return new Response(JSON.stringify(response), {
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  /**
+   * Create an SSE response that keeps the connection open for streaming
+   * This is the SSE transport endpoint
+   */
+  public createSseResponse(): Response {
+    const registry = this.registry;
+    const serverInfo = this.serverInfo;
+    const encoder = new TextEncoder();
+
+    const stream = new ReadableStream({
+      start(controller) {
+        // Send initial server info event
+        const initEvent = `event: endpoint\ndata: ${JSON.stringify({
+          type: 'endpoint',
+          method: 'POST',
+        })}\n\n`;
+        controller.enqueue(encoder.encode(initEvent));
+
+        // Keep connection alive with periodic pings
+        const pingInterval = setInterval(() => {
+          try {
+            controller.enqueue(encoder.encode(': ping\n\n'));
+          } catch {
+            clearInterval(pingInterval);
+          }
+        }, 15000);
+      },
+    });
+
+    return new Response(stream, {
+      headers: {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        'Connection': 'keep-alive',
+        'X-MCP-Server': `${serverInfo.name}/${serverInfo.version}`,
+      },
+    });
+  }
+
+  private async dispatch(method: string, params: unknown): Promise<unknown> {
+    switch (method) {
+      case 'initialize':
+        return {
+          protocolVersion: '2024-11-05',
+          capabilities: { tools: {}, resources: {} },
+          serverInfo: this.serverInfo,
+        };
+
+      case 'tools/list':
+        return {
+          tools: this.registry.getTools().map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+          })),
+        };
+
+      case 'tools/call': {
+        const { name, arguments: args = {} } = params as { name: string; arguments?: Record<string, unknown> };
+        const tool = this.registry.getTool(name);
+        if (!tool) throw new McpError(-32601, `Tool "${name}" not found`);
+        const result = await tool.execute(args);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
+      case 'resources/list':
+        return {
+          resources: this.registry.getResources().map((r) => ({
+            uri: r.uri,
+            name: r.name,
+            description: r.description,
+            mimeType: r.mimeType,
+          })),
+        };
+
+      case 'resources/read': {
+        const { uri } = params as { uri: string };
+        const resource = this.registry.getResource(uri);
+        if (!resource) throw new McpError(-32601, `Resource "${uri}" not found`);
+        const content = await resource.read({});
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: resource.mimeType ?? 'application/json',
+              text: typeof content === 'string' ? content : JSON.stringify(content),
+            },
+          ],
+        };
+      }
+
+      case 'ping':
+        return {};
+
+      default:
+        throw new McpError(-32601, `Method "${method}" not found`);
+    }
+  }
+}
+
+class McpError extends Error {
+  public constructor(
+    public readonly code: number,
+    message: string,
+  ) {
+    super(message);
+  }
+}

package/src/mcp/types.ts

@@ -0,0 +1,63 @@
+/**
+ * MCP tool definition
+ */
+export interface McpToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+}
+
+/**
+ * MCP resource definition
+ */
+export interface McpResourceDefinition {
+  uri: string;
+  name: string;
+  description?: string;
+  mimeType?: string;
+}
+
+/**
+ * MCP server info
+ */
+export interface McpServerInfo {
+  name: string;
+  version: string;
+  description?: string;
+}
+
+/**
+ * MCP transport type
+ */
+export type McpTransport = 'sse' | 'stdio';
+
+export interface McpModuleOptions {
+  transport?: McpTransport;
+  /** Path for SSE endpoint (default: '/mcp') */
+  path?: string;
+  serverInfo: McpServerInfo;
+}
+
+export const MCP_SERVER_TOKEN = Symbol('@dangao/bun-server:mcp:server');
+export const MCP_OPTIONS_TOKEN = Symbol('@dangao/bun-server:mcp:options');
+
+/** Metadata key for @McpTool() */
+export const MCP_TOOL_METADATA_KEY = '@dangao/bun-server:mcp:tool';
+/** Metadata key for @McpResource() */
+export const MCP_RESOURCE_METADATA_KEY = '@dangao/bun-server:mcp:resource';
+
+/** JSON-RPC 2.0 Request */
+export interface JsonRpcRequest {
+  jsonrpc: '2.0';
+  id: string | number | null;
+  method: string;
+  params?: unknown;
+}
+
+/** JSON-RPC 2.0 Response */
+export interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  id: string | number | null;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}

package/src/prompt/index.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './service';
+export * from './prompt-module';
+export * from './stores/memory-store';
+export * from './stores/file-store';

package/src/prompt/prompt-module.ts

@@ -0,0 +1,61 @@
+import { Module, MODULE_METADATA_KEY } from '../di/module';
+import type { ModuleProvider } from '../di/module';
+import { PromptService } from './service';
+import {
+  PROMPT_SERVICE_TOKEN,
+  PROMPT_OPTIONS_TOKEN,
+  type PromptModuleOptions,
+} from './types';
+import { InMemoryPromptStore } from './stores/memory-store';
+
+@Module({ providers: [] })
+export class PromptModule {
+  /**
+   * Configure the prompt module.
+   *
+   * @example
+   * ```typescript
+   * // With in-memory store (default):
+   * PromptModule.forRoot({});
+   *
+   * // With file store:
+   * PromptModule.forRoot({
+   *   store: new FilePromptStore({ promptsDir: './.prompts' }),
+   * });
+   * ```
+   */
+  public static forRoot(options: PromptModuleOptions = {}): typeof PromptModule {
+    const resolvedOptions: PromptModuleOptions = {
+      ...options,
+      store: options.store ?? new InMemoryPromptStore(),
+    };
+
+    const service = new PromptService(resolvedOptions as Required<PromptModuleOptions>);
+
+    const providers: ModuleProvider[] = [
+      { provide: PROMPT_OPTIONS_TOKEN, useValue: resolvedOptions },
+      { provide: PROMPT_SERVICE_TOKEN, useValue: service },
+      PromptService,
+    ];
+
+    const existing = Reflect.getMetadata(MODULE_METADATA_KEY, PromptModule) || {};
+    Reflect.defineMetadata(MODULE_METADATA_KEY, {
+      ...existing,
+      providers: [...(existing.providers || []), ...providers],
+      exports: [
+        ...(existing.exports || []),
+        PROMPT_SERVICE_TOKEN,
+        PromptService,
+      ],
+    }, PromptModule);
+
+    return PromptModule;
+  }
+
+  /**
+   * Reset module state (for testing)
+   */
+  public static reset(): void {
+    Reflect.deleteMetadata(MODULE_METADATA_KEY, PromptModule);
+  }
+}

package/src/prompt/service.ts

@@ -0,0 +1,93 @@
+import { Injectable } from '../di/decorators';
+import { Inject } from '../di/decorators';
+import type {
+  PromptStore,
+  PromptTemplate,
+  CreatePromptTemplateInput,
+  UpdatePromptTemplateInput,
+  PromptModuleOptions,
+} from './types';
+import { PROMPT_OPTIONS_TOKEN, renderTemplate } from './types';
+import { HttpException } from '../error/http-exception';
+
+/**
+ * Manages prompt templates: CRUD operations, versioning, and variable rendering.
+ */
+@Injectable()
+export class PromptService {
+  private readonly store: PromptStore;
+
+  public constructor(
+    @Inject(PROMPT_OPTIONS_TOKEN) options: PromptModuleOptions,
+  ) {
+    this.store = options.store!;
+  }
+
+  /**
+   * Get a template by ID
+   */
+  public async get(id: string): Promise<PromptTemplate> {
+    const template = await this.store.get(id);
+    if (!template) throw new HttpException(404, `Prompt template "${id}" not found`);
+    return template;
+  }
+
+  /**
+   * Get a specific version of a template
+   */
+  public async getVersion(id: string, version: number): Promise<PromptTemplate> {
+    const template = await this.store.getVersion(id, version);
+    if (!template) throw new HttpException(404, `Prompt template "${id}" version ${version} not found`);
+    return template;
+  }
+
+  /**
+   * List all templates
+   */
+  public async list(): Promise<PromptTemplate[]> {
+    return this.store.list();
+  }
+
+  /**
+   * Create a new template
+   */
+  public async create(input: CreatePromptTemplateInput): Promise<PromptTemplate> {
+    return this.store.create(input);
+  }
+
+  /**
+   * Update a template (creates a new version)
+   */
+  public async update(id: string, input: UpdatePromptTemplateInput): Promise<PromptTemplate> {
+    return this.store.update(id, input);
+  }
+
+  /**
+   * Delete a template
+   */
+  public async delete(id: string): Promise<boolean> {
+    return this.store.delete(id);
+  }
+
+  /**
+   * Render a template by replacing {{varName}} with provided values
+   *
+   * @example
+   * ```typescript
+   * const rendered = await promptService.render('greet-user', { name: 'Alice', app: 'MyApp' });
+   * // "Hello, Alice! Welcome to MyApp."
+   * ```
+   */
+  public async render(id: string, vars: Record<string, string>): Promise<string> {
+    const template = await this.get(id);
+    return renderTemplate(template.content, vars);
+  }
+
+  /**
+   * Render a specific version of a template
+   */
+  public async renderVersion(id: string, version: number, vars: Record<string, string>): Promise<string> {
+    const template = await this.getVersion(id, version);
+    return renderTemplate(template.content, vars);
+  }
+}

package/src/prompt/stores/file-store.ts

@@ -0,0 +1,135 @@
+import type {
+  PromptStore,
+  PromptTemplate,
+  CreatePromptTemplateInput,
+  UpdatePromptTemplateInput,
+} from '../types';
+import { extractVariables } from '../types';
+import { InMemoryPromptStore } from './memory-store';
+
+export interface FilePromptStoreConfig {
+  /** Directory containing JSON prompt files (default: './.prompts') */
+  promptsDir?: string;
+}
+
+/**
+ * File-backed prompt store — loads templates from JSON files at startup
+ * and persists changes back to disk.
+ *
+ * Each template is stored as a separate JSON file: `{promptsDir}/{id}.json`
+ *
+ * File format:
+ * ```json
+ * {
+ *   "id": "greet-user",
+ *   "name": "Greet User",
+ *   "content": "Hello, {{name}}! Welcome to {{app}}.",
+ *   "description": "Greeting template"
+ * }
+ * ```
+ */
+export class FilePromptStore implements PromptStore {
+  private readonly promptsDir: string;
+  private readonly memory: InMemoryPromptStore;
+  private loaded = false;
+
+  public constructor(config: FilePromptStoreConfig = {}) {
+    this.promptsDir = config.promptsDir ?? './.prompts';
+    this.memory = new InMemoryPromptStore();
+  }
+
+  public async get(id: string): Promise<PromptTemplate | null> {
+    await this.ensureLoaded();
+    return this.memory.get(id);
+  }
+
+  public async getVersion(id: string, version: number): Promise<PromptTemplate | null> {
+    await this.ensureLoaded();
+    return this.memory.getVersion(id, version);
+  }
+
+  public async list(): Promise<PromptTemplate[]> {
+    await this.ensureLoaded();
+    return this.memory.list();
+  }
+
+  public async create(input: CreatePromptTemplateInput): Promise<PromptTemplate> {
+    await this.ensureLoaded();
+    const template = await this.memory.create(input);
+    await this.writeFile(template);
+    return template;
+  }
+
+  public async update(id: string, input: UpdatePromptTemplateInput): Promise<PromptTemplate> {
+    await this.ensureLoaded();
+    const template = await this.memory.update(id, input);
+    await this.writeFile(template);
+    return template;
+  }
+
+  public async delete(id: string): Promise<boolean> {
+    await this.ensureLoaded();
+    const deleted = await this.memory.delete(id);
+    if (deleted) {
+      try {
+        const path = `${this.promptsDir}/${id}.json`;
+        await Bun.file(path).exists() && Bun.write(path, ''); // Soft delete (empty file)
+      } catch {
+        // ignore
+      }
+    }
+    return deleted;
+  }
+
+  private async ensureLoaded(): Promise<void> {
+    if (this.loaded) return;
+    this.loaded = true;
+
+    try {
+      const glob = new Bun.Glob('*.json');
+      const files = Array.from(glob.scanSync(this.promptsDir));
+
+      for (const file of files) {
+        try {
+          const content = await Bun.file(`${this.promptsDir}/${file}`).text();
+          if (!content.trim()) continue;
+
+          const data = JSON.parse(content) as {
+            id?: string;
+            name: string;
+            content: string;
+            description?: string;
+          };
+
+          const id = data.id ?? file.replace(/\.json$/, '');
+          await this.memory.create({ id, ...data }).catch(() => {
+            // Template already exists — skip
+          });
+        } catch {
+          // Skip malformed files
+        }
+      }
+    } catch {
+      // Directory doesn't exist — start empty
+    }
+  }
+
+  private async writeFile(template: PromptTemplate): Promise<void> {
+    try {
+      const content = JSON.stringify(
+        {
+          id: template.id,
+          name: template.name,
+          content: template.content,
+          description: template.description,
+          variables: extractVariables(template.content),
+        },
+        null,
+        2,
+      );
+      await Bun.write(`${this.promptsDir}/${template.id}.json`, content);
+    } catch {
+      // Ignore write errors (e.g., read-only filesystem)
+    }
+  }
+}