# GhostCrab CLI (`gcp`) and MCP client setup

> **Local dev workflow** (MindBrain sibling repo, vendor submodule, beta zip reinstall): see [`.cursor/skills/ghostcrab-mindbrain-dev/SKILL.md`](../../.cursor/skills/ghostcrab-mindbrain-dev/SKILL.md).

This document covers the **`gcp` / `ghostcrab` launchers** shipped with **`@mindflight/ghostcrab-personal-mcp`**, how to wire them into **Cursor**, **Claude Code**, and **Codex-style** setups, and how that relates to **`ghostcrab-skills`** (and similar starter kits).

## Package and binaries

- **npm package:** `@mindflight/ghostcrab-personal-mcp`
- **Binaries:**
  - **`gcp`** — full CLI (see [gcp-commands.md](../reference/gcp-commands.md))
  - **`ghostcrab`** — backward-compatible shim that runs the same path as **`gcp brain up`** / **`gcp serve`** (stdio MCP), so older client configs that invoke `ghostcrab` keep working.

Install globally (example):

```bash
pnpm add -g @mindflight/ghostcrab-personal-mcp
# or: npm install -g @mindflight/ghostcrab-personal-mcp
```

From a **local pack** (see `pnpm run pack:local` / `make local-pack`):

```bash
pnpm add file:/absolute/path/to/dist-pack/mindflight-ghostcrab-mcp-<version>.tgz
```

## `gcp` commands (summary)

Full JTBD-oriented reference: **[gcp-commands.md](../reference/gcp-commands.md)**.

| Job | Preferred command | Legacy (alias) |
|-----|-------------------|----------------|
| Start MindBrain + MCP on stdio | **`gcp brain up`** (shorthand: **`gcp up`**) | **`gcp serve`** |
| Create / list workspace | **`gcp brain workspace create`**, **`gcp brain workspace list`** | **`gcp init`**, (no `list` alias before) |
| Config file | **`gcp env` …** (`list`, `show`, `get`, `set`, `path`) | **`gcp config` …** |
| Ontologies (schema in DB) | **`gcp brain schema` …** | **`gcp ontologies` …** |
| Registry skills (agent capabilities) | **`gcp agent skills` …**; one-shot: **`gcp agent equip owner/name`** | **`gcp skills` …** |
| JSONL profile load | **`gcp brain load`** or **`gcp load`** | (same) |
| Corpus import / normalize / profile | **`gcp brain document <subcommand> …`** | (no legacy alias) |
| **`gcp --help`** | Full usage text. | |

**MCP clients should pass a start subcommand** (e.g. `brain`, `up`, or legacy `serve`), not bare `gcp` with no args, so the process stays on the MCP stdio contract.

### IDE integration (Cursor, Claude Code, Codex)

On **`gcp brain workspace create`** (alias **`gcp init`**) and explicit **`gcp brain up --install-skills`** (alias **`gcp serve --install-skills`**), GhostCrab can **copy default files** from a **`ghostcrab-skills`** checkout into the current project when it can resolve that tree:

| Resolution | |
|------------|--|
| **`GHOSTCRAB_SKILLS_ROOT`** | Absolute path to the folder that contains `cursor/`, `claude-code/`, `codex/`, and `shared/` |
| **Beside the npm package** | `<install-dir>/ghostcrab-skills` (shipped in the published root package) |

**Detection** (unless you override):

- **`GHOSTCRAB_IDE=cursor` \| `claude-code` \| `codex` \| `generic`**
- Or presence of **`.claude`**, **`.cursor`**, or **`.codex`** in the current working directory (and `CURSOR_*` env when spawned by Cursor)

**What gets installed**

| IDE | Files |
|-----|--------|
| **Cursor** | `cursor/skills/<skill>/` → `~/.cursor/skills/<skill>/` by default; `shared/` → `~/.cursor/skills/ghostcrab-shared/` and `.ghostcrab/skills/shared/` |
| **Claude Code** | `claude-code/skills/<skill>/` → `~/.claude/skills/<skill>/` by default; `shared/` → `~/.claude/skills/ghostcrab-shared/`; `claude-code/self-memory/CLAUDE.md` → `.ghostcrab/claude-self-memory.md` |
| **Codex** | `codex/skills/<skill>/` → `~/.codex/skills/<skill>/` by default; `shared/` → `~/.codex/skills/ghostcrab-shared/`, with `SKILL.md` links rewritten to `../ghostcrab-shared/` |
| **Generic** | `codex/skills/<skill>/` → `~/.agents/skills/<skill>/` by default; `shared/` → `~/.agents/skills/ghostcrab-shared/`; MCP JSON/TOML snippets are printed, not written |

Each install also writes `.ghostcrab/skills/installed.json`, `.ghostcrab/skills/README.md`, and `.ghostcrab/skills/current` (or `.ghostcrab/skills/current.txt` if the platform cannot create a symlink).

**Install / refresh**

- **`gcp brain setup <target>`** — installs skills globally by default; pass **`--skills-scope project`** for project-local skill roots
- **`gcp init`** / **`gcp brain workspace create`** — install matching IDE skill bundles project-locally when an IDE is detected
- **`gcp brain up --install-skills`** / **`gcp serve --install-skills`** — explicitly install matching IDE skill bundles project-locally during server startup
- **`GHOSTCRAB_SKIP_IDE_SKILLS=1`** — same globally
- **`gcp init … --force-skills`** — overwrite existing stubs (`brain up` / `serve` do not take `--force-skills`; use `init` or delete files first)

Messages from **`gcp brain up --install-skills`** / **`gcp serve --install-skills`** go to **stderr** (one or two lines) so stdio MCP stays clean.

### Environment variables (common)

See the root [README.md](../../README.md) for the full table. Typical SQLite defaults:

- `GHOSTCRAB_SQLITE_PATH` — SQLite file (default: `~/.ghostcrab/databases/ghostcrab.sqlite` unless overridden).
- `GHOSTCRAB_BACKEND_ADDR` / `GHOSTCRAB_MINDBRAIN_URL` — backend HTTP address (defaults documented in README).
- `GHOSTCRAB_BACKEND_BIN` — absolute path to a self-built `ghostcrab-backend` (overrides optionalDependency/prebuild resolution; useful after `pnpm run prebuild:local`).
- `GHOSTCRAB_DOCUMENT_ENGINE` — optional explicit path to the `ghostcrab-document` binary (otherwise resolved from the platform package, `prebuilds/`, or a local `zig build document-tool` output).

### Document import (`gcp brain document`)

Use **`gcp brain document`** for PDF/HTML normalization, deterministic ingest, LLM document profiling, enqueue/worker, taxonomy/facet vocabulary listing, and related MindBrain CLI flows. **Quit MCP / stop `ghostcrab-backend` first** so the SQLite file is not locked; the command probes `/health` and refuses to run if the backend is up unless you pass **`--force`**.

Database commands automatically receive **`--db`** matching your **`GHOSTCRAB_SQLITE_PATH`** or the user default `~/.ghostcrab/databases/ghostcrab.sqlite`; pass **`--db <path>`** for a project-local database or **`--default`** to make the user default explicit. **`--workspace`** / `-w` pins the logical `workspace_id` inside that SQLite file; it does not select the SQLite path. Run **`gcp brain document --help`** for examples. The dedicated runbook is [document-import.md](document-import.md). Full flag reference for subcommands such as `document-profile-worker` lives in the vendored MindBrain docs (`vendor/mindbrain/docs/document-profile.md` in this repo).

For controlled qualification setup, first run **`gcp brain document qualification-vocab-list --workspace-id <id> [--collection-id <id>]`** to list taxonomy IDs and facet IDs. The returned `taxonomies[].id` values are used with `--taxonomies`; the returned `facets[].id` values are used with `--facets`. Full LLM `document-qualify` support depends on the installed native document engine exposing that verb; verify with **`gcp brain document --help`** before relying on it.

## MCP configuration examples

Server name `ghostcrab` is conventional; keep it if you copy snippets from **`ghostcrab-skills`**.

The JSON examples in this section are for clients that explicitly read JSON MCP config, such as Cursor and OpenClaw-style clients. **Codex CLI is different:** do not paste these `mcpServers` blocks into Codex. Use `codex mcp add ...` or Codex TOML `[mcp_servers.<name>]` instead.

### Global install: recommended shape

```json
{
  "mcpServers": {
    "ghostcrab": {
      "command": "gcp",
      "args": ["brain", "up", "--workspace", "my-project"]
    }
  }
}
```

### Without global install (`pnpm dlx` / `npx`)

```json
{
  "mcpServers": {
    "ghostcrab": {
      "command": "pnpm",
      "args": ["dlx", "@mindflight/ghostcrab-personal-mcp@latest", "gcp", "brain", "up", "--workspace", "my-project"]
    }
  }
}
```

(Equivalent with `npx`/`npm exec` if you prefer.)

### Cursor

1. Add the MCP server using the JSON above (Cursor’s MCP UI or project/global MCP config, depending on your version).
2. For **selectable Cursor skills**, run `gcp brain setup cursor`: it installs the GhostCrab skill mirrors globally into `~/.cursor/skills/`. It does not install Cursor rules.

### Claude Code

1. Merge an **`mcpServers`** block like the examples above into your project **`.mcp.json`** (or the path Claude Code expects in your layout).
2. Run `gcp brain setup claude`: it installs the Claude Code on-demand skills into `~/.claude/skills/`, merges Claude settings, and writes `.ghostcrab/claude-self-memory.md` for optional root `CLAUDE.md` merge.

**Note:** Some checked-in **`ghostcrab-skills/claude-code/**/.mcp.json`** examples still reference older package names or PostgreSQL `DATABASE_URL`. This **SQLite** product uses **`gcp brain up`** (or legacy **`gcp serve`**) and the **`GHOSTCRAB_*`** variables from the root README; adjust env to match how you run MindBrain.

### Codex

Codex consumes **skills** from `$CODEX_HOME/skills` (default `~/.codex/skills`). `gcp brain setup codex` installs all GhostCrab mirrors under `~/.codex/skills/` and writes shared references under `~/.codex/skills/ghostcrab-shared/`.

Codex MCP wiring is **not** the JSON above. Use:

```bash
gcp brain setup codex
```

or the direct Codex CLI form:

```bash
codex mcp add ghostcrab-personal-mcp -- gcp brain up --workspace my-project
```

For a dedicated SQLite file:

```bash
codex mcp add --env GHOSTCRAB_EMBEDDINGS_MODE=disabled \
  "ghostcrab-personal-mcp story2doc" -- \
  /usr/bin/node /absolute/path/node_modules/@mindflight/ghostcrab-personal-mcp/bin/gcp.mjs \
  brain up --db /absolute/path/data/ghostcrab-story2doc-codex.sqlite
```

After changing Codex MCP config, start a new Codex session and check `/mcp`. Seeing the server registered with `codex mcp list` is only the config layer; tools appear in chat only after Codex starts the MCP process successfully for the active session.

**Dedicated guide:** [ghostcrab-skills/codex/README.md](../../ghostcrab-skills/codex/README.md).

### OpenClaw

OpenClaw uses the same **`mcpServers`** JSON shape; merge the block from **`ghostcrab-skills/openclaw/ghostcrab-memory/mcp.json`** (or the examples above) into the MCP config your OpenClaw build expects. Install **`ghostcrab-memory`** and optionally **`ghostcrab-epistemic-agent`** per OpenClaw’s skill/agent layout; use **`openclaw/scenarios/`** for rehearsal prompts.

**Dedicated guide:** [ghostcrab-skills/openclaw/README.md](../../ghostcrab-skills/openclaw/README.md).

---

## Are `ghostcrab-skills` (or a personal starter kit) inside the `.tgz` or the SQLite DB by default?

**Short answer:** the **npm tarball ships `ghostcrab-skills/`** and generated `bin/ide-skills/` bundles so **`gcp init`**, **`gcp brain workspace create`**, or explicit **`gcp brain up --install-skills`** / **`gcp serve --install-skills`** can install IDE skill bundles (Cursor / Claude Code / Codex / generic). That is separate from what gets loaded into the **SQLite database** (see below).

### What the **npm tarball** contains

The published package **`files`** list includes **`bin/`**, **`dist/`**, **`ghostcrab-skills/`**, operational **`docs/`** subsets, **`examples/`**, etc. It intentionally excludes generated blog-image resources and platform binaries from the root installer package. Override the skills tree with **`GHOSTCRAB_SKILLS_ROOT`**, or skip copying from init/workspace commands with **`GHOSTCRAB_SKIP_IDE_SKILLS=1`**.

### What **SQLite initialisation** loads

When the backend starts and initialises the database, it applies migrations and the **product bootstrap** (canonical facets, schemas, ontology seeds, product graph, agent bootstrap state, etc.) from the **runtime code** — **not** from the Markdown / SKILL.md / Cursor rule files under `ghostcrab-skills/`.

### What **`ghostcrab-skills`** is for

It is **client integration**: rules, prompts, demo profiles, and copies of Codex skills. **`gcp`** copies the right stubs into the **current project** when it detects the IDE (unless skipped). It is documented as **demo / onboarding** material; see **`ghostcrab-skills/README.md`** and **`ghostcrab-skills/GHOSTCRAB_INTEGRATION.md`** (product bootstrap vs demo seed ownership).

### Optional **demo profile** data in the DB

To load **scenario JSONL** into the MindBrain/PostgreSQL database GhostCrab uses, run the demo loader from a **checkout** of this repo (with dev deps):

```bash
# Profile id under ghostcrab-skills/shared/demo-profiles/<id>.jsonl
pnpm run demo:load -- --profile <profile-id>
```

By default it looks for a sibling **`../ghostcrab-skills`**; override with **`--skills-repo-root /path/to/ghostcrab-skills`**.

**Starter kit default seed** (aligned with **starter-kit-ghostcrab-perso** template layout, shipped in this repo under `examples/starterkit-perso/`):

```bash
pnpm run demo:load:starterkit
# same as: pnpm run demo:load -- --profile-file examples/starterkit-perso/starterkit-default.jsonl
```

You can also pass **`--profile-file /any/path/profile.jsonl`** for custom JSONL in the same format as other demo profiles.

### Registry skills / schema

The commands **`gcp agent skills` / `gcp skills`** and **`gcp brain schema` / `gcp ontologies`** manage **registry-backed** artifacts (pull/show/remove), not the static `ghostcrab-skills/` folder on disk. Treat registry content and the skills repo as **related but separate** paths.

---

## See also

- [gcp-commands.md](../reference/gcp-commands.md) — full JTBD command table
- Root [README.md](../../README.md) — install, env vars, SQLite vs PostgreSQL notes.
- [ghostcrab-skills/README.md](../../ghostcrab-skills/README.md) — integration layout and quick start.
- [ghostcrab-skills/GHOSTCRAB_INTEGRATION.md](../../ghostcrab-skills/GHOSTCRAB_INTEGRATION.md) — contract between product and skills repo.
- Local pack / install smoke: `pnpm run pack:local`, `pnpm run verify:local-install` (and Makefile targets `local-pack`, `verify-local-install`).
