@magek/mcp-server 0.0.8

package/README.md

@@ -0,0 +1,42 @@
+# @magek/mcp-server
+
+MCP server that enables AI coding assistants to build Magek applications. Provides documentation, CLI commands, and CQRS patterns to Claude Code, Codex CLI, and other MCP-compatible tools.
+
+## Quick Start
+
+**Claude Code:**
+```bash
+claude mcp add magek -- npx -y @magek/mcp-server
+```
+
+**Codex CLI** — add to `.codex/config.json`:
+```json
+{ "mcpServers": { "magek": { "command": "npx", "args": ["-y", "@magek/mcp-server"] } } }
+```
+
+**Other MCP tools** — add to your MCP configuration:
+```json
+{
+  "mcpServers": {
+    "magek": {
+      "command": "npx",
+      "args": ["-y", "@magek/mcp-server"]
+    }
+  }
+}
+```
+
+## What It Provides
+
+- **Documentation** — All Magek docs available as MCP resources (`magek://docs/*`)
+- **CLI Reference** — Complete scaffolding command reference (`magek://cli/reference`)
+- **CQRS Flow Prompt** — Step-by-step guide for implementing features
+- **Troubleshooting Prompt** — Common issues and solutions
+
+## Documentation
+
+Full documentation: [magek.ai/docs/getting-started/ai-coding-assistants](https://magek.ai/docs/getting-started/ai-coding-assistants)
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createMagekServer } from './server.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Resolve docs path - first check env var, then use bundled docs
+function resolveDocsPath() {
+    if (process.env.MAGEK_DOCS_PATH) {
+        return process.env.MAGEK_DOCS_PATH;
+    }
+    // When installed as a package, docs are in dist/../docs
+    const bundledDocsPath = join(__dirname, '..', 'docs');
+    return bundledDocsPath;
+}
+async function main() {
+    const docsPath = resolveDocsPath();
+    const server = createMagekServer({ docsPath });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error('Failed to start Magek MCP server:', error);
+    process.exit(1);
+});

package/dist/prompts/cqrs-flow.d.ts

@@ -0,0 +1,15 @@
+export declare const CQRS_FLOW_PROMPT_NAME = "magek_cqrs_flow";
+export declare const CQRS_FLOW_PROMPT_DESCRIPTION = "Complete guide for implementing a CQRS feature end-to-end in Magek";
+export interface CqrsFlowArguments {
+    feature: string;
+}
+export declare function getCqrsFlowPrompt(args: CqrsFlowArguments): string;
+export declare function getCqrsFlowPromptDefinition(): {
+    name: string;
+    description: string;
+    arguments: {
+        name: string;
+        description: string;
+        required: boolean;
+    }[];
+};

package/dist/prompts/cqrs-flow.js

@@ -0,0 +1,252 @@
+export const CQRS_FLOW_PROMPT_NAME = 'magek_cqrs_flow';
+export const CQRS_FLOW_PROMPT_DESCRIPTION = 'Complete guide for implementing a CQRS feature end-to-end in Magek';
+export function getCqrsFlowPrompt(args) {
+    const { feature } = args;
+    return `# Implementing "${feature}" in Magek
+
+Follow this guide to implement the "${feature}" feature using Magek's CQRS pattern.
+
+## Overview
+
+Magek follows the CQRS (Command Query Responsibility Segregation) pattern with Event Sourcing:
+
+\`\`\`
+Command → Event → Entity → Read Model
+   ↓         ↓        ↓          ↓
+User     Immutable  State    Query
+Intent    Facts    Reducer   Access
+\`\`\`
+
+## Step 1: Define the Command
+
+Commands represent user intent. Create a command that captures what the user wants to do.
+
+\`\`\`bash
+npx magek new:command <CommandName> --fields <field1:type1> <field2:type2>
+\`\`\`
+
+**Best Practices:**
+- Use imperative naming (Create, Update, Delete, Archive)
+- Include only the fields needed to perform the action
+- Commands should be named after what the user wants to do, not technical operations
+
+**Example for "${feature}":**
+\`\`\`typescript
+@Command({ authorize: 'all' })
+export class <CommandName> {
+  public constructor(
+    // Add fields that represent the command parameters
+    readonly field1: string,
+    readonly field2: number,
+  ) {}
+
+  public static async handle(
+    command: <CommandName>,
+    register: Register
+  ): Promise<void> {
+    // Validate the command
+    // Generate a unique ID for the entity
+    const entityId = UUID.generate()
+
+    // Register the event
+    register.events(new <EventName>(entityId, command.field1, command.field2))
+  }
+}
+\`\`\`
+
+## Step 2: Define the Event
+
+Events are immutable facts. They record what happened as a result of the command.
+
+\`\`\`bash
+npx magek new:event <EventName> --fields <field1:type1> <field2:type2>
+\`\`\`
+
+**Best Practices:**
+- Use past tense naming (Created, Updated, Deleted, Archived)
+- Include the entity ID and all data needed to reconstruct state
+- Events should be self-contained and meaningful
+
+**Example:**
+\`\`\`typescript
+@Event
+export class <EventName> {
+  public constructor(
+    readonly entityId: UUID,
+    readonly field1: string,
+    readonly field2: number,
+  ) {}
+
+  public entityID(): UUID {
+    return this.entityId
+  }
+}
+\`\`\`
+
+## Step 3: Define the Entity
+
+Entities maintain state by reducing events. They are the aggregate roots.
+
+\`\`\`bash
+npx magek new:entity <EntityName> --fields <field1:type1> <field2:type2> --reduces <EventName>
+\`\`\`
+
+**Best Practices:**
+- One entity per aggregate root
+- Entities should only contain state derived from events
+- Use the \`@Reduces\` decorator to specify which events affect this entity
+
+**Example:**
+\`\`\`typescript
+@Entity
+export class <EntityName> {
+  public constructor(
+    readonly id: UUID,
+    readonly field1: string,
+    readonly field2: number,
+  ) {}
+
+  @Reduces(<EventName>)
+  public static reduce<EventName>(
+    event: <EventName>,
+    currentEntity?: <EntityName>
+  ): <EntityName> {
+    return new <EntityName>(
+      event.entityId,
+      event.field1,
+      event.field2,
+    )
+  }
+}
+\`\`\`
+
+## Step 4: Define the Read Model
+
+Read models provide optimized query access to your data.
+
+\`\`\`bash
+npx magek new:read-model <ReadModelName> --fields <field1:type1> <field2:type2> --projects <EntityName>:id
+\`\`\`
+
+**Best Practices:**
+- Design read models for specific query use cases
+- Include only the fields needed for queries
+- You can have multiple read models projecting the same entity
+
+**Example:**
+\`\`\`typescript
+@ReadModel({
+  authorize: 'all'
+})
+export class <ReadModelName> {
+  public constructor(
+    readonly id: UUID,
+    readonly field1: string,
+    readonly field2: number,
+  ) {}
+
+  @Projects(<EntityName>, 'id')
+  public static project<EntityName>(
+    entity: <EntityName>,
+    currentReadModel?: <ReadModelName>
+  ): ProjectionResult<<ReadModelName>> {
+    return new <ReadModelName>(
+      entity.id,
+      entity.field1,
+      entity.field2,
+    )
+  }
+}
+\`\`\`
+
+## Step 5: (Optional) Add Event Handlers
+
+If your feature needs side effects (send emails, call APIs), add an event handler.
+
+\`\`\`bash
+npx magek new:event-handler <HandlerName> --event <EventName>
+\`\`\`
+
+**Example:**
+\`\`\`typescript
+@EventHandler(<EventName>)
+export class <HandlerName> {
+  public static async handle(event: <EventName>): Promise<void> {
+    // Perform side effects here
+    // e.g., send email, call external API, etc.
+  }
+}
+\`\`\`
+
+## Verification Checklist
+
+After implementing all components:
+
+1. ✅ Command validates input and registers events
+2. ✅ Event contains all data needed to reconstruct state
+3. ✅ Entity correctly reduces events to state
+4. ✅ Read model projects entity state for queries
+5. ✅ All files are registered in your application
+
+## Testing
+
+Run your Magek server and test via GraphQL:
+
+\`\`\`bash
+npx magek start
+\`\`\`
+
+Then test your mutation:
+\`\`\`graphql
+mutation {
+  <CommandName>(input: { field1: "value", field2: 123 })
+}
+\`\`\`
+
+And query:
+\`\`\`graphql
+query {
+  <ReadModelName>s {
+    id
+    field1
+    field2
+  }
+}
+\`\`\`
+
+## Common Patterns
+
+### Authorization
+Use the \`authorize\` option to control access:
+- \`'all'\` - Anyone can access
+- \`'authenticated'\` - Must be logged in
+- \`['admin']\` - Specific roles only
+
+### Validation
+Validate in the command handler before registering events:
+\`\`\`typescript
+if (!command.field1) {
+  throw new InvalidParameterError('field1 is required')
+}
+\`\`\`
+
+### Entity References
+Reference other entities using their UUID:
+\`\`\`typescript
+readonly relatedEntityId: UUID
+\`\`\`
+`;
+}
+export function getCqrsFlowPromptDefinition() {
+    return {
+        name: CQRS_FLOW_PROMPT_NAME,
+        description: CQRS_FLOW_PROMPT_DESCRIPTION,
+        arguments: [
+            {
+                name: 'feature',
+                description: 'The feature to implement (e.g., "Create Product", "User Registration")',
+                required: true,
+            },
+        ],
+    };
+}

package/dist/prompts/troubleshooting.d.ts

@@ -0,0 +1,15 @@
+export declare const TROUBLESHOOTING_PROMPT_NAME = "magek_troubleshoot";
+export declare const TROUBLESHOOTING_PROMPT_DESCRIPTION = "Common Magek issues and solutions";
+export interface TroubleshootingArguments {
+    issue?: string;
+}
+export declare function getTroubleshootingPrompt(args: TroubleshootingArguments): string;
+export declare function getTroubleshootingPromptDefinition(): {
+    name: string;
+    description: string;
+    arguments: {
+        name: string;
+        description: string;
+        required: boolean;
+    }[];
+};

package/dist/prompts/troubleshooting.js

@@ -0,0 +1,239 @@
+export const TROUBLESHOOTING_PROMPT_NAME = 'magek_troubleshoot';
+export const TROUBLESHOOTING_PROMPT_DESCRIPTION = 'Common Magek issues and solutions';
+export function getTroubleshootingPrompt(args) {
+    const { issue } = args;
+    const intro = issue
+        ? `# Troubleshooting: ${issue}\n\nHere are solutions for issues related to "${issue}":\n\n`
+        : '# Magek Troubleshooting Guide\n\nCommon issues and their solutions:\n\n';
+    return `${intro}## GraphQL Schema Issues
+
+### Schema not updating after adding new components
+
+**Symptoms:**
+- New commands/queries don't appear in GraphQL playground
+- Types are missing from schema
+
+**Solutions:**
+1. Make sure all components are exported from your main index file
+2. Restart the development server (\`npx magek start\`)
+3. Check that decorators are correctly applied (\`@Command\`, \`@Event\`, \`@Entity\`, \`@ReadModel\`)
+4. Verify imports are correct (no circular dependencies)
+
+\`\`\`typescript
+// src/index.ts - ensure all components are exported
+export * from './commands/CreateProduct'
+export * from './events/ProductCreated'
+export * from './entities/Product'
+export * from './read-models/ProductReadModel'
+\`\`\`
+
+---
+
+## Event Issues
+
+### Events not being reduced by Entity
+
+**Symptoms:**
+- Entity state doesn't update after command executes
+- Read model stays empty
+
+**Solutions:**
+1. Verify the \`@Reduces\` decorator references the correct event class
+2. Check that the event's \`entityID()\` method returns the correct ID
+3. Ensure the reduce method returns a new entity instance (not mutating)
+
+\`\`\`typescript
+@Entity
+export class Product {
+  // Make sure decorator references the actual event class
+  @Reduces(ProductCreated)  // ✅ Correct
+  @Reduces('ProductCreated') // ❌ Won't work
+  public static reduceProductCreated(event: ProductCreated): Product {
+    return new Product(event.entityId, event.name)
+  }
+}
+\`\`\`
+
+### Events registered but command returns error
+
+**Symptoms:**
+- Command throws error even though events were registered
+
+**Solutions:**
+1. Check for validation errors before registering events
+2. Ensure all event constructor parameters are provided
+3. Verify UUID generation is working
+
+---
+
+## Authorization Issues
+
+### "Unauthorized" error on commands/queries
+
+**Symptoms:**
+- 401 or 403 errors when executing mutations/queries
+- Works in playground but fails in app
+
+**Solutions:**
+1. Check the \`authorize\` option in decorators:
+   \`\`\`typescript
+   @Command({ authorize: 'all' })  // Public access
+   @Command({ authorize: 'authenticated' })  // Requires login
+   @Command({ authorize: ['admin'] })  // Requires admin role
+   \`\`\`
+
+2. If using authentication, ensure JWT token is valid
+3. Verify token is passed in Authorization header:
+   \`\`\`
+   Authorization: Bearer <token>
+   \`\`\`
+
+---
+
+## Read Model Issues
+
+### Read model not updating
+
+**Symptoms:**
+- Queries return stale data
+- Entity exists but read model is empty
+
+**Solutions:**
+1. Verify \`@Projects\` decorator is correct:
+   \`\`\`typescript
+   @Projects(Product, 'id')  // Must match entity and join key
+   public static projectProduct(entity: Product): ProductReadModel {
+     return new ProductReadModel(entity.id, entity.name)
+   }
+   \`\`\`
+
+2. Check the projection method returns the correct type
+3. Ensure the join key exists on the entity
+
+### Read model returns null for existing entity
+
+**Solutions:**
+1. Check if the entity ID matches what's used in the projection
+2. Verify the projection method handles all entity states
+3. Look for errors in the server logs
+
+---
+
+## Entity Issues
+
+### "Entity not found" errors
+
+**Symptoms:**
+- Commands that update existing entities fail
+- Entity lookup returns undefined
+
+**Solutions:**
+1. Verify the entity ID is correct (UUID format)
+2. Check that the entity has been created (initial event was processed)
+3. Use \`fetchEntityByID\` or \`fetchEntityByKey\` correctly:
+   \`\`\`typescript
+   const entity = await entityProvider.fetchEntityByID(Product, entityId)
+   if (!entity) {
+     throw new InvalidParameterError('Product not found')
+   }
+   \`\`\`
+
+---
+
+## Development Server Issues
+
+### Server won't start
+
+**Symptoms:**
+- Error on \`npx magek start\`
+- Port already in use
+
+**Solutions:**
+1. Check if another process is using port 3000:
+   \`\`\`bash
+   lsof -i :3000
+   kill -9 <PID>
+   \`\`\`
+
+2. Verify all dependencies are installed:
+   \`\`\`bash
+   npm install
+   \`\`\`
+
+3. Check for TypeScript compilation errors:
+   \`\`\`bash
+   npx tsc --noEmit
+   \`\`\`
+
+### Hot reload not working
+
+**Solutions:**
+1. Check file watcher limits (Linux):
+   \`\`\`bash
+   echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
+   sudo sysctl -p
+   \`\`\`
+
+2. Restart the development server
+
+---
+
+## Type Errors
+
+### TypeScript errors with decorators
+
+**Symptoms:**
+- "Unable to resolve signature" errors
+- "Experimental decorator" warnings
+
+**Solutions:**
+1. Ensure \`tsconfig.json\` has decorator support:
+   \`\`\`json
+   {
+     "compilerOptions": {
+       "experimentalDecorators": true,
+       "emitDecoratorMetadata": true
+     }
+   }
+   \`\`\`
+
+2. Make sure reflect-metadata is imported at the entry point
+
+---
+
+## Database/Persistence Issues
+
+### Data not persisting across restarts
+
+**Symptoms:**
+- All data lost when server restarts
+- Events not saved
+
+**Solutions:**
+1. Check database configuration in your environment
+2. Verify the event store adapter is correctly configured
+3. For development, NeDB stores data in \`.magek/\` directory
+
+---
+
+## Getting More Help
+
+1. **Read the documentation**: \`magek://docs/index\`
+2. **Check CLI reference**: \`magek://cli/reference\`
+3. **Enable debug logging**: Set \`MAGEK_LOG_LEVEL=debug\`
+4. **GitHub Issues**: https://github.com/theam/magek/issues
+`;
+}
+export function getTroubleshootingPromptDefinition() {
+    return {
+        name: TROUBLESHOOTING_PROMPT_NAME,
+        description: TROUBLESHOOTING_PROMPT_DESCRIPTION,
+        arguments: [
+            {
+                name: 'issue',
+                description: 'Specific issue description (optional, e.g., "GraphQL schema not updating")',
+                required: false,
+            },
+        ],
+    };
+}

package/dist/resources/cli-reference.d.ts

@@ -0,0 +1,13 @@
+export declare const CLI_REFERENCE_URI = "magek://cli/reference";
+export declare const CLI_REFERENCE_CONTENT = "# Magek CLI Commands\n\nComprehensive reference for all Magek CLI scaffolding commands. These commands generate TypeScript files following Magek conventions.\n\n## Scaffolding Commands\n\n### Create a Command\n\nCommands represent user intent that triggers events. They are the entry point for all write operations.\n\n```bash\nnpx magek new:command <Name> --fields field1:type1 field2:type2\n```\n\n**Example:**\n```bash\nnpx magek new:command CreateProduct --fields sku:string price:number description:string\n```\n\n**Available field types:** string, number, boolean, UUID, Date\n\n---\n\n### Create an Event\n\nEvents are immutable facts that happened in the system. They are the source of truth.\n\n```bash\nnpx magek new:event <Name> --fields field1:type1 field2:type2\n```\n\n**Example:**\n```bash\nnpx magek new:event ProductCreated --fields productId:UUID sku:string price:number\n```\n\n---\n\n### Create an Entity\n\nEntities (aggregate roots) maintain state from events. Use --reduces to specify which events the entity handles.\n\n```bash\nnpx magek new:entity <Name> --fields field1:type1 field2:type2 --reduces EventName\n```\n\n**Example:**\n```bash\nnpx magek new:entity Product --fields sku:string price:number inStock:boolean --reduces ProductCreated\n```\n\n---\n\n### Create a Read Model\n\nRead models are query-optimized projections. Use --projects to specify which entity to project.\n\n```bash\nnpx magek new:read-model <Name> --fields field1:type1 field2:type2 --projects Entity:joinKey\n```\n\n**Example:**\n```bash\nnpx magek new:read-model ProductReadModel --fields sku:string price:number name:string --projects Product:id\n```\n\n---\n\n### Create an Event Handler\n\nEvent handlers react to events and perform side effects (send emails, call external APIs, etc.).\n\n```bash\nnpx magek new:event-handler <Name> --event EventName\n```\n\n**Example:**\n```bash\nnpx magek new:event-handler SendWelcomeEmail --event UserRegistered\n```\n\n---\n\n### Create a Scheduled Command\n\nScheduled commands run on a cron schedule for recurring tasks.\n\n```bash\nnpx magek new:scheduled-command <Name>\n```\n\n**Example:**\n```bash\nnpx magek new:scheduled-command CleanupExpiredSessions\n```\n\n---\n\n### Create a Query\n\nQueries retrieve data from read models without side effects.\n\n```bash\nnpx magek new:query <Name> --fields field1:type1\n```\n\n**Example:**\n```bash\nnpx magek new:query GetProductBySku --fields sku:string\n```\n\n---\n\n### Create a Type\n\nCustom types for domain modeling.\n\n```bash\nnpx magek new:type <Name> --fields field1:type1 field2:type2\n```\n\n**Example:**\n```bash\nnpx magek new:type Money --fields amount:number currency:string\n```\n\n---\n\n## Project Initialization\n\n### Create a New Magek Project\n\n```bash\nnpx create-magek my-app\n```\n\nOr with pnpm:\n```bash\npnpm create magek my-app\n```\n\n---\n\n## Development Server\n\n### Start the Development Server\n\n```bash\nnpx magek start\n```\n\nThis starts:\n- GraphQL API at http://localhost:3000/graphql\n- GraphQL Playground for testing queries\n\n---\n\n## Field Type Reference\n\n| Type | Description | Example |\n|------|-------------|---------|\n| `string` | Text values | `name:string` |\n| `number` | Numeric values | `price:number` |\n| `boolean` | True/false values | `isActive:boolean` |\n| `UUID` | Unique identifiers | `productId:UUID` |\n| `Date` | Date/time values | `createdAt:Date` |\n\n## Tips for Claude Code\n\nWhen helping users scaffold Magek components:\n\n1. **Start with the Command** - This defines the user action\n2. **Create the Event** - This records what happened\n3. **Create the Entity** - This maintains the state\n4. **Create the Read Model** - This provides query access\n\nAlways use descriptive names that reflect the domain (e.g., `CreateOrder` not `Create`).\n";
+export interface CliReferenceResource {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+}
+export declare function getCliReferenceResource(): CliReferenceResource;
+export declare function readCliReference(): {
+    content: string;
+    mimeType: string;
+};