devdb VS Code Extension

When developing or extending modules within the src/services/mcp/no-vscode/ directory, you must adhere to two critical constraints because these modules are consumed directly by an external Model Context Protocol (MCP) server running in its own process space:

1. No VS Code API Access: Do not attempt to access any VS Code APIs. The MCP server runs independently and does not have access to the VS Code runtime environment.
2. No Writing to STDOUT: Since the MCP server uses STDIO transport, you must not write to standard output (e.g., using console.log()). Doing so will interfere with the MCP protocol communication. For logging, follow the MCP server logging guidelines.

DevDB assigns a unique HTTP port to each project to facilitate communication between the MCP server and the local database connection.

• Port Range: Starts from 50001. If 50001 is occupied, it increments to 50002, 50003, etc.
• Persistence: Port assignments are mapped to the absolute projectRoot path in a JSON file. This ensures the same project gets the same port across VS Code restarts.
• Conflict Resolution: If an assigned port is occupied when you restart VS Code, the system silently finds the next available port and updates the mapping.
• Cleanup: Port mappings are removed from the JSON file when the extension is deactivated for that project.

To use DevDb, ensure your environment meets the following requirements:

• VS Code: Version 1.83 or newer.
• Database: A VS Code project using any of the supported databases.
• OS Support:
  • Linux: x64, arm64, arm, Alpine-x64 (Note: Ubuntu 20.04 and below are not supported).
  • macOS: Darwin-x64, Darwin-arm64 (Apple Silicon).
  • Windows: Win32-x64.

Use the ./boot.sh script to generate and run a Rails application with a pre-configured database. The script automatically creates a sample todo application and loads demo data. It also handles port discovery (starting from 3000) and cleans up resources when interrupted (Ctrl+C).

# Run with SQLite (default)
./boot.sh

# Run with MySQL
./boot.sh mysql

# Run with PostgreSQL
./boot.sh postgres

DevDb is a VS Code extension that auto-loads your database to aid development and debugging. To get started:

1. Ensure you are in a VS Code project using one of the supported databases.
2. Ensure your database is properly configured and accessible from your application code.
3. For zero-config environments, DevDb will automatically discover and auto-load your database.
4. Access your database by opening the DevDb view panel or using the keyboard shortcut.

For optimal development experience with Vue 3 and TypeScript, use VSCode with the following extensions installed:

1. Volar (Vue Language Features)
2. TypeScript Vue Plugin (Volar)

Important: Ensure that the Vetur extension is disabled to avoid conflicts.

DevDb provides specialized integration for Laravel developers:

Eloquent Model Code Lens

When viewing Eloquent models, you can use Code Lens to:

• View the underlying database table.
• Generate a factory for the model (pre-filled with real data from the table).

Query Explainer

Analyze MySQL query execution plans:

1. Open a Laravel PHP file containing a SQL query (Eloquent or DB facade).
2. Select the SQL query.
3. Click the Explain query Code Lens or select it from the context menu.
4. The explanation will open in your browser (integrates with MySQL Visual Explain).

DevDb exposes your database to AI-powered IDEs via the Model Context Protocol (MCP).

For Claude Code

1. Open your project in VS Code with DevDb active.
2. Click the hammer icon in the DevDb view to copy the server script path.
3. Add the MCP server via CLI:

claude mcp add --transport stdio devdb-mcp-server node "<paste-script-path-here>"

For VS Code-based IDEs (Cursor, Windsurf, Cline, etc.)

1. Click the hammer icon in the DevDb view to copy the MCP configuration JSON.
2. Open your IDE's MCP config file and paste the JSON under the appropriate key:
   • VS Code: .vscode/mcp.json
   • Cursor: ~/.cursor/mcp.json
   • Windsurf: ~/.codeium/windsurf/mcp_config.json

To use the boot system, ensure you have the following installed:

• Python 3.7+
• Docker (required if using MySQL or PostgreSQL)
• Django: If Django is missing, install it via pipx install django.

Use the following commands to set up the project and manage the development lifecycle:

• Install dependencies: npm install
• Start development server (Hot-Reload): npm run dev
• Build for production (Compile and Minify): npm run build

You can run component tests using Cypress. Use the dev variant to run in headed mode (with a browser UI) or the standard command for headless testing.

• Headed mode: npm run test:unit:dev
• Headless mode: npm run test:unit