docs(service-worker): runnable example, package READMEs, wiki page

Add examples/helloworld-service-worker (an HTTP controller and an MCP tool
served from one tegg module over ServiceWorkerApp, with its own vitest
suite; the entry lives outside the scanned app/ dir so the module scan does
not execute it), README for both service worker packages, and the wiki
package page + log entry.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: gxkl

examples/helloworld-service-worker/README.md

@@ -0,0 +1,43 @@
+# helloworld-service-worker
+
+Minimal example of `@eggjs/service-worker`: a tegg module served through the
+standalone service worker runtime — HTTP controllers and MCP tools over the
+same fetch event loop, no egg application required.
+
+## Run
+
+```bash
+# from the monorepo root
+ut install --from pnpm
+node --import=@oxc-node/core/register examples/helloworld-service-worker/main.ts
+```
+
+Then:
+
+```bash
+curl 'http://127.0.0.1:7001/hello/?name=you'
+# {"message":"hello, you"}
+
+curl -X POST 'http://127.0.0.1:7001/mcp/calc/stream' \
+  -H 'accept: application/json, text/event-stream' \
+  -H 'content-type: application/json' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"add","arguments":{"a":1,"b":41}}}'
+```
+
+## What's inside
+
+- `app/` — the tegg module (its `package.json` declares `eggModule.name`):
+  - `HelloController.ts` — an `@HTTPController` bound to `GET /hello/`.
+  - `CalcMCPController.ts` — an `@MCPController` exposing an `add` tool over
+    MCP stateless streamable HTTP at `/mcp/calc`.
+  - `HelloService.ts` — a `@ContextProto` service injected into both.
+- `main.ts` — boots `ServiceWorkerApp` on the module dir and serves it over
+  `node:http`. The entry lives outside `app/` so the module scan doesn't
+  execute it.
+
+## Test
+
+```bash
+# from the monorepo root
+utx vitest run examples/helloworld-service-worker --config examples/helloworld-service-worker/vitest.config.ts
+```

examples/helloworld-service-worker/app/CalcMCPController.ts

@@ -0,0 +1,27 @@
+import { Inject, MCPController, MCPTool, ToolArgsSchema } from '@eggjs/tegg';
+import { z } from 'zod';
+
+import { HelloService } from './HelloService.ts';
+
+const AddArgsSchema = {
+  a: z.number(),
+  b: z.number(),
+};
+
+@MCPController({ name: 'calc' })
+export class CalcMCPController {
+  @Inject()
+  private readonly helloService: HelloService;
+
+  @MCPTool({ description: 'add two numbers' })
+  async add(@ToolArgsSchema(AddArgsSchema) args: { a: number; b: number }) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `${this.helloService.hello('mcp')}: ${args.a + args.b}`,
+        },
+      ],
+    };
+  }
+}

examples/helloworld-service-worker/app/HelloController.ts

@@ -0,0 +1,14 @@
+import { HTTPController, HTTPMethod, HTTPMethodEnum, HTTPQuery, Inject } from '@eggjs/tegg';
+
+import { HelloService } from './HelloService.ts';
+
+@HTTPController({ path: '/hello' })
+export class HelloController {
+  @Inject()
+  private readonly helloService: HelloService;
+
+  @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/' })
+  async hello(@HTTPQuery({ name: 'name' }) name: string) {
+    return { message: this.helloService.hello(name ?? 'service worker') };
+  }
+}

examples/helloworld-service-worker/app/HelloService.ts

@@ -0,0 +1,8 @@
+import { ContextProto } from '@eggjs/tegg';
+
+@ContextProto()
+export class HelloService {
+  hello(name: string): string {
+    return `hello, ${name}`;
+  }
+}

examples/helloworld-service-worker/app/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "helloworld-service-worker-app",
+  "type": "module",
+  "eggModule": {
+    "name": "helloWorldServiceWorker"
+  }
+}

examples/helloworld-service-worker/main.ts

@@ -0,0 +1,25 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { ServiceWorkerApp } from '@eggjs/service-worker';
+
+const app = new ServiceWorkerApp(path.join(path.dirname(fileURLToPath(import.meta.url)), 'app'));
+const server = await app.serve({ port: 7001 });
+console.log('service worker listening on http://127.0.0.1:7001');
+console.log('  GET  /hello/?name=you');
+console.log('  POST /mcp/calc (MCP streamable http)');
+
+for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+  process.once(signal, () => {
+    console.log(`received ${signal}, shutting down`);
+    app
+      .destroy()
+      .then(() => process.exit(0))
+      .catch((e) => {
+        console.error(e);
+        process.exit(1);
+      });
+  });
+}
+
+void server;

examples/helloworld-service-worker/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "helloworld-service-worker",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Hello World example using the standalone service worker",
+  "type": "module",
+  "scripts": {
+    "start": "node --import=@oxc-node/core/register main.ts",
+    "test": "vitest run",
+    "typecheck": "tsgo --noEmit"
+  },
+  "dependencies": {
+    "@eggjs/service-worker": "workspace:*",
+    "@eggjs/tegg": "workspace:*",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@eggjs/tsconfig": "workspace:*",
+    "@oxc-node/core": "catalog:",
+    "@types/node": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  }
+}

examples/helloworld-service-worker/test/index.test.ts

@@ -0,0 +1,46 @@
+import assert from 'node:assert/strict';
+import type { AddressInfo } from 'node:net';
+import path from 'node:path';
+
+import { ServiceWorkerApp } from '@eggjs/service-worker';
+import { afterAll, beforeAll, describe, it } from 'vitest';
+
+describe('examples/helloworld-service-worker', () => {
+  let app: ServiceWorkerApp;
+  let base: string;
+
+  beforeAll(async () => {
+    app = new ServiceWorkerApp(path.join(__dirname, '../app'));
+    const server = await app.serve();
+    const { address, port } = server.address() as AddressInfo;
+    base = `http://${address}:${port}`;
+  });
+
+  afterAll(async () => {
+    await app.destroy();
+  });
+
+  it('should say hello over http', async () => {
+    const res = await fetch(`${base}/hello/?name=egg`);
+    assert.deepEqual(await res.json(), { message: 'hello, egg' });
+  });
+
+  it('should serve the calc MCP tool', async () => {
+    const res = await fetch(`${base}/mcp/calc/stream`, {
+      method: 'POST',
+      headers: {
+        accept: 'application/json, text/event-stream',
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'tools/call',
+        params: { name: 'add', arguments: { a: 1, b: 41 } },
+      }),
+    });
+    assert.equal(res.status, 200);
+    const text = await res.text();
+    assert.match(text, /hello, mcp: 42/);
+  });
+});

examples/helloworld-service-worker/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "@eggjs/tsconfig"
+}

examples/helloworld-service-worker/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineProject } from 'vitest/config';
+
+export default defineProject({
+  test: {
+    include: ['test/**/*.test.ts'],
+  },
+});