Metadata-Version: 2.4
Name: flightdeck-connect
Version: 0.3.1
Summary: The MCP rail for NorthGate AI FlightDeck - provision governed MCP tools into Claude Code, Cursor, Codex, and Kimi; 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.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: signature
Requires-Dist: cryptography; extra == "signature"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: setuptools>=68.0; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Dynamic: license-file

# 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, Kimi), 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`, Kimi
  `~/.kimi-code/mcp.json`), 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 **46 tools** (21 `conductor_*` + 25 `flightdeck_*`, scoped at
  runtime via `MCP_TOOL_SET=flightdeck|conductor|all`) to MCP-aware agent
  runtimes (Claude Code, Cursor, Codex, Kimi, 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. It
  always checks hashes + chain and reports the detached-signature state;
  install the optional `signature` extra to cryptographically verify an
  Ed25519 seal (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+.

For cryptographic verification of signed release packs:

```bash
pip install "flightdeck-connect[signature]"
```

Without that optional backend, a present signature is reported as
`unverified-no-lib` and the aggregate does not pass. Unsigned packs remain a
legitimate, explicit state.

To make a seal an *attribution* rather than a self-consistency check, pin the
signing key's fingerprint — see
[Trust anchor](#trust-anchor-who-signed-it) below.

## 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
# -> signature_status: verified | unsigned | untrusted-key |
#                      unverified-no-anchor | unverified-no-lib |
#                      broken | invalid
# -> Exit 0 only for clean verified or explicitly unsigned packs.
```

`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:/FlightDeck/Board"

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."
```

The board must be on a local-only filesystem path. FlightDeck refuses board
writes under OneDrive, Dropbox, Google Drive, iCloud, or Box because locks on
one machine cannot protect a second machine from forking the event chain.

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

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). If
`SHA256SUMS.sig` is present, it also checks the Ed25519 signature over the
exact `SHA256SUMS` bytes when the optional `cryptography` backend is
available. Invalid, broken, and unavailable signature checks produce a
non-clean aggregate and a specific state; they never pass from presence.

The state contract mirrors the embedded `audit-chain/verify.py` script that
ships inside every pack — `conductor verify` is the more convenient
hand-typed form and additionally refuses to summarize
`unverified-no-lib` as clean.

### Trust anchor (who signed it)

`trustflash_public_key.pem` ships **inside the pack**. A signature that checks
out against a key read from the artifact under examination proves only that the
pack is internally self-consistent: anyone who edits a pack can regenerate
`SHA256SUMS`, mint a fresh Ed25519 keypair, sign with it, and drop the new
public key in. The seal becomes an attribution only when the key is anchored
somewhere the pack cannot reach.

Pin the fingerprint(s) you trust — SHA-256 of the key's DER/SPKI bytes, hex,
comma/whitespace-separated, `sha256:` prefix optional:

```bash
export FLIGHTDECK_RELEASE_PACK_KEY_FINGERPRINTS=sha256:9f86d081...
conductor verify release.tar.gz
```

The same env var is read by FlightDeck Desktop's verifier
(`electron/releasePack.ts`), so a key you trust in one is trusted in both. A
list is supported so a signer rotation has an overlap window.

| Situation | State | Aggregate |
|---|---|---|
| key fingerprint matches an anchor, signature valid | `verified` | pass |
| key fingerprint matches no configured anchor | `untrusted-key` | **fail** |
| no anchor configured at all | `unverified-no-anchor` | **fail (incomplete)** |

**No anchor configured is deliberately not a pass.** A stock install ships
with no compiled-in anchor — the production signer's fingerprint has not been
published into this repo, and inventing one to make the check look finished
would be the fabrication this whole state family exists to prevent. Until you
pin a fingerprint, `conductor verify` tells you the seal is self-consistent and
unattributed, and exits non-zero. That is the honest reading, and it is
distinct from `untrusted-key`, which means the check ran and the key was
rejected.

The fingerprint of the key a pack actually carries is printed in the
`signature_errors` line for both states, so pinning is a copy-paste once you
have confirmed the key out of band.

## Privacy Policy

**Full policy: <https://ai-flightdeck.com/privacy>** — Northgate Strategic LLC,
effective 2026-07-31.

FlightDeck is local-first. The short version is the whole design:

- **Local board tools send nothing, anywhere.** Board reads, packet creation,
  signals, handoffs, workspace verification and HOLD records operate entirely
  on the board folder you choose at install. There is **no telemetry, no
  analytics, no crash reporting, no phone-home.** No identifier of you or your
  machine is collected.
- **Cloud tools are opt-in and inert by default.** The conductor-cloud tools
  appear only if you select the `all` tool set, and do nothing at all until you
  supply an enrollment token issued to you. Once enabled, each transmits
  exactly the data its description names — task packets, workflow events,
  evidence references — over HTTPS to your own tenant.
- **Your data is yours.** We do not sell or share it, and do not use it to
  train any model. Local data lives on your disk; delete it and it is gone.
  Tenant data leaves live systems within 30 days of deletion.
- **Subprocessors:** Cloudflare (site delivery) and Google Cloud (Conductor API
  hosting). Nothing else.

Which tools touch the network is not something you have to take on faith — it
is declared in each tool's annotations, and the board-scoped tools are marked
accordingly.

Access, export, deletion, or questions: contact details are on the policy page;
we respond within 30 days.

## 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.

## License and patents

Proprietary — free to install and run as distributed; see LICENSE. The
governed-engineering architecture is **U.S. patent pending** (incl. App.
No. 19/765,031).
