# @cognisos/fabric-mcp The authenticated Cognisos Fabric `beta-candidate` combines the local Indexer and governed Fractal memory behind one account-gated MCP connector. 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 skip 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). Windows helpers are build-validated, but the peer-authenticated local singleton isn't enabled on Windows in this beta-candidate; see Troubleshooting for WSL2. * On Linux, an unlocked Secret Service session (for example libsecret with `gnome-keyring-daemon`) is required for authenticated setup. * A project containing a recognized marker such as `.git`, `package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `pom.xml`, or a Gradle build file. * A repository under 1.5 GB. * At least one supported client: Claude Code, Claude Desktop, Cursor, or Codex. ## 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 setup ``` Setup runs from the exact directory you're in, no need to pass a path or run `pwd`. For automation or setup from another directory, pass `--project /path/to/your/project` explicitly. In one step, setup signs you in, installs the pinned Fractal runtime, builds the initial project index, and registers one `fabric` connector in every client it detects. See Troubleshooting for what to do if registration or a Keychain prompt doesn't go as expected. ## 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. Run `fabric_status` and `fractal_status` from your client to inspect each engine. Two different background processes may appear in that 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, so seeing `not_running` there is expected, not a failure. The Indexer graph and Fractal store stay on your machine. Authentication, approved telemetry, and the Shared Fabric transport may contact Cognisos; your project source is never uploaded by the local engines. ## How agents use it The connector gives agents one workflow instead of a bag of unrelated tools: 1. check `fabric_status`, then use `fabric_query` to discover the relevant module, symbol, Markdown passage, or JSON value; 2. use `fabric_slice`, `fabric_impact`, `fabric_contracts`, or `fabric_explain` for relationships and bounded context; 3. use `fabric_text_search` for exact literals and line evidence; and 4. fall back to shell search only when Fabric is unavailable, explicitly incomplete, or doesn't support the file type. Setup and the watcher own initial and incremental indexing, so an agent never needs to call hidden lifecycle tools directly, this workflow is also published to compatible clients as server instructions. The Indexer builds structural graphs for its supported code languages, and also indexes `.md`, `.mdx`, and `.json` files through the same watcher and update lifecycle. Markdown/JSON are searchable as document modules and exact text, Fabric doesn't fabricate code symbols or relationships for them. Documents have a separate 4 MiB default size bound, and generated `package-lock.json`/`npm-shrinkwrap.json` files are excluded from document search. Broader document/media formats are separate future work. ## 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 storage inspect ``` To rebuild a project's index, remove only its derived Indexer data: ```bash npx -y @cognisos/fabric-mcp@beta storage cleanup --project . --yes npx -y @cognisos/fabric-mcp@beta setup ``` If the original project directory was moved or deleted, copy its exact `store_id` from `storage inspect` first, then: ```bash npx -y @cognisos/fabric-mcp@beta storage cleanup --store-id --yes ``` `storage inspect` may also list older backups explicitly marked cleanup-eligible. Remove one by its exact `backup_id`: ```bash npx -y @cognisos/fabric-mcp@beta storage cleanup --backup-id --yes ``` Project/store cleanup stops and verifies the Indexer bound to that project, preserves Fractal memory, and leaves an empty store for setup to rebuild. Backup cleanup removes only the selected backup; it doesn't stop a project daemon or change its active store. Use either only when `doctor` or support recommends it, the retained `indexer/v1/store/v2` predecessor used for rollback is not cleanup-eligible and must not be removed manually. ## Logout ```bash npx -y @cognisos/fabric-mcp@beta 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 and trust 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 doesn't report success until both engines, the combined tool surface, and every required client registration are proven. Shared Fabric and See Your Memory are present for bounded candidate validation. Direct `liminal` or raw helper invocation isn't a supported path, the single authenticated connector exposes only the three curated teammate retrieval workflows described above; explicit owner share/grant/revoke remains a controlled CLI workflow. ## License Licensed under either Apache-2.0 or MIT, at your option. See `LICENSE`, `LICENSE-APACHE`, and `LICENSE-MIT` in the package. ## Troubleshooting **WSL2** is best-effort, 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, so a browser authorization page alone isn't proof that setup completed. Wait for setup to report success in the WSL terminal, then confirm with `doctor`. If the terminal keeps waiting or times out, the credential exchange didn't complete, use native Linux or an isolated Linux VM for a qualified beta run instead. **One release line per OS user.** This beta supports multiple projects, but only one Fabric release line per OS user, don't 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. **Repeated Keychain prompts on macOS.** Setup and the AI client's first connector launch are separate Node processes, so Keychain may ask for access at both boundaries, that's expected. The credential must never be pasted into a prompt or configuration file. **`setup --local` is rejected.** It isn't a beta-candidate path, since candidate tools require an authenticated Cognisos account. **What one `setup` run actually does**, in order: it signs in through Cognisos OAuth (or validates an existing keychain session); installs the exact embedded Liminal and Fractal runtime versions and verifies the platform archive digest; starts or attaches the private singleton Indexer and proves its initial index, watcher, and freshness state; writes a private, hash-addressed connector wrapper that resolves the bearer from the OS keychain; then atomically registers one `fabric` connector in every detected client. Any registration or runtime-identity failure restores all prior config bytes. **Beta promotion gate.** Promotion to beta 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 proves both engines deny it within the lease bound; a build that relies only on cached `whoami` validation isn't eligible. Separately, release qualification for sharing 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 aren't implied merely by successful installation. Both are release-engineering gates, not something you need to think about as a user.