# @cognisos/fabric-mcp The authenticated Cognisos Fabric `beta-candidate` combines the local Indexer and governed Fractal memory behind one account-gated MCP connector. Install a candidate version only after the release owner announces GO for that exact version. The `beta` and `latest` tags, hosted RSC/database rollout, and broader provider rollout are outside this local-tools candidate. The two local engines have distinct responsibilities: * the singleton Indexer builds and continuously refreshes a typed graph for one explicit project; and * Fractal provides governed local memory, recall, provenance, correction, and status tools from an immutable, checksum-bound runtime. An account is required. When no valid credential already exists, setup opens Cognisos in your browser so you can sign in or create an account. Returning users with a valid OS-keychain credential do not repeat browser sign-in. The credential is never written into MCP configuration or process arguments. ## Requirements * Node.js 20.18.1 or newer. * macOS (Apple Silicon or Intel) or Linux (x64 glibc, x64 musl, or ARM64). * On Linux, an unlocked Secret Service session (for example libsecret with `gnome-keyring-daemon`) is required for authenticated setup. Headless sessions without an OS keyring fail closed before browser sign-in. * A project containing a recognized marker such as `.git`, `package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `pom.xml`, or a Gradle build file. * At least one supported client: Claude Code, Claude Desktop, Cursor, or Codex. Windows helpers are build-validated, but the peer-authenticated local singleton is not enabled on Windows in this beta-candidate. WSL2 is best-effort and is not a release-qualified target for this candidate. A Windows-host browser may be unable to reach the Linux guest's `127.0.0.1` OAuth callback. A browser authorization page alone is not proof that setup completed: wait for setup to report success in the WSL terminal, then require `doctor` to pass. If the terminal keeps waiting or times out, the credential exchange did not complete; use native Linux or an isolated Linux VM for a qualified beta run. ## Install In a terminal, enter the project you want Fabric to understand, then run setup: ```bash cd /path/to/your/project npx -y @cognisos/fabric-mcp@beta-candidate setup ``` Setup uses the exact directory you are in. You do not need to copy its full path or run `pwd`. For automation or setup from another directory, pass `--project /path/to/your/project` explicitly. This beta supports multiple projects, but only one Fabric release line per OS user. Do not install stable and beta side by side in the same user profile. For version comparisons, use a separate OS user, VM, or container. Setup detects verified project/runtime ownership and fails closed instead of taking over an incompatible installation. Setup performs one coherent transaction: 1. signs in through Cognisos OAuth or validates the existing keychain session; 2. installs the exact embedded Liminal and Fractal runtime versions and verifies the platform archive digest; 3. starts or attaches the private singleton Indexer, completes the initial index, and proves its watcher and freshness state; 4. writes a private, hash-addressed connector wrapper that resolves the bearer from the OS keychain; and 5. atomically registers one `fabric` connector in every detected client. Any registration or final runtime-identity failure restores all prior config bytes. On macOS, setup and the AI client's first connector launch are separate Node processes, so Keychain may ask for access at both boundaries. The credential must never be pasted into a prompt or configuration file. `setup --local` is not a beta-candidate path. It is rejected because candidate tools require an authenticated Cognisos account. ## What you get The same connector exposes three tool families without duplicate names: * `fabric_*` for code graph search, slicing, impact, contracts, change history, staleness, debt, explanation, governance, and authoritative Indexer status; * `fractal_*` for governed memory status, continuity, recall, provenance, honest uncertainty, correction/demotion, and the product-profile operations shipped by the pinned Fractal engine; * `shared_fabric_status`, `shared_fabric_list`, and `shared_fabric_accept` for authenticated teammate-package readiness, ACL-visible inventory, and one explicit provenance-preserving import. Raw share/grant/revoke and arbitrary bundle/config operations remain operator-owned and are not model tools. Use `fabric_status` and `fractal_status` from your client to inspect each engine. Beta promotion requires an authoritative, signed product-runtime lease at startup and every bounded renewal. The gate warms the ordinary auth cache, revokes a real key, and then proves both engines deny it within the lease bound. An artifact that relies only on cached `whoami` validation is not eligible. Two different background processes may appear in status output: * the **Fabric Code Indexer daemon** is required; it indexes the project and keeps the graph fresh; and * the **Fractal background capture daemon** is optional and off by default. The required Fractal memory engine is available through the connector even when its optional background capture daemon reports `not_running`. That status alone does not mean setup failed. The Indexer graph and Fractal store remain on the user's machine. Authentication, approved telemetry, and existing Shared Fabric transport may contact Cognisos; project source is not uploaded by the local engines. ## Indexer storage recovery The Indexer limits both per-project and aggregate local storage growth. If `doctor` reports a storage failure, inspect the exact stores and quotas with: ```bash npx -y @cognisos/fabric-mcp@beta-candidate storage inspect ``` If a project index must be rebuilt, remove only its derived Indexer data with: ```bash npx -y @cognisos/fabric-mcp@beta-candidate storage cleanup --project . --yes npx -y @cognisos/fabric-mcp@beta-candidate setup ``` If the original project directory was moved or deleted, first copy its exact `store_id` from `storage inspect`, then use: ```bash npx -y @cognisos/fabric-mcp@beta-candidate storage cleanup --store-id --yes ``` `storage inspect` may also list older backups that are explicitly marked cleanup-eligible. Remove only one of those listed backups by its exact `backup_id`: ```bash npx -y @cognisos/fabric-mcp@beta-candidate storage cleanup --backup-id --yes ``` Project/store cleanup stops and verifies the Indexer bound to that exact project, preserves Fractal memory, and leaves a private empty store topology for setup to rebuild. Backup cleanup removes only the exact retained backup selected by `backup_id`; it does not stop a project daemon or change its active store. Do not use either cleanup routinely; use it only when `doctor` or support recommends it. The retained `indexer/v1/store/v2` predecessor used for rollback is not a cleanup-eligible backup and must not be removed manually. ## Sharing and dashboard acceptance Shared Fabric and See Your Memory are present for bounded candidate validation. Direct `liminal` or raw helper invocation is not a supported model path. The single authenticated connector exposes only the three curated teammate retrieval workflows above; explicit owner share/grant/revoke remains a controlled CLI workflow. Release qualification requires a clean-user acceptance run proving the connector path, deny/grant/import/recall/rehydrate/revoke semantics, and real dashboard data on the final signed bytes. Those capabilities are not implied merely by successful installation. ## Logout ```bash npx -y @cognisos/fabric-mcp@beta-candidate logout ``` Logout revokes the device key, removes the connector from supported clients, clears the keychain entry, and wipes the local Fabric directory. Use `--all-devices` only when you intend to revoke every device on the account. ## Security boundary The Indexer helper, private connector wrapper, keyring binding, and Fractal runtime are exact-version and digest verified. The singleton daemon is bound to one local user and store over a private peer-user Unix socket. Fractal is a required engine, not a best-effort add-on. Setup does not report success until both engines, the combined tool surface, and every required client registration are proven. ## License Licensed under either Apache-2.0 or MIT, at your option. See `LICENSE`, `LICENSE-APACHE`, and `LICENSE-MIT` in the package.