# jbv-sdlc MCP (TypeScript + Docker)

Remote MCP for `jbv_global` SDLC: create/resolve/entomb artifacts and **push straight to `main`**.

> Warning: direct `main` writes are dangerous. Protect with a strong `MCP_AUTH_TOKEN`,
> HTTPS, and ideally IP allowlist. Prefer a bot account with limited repo access.

## Why Docker

On Ubuntu 22.04 VPS Docker gives you:

- isolated Node 22 + git
- persistent clone in a volume
- simple restart (`restart: unless-stopped`)
- nginx on the host only proxies to `127.0.0.1:8080`

Compose layout: **one container** for MCP is enough. nginx stays on the host (certbot-friendly). Optional second container for nginx later if you want fully containerized TLS.

## Tools

| Tool | Action |
|------|--------|
| `sdlc_sync` | `git pull --ff-only` |
| `sdlc_next_id` | next free `ACTOR`/`ENT`/`EVT`/`UC`/`MOD`/`BT` |
| `sdlc_resolve` / `sdlc_get` / `sdlc_list` | read |
| `sdlc_create` | create markdown + commit + push `main` |
| `sdlc_create_uc` | UC with filename provenance; checks upstream ids live |
| `sdlc_entomb` | move to `obsolete/` + push |

Writes are locked (`proper-lockfile`) so two agents do not interleave pull/commit/push.

## Local dev

```bash
cd tools/sdlc-mcp
cp .env.example .env
# edit .env — GIT_REPO_URL, GIT_TOKEN, MCP_AUTH_TOKEN, REPO_DIR=./.data/repo
npm install
npm run dev
```

Health: `curl http://127.0.0.1:8080/healthz`

## VPS (Ubuntu 22.04)

```bash
# docker + compose plugin
sudo apt update && sudo apt install -y docker.io docker-compose-v2 nginx certbot python3-certbot-nginx
sudo usermod -aG docker $USER   # re-login

git clone <this-repo> /opt/jbv-global
cd /opt/jbv-global/tools/sdlc-mcp
cp .env.example .env
nano .env   # tokens, GIT_REPO_URL

docker compose up -d --build
curl -s http://127.0.0.1:8080/healthz
```

nginx:

```bash
sudo cp nginx/ra-mcp-7.skobeltsyn.com.conf.example /etc/nginx/sites-available/ra-mcp-7.skobeltsyn.com
sudo ln -s /etc/nginx/sites-available/ra-mcp-7.skobeltsyn.com /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d ra-mcp-7.skobeltsyn.com
```

## Cursor

`.cursor/mcp.json` (project or user):

```json
{
  "mcpServers": {
    "jbv-sdlc": {
      "url": "https://ra-mcp-7.skobeltsyn.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_AUTH_TOKEN"
      }
    }
  }
}
```

Reload Cursor → Tools & MCP → green status.

## GitHub token

Fine-grained PAT or classic with `contents:write` on `jbv-global`.  
Set as `GIT_TOKEN`. Commits appear as `GIT_USER_NAME` / `GIT_USER_EMAIL`.

## Pipeline law (enforced partially in code)

- new file only (no overwrite)
- UC requires live ACTOR/EVT/ENT
- paths only under `ALLOW_PREFIXES` (default `sdlc/`)
- id allocation by scanning filenames

Indexes (`README`, `TRACEABILITY`) are **not** auto-regenerated yet — ask the agent to update them in a follow-up or extend tools later.