devkit-mcp

Custom MCP server that scaffolds and enforces a standard Next.js (App Router) + Supabase + OpenAI architecture.

Run (stdio)

Most MCP clients run local servers over stdio:

{
  "command": "npx",
  "args": ["-y", "devkit-mcp"]
}

Client configuration

This server is a stdio MCP server. Most clients support a config where you provide a command and args.

Codex CLI

Edit ~/.codex/config.toml and add a new mcp_servers entry:

[mcp_servers.devkit_mcp]
command = "npx"
args = ["-y", "devkit-mcp"]

If you want the tools to run against a specific project directory, add cwd:

[mcp_servers.devkit_mcp]
command = "npx"
args = ["-y", "devkit-mcp"]
cwd = "/absolute/path/to/your-nextjs-project"

Claude Desktop

Open your Claude Desktop config JSON and add an entry under mcpServers:

{
  "mcpServers": {
    "devkit-mcp": {
      "command": "npx",
      "args": ["-y", "devkit-mcp"]
    }
  }
}

Common config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\\Claude\\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Local development (point to your workspace build)

If you want to use the local code without publishing:

{
  "mcpServers": {
    "devkit-mcp-local": {
      "command": "node",
      "args": ["/absolute/path/to/devkit_mcp/dist/bin.js"]
    }
  }
}

Tools (MVP)

All tools return a common envelope:

• Success: { ok: true, ... }
• Failure: { ok: false, error: { code, message, details? }, ... }

scaffold_project

Input:

{ "name": "myapp", "packageManager": "pnpm", "dryRun": true }

Creates a minimal Next.js App Router project skeleton under ./myapp.

scaffold_feature

Input:

{ "feature": "deck", "withApi": true, "withUi": true, "dryRun": true }

Creates feature folders/files under:

• src/server/<feature>/
• app/api/<feature>/
• src/components/<feature>/ (optional)

generate_api_route

Input:

{ "route": "/api/deck/create", "method": "POST", "schemaName": "CreateDeck", "dryRun": true }

Creates:

• app/api/deck/create/route.ts
• src/server/deck/create.ts

generate_ai_route

Input:

{ "route": "/api/ai/suggest", "schemaName": "SuggestResult", "modelHint": "gpt-5.2", "dryRun": true }

Creates:

• app/api/ai/suggest/route.ts
• src/server/ai/suggest.ts
• Ensures src/server/openai/client.ts and src/env.ts exist.

generate_supabase_module

Input:

{ "table": "decks", "ownerColumn": "user_id", "withRls": true, "dryRun": true }

Creates:

• supabase/migrations/*_create_decks.sql
• src/server/supabase/decks.ts

check_conventions

Input:

{ "path": ".", "strict": true }

Reports violations for:

• Direct process.env.* usage outside src/env.ts
• API routes not using the standard response helpers
• Missing Zod validation in app/api/**/route.ts
• any usage (strict mode)