Metadata-Version: 2.4
Name: flightdeck-connect
Version: 0.1.0
Summary: The MCP rail for NorthGate AI FlightDeck — provision governed MCP tools into Claude Code, Cursor, and Codex; run governed agent lanes; verify signed evidence packs offline.
Author-email: NorthGate Strategic LLC <support@northgatestrategic.com>
License: Proprietary
Project-URL: Homepage, https://ai-flightdeck.com
Project-URL: Company, https://airecai.com
Keywords: ai,agents,mcp,model-context-protocol,ai-flightdeck,evidence,verification,audit,conductor
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# conductor-cli

Agent CLI + Model Context Protocol server for **Conductor** — NorthGate's
AI-assisted-delivery governance substrate.

After `pip install conductor-cli` you get:

- **`conductor`** — a stdlib-only HTTP client for the `/v1/conductor/*` API.
- **`conductor-mcp`** — a stdio JSON-RPC Model Context Protocol server that
  exposes **34 tools** (21 `conductor_*` + 13 `flightdeck_*`, scoped at
  runtime via `MCP_TOOL_SET=flightdeck|conductor|all`) to MCP-aware agent
  runtimes (Claude Code, Cursor, Codex, VS Code agents). The `flightdeck_*`
  family implements the FlightDeck Agent Contract v1 loop —
  `get_handoff → read_exam → prepare_workspace → submit_return`.
- **`flightdeck-verify`** — standalone offline evidence-pack verifier
  (stdlib-only; exit 0/1/2; `--json`).
- **`flightdeck-gate`** — pre-merge git gate for verify-gated merges
  (chain walk + accept-gate conjuncts + reference-transaction guard).

## Install

```bash
pip install conductor-cli
```

Zero runtime dependencies (pure Python stdlib). Python 3.8+.

## Auth

The CLI authenticates one of two ways:

| Header | Env var | Source |
|---|---|---|
| `X-Agent-Token` | `CONDUCTOR_AGENT_TOKEN` | Service token issued by `/v1/conductor/projects/{id}/agent-tokens`. Preferred for agents. |
| `X-JWT-Token` | `CONDUCTOR_USER_JWT` | A standard TrustSHIELD access token. Fallback for humans. |

```bash
export CONDUCTOR_AGENT_TOKEN=cdtr_...
conductor whoami
```

## CLI quickstart

```bash
# Probe auth + caller mode
conductor whoami

# Project + task ops
conductor project list
conductor project create --name "TrustSHIELD Conductor delivery"
conductor task list --project <project-id>

# Workflow transition (Policy Mesh gated)
conductor transition TASK-0040 \
    --action submit_review --to-state review_ready \
    --actor-member-id <member-id> \
    --reason "tests pass, ruff clean" \
    --evidence gitlab_mr=https://gitlab.com/.../merge_requests/126

# Release pack — download + offline verify
conductor export --project <project-id> --out release.tar.gz
conductor verify release.tar.gz
# -> Exit 0 + "OK: pack integrity verified." == nothing tampered.
```

`conductor --help` lists every subcommand. `--json` on any command gives
machine-readable output for scripting; the default is friendly text.

## Local board mode

Local board mode is the zero-cloud bridge for IDEs. It operates directly on a
filesystem board folder:

```text
<Project Conductor folder>/queue/TASK-*.md
```

No `CONDUCTOR_AGENT_TOKEN` or `CONDUCTOR_USER_JWT` is required.

```bash
BOARD="C:/Users/ericg/OneDrive - NorthGate Strategic LLC/Project Conductor"

conductor --json local list --board "$BOARD"
conductor --json local list --board "$BOARD" --state READY
conductor --json local read TASK-0001 --board "$BOARD"
conductor local handoff TASK-0001 --board "$BOARD"
```

Create and update packets:

```bash
conductor --json local create \
  --board "$BOARD" \
  --title "Audit the installer handoff" \
  --objective "Verify artifacts and append evidence." \
  --owner Codex \
  --reviewer "Claude Code"

conductor --json local signal TASK-0001 \
  --board "$BOARD" \
  --state REVIEW_READY \
  --action submit_review \
  --verdict "Audit completed; report attached." \
  --next "Reviewer checks the evidence and accepts or requests changes."
```

## MCP server (Claude Code / Cursor / Codex)

The `conductor-mcp` script implements the Model Context Protocol
(2024-11-05) over stdio. Sample config snippets:

**Claude Code** (`~/.config/claude/claude_desktop_config.json` or project-
level `.mcp.json`):

```json
{
  "mcpServers": {
    "conductor": {
      "command": "conductor-mcp",
      "env": {
        "CONDUCTOR_AGENT_TOKEN": "cdtr_..."
      }
    }
  }
}
```

**Cursor** (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "conductor": {
      "command": "conductor-mcp",
      "env": {
        "CONDUCTOR_AGENT_TOKEN": "cdtr_..."
      }
    }
  }
}
```

After restart, the agent's tool list includes 21 `conductor_*` tools —
`conductor_project_list`, `conductor_transition`, `conductor_export`,
`conductor_verify`, plus local-board tools such as `conductor_local_list`
and `conductor_local_signal`. Tool-execution failures surface as
`isError: true` in the MCP response (per spec); protocol/transport
failures use the JSON-RPC error channel.

## Custom API endpoint

If you're targeting an environment other than the default
(`https://airec-api-dxol6hwotq-uk.a.run.app`):

```bash
export CONDUCTOR_API_BASE=https://your-conductor-api.example.com
# OR pass per-invocation:
conductor --api-base https://your-conductor-api.example.com whoami
```

## Offline pack verification

`conductor verify <pack.tar.gz>` works without API access. It extracts the
archive in a temp dir, walks `SHA256SUMS` to verify every file's hash, then
walks `audit-chain/chain.jsonl` to confirm per-tenant chain integrity
(monotonic `chain_position` + `prev_event_hash` threading). Either kind of
tampering surfaces a non-zero exit and a specific error.

The check is identical to the embedded `audit-chain/verify.py` script that
ships inside every pack — `conductor verify` is the more convenient
hand-typed form.

## Source

Mirror of `packages/api/src/conductor/{cli,mcp}.py` from the upstream
TrustSHIELD repo. See
[Conductor-Build-Plan-2026-05-23.md](https://gitlab.com/dcairecai-group/erics-workspace)
sections 4.2 + 5 for the full design.
