@magek/mcp-server 0.0.8

package/docs/features/error-handling.md

@@ -0,0 +1,204 @@
+---
+title: "Error Handling"
+group: "Features"
+---
+
+# Error handling
+
+## Error handling in Magek
+
+Magek provides a default error handling mechanism that will try to catch all the errors that are thrown in the application and will log them. This is useful for debugging purposes, but you may want to customize the error handling in your application. For example, you may want to email the administrator when an error occurs.
+
+### Custom error handling
+
+To customize the error handling, you need to create a class decorated with the `@GlobalErrorHandler` decorator. This class will contain the methods that will be called when an error is thrown. There is one method for each component in the application where an error can be thrown. All these functions receive the error that was thrown and the information about the component that was being executed when the error occurred. 
+
+They must return a promise that resolves to an `Error` object or `undefined`. If the promise resolves to `undefined`, the error will be ignored and **Magek** will continue working. If the promise resolves to an `Error` object, the error will be thrown and **Magek** will handle it on a case-by-case basis in the default way.
+
+### Command handle errors
+
+These are the errors that are thrown in the `handle` method of the `@Command`. You can catch and return new errors in this method annotating a class with `@GlobalErrorHandler` and implementing the following method:
+
+```typescript
+@GlobalErrorHandler()
+export class MyErrorHandler {
+  public static async onCommandHandlerError(
+    error: Error,
+    commandEnvelope: CommandEnvelope,
+    commandMetadata: CommandMetadata
+  ): Promise<Error | undefined> {
+    // Do something with the error
+  }
+}
+```
+
+This method receives the error that was thrown and the command that was being handled when the error occurred. 
+
+### Scheduled command handle errors
+
+These are the errors that are thrown in the `handle` method of the `@ScheduledCommand`. You can catch and return new errors in this function annotating a class with `@GlobalErrorHandler` and implementing the following method:
+
+```typescript
+@GlobalErrorHandler()
+export class MyErrorHandler {
+  public static async onScheduledCommandHandlerError(
+    error: Error,
+    scheduledCommandEnvelope: ScheduledCommandEnvelope,
+    scheduledCommandMetadata: ScheduledCommandMetadata
+  ): Promise<Error | undefined> {
+    // Do something with the error
+  }
+}
+```
+
+Note that if an error is thrown on a ScheduleCommand, **Magek** will stop working.
+
+### Event handler errors
+
+These are the errors that are thrown in the `handle` method of the `@Event`. You can catch and return new errors in this function annotating a class with `@GlobalErrorHandler` and implementing the following method:
+
+```typescript
+@GlobalErrorHandler()
+export class MyErrorHandler {
+  public static async onDispatchEventHandlerError(
+    error: Error,
+    eventEnvelope: EventEnvelope | NotificationInterface,
+    eventHandlerMetadata: unknown,
+    eventInstance: EventInterface
+  ): Promise<Error | undefined> {
+    // Do something with the error
+  }
+}
+```
+
+### Reducer errors
+
+These are the errors that are thrown in the `@reduces` method of the `@Entity`. You can catch and return new errors in this function annotating a class with `@GlobalErrorHandler` and implementing the following method:
+
+```typescript
+@GlobalErrorHandler()
+export class MyErrorHandler {
+  public static async onReducerError(
+    error: Error,
+    eventEnvelope: EventEnvelope,
+    reducerMetadata: ReducerMetadata,
+    eventInstance: EventInterface,
+    snapshotInstance: EntityInterface | null
+  ): Promise<Error> {
+    // Do something with the error
+  }
+}
+```
+
+Note you can not ignore a Reducer error as the new entity could not be created
+
+### Event errors
+
+These are the errors that are thrown if the event doesn't exist. You can catch and return new errors in this function annotating a class with `@GlobalErrorHandler` and implementing the following method:
+
+```typescript
+@GlobalErrorHandler()
+export class MyErrorHandler {
+  public static async onEventError(error: Error, eventEnvelope: EventEnvelope): Promise<Error | undefined> {
+    // Do something with the error
+  }
+}
+```
+
+This method receives the error that was thrown and the event received.
+
+### Projection errors
+
+These are the errors that are thrown in the `@projects` method of the `@ReadModel`. You can catch and return new errors in this function annotating a class with `@GlobalErrorHandler` and implementing the following method:
+
+```typescript
+@GlobalErrorHandler()
+export class MyErrorHandler {
+  public static async onProjectionError(
+    error: Error,
+    entityEnvelope: EntitySnapshotEnvelope,
+    projectionMetadata: ProjectionMetadata<EntityInterface>,
+    entity: EntityInterface,
+    readModel: ReadModelInterface | undefined
+  ): Promise<Error | undefined> {
+    // Do something with the error
+  }
+}
+```
+
+### All errors
+
+These are the errors that are thrown in any of the previous methods. You can catch and return new errors in this function annotating a class with `@GlobalErrorHandler` and implementing the following method:
+
+```typescript
+@GlobalErrorHandler()
+export class MyErrorHandler {
+  public onError(error: Error | undefined): Promise<Error | undefined> {
+    // Do something with the error
+  }
+}
+```
+
+This method receives the error that was thrown.
+
+## Global error handler example
+
+You can implement all error handling functions in the same class. Here is an example of a global error handler that will handle all the errors mentioned above:
+
+```typescript
+@GlobalErrorHandler()
+export class AppErrorHandler {
+  public static async onCommandHandlerError(
+    error: Error,
+    commandEnvelope: CommandEnvelope,
+    commandMetadata: CommandMetadata
+  ): Promise<Error | undefined> {
+    return error
+  }
+
+  public static async onScheduledCommandHandlerError(
+    error: Error,
+    scheduledCommandEnvelope: ScheduledCommandEnvelope,
+    scheduledCommandMetadata: ScheduledCommandMetadata
+  ): Promise<Error | undefined> {
+    return error
+  }
+
+  public static async onDispatchEventHandlerError(
+    error: Error,
+    eventEnvelope: EventEnvelope | NotificationInterface,
+    eventHandlerMetadata: unknown,
+    eventInstance: EventInterface
+  ): Promise<Error | undefined> {
+    return error
+  }
+
+  public static async onReducerError(
+    error: Error,
+    eventEnvelope: EventEnvelope,
+    reducerMetadata: ReducerMetadata,
+    eventInstance: EventInterface,
+    snapshotInstance: EntityInterface | null
+  ): Promise<Error | undefined> {
+    return error
+  }
+
+  public static async onProjectionError(
+    error: Error,
+    entityEnvelope: EntitySnapshotEnvelope,
+    projectionMetadata: ProjectionMetadata<EntityInterface>,
+    entity: EntityInterface,
+    readModel: ReadModelInterface | undefined
+  ): Promise<Error | undefined> {
+    return error
+  }
+
+  public static async onEventError(error: Error, eventEnvelope: EventEnvelope): Promise<Error | undefined> {
+    return error
+  }
+
+  public static async onError(error: Error | undefined): Promise<Error | undefined> {
+    return error
+  }
+}
+```

package/docs/features/event-stream.md

@@ -0,0 +1,35 @@
+---
+title: "Event Stream API"
+group: "Features"
+---
+
+# The event stream
+
+The event stream API is a read-only API that allows you to fetch the events that have been generated by your application. It's useful for debugging purposes, but also for building your own analytics tools. The access to this API is disabled by default, but you can enable it by configuring the `authorizeReadEvents` policy in your entities. You can also use the `authorizeReadEvents` policy to restrict access to the events of certain entities.
+
+## Accessing the event streams API
+
+The `authorizeReadEvents` policy can be configured with any of the supported authorization mechanisms:
+
+- `'all'` to make them public.
+- an array of roles.
+- An [authorizer function](/security/authorization#event-stream-authorizers) that matches the `EventStreamAuthorizer` type signature. For example
+
+```typescript
+@Entity({
+  authorizeReadEvents: 'all', // Anyone can read any Cart's event
+})
+export class Cart {
+  public constructor(
+    readonly id: UUID,
+    readonly cartItems: Array<CartItem>,
+    public shippingAddress?: Address,
+    public checks = 0
+  ) {}
+  // <reducers...>
+}
+```
+
+> **Note:** Be careful when exposing events data, as this data is likely to hold internal system state. Pay special attention when authorizing public access with the `'all'` option, it's always recommended to look for alternate solutions that limit access.
+
+To read more about how to restrict the access to the event stream API, check out the [authorization guide](/security/authorization).

package/docs/features/logging.md

@@ -0,0 +1,81 @@
+---
+title: "Logging"
+group: "Features"
+---
+
+# Logging in Magek
+
+If no configuration is provided, Magek uses the default JavaScript logging capabilities. Depending on the log level, it will call different logging methods:
+
+- `console.debug` for `Level.debug`
+- `console.info` for `Level.info`
+- `console.warn` for `Level.warn`
+- `console.error` for `Level.error`
+
+In this regard, there's no distinction from any other node process and you'll find the logs in your standard output.
+
+## Advanced logging
+
+You may need some advanced logging capabilities, such as redirecting your logs to a log aggregator. Magek also supports overriding the default behavior by providing custom loggers. The only thing you need to do is to provide an object that implements the `Logger` interface at config time:
+
+```typescript title="@magek/common/lib/logger.ts"
+interface Logger {
+  debug(message?: any, ...optionalParams: any[]): void
+  info(message?: any, ...optionalParams: any[]): void
+  warn(message?: any, ...optionalParams: any[]): void
+  error(message?: any, ...optionalParams: any[]): void
+}
+```
+
+```typescript title="src/config/config.ts"
+
+Magek.configure('development', (config: MagekConfig): void => {
+  config.appName = 'my-store'
+  config.runtime = ServerRuntime
+  config.eventStoreAdapter = eventStore
+  // highlight-start
+  config.logger = new MyCustomLogger() // Overrides the default logger object
+  config.logLevel = Level.debug        // Sets the log level at 'debug'     
+  config.logPrefix = 'my-store-dev'    // Sets the default prefix
+  // highlight-end
+})
+```
+
+## Using the Magek's logger
+
+All framework's components will use this logger by default and will generate logs that match the following pattern:
+
+```text
+[<logPrefix>]|moduleName: <message>
+```
+
+You can get a custom logger instance that extends the configured logger by adding your moduleName and optionally overriding the configured prefix with the `getLogger` helper function. It's a good practice to build and use a separate logger instance built with this method for each context, as this will make it easier to filter your logs when you need to investigate a problem.
+
+_Example: Obtaining a logger for your command:_
+
+```typescript
+@Command({
+  authorize: [User],
+})
+export class UpdateShippingAddress {
+  @field()
+  readonly cartId!: UUID
+
+  @field()
+  readonly address!: Address
+
+  public static async handle(command: UpdateShippingAddress, register: Register): Promise<void> {
+    const logger = getLogger(Magek.config, 'UpdateShippingCommand#handler', 'MyApp')
+    logger.debug(`User ${register.currentUser?.username} changed shipping address for cart ${command.cartId}: ${JSON.stringify(command.address}`)
+    register.events(new ShippingAddressUpdated(command.cartId, command.address))
+  }
+}
+```
+
+When a `UpdateShippingAddress` command is handled, it wil log messages that look like the following:
+
+```text
+[MyApp]|UpdateShippingCommand#handler: User buyer42 changed shipping address for cart 314: { street: '13th rue del percebe', number: 6, ... }
+```
+
+Using the configured Magek logger is not mandatory for your application, but it might be convenient to centralize your logs and this is a standard way to do it.

package/docs/features/schedule-actions.md

@@ -0,0 +1,44 @@
+---
+title: "Scheduled Actions"
+group: "Features"
+---
+
+# Schedule actions
+
+There are many cases in which you want to trigger some action periodically. For example, you may want to send a reminder email to a user every day at 10:00 AM. For this, you can use scheduled commands.
+
+## Scheduled command
+
+Commands represent an action. Therefore, the way to trigger an action periodically is by scheduling a command. Scheduled commands are the way to add automated tasks to your application, like cron jobs in other frameworks. Magek scheduled commands are TypeScript classes decorated with `@ScheduledCommand`. Unlike conventional commands, **the handle function doesn't have any parameters**.
+
+In Magek, a scheduled command looks like this:
+
+```typescript
+@ScheduledCommand({
+  minute: '0/5', // runs every 5 minutes
+})
+export class CheckCartCount {
+  public static async handle(): Promise<void> {
+    /* YOUR CODE HERE */
+  }
+}
+```
+
+You can pass the following parameters to the `@ScheduledCommand` decorator:
+
+* `minute`: A cron expression to specify the minute(s) in which the command will be triggered. For example, `0/5` means "every 5 minutes". You can also use a comma-separated list of values, like `1,5,10,15,20,25,30,35,40,45,50,55` to specify a list of minutes.
+* `hour`: A cron expression to specify the hour(s) in which the command will be triggered. For example, `0/2` means "every 2 hours". You can also use a comma-separated list of values, like `1,3,5,7,9,11,13,15,17,19,21,23` to specify a list of hours.
+* `day`: A cron expression to specify the day(s) in which the command will be triggered. For example, `1/2` means "every 2 days". You can also use a comma-separated list of values, like `1,3,5,7,9,11,13,15,17,19,21,23,25,27,29,31` to specify a list of days.
+* `month`: A cron expression to specify the month(s) in which the command will be triggered. For example, `1/2` means "every 2 months". You can also use a comma-separated list of values, like `1,3,5,7,9,11` to specify a list of months.
+* `weekDay`: A cron expression to specify the day(s) of the week in which the command will be triggered. For example, `1/2` means "every 2 days of the week". You can also use a comma-separated list of values, like `1,3,5` to specify a list of days of the week.
+* `year`: A cron expression to specify the year(s) in which the command will be triggered. For example, `2020/2` means "every 2 years". You can also use a comma-separated list of values, like `2020,2022,2024,2026,2028,2030` to specify a list of years.
+
+By default, if no paramaters are passed, the scheduled command will not be triggered.
+
+## Creating a scheduled command
+
+The preferred way to create a scheduled command is by using the generator, e.g.
+
+```bash
+npx magek new:scheduled-command CheckCartCount
+```

package/docs/getting-started/ai-coding-assistants.md

@@ -0,0 +1,181 @@
+---
+title: "AI Coding Assistants"
+group: "Getting Started"
+---
+
+# AI Coding Assistants
+
+Magek provides an MCP (Model Context Protocol) server that enables AI coding assistants like **Claude Code** and **Codex CLI** to understand and work with Magek projects. This gives your AI assistant access to Magek documentation, CLI commands, and best practices — so it can help you build event-sourced applications faster.
+
+## Quick Start
+
+### Claude Code
+
+Add Magek to Claude Code with a single command:
+
+```bash
+claude mcp add magek -- npx -y @magek/mcp-server
+```
+
+That's it! Claude Code now has access to Magek documentation and can help you scaffold commands, events, entities, and read models.
+
+### Codex CLI
+
+Add to your project's `.codex/config.json`:
+
+```json
+{
+  "mcpServers": {
+    "magek": {
+      "command": "npx",
+      "args": ["-y", "@magek/mcp-server"]
+    }
+  }
+}
+```
+
+### Manual Configuration
+
+For other MCP-compatible tools, add to your configuration:
+
+```json
+{
+  "mcpServers": {
+    "magek": {
+      "command": "npx",
+      "args": ["-y", "@magek/mcp-server"]
+    }
+  }
+}
+```
+
+## What Your AI Assistant Can Do
+
+Once configured, your AI coding assistant can:
+
+### Access Documentation
+
+The MCP server provides all Magek documentation as resources. Your assistant can read about:
+
+- Commands, Events, Entities, and Read Models
+- Authentication and Authorization
+- Event Handlers and Scheduled Commands
+- Advanced topics like Data Migrations and Testing
+
+### Use CLI Commands
+
+Your assistant knows all Magek CLI scaffolding commands and can execute them for you:
+
+```bash
+# Create a command
+npx magek new:command CreateProduct --fields sku:string price:number
+
+# Create an event
+npx magek new:event ProductCreated --fields productId:UUID sku:string price:number
+
+# Create an entity
+npx magek new:entity Product --fields sku:string price:number --reduces ProductCreated
+
+# Create a read model
+npx magek new:read-model ProductReadModel --fields sku:string price:number --projects Product:id
+```
+
+### Follow CQRS Patterns
+
+The MCP server includes a CQRS flow prompt that guides your assistant through implementing complete features:
+
+1. **Command** → User intent (e.g., `CreateProduct`)
+2. **Event** → Immutable fact (e.g., `ProductCreated`)
+3. **Entity** → State reducer (e.g., `Product`)
+4. **Read Model** → Query access (e.g., `ProductReadModel`)
+
+### Troubleshoot Issues
+
+The troubleshooting prompt helps your assistant diagnose common issues:
+
+- GraphQL schema not updating
+- Events not being reduced
+- Authorization errors
+- Entity not found errors
+
+## Available Resources
+
+| Resource | Description |
+|----------|-------------|
+| `magek://docs/index` | Index of all documentation topics |
+| `magek://docs/introduction` | Introduction to Magek |
+| `magek://docs/getting-started/*` | Installation and coding guides |
+| `magek://docs/architecture/*` | Commands, Events, Entities, Read Models |
+| `magek://docs/security/*` | Authentication and Authorization |
+| `magek://docs/features/*` | Error handling, Logging, Scheduling |
+| `magek://docs/advanced/*` | Testing, Migrations, Configuration |
+| `magek://cli/reference` | Complete CLI command reference |
+
+## Available Prompts
+
+| Prompt | Description |
+|--------|-------------|
+| `magek_cqrs_flow` | Step-by-step guide for implementing a feature |
+| `magek_troubleshoot` | Common issues and solutions |
+
+## Example Conversation
+
+Here's how you might interact with your AI assistant:
+
+> **You:** Create a user registration feature for my Magek app
+>
+> **Assistant:** I'll help you implement user registration using Magek's CQRS pattern. Let me create the command, event, entity, and read model...
+>
+> ```bash
+> npx magek new:command RegisterUser --fields email:string password:string name:string
+> npx magek new:event UserRegistered --fields userId:UUID email:string name:string
+> npx magek new:entity User --fields email:string name:string --reduces UserRegistered
+> npx magek new:read-model UserReadModel --fields email:string name:string --projects User:id
+> ```
+
+## Custom Documentation Path
+
+If you're developing Magek itself or want to use local documentation:
+
+```json
+{
+  "mcpServers": {
+    "magek": {
+      "command": "npx",
+      "args": ["-y", "@magek/mcp-server"],
+      "env": {
+        "MAGEK_DOCS_PATH": "./docs/content"
+      }
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+### MCP Server Not Found
+
+Make sure you have Node.js 22+ installed:
+
+```bash
+node -v
+# Should output v22.x.x or higher
+```
+
+### Documentation Not Loading
+
+The MCP server bundles documentation from the published package. If you need the latest docs, update the package:
+
+```bash
+npx -y @magek/mcp-server@latest
+```
+
+### Claude Code Can't Find Magek
+
+Verify the MCP server is configured:
+
+```bash
+claude mcp list
+```
+
+You should see `magek` in the list of configured servers.