@donkeylabs/mcp 0.4.2 → 0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donkeylabs/mcp",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "MCP server for AI-assisted development with @donkeylabs/server",
   "type": "module",
   "main": "./src/server.ts",

package/src/server.ts

@@ -282,6 +282,13 @@ function findDocsDir(): string {
 const DOCS_DIR = findDocsDir();
 
 const RESOURCES = [
+  {
+    uri: "donkeylabs://docs/database",
+    name: "Database (Kysely)",
+    description: "Kysely queries, CRUD operations, joins, transactions, migrations",
+    mimeType: "text/markdown",
+    docFile: "database.md",
+  },
   {
     uri: "donkeylabs://docs/project-structure",
     name: "Project Structure",
@@ -939,6 +946,25 @@ async function getArchitectureGuidance(args: { task: string }): Promise<string>
 
   let guidance = `# Architecture Guidance\n\n**Task:** ${task}\n\n`;
 
+  // Always include the Plugin vs Route decision guidance
+  guidance += `## When to Create a Plugin vs Route\n\n`;
+  guidance += `**Core Principle:** Plugins = Reusable Business Logic | Routes = App-Specific API Endpoints\n\n`;
+  guidance += `### Create a Plugin when:\n`;
+  guidance += `- The logic could be **reused** across multiple routes or apps (auth, email, payments)\n`;
+  guidance += `- You need **database tables** for a domain concept (users, orders, products)\n`;
+  guidance += `- The functionality is **self-contained** with its own data and operations\n`;
+  guidance += `- You're building **cross-cutting concerns** like middleware\n\n`;
+  guidance += `### Create a Route when:\n`;
+  guidance += `- **Exposing plugin functionality** via HTTP (thin wrapper calling plugin methods)\n`;
+  guidance += `- **Combining multiple plugins** for a specific use case\n`;
+  guidance += `- Building **app-specific endpoints** that don't need reuse\n`;
+  guidance += `- **Simple operations** that don't warrant a full plugin\n\n`;
+  guidance += `### Workflow:\n`;
+  guidance += `1. Identify reusable domains → Create plugins with business logic\n`;
+  guidance += `2. Create routes that use plugins to expose functionality\n`;
+  guidance += `3. Keep routes thin - delegate to plugin service methods\n\n`;
+  guidance += `---\n\n`;
+
   // Pattern matching for common tasks
   if (taskLower.includes("auth") || taskLower.includes("login") || taskLower.includes("user")) {
     guidance += `## Recommended Approach: Authentication System\n\n`;
@@ -1073,10 +1099,11 @@ async function getArchitectureGuidance(args: { task: string }): Promise<string>
   }
 
   guidance += `\n## Documentation Resources\n`;
-  guidance += `- \`donkeylabs://docs/plugins\` - Plugin patterns\n`;
-  guidance += `- \`donkeylabs://docs/router\` - Route patterns\n`;
-  guidance += `- \`donkeylabs://docs/api-client\` - Client usage & generation\n`;
-  guidance += `- \`donkeylabs://docs/project-structure\` - Best practices\n`;
+  guidance += `- \`donkeylabs://docs/database\` - Kysely queries, CRUD, joins, transactions\n`;
+  guidance += `- \`donkeylabs://docs/plugins\` - Plugin patterns & When to Create a Plugin vs Route\n`;
+  guidance += `- \`donkeylabs://docs/router\` - Route patterns & best practices\n`;
+  guidance += `- \`donkeylabs://docs/api-client\` - Generated client usage\n`;
+  guidance += `- \`donkeylabs://docs/handlers\` - Class-based handlers\n`;
 
   return guidance;
 }
@@ -1153,7 +1180,9 @@ async function createPlugin(args: {
   // Build the createPlugin chain
   let createPluginChain = "createPlugin";
   if (hasSchema) {
-    createPluginChain += `\n  .withSchema<${toPascalCase(name)}Schema>()`;
+    // Note: DB type is auto-generated by kysely-codegen from migrations
+    // Use {} until `donkeylabs generate` creates schema.ts, then change to DB
+    createPluginChain += `\n  .withSchema<{}>() // Change to <DB> after running \`donkeylabs generate\``;
   }
   if (hasConfig) {
     createPluginChain += `\n  .withConfig<${toPascalCase(name)}Config>()`;
@@ -1162,11 +1191,14 @@ async function createPlugin(args: {
 
   // Generate imports
   let imports = `import { createPlugin } from "@donkeylabs/server";\n`;
+  imports += `import { z } from "zod";\n`;
   if (dependencies.length > 0) {
     imports += dependencies.map(d => `import { ${d}Plugin } from "../${d}";`).join("\n") + "\n";
   }
   if (hasSchema) {
-    imports += `import type { ${toPascalCase(name)}Schema } from "./schema";\n`;
+    // Note: schema.ts is auto-generated after running `donkeylabs generate`
+    // Once generated, uncomment this import:
+    imports += `// import type { DB } from "./schema"; // Uncomment after running \`donkeylabs generate\`\n`;
   }
 
   // Generate config interface if needed
@@ -1224,43 +1256,36 @@ ${ctxComment}
 
   await Bun.write(join(pluginDir, "index.ts"), indexContent);
 
-  // Create schema and migrations if needed
+  // Create migrations folder if plugin has schema
+  // Note: schema.ts is auto-generated by `donkeylabs generate` from migrations
   if (hasSchema) {
     mkdirSync(join(pluginDir, "migrations"), { recursive: true });
 
-    const schemaContent = `// Database schema types for ${name} plugin
-// Run 'donkeylabs generate' after adding migrations to generate types
+    const migrationContent = `import { Kysely, sql } from "kysely";
 
-export interface ${toPascalCase(name)}Schema {
-  // Tables will be generated here
+/**
+ * Migration: 001_initial
+ * Created: ${new Date().toISOString()}
+ * Plugin: ${name}
+ */
+
+export async function up(db: Kysely<any>): Promise<void> {
+  // Create your tables here
   // Example:
-  // ${name}: {
-  //   id: Generated<number>;
-  //   name: string;
-  //   created_at: string;
-  // };
+  // await db.schema
+  //   .createTable("${name}")
+  //   .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+  //   .addColumn("name", "text", (col) => col.notNull())
+  //   .addColumn("created_at", "text", (col) => col.defaultTo(sql\`CURRENT_TIMESTAMP\`))
+  //   .execute();
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  // Drop your tables here
+  // await db.schema.dropTable("${name}").execute();
 }
 `;
-    await Bun.write(join(pluginDir, "schema.ts"), schemaContent);
-
-    const migrationContent = `-- Migration: 001_initial
--- Created: ${new Date().toISOString()}
--- Plugin: ${name}
-
--- UP
--- Add your CREATE TABLE statements here
--- Example:
--- CREATE TABLE ${name} (
---   id INTEGER PRIMARY KEY AUTOINCREMENT,
---   name TEXT NOT NULL,
---   created_at TEXT DEFAULT CURRENT_TIMESTAMP
--- );
-
--- DOWN
--- Add your DROP TABLE statements here
--- DROP TABLE IF EXISTS ${name};
-`;
-    await Bun.write(join(pluginDir, "migrations", "001_initial.sql"), migrationContent);
+    await Bun.write(join(pluginDir, "migrations", "001_initial.ts"), migrationContent);
   }
 
   // Build registration example based on plugin type
@@ -1401,25 +1426,35 @@ async function addMigration(args: {
     mkdirSync(migrationsDir, { recursive: true });
   }
 
-  // Find next migration number
+  // Find next migration number - check both .ts and .sql files for backwards compatibility
   const existing = readdirSync(migrationsDir)
-    .filter((f) => f.endsWith(".sql"))
+    .filter((f) => f.endsWith(".ts") || f.endsWith(".sql"))
     .map((f) => parseInt(f.split("_")[0], 10))
     .filter((n) => !isNaN(n));
 
   const nextNum = existing.length > 0 ? Math.max(...existing) + 1 : 1;
   const numStr = String(nextNum).padStart(3, "0");
-  const filename = `${numStr}_${migrationName}.sql`;
+  const filename = `${numStr}_${migrationName}.ts`;
+
+  // Escape backticks in SQL for template literal
+  const escapedUpSql = upSql.replace(/`/g, "\\`");
+  const escapedDownSql = (downSql || "").replace(/`/g, "\\`");
+
+  const content = `import { Kysely, sql } from "kysely";
 
-  const content = `-- Migration: ${numStr}_${migrationName}
--- Created: ${new Date().toISOString()}
--- Plugin: ${pluginName}
+/**
+ * Migration: ${numStr}_${migrationName}
+ * Created: ${new Date().toISOString()}
+ * Plugin: ${pluginName}
+ */
 
--- UP
-${upSql}
+export async function up(db: Kysely<any>): Promise<void> {
+  await sql\`${escapedUpSql}\`.execute(db);
+}
 
--- DOWN
-${downSql || "-- Add rollback SQL here"}
+export async function down(db: Kysely<any>): Promise<void> {
+  ${escapedDownSql ? `await sql\`${escapedDownSql}\`.execute(db);` : "// Add rollback logic here"}
+}
 `;
 
   await Bun.write(join(migrationsDir, filename), content);
@@ -1431,7 +1466,7 @@ ${downSql || "-- Add rollback SQL here"}
 
 ### Next Steps
 
-1. Review the migration SQL
+1. Review the migration
 2. Run \`donkeylabs generate\` to update schema types
 3. The migration will run automatically on server start
 
@@ -1589,7 +1624,7 @@ export class ${handlerClassName} implements Handler<Routes.${prefix}.${handlerNa
     this.ctx = ctx;
   }
 
-  async handle(input: Routes.${prefix}.${handlerName}["input"]): Promise<Routes.${prefix}.${handlerName}["output"]> {
+  async handle(input: Routes.${prefix}.${handlerName}.Input): Promise<Routes.${prefix}.${handlerName}.Output> {
     ${handler}
   }
 }