@nexus-lab/create-mcp-server 0.1.1 → 0.3.0

package/templates/auth/tests/auth.test.ts

@@ -0,0 +1,171 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import jwt from "jsonwebtoken";
+
+// Set environment before importing modules
+const TEST_JWT_SECRET = "test-secret-for-unit-tests";
+const TEST_API_KEYS = "test-key-1,test-key-2";
+
+process.env.JWT_SECRET = TEST_JWT_SECRET;
+process.env.API_KEYS = TEST_API_KEYS;
+
+// Dynamic import to ensure env is set before module loads
+const { authMiddleware, generateToken } = await import("../src/auth.js");
+
+// Helper to create mock Express objects
+function createMockReq(headers: Record<string, string> = {}) {
+  return {
+    headers,
+    user: undefined,
+  } as any;
+}
+
+function createMockRes() {
+  const res: any = {
+    statusCode: 200,
+    body: null,
+    headers: {} as Record<string, string>,
+    status(code: number) {
+      res.statusCode = code;
+      return res;
+    },
+    json(data: any) {
+      res.body = data;
+      return res;
+    },
+    setHeader(key: string, value: string) {
+      res.headers[key] = value;
+      return res;
+    },
+  };
+  return res;
+}
+
+describe("API Key Authentication", () => {
+  it("should authenticate with a valid API key", () => {
+    const req = createMockReq({ "x-api-key": "test-key-1" });
+    const res = createMockRes();
+    const next = vi.fn();
+
+    authMiddleware(req, res, next);
+
+    expect(next).toHaveBeenCalledOnce();
+    expect(req.user).toBeDefined();
+    expect(req.user.authMethod).toBe("api-key");
+  });
+
+  it("should reject an invalid API key", () => {
+    const req = createMockReq({ "x-api-key": "invalid-key" });
+    const res = createMockRes();
+    const next = vi.fn();
+
+    authMiddleware(req, res, next);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(401);
+    expect(res.body.error).toBe("Invalid API key");
+  });
+
+  it("should reject an empty API key", () => {
+    const req = createMockReq({ "x-api-key": "" });
+    const res = createMockRes();
+    const next = vi.fn();
+
+    authMiddleware(req, res, next);
+
+    // Empty key falls through to "no credentials" path
+    expect(next).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(401);
+  });
+});
+
+describe("JWT Authentication", () => {
+  it("should authenticate with a valid JWT", () => {
+    const token = jwt.sign({ sub: "user-1", role: "admin" }, TEST_JWT_SECRET, {
+      expiresIn: "1h",
+    });
+    const req = createMockReq({ authorization: `Bearer ${token}` });
+    const res = createMockRes();
+    const next = vi.fn();
+
+    authMiddleware(req, res, next);
+
+    expect(next).toHaveBeenCalledOnce();
+    expect(req.user).toBeDefined();
+    expect(req.user.id).toBe("user-1");
+    expect(req.user.role).toBe("admin");
+    expect(req.user.authMethod).toBe("jwt");
+  });
+
+  it("should reject an expired JWT", () => {
+    const token = jwt.sign({ sub: "user-1" }, TEST_JWT_SECRET, {
+      expiresIn: "-1s",
+    });
+    const req = createMockReq({ authorization: `Bearer ${token}` });
+    const res = createMockRes();
+    const next = vi.fn();
+
+    authMiddleware(req, res, next);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(401);
+    expect(res.body.error).toBe("Token has expired");
+  });
+
+  it("should reject a JWT signed with wrong secret", () => {
+    const token = jwt.sign({ sub: "user-1" }, "wrong-secret");
+    const req = createMockReq({ authorization: `Bearer ${token}` });
+    const res = createMockRes();
+    const next = vi.fn();
+
+    authMiddleware(req, res, next);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(401);
+    expect(res.body.error).toBe("Invalid token");
+  });
+
+  it("should reject an empty Bearer token", () => {
+    const req = createMockReq({ authorization: "Bearer " });
+    const res = createMockRes();
+    const next = vi.fn();
+
+    authMiddleware(req, res, next);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(401);
+    expect(res.body.error).toBe("Bearer token is empty");
+  });
+});
+
+describe("No Credentials", () => {
+  it("should return 401 with hint when no auth is provided", () => {
+    const req = createMockReq({});
+    const res = createMockRes();
+    const next = vi.fn();
+
+    authMiddleware(req, res, next);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(401);
+    expect(res.body.error).toBe("Authentication required");
+    expect(res.body.hint).toBeDefined();
+  });
+});
+
+describe("generateToken", () => {
+  it("should generate a valid JWT with correct claims", () => {
+    const token = generateToken("user-42", "admin", "1h");
+    const decoded = jwt.verify(token, TEST_JWT_SECRET) as jwt.JwtPayload;
+
+    expect(decoded.sub).toBe("user-42");
+    expect(decoded.role).toBe("admin");
+    expect(decoded.exp).toBeDefined();
+  });
+
+  it("should default to 'user' role", () => {
+    const token = generateToken("user-99");
+    const decoded = jwt.verify(token, TEST_JWT_SECRET) as jwt.JwtPayload;
+
+    expect(decoded.role).toBe("user");
+  });
+});

package/templates/auth/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/templates/auth/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: ["tests/**/*.test.ts"],
+    coverage: {
+      provider: "v8",
+      include: ["src/**/*.ts"],
+      exclude: ["src/index.ts"],
+    },
+  },
+});

package/templates/database/.env.example

@@ -0,0 +1 @@
+DATABASE_URL=./data.db

package/templates/database/README.md

@@ -0,0 +1,110 @@
+# MCP Server — Database Template
+
+A production-ready [Model Context Protocol](https://modelcontextprotocol.io/) server with built-in SQLite database connectivity, powered by [Drizzle ORM](https://orm.drizzle.team/).
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Copy environment config
+cp .env.example .env
+
+# Build the project
+npm run build
+
+# Start the server
+npm start
+```
+
+## Available Tools
+
+| Tool            | Description                                          |
+| --------------- | ---------------------------------------------------- |
+| `create-note`   | Create a new note with a title and optional content  |
+| `list-notes`    | List all notes, with optional search query filtering |
+| `get-note`      | Retrieve a single note by its ID                     |
+| `update-note`   | Update a note's title and/or content by ID           |
+| `delete-note`   | Delete a note by its ID                              |
+
+## Available Resources
+
+| URI            | Description                          |
+| -------------- | ------------------------------------ |
+| `notes://list` | All notes in the database as JSON    |
+| `db://schema`  | Database schema documentation        |
+
+## Configuration
+
+### Environment Variables
+
+| Variable       | Default      | Description                 |
+| -------------- | ------------ | --------------------------- |
+| `DATABASE_URL` | `./data.db`  | Path to the SQLite database |
+
+### Claude Desktop Integration
+
+Add this to your Claude Desktop config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "my-mcp-server": {
+      "command": "node",
+      "args": ["/absolute/path/to/dist/index.js"]
+    }
+  }
+}
+```
+
+## Database Management
+
+```bash
+# Generate migration files from schema changes
+npm run db:generate
+
+# Apply migrations
+npm run db:migrate
+
+# Open Drizzle Studio (visual DB browser)
+npm run db:studio
+```
+
+## Development
+
+```bash
+# Watch mode — recompiles on file changes
+npm run dev
+
+# Run tests
+npm test
+```
+
+## Extending the Schema
+
+1. Edit `src/schema.ts` to add new tables or columns.
+2. Run `npm run db:generate` to create a migration.
+3. Run `npm run db:migrate` to apply it.
+4. Add corresponding tools in `src/tools.ts` and resources in `src/resources.ts`.
+
+## Project Structure
+
+```
+├── src/
+│   ├── index.ts        # Entry point — server setup and transport
+│   ├── db.ts           # Database connection and initialization
+│   ├── schema.ts       # Drizzle ORM table definitions
+│   ├── tools.ts        # MCP tool handlers (CRUD)
+│   └── resources.ts    # MCP resource handlers
+├── tests/
+│   └── tools.test.ts   # CRUD operation tests
+├── drizzle.config.ts   # Drizzle Kit configuration
+├── vitest.config.ts    # Test runner configuration
+├── tsconfig.json       # TypeScript configuration
+└── package.json
+```
+
+## License
+
+MIT

package/templates/database/_gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+*.log
+.env
+*.db
+coverage/
+drizzle/

package/templates/database/drizzle.config.ts

@@ -0,0 +1,11 @@
+import "dotenv/config";
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+  schema: "./src/schema.ts",
+  out: "./drizzle",
+  dialect: "sqlite",
+  dbCredentials: {
+    url: process.env.DATABASE_URL ?? "./data.db",
+  },
+});

package/templates/database/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "my-mcp-server",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "MCP server with database connectivity powered by Drizzle ORM",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:studio": "drizzle-kit studio"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "better-sqlite3": "^11.8.1",
+    "dotenv": "^16.5.0",
+    "drizzle-orm": "^0.39.3",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.15.3",
+    "drizzle-kit": "^0.31.1",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.2"
+  }
+}

package/templates/database/src/db.ts

@@ -0,0 +1,51 @@
+import Database from "better-sqlite3";
+import { drizzle, BetterSQLite3Database } from "drizzle-orm/better-sqlite3";
+import * as schema from "./schema.js";
+
+const DATABASE_URL = process.env.DATABASE_URL ?? "./data.db";
+
+const sqlite = new Database(DATABASE_URL);
+
+// Enable WAL mode for better concurrent read performance
+sqlite.pragma("journal_mode = WAL");
+sqlite.pragma("foreign_keys = ON");
+
+export const db: BetterSQLite3Database<typeof schema> = drizzle(sqlite, {
+  schema,
+});
+
+/**
+ * Initialize the database by creating tables if they don't exist.
+ * Called once at server startup.
+ */
+export function setupDatabase(): void {
+  sqlite.exec(`
+    CREATE TABLE IF NOT EXISTS notes (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      title TEXT NOT NULL,
+      content TEXT NOT NULL DEFAULT '',
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+  `);
+}
+
+/**
+ * Create a database instance from a custom SQLite connection.
+ * Useful for testing with in-memory databases.
+ */
+export function createDatabase(
+  connection: Database.Database,
+): BetterSQLite3Database<typeof schema> {
+  connection.pragma("foreign_keys = ON");
+  connection.exec(`
+    CREATE TABLE IF NOT EXISTS notes (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      title TEXT NOT NULL,
+      content TEXT NOT NULL DEFAULT '',
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+  `);
+  return drizzle(connection, { schema });
+}

package/templates/database/src/index.ts

@@ -0,0 +1,30 @@
+import "dotenv/config";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { setupDatabase } from "./db.js";
+import { registerTools } from "./tools.js";
+import { registerResources } from "./resources.js";
+
+const server = new McpServer({
+  name: "my-mcp-server",
+  version: "0.1.0",
+});
+
+// Initialize the database (creates tables if they don't exist)
+setupDatabase();
+
+// Register all tools and resources
+registerTools(server);
+registerResources(server);
+
+// Start the server with stdio transport
+async function main(): Promise<void> {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("MCP server running on stdio");
+}
+
+main().catch((error: unknown) => {
+  console.error("Fatal error starting server:", error);
+  process.exit(1);
+});

package/templates/database/src/resources.ts

@@ -0,0 +1,68 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BetterSQLite3Database } from "drizzle-orm/better-sqlite3";
+import { db as defaultDb } from "./db.js";
+import { notes } from "./schema.js";
+import type * as schema from "./schema.js";
+
+type Db = BetterSQLite3Database<typeof schema>;
+
+/** Database schema description exposed as a resource. */
+const SCHEMA_DESCRIPTION = `# Database Schema
+
+## Table: notes
+
+| Column     | Type    | Constraints                         |
+|------------|---------|-------------------------------------|
+| id         | INTEGER | PRIMARY KEY, AUTOINCREMENT          |
+| title      | TEXT    | NOT NULL                            |
+| content    | TEXT    | NOT NULL, DEFAULT ''                |
+| created_at | TEXT    | NOT NULL, DEFAULT datetime('now')   |
+| updated_at | TEXT    | NOT NULL, DEFAULT datetime('now')   |
+
+### Notes
+- Timestamps are stored as ISO 8601 strings (SQLite has no native datetime type).
+- WAL journal mode is enabled for better concurrent read performance.
+- Foreign keys are enforced.
+`;
+
+/**
+ * Register all resources on the given MCP server.
+ * Accepts an optional database override for testing.
+ */
+export function registerResources(server: McpServer, database?: Db): void {
+  const db = database ?? defaultDb;
+
+  // ── notes://list ─────────────────────────────────────────────────────
+  server.resource("notes-list", "notes://list", {
+    description: "List all notes in the database as JSON",
+    mimeType: "application/json",
+  }, async () => {
+    const allNotes = db.select().from(notes).all();
+
+    return {
+      contents: [
+        {
+          uri: "notes://list",
+          mimeType: "application/json",
+          text: JSON.stringify(allNotes, null, 2),
+        },
+      ],
+    };
+  });
+
+  // ── db://schema ──────────────────────────────────────────────────────
+  server.resource("db-schema", "db://schema", {
+    description: "Database schema documentation",
+    mimeType: "text/markdown",
+  }, async () => {
+    return {
+      contents: [
+        {
+          uri: "db://schema",
+          mimeType: "text/markdown",
+          text: SCHEMA_DESCRIPTION,
+        },
+      ],
+    };
+  });
+}

package/templates/database/src/schema.ts

@@ -0,0 +1,26 @@
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+import { sql } from "drizzle-orm";
+
+/**
+ * Notes table — stores user notes with title, content, and timestamps.
+ *
+ * Timestamps are stored as ISO 8601 strings (SQLite has no native date type).
+ * Defaults are handled at the database level via SQL expressions.
+ */
+export const notes = sqliteTable("notes", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  title: text("title").notNull(),
+  content: text("content").notNull().default(""),
+  createdAt: text("created_at")
+    .notNull()
+    .default(sql`(datetime('now'))`),
+  updatedAt: text("updated_at")
+    .notNull()
+    .default(sql`(datetime('now'))`),
+});
+
+/** TypeScript type for a note row returned from the database. */
+export type Note = typeof notes.$inferSelect;
+
+/** TypeScript type for inserting a new note. */
+export type NewNote = typeof notes.$inferInsert;