Metadata-Version: 2.4
Name: flightdeck-connect
Version: 0.1.1
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"

# flightdeck-connect

The MCP rail for **NorthGate AI FlightDeck** — the governed multi-agent
engineering console. Provision governed MCP tools into the coding tools you
already use (Claude Code, Cursor, Codex), run governed agent lanes, and
verify signed evidence packs offline.

(Import package and console-script names retain the legacy `conductor`
naming — FlightDeck was formerly Conductor, and existing integrations are
never broken by a rename.)

After `pip install flightdeck-connect` you get:

- **`flightdeck-connect`** — detect the AI coding tools on this machine and
  idempotently provision the FlightDeck MCP server into each (Claude Code
  project `.mcp.json`, Cursor `mcp.json`, `codex mcp add`), profiled by task,
  chain-recording the provisioning when a board is given.

- **`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 flightdeck-connect
```

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.
