---
name: fluent-cli-mcp-cicd
description: Fluent CLI MCP and CI/CD operations guide. Use for configuring `fluent mcp server --stdio`, validating MCP connectivity, and applying safe module deployment patterns in automation pipelines. Triggers on "mcp cicd", "ci cd pipeline", "automation pipeline", "mcp server setup", "fluent mcp stdio".
user-invocable: true
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
argument-hint: [mcp|cicd] [--profile name] [--retailer ref]
cursor-tier: auto
---

# CLI MCP and CI/CD

Configure the official Fluent MCP server via CLI and apply guardrails for CI/CD module delivery.

> **New to Fluent CLI?** Start with `/fluent-cli-index` for a complete command reference and routing guide.

## When to Use

- User asks to enable `fluent mcp` in an IDE/client
- User asks for pipeline-safe deploy patterns
- User wants non-interactive validation before deploy

## MCP Setup via CLI

Validate commands first:

```bash
fluent mcp --help
fluent mcp server --help
```

Start the MCP server in stdio mode:

```bash
fluent mcp server --stdio --profile <profile-name>
```

If retailer context is required, set profile+retailer first:

```bash
fluent profile use <profile-name> --retailer <retailer-ref>
fluent profile active
```

## Pipeline Guardrails

Before deployment in CI:

1. Validate CLI and auth context.
2. Validate module package and config files exist.
3. Run dry diagnostics (`flow-run` without `--deploy`).
4. Require explicit confirmation flags before deploy.

Example:

```bash
npx @fluentcommerce/ai-skills flow-run \
  --profile <profile-name> \
  --retailer <retailer-ref> \
  --module dist/module.zip \
  --config config/module.config.json
```

Deploy only with explicit confirmation:

```bash
npx @fluentcommerce/ai-skills flow-run \
  --profile <profile-name> \
  --retailer <retailer-ref> \
  --module dist/module.zip \
  --config config/module.config.json \
  --deploy --yes
```

## CI/CD Pipeline Templates

### GitHub Actions

```yaml
name: Fluent Module Deploy
on:
  push:
    branches: [main]
    paths: ['plugins/**', 'resources/**']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Java
        uses: actions/setup-java@v4
        with: { distribution: temurin, java-version: 17 }

      - name: Setup Node
        uses: actions/setup-node@v4
        with: { node-version: 20 }

      - name: Install Fluent CLI
        # Install method: https://docs.fluentcommerce.com/building-blocks/fluent-cli-package
        run: echo "Replace with your org's Fluent CLI install step"

      - name: Create profile
        run: |
          fluent profile create deploy-target \
            --id ${{ secrets.FLUENT_ACCOUNT_ID }} \
            --base-url ${{ secrets.FLUENT_BASE_URL }} \
            --username ${{ secrets.FLUENT_USERNAME }} \
            --password ${{ secrets.FLUENT_PASSWORD }} \
            --client-secret ${{ secrets.FLUENT_CLIENT_SECRET }}

      - name: Build module
        run: cd plugins && mvn clean install -q

      - name: Pre-deploy diagnostics
        run: |
          npx @fluentcommerce/ai-skills flow-run \
            --profile deploy-target \
            --retailer ${{ vars.RETAILER_REF }} \
            --module dist/module.zip

      - name: Deploy module
        run: |
          fluent module install dist/module.zip \
            -p deploy-target \
            -r ${{ vars.RETAILER_REF }}
```

### GitLab CI

```yaml
fluent-deploy:
  image: node:20
  stage: deploy
  only:
    changes: [plugins/**, resources/**]
  before_script:
    # Install method: https://docs.fluentcommerce.com/building-blocks/fluent-cli-package
    - echo "Replace with your org's Fluent CLI install step"
    - apt-get update && apt-get install -y maven
  script:
    - fluent profile create deploy-target --id $FLUENT_ACCOUNT_ID --base-url $FLUENT_BASE_URL --username $FLUENT_USERNAME --password $FLUENT_PASSWORD --client-secret $FLUENT_CLIENT_SECRET
    - cd plugins && mvn clean install -q && cd ..
    - npx @fluentcommerce/ai-skills flow-run --profile deploy-target --retailer $RETAILER_REF --module dist/module.zip
    - fluent module install dist/module.zip -p deploy-target -r $RETAILER_REF
```

**Key principles:**
- Never store credentials in pipeline files — use CI/CD secrets/variables
- Always run `flow-run` (diagnostics) before `module install` (deploy)
- Separate build and deploy stages for rollback granularity
- Use `--yes` flag only after diagnostics pass

## CI/CD Pipeline Template

Minimal GitHub Actions workflow for module validation and deployment:

```yaml
name: Fluent Deploy
on:
  push:
    branches: [main]
    paths: ['modules/**']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      # Install method: https://docs.fluentcommerce.com/building-blocks/fluent-cli-package
      - run: echo "Replace with your org's Fluent CLI install step"
      - name: Validate
        run: fluent module validate --path ${{ github.workspace }}/modules/$MODULE_NAME
      - name: Pre-deploy check
        run: |
          npx @fluentcommerce/ai-skills flow-run --profile $FLUENT_PROFILE --retailer $RETAILER_REF --check pre-deploy
      - name: Deploy (requires explicit approval)
        if: github.ref == 'refs/heads/main'
        run: |
          fluent module install --path ${{ github.workspace }}/modules/$MODULE_NAME -p $FLUENT_PROFILE -r $RETAILER_REF
    env:
      FLUENT_PROFILE: ${{ secrets.FLUENT_PROFILE }}
      RETAILER_REF: ${{ secrets.RETAILER_REF }}
      MODULE_NAME: ${{ vars.MODULE_NAME }}
```

Adapt for GitLab CI by replacing `jobs:` with `stages:` and `steps:` with `script:`. The key principle is: validate -> pre-deploy-check -> deploy, with explicit approval gates between stages.

## Troubleshooting

| Issue | Likely Cause | Fix |
|---|---|---|
| MCP server fails to start | Profile/auth invalid | Verify with `fluent profile active` and rerun |
| MCP tools unavailable in client | Client not reloaded or wrong config path | Reload client and confirm `.mcp.json` location |
| CI deploy blocked | Guardrails require confirmation | Add required flags only after diagnostics pass |
