@magek/mcp-server 0.0.8

package/dist/resources/cli-reference.js

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

package/dist/resources/documentation.d.ts

@@ -0,0 +1,18 @@
+import type { DocsLoader } from '../utils/docs-loader.js';
+export interface DocumentationResource {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+}
+export declare class DocumentationResources {
+    private readonly docsLoader;
+    constructor(docsLoader: DocsLoader);
+    listResources(): Promise<DocumentationResource[]>;
+    readResource(uri: string): Promise<{
+        content: string;
+        mimeType: string;
+    }>;
+    private getIndex;
+    private organizeByCategory;
+}

package/dist/resources/documentation.js

@@ -0,0 +1,62 @@
+export class DocumentationResources {
+    docsLoader;
+    constructor(docsLoader) {
+        this.docsLoader = docsLoader;
+    }
+    async listResources() {
+        const documents = await this.docsLoader.loadIndex();
+        const resources = documents.map((doc) => ({
+            uri: doc.uri,
+            name: doc.title,
+            description: doc.description || `Magek documentation: ${doc.path}`,
+            mimeType: 'text/markdown',
+        }));
+        // Add the index resource
+        resources.unshift({
+            uri: 'magek://docs/index',
+            name: 'Documentation Index',
+            description: 'Index of all Magek documentation topics',
+            mimeType: 'application/json',
+        });
+        return resources;
+    }
+    async readResource(uri) {
+        if (uri === 'magek://docs/index') {
+            return this.getIndex();
+        }
+        const path = this.docsLoader.resolveUriToPath(uri);
+        if (!path) {
+            throw new Error(`Invalid resource URI: ${uri}`);
+        }
+        const content = await this.docsLoader.loadDocument(path);
+        return { content, mimeType: 'text/markdown' };
+    }
+    async getIndex() {
+        const documents = await this.docsLoader.loadIndex();
+        const index = {
+            description: 'Magek Documentation Index',
+            topics: this.organizeByCategory(documents),
+        };
+        return {
+            content: JSON.stringify(index, null, 2),
+            mimeType: 'application/json',
+        };
+    }
+    organizeByCategory(documents) {
+        const categories = {};
+        for (const doc of documents) {
+            // Extract category from path (e.g., "getting-started/installation.md" -> "getting-started")
+            const pathParts = doc.path.split('/');
+            const category = pathParts.length > 1 ? pathParts[0] : 'general';
+            if (!categories[category]) {
+                categories[category] = [];
+            }
+            categories[category].push({
+                title: doc.title,
+                uri: doc.uri,
+                description: doc.description,
+            });
+        }
+        return categories;
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,5 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+export interface MagekServerOptions {
+    docsPath: string;
+}
+export declare function createMagekServer(options: MagekServerOptions): Server;

package/dist/server.js

@@ -0,0 +1,127 @@
+import { createRequire } from 'node:module';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { DocsLoader } from './utils/docs-loader.js';
+const require = createRequire(import.meta.url);
+const packageJson = require('../package.json');
+import { DocumentationResources } from './resources/documentation.js';
+import { CLI_REFERENCE_URI, getCliReferenceResource, readCliReference, } from './resources/cli-reference.js';
+import { CQRS_FLOW_PROMPT_NAME, getCqrsFlowPrompt, getCqrsFlowPromptDefinition, } from './prompts/cqrs-flow.js';
+import { TROUBLESHOOTING_PROMPT_NAME, getTroubleshootingPrompt, getTroubleshootingPromptDefinition, } from './prompts/troubleshooting.js';
+export function createMagekServer(options) {
+    const { docsPath } = options;
+    const docsLoader = new DocsLoader(docsPath);
+    const docResources = new DocumentationResources(docsLoader);
+    const server = new Server({
+        name: 'magek',
+        version: packageJson.version,
+    }, {
+        capabilities: {
+            resources: {},
+            prompts: {},
+            tools: {},
+        },
+    });
+    // List resources handler
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        const resources = await docResources.listResources();
+        // Add CLI reference resource
+        resources.push(getCliReferenceResource());
+        return {
+            resources: resources.map((r) => ({
+                uri: r.uri,
+                name: r.name,
+                description: r.description,
+                mimeType: r.mimeType,
+            })),
+        };
+    });
+    // Read resource handler
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const { uri } = request.params;
+        // Handle CLI reference
+        if (uri === CLI_REFERENCE_URI) {
+            const { content, mimeType } = readCliReference();
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType,
+                        text: content,
+                    },
+                ],
+            };
+        }
+        // Handle documentation resources
+        if (uri.startsWith('magek://docs/')) {
+            const { content, mimeType } = await docResources.readResource(uri);
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType,
+                        text: content,
+                    },
+                ],
+            };
+        }
+        throw new Error(`Unknown resource: ${uri}`);
+    });
+    // List prompts handler
+    server.setRequestHandler(ListPromptsRequestSchema, async () => {
+        return {
+            prompts: [getCqrsFlowPromptDefinition(), getTroubleshootingPromptDefinition()],
+        };
+    });
+    // Get prompt handler
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        if (name === CQRS_FLOW_PROMPT_NAME) {
+            const feature = args?.feature;
+            if (!feature || typeof feature !== 'string') {
+                throw new Error('Required argument "feature" is missing');
+            }
+            return {
+                description: `CQRS implementation guide for: ${feature}`,
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: getCqrsFlowPrompt({ feature }),
+                        },
+                    },
+                ],
+            };
+        }
+        if (name === TROUBLESHOOTING_PROMPT_NAME) {
+            const issue = args?.issue;
+            return {
+                description: issue
+                    ? `Troubleshooting guide for: ${issue}`
+                    : 'General Magek troubleshooting guide',
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: getTroubleshootingPrompt({
+                                issue: typeof issue === 'string' ? issue : undefined,
+                            }),
+                        },
+                    },
+                ],
+            };
+        }
+        throw new Error(`Unknown prompt: ${name}`);
+    });
+    // List tools handler - no tools for now, just resources and prompts
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return { tools: [] };
+    });
+    // Call tool handler - no tools for now
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        throw new Error(`Unknown tool: ${request.params.name}`);
+    });
+    return server;
+}

package/dist/utils/docs-loader.d.ts

@@ -0,0 +1,19 @@
+export interface DocumentInfo {
+    uri: string;
+    path: string;
+    title: string;
+    description: string | null;
+}
+export interface DocsIndex {
+    documents: DocumentInfo[];
+}
+export declare class DocsLoader {
+    private readonly docsPath;
+    constructor(docsPath: string);
+    loadDocument(relativePath: string): Promise<string>;
+    loadIndex(): Promise<DocumentInfo[]>;
+    private scanDocuments;
+    private extractTitle;
+    private extractDescription;
+    resolveUriToPath(uri: string): string | null;
+}

package/dist/utils/docs-loader.js

@@ -0,0 +1,111 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, normalize, relative, resolve } from 'node:path';
+export class DocsLoader {
+    docsPath;
+    constructor(docsPath) {
+        this.docsPath = docsPath;
+    }
+    async loadDocument(relativePath) {
+        const fullPath = resolve(this.docsPath, relativePath);
+        const normalizedDocsPath = resolve(this.docsPath);
+        // Security: ensure the resolved path is within docsPath
+        if (!fullPath.startsWith(normalizedDocsPath + '/') && fullPath !== normalizedDocsPath) {
+            throw new Error(`Invalid path: ${relativePath}`);
+        }
+        if (!existsSync(fullPath)) {
+            throw new Error(`Document not found: ${relativePath}`);
+        }
+        return readFile(fullPath, 'utf-8');
+    }
+    async loadIndex() {
+        const indexPath = join(this.docsPath, 'docs-index.json');
+        if (existsSync(indexPath)) {
+            const content = await readFile(indexPath, 'utf-8');
+            return JSON.parse(content);
+        }
+        // Fallback: scan directory
+        return this.scanDocuments();
+    }
+    async scanDocuments(dir = this.docsPath, documents = []) {
+        if (!existsSync(dir)) {
+            return documents;
+        }
+        const entries = await readdir(dir);
+        for (const entry of entries) {
+            const fullPath = join(dir, entry);
+            const stats = await stat(fullPath);
+            if (stats.isDirectory()) {
+                await this.scanDocuments(fullPath, documents);
+            }
+            else if (entry.endsWith('.md')) {
+                const relativePath = relative(this.docsPath, fullPath);
+                const uri = relativePath.replace(/\.md$/, '').replace(/\\/g, '/');
+                const content = await readFile(fullPath, 'utf-8');
+                documents.push({
+                    uri: `magek://docs/${uri}`,
+                    path: relativePath.replace(/\\/g, '/'),
+                    title: this.extractTitle(content) || uri.split('/').pop() || uri,
+                    description: this.extractDescription(content),
+                });
+            }
+        }
+        return documents;
+    }
+    extractTitle(content) {
+        // Try to extract title from first H1 heading
+        const h1Match = content.match(/^#\s+(.+)$/m);
+        if (h1Match) {
+            return h1Match[1].trim();
+        }
+        // Try to extract from frontmatter title
+        const frontmatterMatch = content.match(/^---[\s\S]*?title:\s*['"]?([^'"\n]+)['"]?[\s\S]*?---/m);
+        if (frontmatterMatch) {
+            return frontmatterMatch[1].trim();
+        }
+        return null;
+    }
+    extractDescription(content) {
+        // Remove frontmatter
+        const contentWithoutFrontmatter = content.replace(/^---[\s\S]*?---\n*/m, '');
+        // Find first paragraph after H1
+        const lines = contentWithoutFrontmatter.split('\n');
+        let foundH1 = false;
+        let description = '';
+        for (const line of lines) {
+            if (line.startsWith('# ')) {
+                foundH1 = true;
+                continue;
+            }
+            if (foundH1 && line.trim() && !line.startsWith('#')) {
+                description = line.trim();
+                break;
+            }
+        }
+        // Truncate to reasonable length
+        if (description.length > 200) {
+            description = description.substring(0, 197) + '...';
+        }
+        return description || null;
+    }
+    resolveUriToPath(uri) {
+        // Convert magek://docs/getting-started/installation -> getting-started/installation.md
+        const match = uri.match(/^magek:\/\/docs\/(.+)$/);
+        if (!match) {
+            return null;
+        }
+        const pathSegment = match[1];
+        // Security: reject path traversal attempts and absolute paths
+        if (pathSegment.includes('..') ||
+            pathSegment.startsWith('/') ||
+            pathSegment.includes('\\')) {
+            return null;
+        }
+        // Normalize and verify it's a clean relative path
+        const normalized = normalize(pathSegment);
+        if (normalized.startsWith('..') || normalized.startsWith('/')) {
+            return null;
+        }
+        return `${normalized}.md`;
+    }
+}

package/docs/advanced/custom-templates.md

@@ -0,0 +1,96 @@
+---
+title: "Custom Templates"
+group: "Advanced"
+---
+
+# Customizing CLI resource templates
+
+You can change what the newly created Magek resources will contain by customizing the resource template files.
+
+To do this, you first need to publish the resource templates by running the `npx magek stub:publish` command. This will create a folder `stubs` in the root directory of the project, and it will contain all the resources that you can customize:
+
+```
+stubs/
+├─ command.stub
+├─ entity.stub
+├─ event.stub
+├─ event-handler.stub
+├─ read-model.stub
+├─ scheduled-command.stub
+└─ type.stub
+```
+
+After that, Magek CLI will start using your local templates instead of the default ones.
+Let's try this by adding a simple comment to the `type.stub` file.
+
+```
+// Look I am a comment that will now appear in every new type file 🐙
+export class {{{ name }}} {
+  public constructor(
+    {{#fields}}
+    public {{{name}}}: {{{type}}},
+    {{/fields}}
+  ) {}
+}
+```
+
+Now if you run `npx magek new:type CartItem --fields sku:string` command, you will get `common/cart-item.ts` file with following content:
+```typescript
+// Look I am a comment that will now appear in every new type file 🐙
+export class CartItem {
+  public constructor(
+      public sku: string,
+  ) {}
+}
+```
+
+You did it, we just updated our resource template file! Now when you run `npx magek new:type`, it will contain the comment you added earlier 🚀
+Of course, this is a simple example, and you may want to add new methods, import something, you name it!
+
+Here are some answers to questions you may have:
+
+#### QA
+
+**Can I have only one stub for a certain resource?**
+
+Yes! The resource generator will check if you have a custom template or it will use the default template
+
+**How can I keep up with new template updates?**
+
+1. Run `npx magek stub:publish --force` command
+2. Review changes
+3. Done!
+
+**Can I adjust the command template and leave the other resources as they are?**
+
+Yes. You can only have the `command.stub` file in the `/stubs` folder and customize it.
+The generator will use the default templates for the other resources.
+
+**How can I use the default templates again!?**
+
+Simply delete the `/stubs` folder or a specific resource file.
+
+**What are these strange name, #fields, etc. things????**
+
+These are the variables and sections used by the mustache.js templating engine.
+They allow us to dynamically generate new resources.
+
+**How do I use custom project templates?**
+
+Project creation now uses the modern `npm create` pattern instead of the CLI. You can use custom project templates in two ways:
+
+**From GitHub repositories:**
+```bash
+npm create magek@latest my-app -- --template user/custom-template
+```
+
+**From local filesystem:**
+```bash
+npm create magek@latest my-app -- --template ./path/to/local/template
+```
+
+The template should contain a Magek project structure with mustache placeholders like `{{PROJECT_NAME}}`, `{{description}}`, etc.
+
+**I have another question!**
+
+You can ask questions on our Discord channel or create discussion on Github.