@frontmcp/skills 1.0.0-beta.9 → 1.0.0

package/catalog/frontmcp-guides/examples/example-weather-api/unit-and-e2e-tests.md

@@ -0,0 +1,142 @@
+---
+name: unit-and-e2e-tests
+reference: example-weather-api
+level: intermediate
+description: 'Shows how to write unit tests for tools by mocking context methods, and E2E tests using `McpTestClient` and `TestServer`.'
+tags: [guides, e2e, unit-test, weather, api, unit]
+features:
+  - 'Unit testing tools by mocking `this.fetch()`, `this.fail()`, and other context methods'
+  - 'Using `Object.assign(tool, ctx)` to inject mock context into the tool instance'
+  - 'E2E testing with `TestServer.start()` and `McpTestClient.create()`'
+  - 'Using `toContainTool()` custom matcher for asserting tool presence'
+  - 'Proper cleanup with `client.disconnect()` and `server.stop()` in `afterAll`'
+---
+
+# Weather API: Unit and E2E Tests
+
+Shows how to write unit tests for tools by mocking context methods, and E2E tests using `McpTestClient` and `TestServer`.
+
+## Code
+
+```typescript
+// test/get-weather.tool.spec.ts
+import { ToolContext } from '@frontmcp/sdk';
+import { GetWeatherTool } from '../src/tools/get-weather.tool';
+
+describe('GetWeatherTool', () => {
+  let tool: GetWeatherTool;
+
+  beforeEach(() => {
+    tool = new GetWeatherTool();
+  });
+
+  it('should return weather data for a valid city', async () => {
+    const mockResponse = {
+      ok: true,
+      json: async () => ({
+        temp: 22,
+        condition: 'Sunny',
+        humidity: 45,
+      }),
+    } as unknown as Response;
+
+    const ctx = {
+      fetch: jest.fn().mockResolvedValue(mockResponse),
+      fail: jest.fn((err: Error) => {
+        throw err;
+      }),
+      mark: jest.fn(),
+      get: jest.fn(),
+      tryGet: jest.fn(),
+      notify: jest.fn(),
+      respondProgress: jest.fn(),
+    } as unknown as ToolContext;
+    Object.assign(tool, ctx);
+
+    const result = await tool.execute({ city: 'London', units: 'celsius' });
+
+    expect(result).toEqual({
+      temperature: 22,
+      condition: 'Sunny',
+      humidity: 45,
+      city: 'London',
+    });
+    expect(ctx.fetch).toHaveBeenCalledWith(expect.stringContaining('city=London'));
+  });
+
+  it('should fail when the weather API returns an error', async () => {
+    const mockResponse = {
+      ok: false,
+      status: 404,
+      statusText: 'Not Found',
+    } as unknown as Response;
+
+    const failFn = jest.fn((err: Error) => {
+      throw err;
+    });
+    const ctx = {
+      fetch: jest.fn().mockResolvedValue(mockResponse),
+      fail: failFn,
+      mark: jest.fn(),
+      get: jest.fn(),
+      tryGet: jest.fn(),
+      notify: jest.fn(),
+      respondProgress: jest.fn(),
+    } as unknown as ToolContext;
+    Object.assign(tool, ctx);
+
+    await expect(tool.execute({ city: 'Atlantis', units: 'celsius' })).rejects.toThrow(
+      'Weather API error: 404 Not Found',
+    );
+    expect(failFn).toHaveBeenCalled();
+  });
+});
+```
+
+```typescript
+// test/weather.e2e.spec.ts
+import { McpTestClient, TestServer } from '@frontmcp/testing';
+
+describe('Weather Server E2E', () => {
+  let client: McpTestClient;
+  let server: TestServer;
+
+  beforeAll(async () => {
+    server = await TestServer.start({ command: 'npx tsx src/main.ts' });
+    client = await McpTestClient.create({ baseUrl: server.info.baseUrl }).buildAndConnect();
+  });
+
+  afterAll(async () => {
+    await client.disconnect();
+    await server.stop();
+  });
+
+  it('should list tools including get_weather', async () => {
+    const { tools } = await client.listTools();
+
+    expect(tools.length).toBeGreaterThan(0);
+    expect(tools).toContainTool('get_weather');
+  });
+
+  it('should read the cities resource', async () => {
+    const result = await client.readResource('weather://cities');
+    const cities = JSON.parse(result.contents[0].text);
+
+    expect(Array.isArray(cities)).toBe(true);
+    expect(cities).toContain('London');
+    expect(cities).toContain('Tokyo');
+  });
+});
+```
+
+## What This Demonstrates
+
+- Unit testing tools by mocking `this.fetch()`, `this.fail()`, and other context methods
+- Using `Object.assign(tool, ctx)` to inject mock context into the tool instance
+- E2E testing with `TestServer.start()` and `McpTestClient.create()`
+- Using `toContainTool()` custom matcher for asserting tool presence
+- Proper cleanup with `client.disconnect()` and `server.stop()` in `afterAll`
+
+## Related
+
+- See `example-weather-api` for the full end-to-end weather API example

package/catalog/frontmcp-guides/examples/example-weather-api/weather-tool-with-schemas.md

@@ -0,0 +1,74 @@
+---
+name: weather-tool-with-schemas
+reference: example-weather-api
+level: basic
+description: 'Shows how to create a tool with Zod input and output schemas, use `this.fetch()` for HTTP calls, and handle errors with `this.fail()`.'
+tags: [guides, weather, api, tool, schemas]
+features:
+  - 'Defining Zod `inputSchema` with validation (`.min(1)`, `.enum()`, `.default()`)'
+  - 'Defining `outputSchema` to prevent data leaks and ensure type safety'
+  - 'Using `this.fetch()` for HTTP calls within tools'
+  - 'Using `this.fail()` for business-logic error handling'
+  - 'Using `.describe()` on schema fields for LLM-friendly tool descriptions'
+---
+
+# Weather Tool with Zod Input/Output Schemas
+
+Shows how to create a tool with Zod input and output schemas, use `this.fetch()` for HTTP calls, and handle errors with `this.fail()`.
+
+## Code
+
+```typescript
+// src/tools/get-weather.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'get_weather',
+  description: 'Get current weather for a city',
+  inputSchema: {
+    city: z.string().min(1).describe('City name'),
+    units: z.enum(['celsius', 'fahrenheit']).default('celsius').describe('Temperature units'),
+  },
+  outputSchema: {
+    temperature: z.number(),
+    condition: z.string(),
+    humidity: z.number(),
+    city: z.string(),
+  },
+})
+export class GetWeatherTool extends ToolContext {
+  async execute(input: { city: string; units: 'celsius' | 'fahrenheit' }) {
+    const url = `https://api.weather.example.com/v1/current?city=${encodeURIComponent(input.city)}&units=${input.units}`;
+
+    // Use this.fetch() for HTTP calls — the framework handles errors in the tool execution flow.
+    const response = await this.fetch(url);
+
+    if (!response.ok) {
+      // Use this.fail() for business-logic errors
+      this.fail(new Error(`Weather API error: ${response.status} ${response.statusText}`));
+    }
+
+    const data = await response.json();
+
+    return {
+      temperature: data.temp,
+      condition: data.condition,
+      humidity: data.humidity,
+      city: input.city,
+    };
+  }
+}
+```
+
+## What This Demonstrates
+
+- Defining Zod `inputSchema` with validation (`.min(1)`, `.enum()`, `.default()`)
+- Defining `outputSchema` to prevent data leaks and ensure type safety
+- Using `this.fetch()` for HTTP calls within tools
+- Using `this.fail()` for business-logic error handling
+- Using `.describe()` on schema fields for LLM-friendly tool descriptions
+
+## Related
+
+- See `example-weather-api` for the full end-to-end weather API example with tests

package/catalog/frontmcp-guides/references/example-knowledge-base.md

@@ -1,3 +1,8 @@
+---
+name: example-knowledge-base
+description: Multi-app knowledge base with vector storage, semantic search, AI research agent, and audit plugin
+---
+
 # Example: Knowledge Base (Advanced)
 
 > Skills used: setup-project, multi-app-composition, create-tool, create-resource, create-provider, create-agent, create-plugin, configure-auth, deploy-to-vercel
@@ -634,3 +639,13 @@ describe('AuditLogPlugin', () => {
   });
 });
 ```
+
+## Examples
+
+| Example                                                                                            | Level        | Description                                                                                                                                   |
+| -------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`agent-and-plugin`](../examples/example-knowledge-base/agent-and-plugin.md)                       | Advanced     | Shows an autonomous research agent with inner tools and configurable depth, and a plugin that hooks into tool execution for audit logging.    |
+| [`multi-app-composition`](../examples/example-knowledge-base/multi-app-composition.md)             | Basic        | Shows how to compose multiple apps (Ingestion, Search, Research) into a single server with shared providers, plugins, and agent registration. |
+| [`vector-search-and-resources`](../examples/example-knowledge-base/vector-search-and-resources.md) | Intermediate | Shows a semantic search tool with embedding generation and a resource template for retrieving documents by ID using URI parameters.           |
+
+> See all examples in [`examples/example-knowledge-base/`](../examples/example-knowledge-base/)

package/catalog/frontmcp-guides/references/example-task-manager.md

@@ -1,3 +1,8 @@
+---
+name: example-task-manager
+description: Authenticated task management server with CRUD tools, Redis storage, OAuth, and Vercel deployment
+---
+
 # Example: Task Manager (Intermediate)
 
 > Skills used: setup-project, create-tool, create-provider, configure-auth, configure-session, setup-redis, setup-testing, deploy-to-vercel
@@ -304,21 +309,18 @@ export class UpdateTaskTool extends ToolContext {
       this.fail(new Error('Authentication required'));
     }
 
-    try {
-      const updated = await store.update(input.id, userId, {
-        ...(input.status && { status: input.status }),
-        ...(input.priority && { priority: input.priority }),
-      });
-
-      return {
-        id: updated.id,
-        title: updated.title,
-        priority: updated.priority,
-        status: updated.status,
-      };
-    } catch (err) {
-      this.fail(new Error(`Failed to update task: ${String(err)}`));
-    }
+    // No try/catch needed — the framework handles errors in the tool execution flow.
+    const updated = await store.update(input.id, userId, {
+      ...(input.status && { status: input.status }),
+      ...(input.priority && { priority: input.priority }),
+    });
+
+    return {
+      id: updated.id,
+      title: updated.title,
+      priority: updated.priority,
+      status: updated.status,
+    };
   }
 }
 ```
@@ -353,12 +355,9 @@ export class DeleteTaskTool extends ToolContext {
       this.fail(new Error('Authentication required'));
     }
 
-    try {
-      await store.delete(input.id, userId);
-      return { deleted: true, id: input.id };
-    } catch (err) {
-      this.fail(new Error(`Failed to delete task: ${String(err)}`));
-    }
+    // No try/catch needed — the framework handles errors in the tool execution flow.
+    await store.delete(input.id, userId);
+    return { deleted: true, id: input.id };
   }
 }
 ```
@@ -510,3 +509,13 @@ describe('Task Manager E2E', () => {
   });
 });
 ```
+
+## Examples
+
+| Example                                                                                  | Level        | Description                                                                                                                                    |
+| ---------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`auth-and-crud-tools`](../examples/example-task-manager/auth-and-crud-tools.md)         | Basic        | Shows how to create CRUD tools with authentication, using `this.context.session` for user isolation and `this.get()` for dependency injection. |
+| [`authenticated-e2e-tests`](../examples/example-task-manager/authenticated-e2e-tests.md) | Advanced     | Shows how to write E2E tests with authentication using `TestTokenFactory`, and unit tests for tools that require session context.              |
+| [`redis-provider-with-di`](../examples/example-task-manager/redis-provider-with-di.md)   | Intermediate | Shows how to create a Redis-backed provider with a DI token, lifecycle hooks (`onInit`/`onDestroy`), and how tools inject it.                  |
+
+> See all examples in [`examples/example-task-manager/`](../examples/example-task-manager/)

package/catalog/frontmcp-guides/references/example-weather-api.md

@@ -1,3 +1,8 @@
+---
+name: example-weather-api
+description: Beginner MCP server with a weather lookup tool, static resource, Zod schemas, and E2E tests
+---
+
 # Example: Weather API (Beginner)
 
 > Skills used: setup-project, create-tool, create-resource, setup-testing, deploy-to-node
@@ -94,12 +99,9 @@ export class GetWeatherTool extends ToolContext {
   async execute(input: { city: string; units: 'celsius' | 'fahrenheit' }) {
     const url = `https://api.weather.example.com/v1/current?city=${encodeURIComponent(input.city)}&units=${input.units}`;
 
-    let response: Response;
-    try {
-      response = await this.fetch(url);
-    } catch (err) {
-      this.fail(new Error(`Weather API unreachable: ${String(err)}`));
-    }
+    // No try/catch needed — the framework's tool execution flow handles errors automatically.
+    // Use this.fail() only for business-logic errors (e.g., invalid response).
+    const response = await this.fetch(url);
 
     if (!response.ok) {
       this.fail(new Error(`Weather API error: ${response.status} ${response.statusText}`));
@@ -290,3 +292,13 @@ describe('Weather Server E2E', () => {
   });
 });
 ```
+
+## Examples
+
+| Example                                                                                     | Level        | Description                                                                                                                            |
+| ------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
+| [`server-and-app-setup`](../examples/example-weather-api/server-and-app-setup.md)           | Basic        | Shows the server entry point, app registration, and static resource for a beginner FrontMCP weather API server.                        |
+| [`unit-and-e2e-tests`](../examples/example-weather-api/unit-and-e2e-tests.md)               | Intermediate | Shows how to write unit tests for tools by mocking context methods, and E2E tests using `McpTestClient` and `TestServer`.              |
+| [`weather-tool-with-schemas`](../examples/example-weather-api/weather-tool-with-schemas.md) | Basic        | Shows how to create a tool with Zod input and output schemas, use `this.fetch()` for HTTP calls, and handle errors with `this.fail()`. |
+
+> See all examples in [`examples/example-weather-api/`](../examples/example-weather-api/)

package/catalog/frontmcp-observability/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: frontmcp-observability
+description: 'Use when you want to add tracing, structured logging, or monitoring to your FrontMCP server. Covers OpenTelemetry instrumentation, vendor integrations (Coralogix, Datadog, Logz.io, Grafana), this.telemetry API for custom spans, structured JSON logging with sinks, and testing observability. Triggers: observability, telemetry, tracing, logging, monitoring, opentelemetry, otel, spans, datadog, coralogix, logz, grafana, winston, pino.'
+tags: [router, observability, telemetry, tracing, logging, monitoring, opentelemetry, otel, spans]
+category: observability
+targets: [all]
+bundle: [recommended, full]
+priority: 10
+visibility: both
+license: Apache-2.0
+metadata:
+  docs: https://docs.agentfront.dev/frontmcp/guides/observability
+---
+
+# FrontMCP Observability
+
+Router for adding observability to FrontMCP servers. Covers distributed tracing (OpenTelemetry), structured JSON logging, per-request log collection, the `this.telemetry` developer API, and vendor integrations.
+
+## When to Use This Skill
+
+### Must Use
+
+- Adding tracing, logging, or monitoring to a FrontMCP server
+- Connecting Coralogix, Datadog, Logz.io, Grafana, or any OTLP backend
+- Using `this.telemetry` to create custom spans in tools, plugins, or agents
+- Setting up structured logging with winston, pino, or NDJSON stdout
+- Testing that spans and log entries are created correctly
+
+### Recommended
+
+- Before going to production (see also `frontmcp-production-readiness`)
+- When debugging request latency or error rates
+- When building plugins that need trace context propagation
+
+### Skip When
+
+- Building a prototype that doesn't need observability yet
+- Configuring auth, transport, or throttle (see `frontmcp-config`)
+- Setting up the project from scratch (see `frontmcp-setup`)
+
+> **Decision:** Use this skill when you need to observe, trace, or log your server. Start with `tracing-setup` for auto-instrumentation, add `structured-logging` for production logs, and use `telemetry-api` for custom spans in your code.
+
+## Prerequisites
+
+- A working FrontMCP server (see `frontmcp-setup`)
+- `npm install @frontmcp/observability`
+
+## Step 1: Choose What You Need
+
+| I want to...                                       | Reference                             |
+| -------------------------------------------------- | ------------------------------------- |
+| Enable auto-tracing for all flows                  | `references/tracing-setup.md`         |
+| Add structured JSON logging with trace correlation | `references/structured-logging.md`    |
+| Create custom spans in tools/plugins               | `references/telemetry-api.md`         |
+| Connect Coralogix, Datadog, Logz.io, Grafana       | `references/vendor-integrations.md`   |
+| Test that spans and logs are correct               | `references/testing-observability.md` |
+
+## Step 2: Enable Observability
+
+The simplest way — one config line:
+
+```typescript
+@FrontMcp({
+  observability: true,
+})
+```
+
+This enables auto-tracing for all 33 SDK flows. Add structured logging:
+
+```typescript
+@FrontMcp({
+  observability: {
+    tracing: true,
+    logging: { sinks: [{ type: 'stdout' }] },
+    requestLogs: true,
+  },
+})
+```
+
+## Step 3: Read the Relevant Reference
+
+Follow the scenario routing table above to find the right reference for your use case.
+
+## Scenario Routing Table
+
+| Scenario                             | Reference                             | Description                                                                 |
+| ------------------------------------ | ------------------------------------- | --------------------------------------------------------------------------- |
+| Enable OpenTelemetry tracing         | `references/tracing-setup.md`         | Zero-config auto-instrumentation, setupOTel(), span hierarchy               |
+| Add JSON logs with trace correlation | `references/structured-logging.md`    | Sinks (stdout, console, OTLP, winston, pino), redaction, log format         |
+| Custom spans in tools/plugins        | `references/telemetry-api.md`         | `this.telemetry.startSpan()`, `withSpan()`, `addEvent()`, `setAttributes()` |
+| Connect to monitoring platforms      | `references/vendor-integrations.md`   | Coralogix, Datadog, Logz.io, Grafana — OTLP and direct                      |
+| Test spans and log entries           | `references/testing-observability.md` | `createTestTracer()`, `assertSpanExists()`, integration test patterns       |
+
+## Cross-Cutting Patterns
+
+| Pattern              | Correct                                     | Incorrect                                         | Why                                                           |
+| -------------------- | ------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------- |
+| Enable observability | `observability: true` in `@FrontMcp` config | Import and install `ObservabilityPlugin` manually | Config-driven is the standard pattern since v1.0              |
+| Custom spans         | `this.telemetry.withSpan('op', fn)`         | `trace.getTracer().startSpan()` directly          | `this.telemetry` auto-inherits trace context                  |
+| Log correlation      | `this.logger.info('msg', { key: val })`     | `console.log('msg')`                              | SDK logger flows through StructuredLogTransport with trace_id |
+| Session ID           | Use `mcp.session.id` attribute (hashed)     | Log the real session ID                           | Privacy: the hash is sufficient for correlation               |
+| Vendor integration   | Use `{ type: 'otlp', endpoint }` sink       | Build vendor-specific HTTP clients                | OTLP is the universal standard                                |
+
+## Quick Reference: What Gets Traced
+
+| Category       | Flows                                                | Attributes                                        |
+| -------------- | ---------------------------------------------------- | ------------------------------------------------- |
+| HTTP requests  | traceRequest, auth, route, finalize                  | `http.request.method`, `url.path`                 |
+| Tool calls     | parseInput → findTool → execute → finalize           | `mcp.component.type=tool`, `enduser.id`           |
+| Resource reads | parseInput → findResource → execute                  | `mcp.component.type=resource`, `mcp.resource.uri` |
+| Prompts        | parseInput → findPrompt → execute                    | `mcp.component.type=prompt`                       |
+| Agents         | parseInput → findAgent → execute (nested tool calls) | `mcp.component.type=agent`                        |
+| Auth           | verify, session verify, OAuth flows                  | `frontmcp.auth.mode`, `frontmcp.auth.result`      |
+| Transport      | SSE, Streamable HTTP, Stateless HTTP                 | `frontmcp.transport.type`                         |
+| Skills         | search, load, HTTP endpoints                         | `frontmcp.flow.name`                              |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] `@frontmcp/observability` installed
+- [ ] `observability` field added to `@FrontMcp` config
+- [ ] TracerProvider configured (via `setupOTel()` or external SDK)
+- [ ] Logging sinks configured for production (stdout or OTLP)
+
+### Runtime
+
+- [ ] Spans appear in trace backend when calling a tool
+- [ ] Log entries include `trace_id` and `span_id`
+- [ ] `this.telemetry` is available in tool execution contexts
+- [ ] Session tracing ID is consistent across all spans in a request
+- [ ] Errors are recorded on spans with `ERROR` status
+
+### Testing
+
+- [ ] Tests verify span creation with `createTestTracer()`
+- [ ] Tests verify log entries via `CallbackSink`
+- [ ] No test isolation issues (each test resets exporter)
+
+## Reference
+
+- [Observability Guide](https://docs.agentfront.dev/frontmcp/guides/observability)
+- [Telemetry API Reference](https://docs.agentfront.dev/frontmcp/sdk-reference/telemetry)
+- Related skills: `frontmcp-production-readiness`, `frontmcp-config`, `frontmcp-testing`, `frontmcp-development`

package/catalog/frontmcp-observability/examples/structured-logging/stdout-logging.md

@@ -0,0 +1,71 @@
+---
+name: stdout-logging
+reference: structured-logging
+level: basic
+description: 'Enable NDJSON structured logging to stdout with automatic trace correlation and field redaction.'
+tags: [logging, stdout, ndjson, redaction, basic]
+features:
+  - 'NDJSON format for stdout (Docker/K8s log collection)'
+  - 'Automatic trace context enrichment (trace_id, span_id)'
+  - 'Sensitive field redaction (token → [REDACTED])'
+---
+
+# Stdout Structured Logging
+
+Enable NDJSON structured logging to stdout with automatic trace correlation and field redaction.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp } from '@frontmcp/sdk';
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  observability: {
+    tracing: true,
+    logging: {
+      sinks: [{ type: 'stdout' }],
+      redactFields: ['password', 'token', 'secret', 'authorization'],
+      includeStacks: process.env.NODE_ENV !== 'production',
+    },
+  },
+})
+export default class Server {}
+```
+
+```typescript
+// In any tool:
+this.logger.info('user authenticated', { userId: 'u-123', token: 'secret-jwt' });
+```
+
+Output (NDJSON, one line per entry):
+
+```json
+{
+  "timestamp": "2026-04-03T10:15:30.123Z",
+  "level": "info",
+  "severity_number": 9,
+  "message": "user authenticated",
+  "trace_id": "abcdef...",
+  "span_id": "123456...",
+  "request_id": "req-001",
+  "session_id_hash": "a3f8b2c1d4e5f6a7",
+  "scope_id": "my-app",
+  "flow_name": "tools:call-tool",
+  "elapsed_ms": 42,
+  "prefix": "MyTool",
+  "attributes": { "userId": "u-123", "token": "[REDACTED]" }
+}
+```
+
+## What This Demonstrates
+
+- NDJSON format for stdout (Docker/K8s log collection)
+- Automatic trace context enrichment (trace_id, span_id)
+- Sensitive field redaction (token → [REDACTED])
+
+## Related
+
+- See `structured-logging` for all sink types

package/catalog/frontmcp-observability/examples/structured-logging/winston-integration.md

@@ -0,0 +1,70 @@
+---
+name: winston-integration
+reference: structured-logging
+level: intermediate
+description: 'Forward FrontMCP structured log entries to your existing winston logger. Each entry includes trace_id and span_id as metadata.'
+tags: [logging, winston, integration, intermediate]
+features:
+  - 'WinstonSink forwarding structured entries with trace metadata'
+  - 'Multiple sinks running simultaneously (stdout + winston)'
+  - 'Winston transports handle file logging, remote forwarding, etc.'
+---
+
+# Winston Integration
+
+Forward FrontMCP structured log entries to your existing winston logger. Each entry includes trace_id and span_id as metadata.
+
+## Code
+
+```typescript
+// src/server.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import winston from 'winston';
+
+const logger = winston.createLogger({
+  level: 'info',
+  format: winston.format.combine(winston.format.timestamp(), winston.format.json()),
+  transports: [new winston.transports.Console(), new winston.transports.File({ filename: 'app.log' })],
+});
+
+@FrontMcp({
+  info: { name: 'my-server', version: '1.0.0' },
+  apps: [MyApp],
+  observability: {
+    tracing: true,
+    logging: {
+      sinks: [
+        { type: 'winston', logger }, // Forward to winston
+        { type: 'stdout' }, // Also write NDJSON to stdout
+      ],
+    },
+  },
+})
+export default class Server {}
+```
+
+Winston receives entries like:
+
+```json
+{
+  "level": "info",
+  "message": "tool executed",
+  "timestamp": "2026-04-03T10:15:30.123Z",
+  "trace_id": "abcdef1234567890abcdef1234567890",
+  "span_id": "1234567890abcdef",
+  "request_id": "req-001",
+  "session_id_hash": "a3f8b2c1d4e5f6a7",
+  "attributes": { "tool": "get_weather", "duration_ms": 142 }
+}
+```
+
+## What This Demonstrates
+
+- WinstonSink forwarding structured entries with trace metadata
+- Multiple sinks running simultaneously (stdout + winston)
+- Winston transports handle file logging, remote forwarding, etc.
+
+## Related
+
+- See `structured-logging` for all sink types
+- See `vendor-integrations` for connecting to Coralogix/Datadog via winston