ai-dev-system

# AI Dev MCP System Local system for development with AI agents. It provides MCP tools for repository context, knowledge base and skills, search, launching quality gates and verifiable task management. The server works over `stdio`: does not open a network port and does not require a remote MCP server. You need to connect to it not "model directly", but an MCP-compatible client, in which the model is selected: Codex, Cursor, Claude Desktop or Claude Code, VS Code with MCP, Gemini CLI/Code Assist or another MCP host. The same local configuration is available to all these clients. ## What's Included - Local MCP server on Node.js; - Knowledge base, project context and managed library of skills; - Hybrid search: SQLite FTS, sparse search and optional local BGE-M3; - Task lifecycle: `begin_task`, `checkpoint_task`, `verify_task`, `complete_task`; - Quality gate, security checks and Frontend QA with Playwright/Chromium; - Docker image for the team: without personal Vault, passwords, tokens, projects and task history. ## Requirements For Docker variant: - Docker Desktop (Windows/macOS) or Docker Engine with Compose v2 (Linux); - Docker must have access to the selected project folder. To run from sources, Node.js 24 and npm are additionally required. On Windows, you can use the bundled runtime Codex, described in [README server](ai-dev-mcp-server/README.md). ## One-Click Launch on Windows After `git clone`, open PowerShell in the clone root and run: ```powershell powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\bootstrap.ps1 ``` The script will create an isolated folder `AI-Dev-Projects` in the home directory, install Docker Desktop and Node.js 24 LTS via `winget` if they are not present, prepare and check the Docker image, and then add the local MCP server `ai-dev` to Codex, Cursor, Gemini, VS Code and Claude. For Windows, it also installs a copy of just the launcher in `C:\ProgramData\AI-Dev-System\run-mcp.ps1`: this eliminates encoding issues when the path to the clone contains Cyrillic characters. No projects, Vault, tokens or passwords are copied to this folder. For Claude Desktop, a compact `ClaudeMcpProxy.exe` is additionally created in the same folder. It responds to MCP initialization before launching Docker, so a short startup timeout of Claude is bypassed; then the entire exchange is transparently transferred to the local Docker container. The first launch must be performed **as an administrator**, only if Docker Desktop or Node.js are not yet installed: `winget` and Docker may request elevated rights. With Docker Desktop already installed, a regular PowerShell is sufficient. For a different folder with repositories and client selection: ```powershell powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\bootstrap.ps1 ` -ProjectPath "D:\Projects" ` -Clients "codex,cursor,vscode" ``` The path is stored only in the local settings of the selected clients. Tokens, passwords, contents of this folder or your profile are not recorded in Git. After executing, restart the required AI client. ## One-Click Launch on macOS and Linux After `git clone` in the repository root, run: ```bash sh ./bootstrap.sh ``` The script does not require Node.js on the host: to prepare the Docker context and configure MCP, it uses a temporary `node:24` container. By default, the working folder is created as `~/AI-Dev-Projects`. It is mounted into the MCP container as `/workspace`. So that Claude Desktop and other clients do not interrupt the slow cold start of Docker, bootstrap creates a service container `ai-dev-system-runtime-$(id -u)`. It runs without a network, with a read-only filesystem, without Linux capabilities and with `no-new-privileges`; access is granted only to the named volume of the system and the selected project folder. The MCP process itself is launched through a quick `docker exec`, and the launcher immediately completes the protocol initialization. The container automatically starts up after restarting Docker due to `restart=unless-stopped`. On macOS, pre-install and launch Docker Desktop. On Linux, if Docker is not present, you can run `sh ./bootstrap.sh --install-prerequisites`: the script uses `sudo` and supports `apt`, `dnf` and `pacman`. After adding the user to the `docker` group, you will need to log out and log in, then repeat the command. This is the only case when administrator rights are required. For a different projects folder and part of clients: ```bash sh ./bootstrap.sh --project-path "$HOME/Dev" --clients "codex,cursor,vscode" ``` A repeated launch of the same command safely updates only the managed runtime container. Named volume, indexes, knowledge base and project files are not deleted. You can check the runtime with the command: ```bash docker ps --filter "label=ai-dev.system.runtime=true" ``` ## Quick Start: Docker ### 1. Get the Image After the first publication of the team, replace `OWNER/REPOSITORY` with the GitHub owner and repository name: ```powershell docker pull ghcr.io/OWNER/REPOSITORY:latest ``` Or build the image from the repository clone: ```powershell cd ai-dev-mcp-server npm ci --ignore-scripts --no-audit --no-fund npm run docker:prepare npm run docker:audit npm run docker:build npm run docker:smoke -- --image ai-dev-system:local ``` The build always uses a temporary allowlist context `.docker/build-context`, not the repository root or Obsidian Vault. Do not change the Docker context to the Vault root. ### 2. Choose a Working Folder Create or select a folder in which only repositories that the agent is allowed to work with are located. For example, `C:\\Dev` on Windows or `$HOME/Dev` on macOS/Linux. This folder will be connected to the container as `/workspace`. Do not specify a personal Vault, the entire home folder, a folder with secrets or backups. ### 3. Check Local Launch Windows: ```powershell $env:AI_DEV_IMAGE = "ai-dev-system:local" $env:AI_DEV_PROJECT_PATH = "C:\\Dev" powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\\docker\\run-mcp.ps1 ``` macOS/Linux: ```bash export AI_DEV_IMAGE="ai-dev-system:local" export AI_DEV_PROJECT_PATH="$HOME/Dev" sh ./docker/run-mcp.sh ``` The process will wait for MCP messages at the standard input. This is the expected behavior: complete the check with `Ctrl+C`, then connect the launcher to the MCP client. ## Connecting to AI Agents In all cases, replace `C:\\ABSOLUTE\\PATH` with the absolute path to the clone of this repository, and `C:\\Dev` with the allowed folder with your projects. Do not add these values to Git. ### Codex Add to the user `config.toml`: ```toml [mcp_servers.ai-dev] command = "powershell.exe" args = ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "C:\\ABSOLUTE\\PATH\\docker\\run-mcp.ps1"] env = { AI_DEV_IMAGE = "ai-dev-system:local", AI_DEV_PROJECT_PATH = "C:\\Dev" } startup_timeout_sec = 120 tool_timeout_sec = 3600 ``` On macOS/Linux, use `command = "/bin/sh"`, and in `args` pass the absolute path to `docker/run-mcp.sh`. In `env`, also specify the name created by bootstrap: `AI_DEV_RUNTIME_CONTAINER = "ai-dev-system-runtime-UID"`, where `UID` returns `id -u`. The automatic installer does this itself. Restart Codex and check that the `ai-dev` server has appeared in the MCP tool list. ### Cursor, Claude Desktop, Claude Code and Gemini These clients use JSON with the `mcpServers` property. Add or merge the following block with their existing configuration: When running `bootstrap.ps1 -Clients claude`, the installer updates both local Claude files: `%USERPROFILE%\\.claude.json` for Claude Code and `%APPDATA%\\Claude\\claude_desktop_config.json` for Claude Desktop. Existing servers are saved, and the modified file receives a backup. For the Microsoft Store version of Claude, the installer also updates the isolated application profile in `%LOCALAPPDATA%\\Packages\\Claude_*`. On Windows, do not replace the automatically installed Claude configuration with the example below: it uses `C:\ProgramData\AI-Dev-System\ClaudeMcpProxy.exe` for a quick start of Docker-MCP. On macOS/Linux, bootstrap similarly saves `AI_DEV_RUNTIME_CONTAINER` in the configuration and connects a quick launcher; manual editing of Claude files after bootstrap is not required. ```json { "mcpServers": { "ai-dev": { "command": "powershell.exe", "args": [ "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "C:\\ABSOLUTE\\PATH\\docker\\run-mcp.ps1" ], "env": { "AI_DEV_IMAGE": "ai-dev-system:local", "AI_DEV_PROJECT_PATH": "C:\\Dev" } } } } ``` A ready minimal template without access to projects is located in [docker/mcp-config.example.json](docker/mcp-config.example.json). After changing the configuration, completely restart the client. In Claude Code and Gemini CLI, the configuration can be added via their own MCP management command, but the launch command and environment variables remain the same. Code Create `.vscode.json` in the specific working repository or add the same server to the user MCP VS Code: ```json { "servers": { -dev": { "type": "stdio", "command": "powershell.exe", "args": [ "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "C:\\ABPATH\\docker\\run-mcp.ps1" ], "env "AI_DEV_IMAGE": "ai-dev-system:local", "AI_DEV_PROJECT_PATH": "C:\\Dev" } } } } ``` Reload the VS Code window. Inside the container, the paths to mounted repositories start with `/workspace`; for example, use `/workspace/my-project` for `begin_task`. ## Working with the Agent 1. Open the required repository in the chosen MCP client. 2. Give the agent a specific task and path within `/workspace`. 3. For meaningful work, the agent runs `begin_task`, studies the formed context, and more than three selected skills. 4. After code, the agent fixes `checkpoint_task`, runs `verify and completes work through `complete_task` only with relevant evidence. to the agent: ```text Use the MCP server ai-dev. Start for /workspace/my-project: add export report in CSV, cover with tests, and run verify_task. ``` ## Local Data and Security The image contains only verified public seed: rules, prompts, quality gates, and runtime. It does: - passwords, tokens,`, keys, and user configurations personal Obsidian Vault, `.`, `.ai-dev`, Git history, and local caches; - `/Projects`, `02-knowledge/Task Runs`, indexes, logs, backup archives; - project sources and- BGE-M3 weights. Data created by the container is stored local Docker volume `ai-dev`. Updating the image does not overwrite this volume. By default, runs without a network, root, with a read-only root filesystem, without Linux capabilities, andno-new-privileges`. If the project really needs the internet during verification `AI_DEV_DOCKER_NETWORK=bridge` consciously only for such a## Docker Compose and B3 For Compose, copy/compose.local.example.yaml`docker/compose.local.yaml`, local `AI_DEV_PROJECT_PATH run: ```bash docker compose docker/compose.yaml -f docker/compose.local.yaml run -- ai-dev-mcp compose.local.yaml` and `docker` are ignored by they may contain local paths. For more accurate semantic search, you can variant with BGE-M3bash docker build --build-arg INSTALL_BGE_M3=1 ai-dev-system:bge .-context ``` Model weights are not embedded in the image. Mount folder through `AI_DEV_MODEL the launcher will connect it as `/models/bge-m## Publishing for the Team The-publish.yml](.github/workflows/docker-publish.yml) workflow privacy policy, rebuild allowlist context, runs the test publishes `linux64` and `linux/arm images to the GitHub with SBOM and provenance. first push: 1. package in GitHub and selectprivate/internal` for the team or `public`. 2. Ensure colleagues have permission to read GitHub Packages. 3 colleagues with the address `gh/OWNER/REPOSITORY:latest` and this README. 4. Each colleague specifies their local project folder through `AI_DEV_PROJECT_PATH`; foreign files do not get into the image and Git. ## Verification and Diagnostics Before releasing from `ai-dev-mcp-server`, execute: ```powershell npm run check npm run docker:prepare npm run docker:audit npm run docker:smoke -- --image ai-dev-system:local ``` For check of the entire```powershell ..\\scripts\\run-acceptance.ps1 ``` If Docker Desktop cannot download the with an active VPN or corporate configure the proxy/D Docker Desktop. Do not pass in Dockerfile, Git, build or project files. A image runs without internet access. Compose