# Source: CHANGELOG.md URL: https://hela.my.id/library/CHANGELOG.html # Changelog All notable changes to this project. ## [1.6.2] - 2026-11-08 - Adopt the Dependabot-updated Plastid and Receptor lockfiles, clearing the open MCP SDK and `@hono/node-server` advisories. - Replace Plastid's `"@modelcontextprotocol/sdk": "latest"` with a caret range so future lock refreshes are reviewable instead of silent. - Plastid keeps 12 passing regressions and `npm audit` reports zero vulnerabilities; Receptor keeps 123 passing tests. - Cell versions and every other pin are unchanged from 1.6.1. ## [1.6.1] - 2026-11-08 - Add `setup.sh mode` to convert an existing managed installation between `individual`, `runtime`, `docker`, `docker-runtime`, and `nix` in place. - Reuse cells already built at the pinned revision, preserve `data/` and the profile/snapshot, and verify the converted installation with doctor before reporting success. - Restore the previous manifest and leave a pending marker when verification fails; refuse pending, unmanaged, or unchanged targets. - Cover host-family switching, transport guards, pending markers, and Docker round-trips in tests and CI. Enzyme, runtime, and other cell pins are unchanged from 1.6.0. ## [1.6.0] - 2026-11-08 - Pin Enzyme 4.0.0, whose `google_search` now requires `query`. The old `q` argument is rejected rather than translated; batch tools keep `queries`. - Share one strict search schema between Enzyme's shipped and modular entrypoints: trimmed non-empty queries, integer result counts from 1 to 10, unknown fields refused before any provider request. - Add `setup.sh mode` to convert a managed installation between individual, runtime, Docker, Docker-runtime, and Nix in place, reusing verified builds and preserving data directories. - Regenerate the canonical tool catalog and documentation from the new Enzyme schema. Tool counts and all other cell/runtime pins are unchanged. - Preserve every historical snapshot from v1.0.0 through v1.5.3. ## [1.5.3] - 2026-11-07 - Render Genome relation links in canonical order so replicas with different SQLite insertion orders produce identical notes. - Add an insertion-order regression; all 19 suites / 264 tests, the TypeScript build and zero-warning source lint pass. - Preserve the published 1.5.2 snapshot and all other cell/runtime pins. ## [1.5.2] - 2026-11-07 - Pin Genome's replicated vault timestamp/order convergence fix and explicit archived repair API; ordinary CLI sync still leaves divergent notes unresolved. - Replace Genome's unsafe `any` types with typed database results and validated request/import boundaries. Source lint now covers top-level files and fails on warnings; 19 suites / 263 tests and the TypeScript build pass. - Retain the managed individual/runtime/Docker/Nix installer and doctor shipped after 1.5.1; its mechanism acceptance remains documented separately. - Keep all other cell/runtime pins and historical versioned snapshots unchanged. No vault content, credentials, or operational backups are included in this source snapshot. ## [1.5.1] - 2026-11-06 - Refresh current EN/ID web pages, setup/integration/troubleshooting guides, and all ten cells' version/tool references from canonical metadata. - Validate generated documentation, local links/anchors, and browser configuration previews before Pages publication. - Refresh sanitized client examples and document deferred security, provider/hardware validation, SQLite safety, and optional Obsidian mirroring accurately. - Pin documentation-only cell commits in a new immutable snapshot. Cells remain 3.0.0; runtime remains 1.2.0. Historical snapshots, vendor versions, and live services are unchanged. ## [1.5.0] - 2026-11-06 - Pin runtime 1.2.0 with true first-call startup and profile/build/config-aware schema caching. - Generate standalone schema catalogs and documentation counts from canonical inventory metadata and isolated feature-variant probes. - Share inventory validation/path resolution across config, doctor, version, profile, and integration tooling; verify runtime catalog parity without child startup. - Measure cold/warm routing across all profiles; retain standalone compatibility and machine selections. ## [1.4.0] - 2026-11-06 - Pin current published cell/runtime revisions in a new snapshot; retain v1.0.0–v1.3.0 unchanged and correct runtime snapshot metadata to 1.1.0. - Include Genome memory safety, atomic claims, runtime timeout recovery, and clean-install Zod 4 compatibility fixes. - Replace process-alive smoke checks with isolated MCP initialize/tool discovery and strict version/pin agreement. - Correct Codex TOML to `mcp_servers`, escape generated values, and verify the 80-combination configuration matrix. - Record native x86_64/aarch64 Linux Nix builds separately from client authentication, hardware testing, and unresolved vault conflicts. ## [3.0.0] - 2026-10-31 ### Changed - **Version reset to 3.0.0** β€” per-server version metadata baseline reset (Phase 7). All `package.json`, MCP `ServerInfo.version`, and HTTP metadata now report `3.0.0`. This is a metadata/interface baseline reset; for `hela-plastid` it is not an upgrade from the previous `4.2.0` advert. --- # Source: CONTRIBUTING.md URL: https://hela.my.id/library/CONTRIBUTING.html # Contributing to the HeLa MCP Ecosystem Thank you for your interest in contributing to the **HeLa MCP Ecosystem**! This document provides guidelines and information for contributors and maintainers. ![Blotcat carefully placing a new, glowing building block on top of an established, complex structure](assets/blotcat-contributing.jpg) --- ## 1. Architectural Boundaries & 10-MCP Ceiling * **The 10-MCP Capability Ceiling**: The ecosystem maintains exactly 10 canonical MCP servers (7 core headless, 3 specialized GUI/device). Contributions focus on reliability, performance, tool quality, and testing rather than adding new server repositories. * **The 4-Tier Naming Architecture**: * Tier 1: Public Identity (`HeLa `, e.g. *HeLa Mitosis*, *HeLa Genome*) * Tier 2: Machine Identifier (`hela-*`, e.g. `hela-mitosis`, `hela-genome`) * Tier 3: Technical Source Repository (`chaining-mcp`, `project-mcp`, etc.) * Tier 4: Immutable Commit Hash (the selected immutable snapshot in `config/snapshots/`) * **Repository Autonomy**: Upstream repositories remain independent and modular. --- ## 2. Development & Verification Workflow ### 2.1 Local Environment Setup ```bash git clone https://github.com/Hela-Ecosystem/hela-mcp-ecosystem.git cd hela-mcp-ecosystem ./setup.sh --profile dev-workspace --client skip --non-interactive ``` ### 2.2 Running Diagnostics & Tests Before submitting changes, ensure all test suites pass locally: ```bash # 1. Run diagnostic health checks npm run doctor # 2. Run 80-combination client configuration checks npm run test:matrix # 3. Run standalone MCP integration (tool counts depend on features) npm test # 4. Keep generated versions, tool references and site metadata current npm ci --ignore-scripts npm run docs:generate npm run docs:check npm run test:docs # 5. Run configured pre-commit checks pre-commit run --all-files ``` ### 2.3 Build and preview the complete documentation site Use Node.js 22 LTS. Markdown rendering is a pinned build-only dependency; visitors receive static HTML, not a client-side Markdown framework. ```bash npm ci --ignore-scripts npm run docs:generate npm run docs:build python3 -m http.server 8080 --bind 127.0.0.1 --directory _site ``` Open `http://127.0.0.1:8080/library.html`. The builder publishes tracked root documentation, all Markdown under `docs/` (except website source files), the license, and public configuration examples. Add new documents to Git before building so they enter the publication inventory. Untracked notes, credentials, databases, Git internals and unrelated directories are not published. The document bodies remain in their source language; English and Indonesian navigation lead to the same source content. Dated verification reports are labeled historical. Relative document links, heading anchors and illustrations resolve within the website; original source downloads and `llms-full.txt` are generated from the same files. `npm run test:docs` checks publication coverage, links and anchors, safe Markdown rendering, source downloads, search, and deterministic builds. The existing Pages workflow installs the locked dependencies, checks the docs, and publishes `_site` to `gh-pages` when public documentation changes. Do not edit `_site` by hand. --- ## 3. Pull Request Guidelines 1. **Target Branch**: Target the maintained default branch (`master`) unless a maintainer requests a release/development branch. 2. **Commit Conventions**: Follow standard Conventional Commits: * `feat(scope): ...` * `fix(scope): ...` * `docs(scope): ...` * `test(scope): ...` * `chore(scope): ...` 3. **CI Matrix Conformance**: Configuration checks cover `ubuntu-latest` and `macos-latest` on Node.js 18, 20, and 22; documentation builds and tests run on Node 22. This is not MCP runtime compatibility evidence for Node 18; use Node 22 LTS for the tested full-stack development environment. Hardware, provider and authenticated GUI integrations need separate validation. --- ## 4. Attribution & Recognition The HeLa project respectfully recognizes **Henrietta Lacks** and the enduring scientific legacy of HeLa cells as an inspiration for immortal, modular cellular architecture in software. --- # Source: LICENSE URL: https://hela.my.id/library/LICENSE.html MIT License Copyright (c) 2026 Azzar Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. --- This license applies to the AZZAR MCP Server Suite repository and its contents. Individual MCP servers maintain their own licenses. Please check each server's repository for specific licensing information. --- # Source: README.md URL: https://hela.my.id/library/README.html # HeLa MCP Ecosystem A modular, immortal cellular AI tooling ecosystem built on the Model Context Protocol (MCP), engineered by Azzar to equip AI agents with full-spectrum autonomous capabilities across reasoning, persistent memory, workspace management, system execution, research, design, device automation, and 3D modeling. > **New to MCP?** Read the **[Beginner's Guide](docs/beginner-guide.md)** for requirements, profile selection, installation, and verification. **Read all documentation on the website:** [Document library](https://hela.my.id/library.html) Β· [Navigasi Bahasa Indonesia](https://hela.my.id/id/library.html). Guides, release history, contribution rules, and verification reports are published in full, with search and source downloads. Documents retain their source language. Current source snapshot: **v1.6.2**, with runtime **1.2.0**. True first-call startup, fingerprinted discovery caches, canonical inventory tooling, and all-profile checks are implemented; see [on-demand runtime](docs/on-demand-runtime.md). Authenticated Zed/Codex ACP sessions, hardware integrations, and live vault conflict resolution remain separate; see [release notes](RELEASE_NOTES.md). ![Blotcat plugging MCP server cables into the central AI Hub](assets/blotcat-hero.jpg) --- ## Respectful Attribution & Metaphor The **HeLa MCP Ecosystem** is named in respectful recognition of **Henrietta Lacks** (1920–1951) and the immortal scientific legacy of HeLa cells, which transformed global biomedical research. In this software architecture, HeLa serves as a **cellular biology metaphor**: * **Cellular Modularity**: Just as biological cells contain specialized organelles coordinated by the nucleus and genome, the HeLa MCP Ecosystem deploys specialized tool servers coordinated by a dual backbone. * **Continuous Replicability & Immortality**: Environments can be snapshot-pinned, reproduced deterministically on any machine, and restored cleanly without state degradation. * **Component Independence**: Underlying repositories, technical package names, and Git commit histories remain autonomous and unaltered while functioning as a harmonious organism. --- ## Dual-Backbone Architecture Every profile in the HeLa ecosystem is anchored by two core backbone servers: ```mermaid flowchart TB Agent["Agent / LLM Orchestrator"] Mitosis["HeLa Mitosis
(Orchestrator)
- Dynamic Routing
- Step Reasoning
- Tool Planning"] Genome["HeLa Genome
(State & Memory)
- Knowledge Graph
- Entities / Relations
- Observations"] Membrane["HeLa Membrane
Workspace FS"] Nucleus["HeLa Nucleus
Command Exec"] Ribosome["HeLa Ribosome
PTY Harness"] Enzyme["HeLa Enzyme
Research / Wiki"] Cytosol["HeLa Cytosol
Browser DOM"] Agent -- "stdio JSON-RPC" --> Mitosis Agent -- "stdio JSON-RPC" --> Genome Mitosis <-->|"Shared Context"| Genome Mitosis --> Membrane & Nucleus & Ribosome & Enzyme & Cytosol Genome --> Membrane & Nucleus & Ribosome & Enzyme & Cytosol ``` * **HeLa Mitosis (`hela-mitosis`)**: Cellular division and orchestration backbone. Handles dynamic tool routing, prompt decomposition, Needle-backed sequential reasoning (`sequentialthinking` / `agent_run`), and multi-tool planning. * **HeLa Genome (`hela-genome`)**: Cellular memory and state backbone. Maintains the persistent SQLite knowledge graph (`memory.db`), entity-relation tracking, session restoration, and project milestones. --- ## 10-MCP Component Taxonomy | Canonical Identity | Machine ID (`id`) | Technical Source Repo | Scope | Cellular Metaphor & Role | |---|---|---|---|---| | **HeLa Mitosis** | `hela-mitosis` | [`chaining-mcp`](https://github.com/Hela-Ecosystem/chaining-mcp) | Core | **Orchestrator**: Bundled Needle 3 agent runtime, dynamic routing, 40 bundled prompt templates | | **HeLa Genome** | `hela-genome` | [`project-mcp`](https://github.com/Hela-Ecosystem/project-mcp) | Core | **State Backbone**: Entity-relation knowledge graph, milestone tracking, memory persistence | | **HeLa Membrane** | `hela-membrane` | [`filesystem-mcp`](https://github.com/Hela-Ecosystem/filesystem-mcp) | Core | **Workspace**: Sandboxed filesystem operations, recursive search, archive extraction | | **HeLa Nucleus** | `hela-nucleus` | [`terminal-mcp`](https://github.com/Hela-Ecosystem/terminal-mcp) | Core | **Execution**: Command execution, subshell isolation, RTK token-optimized execution | | **HeLa Ribosome** | `hela-ribosome` | [`menager-mcp`](https://github.com/Hela-Ecosystem/menager-mcp) | Core | **Process Harness**: Interactive PTY multiplexing, Regex hooks, lifecycle management | | **HeLa Enzyme** | `hela-enzyme` | [`researcher-mcp`](https://github.com/Hela-Ecosystem/researcher-mcp) | Core | **Knowledge**: Zero-key dual-tier web search + arXiv + Google News RSS + Wikipedia synthesis and fact-checking | | **HeLa Cytosol** | `hela-cytosol` | [`browser-mcp`](https://github.com/Hela-Ecosystem/browser-mcp) | Core | **Interaction**: Playwright browser automation, accessibility trees, DOM perception | | **HeLa Phenotype** | `hela-phenotype` | [`designer-mcp`](https://github.com/Hela-Ecosystem/designer-mcp) | Specialized | **Design**: UI/UX design tokens, OKLCH color palettes, Tailwind and component synthesis | | **HeLa Receptor** | `hela-receptor` | [`scrcpy-mcp`](https://github.com/Hela-Ecosystem/scrcpy-mcp) | Specialized | **Mobile**: Android device automation, ADB bridge, XML view hierarchy inspection | | **HeLa Plastid** | `hela-plastid` | [`ll3m-mcp`](https://github.com/Hela-Ecosystem/ll3m-mcp) | Specialized | **3D Modeling**: Autonomous Blender procedural modeling, materials, and render pipeline | --- ## Quick Start ### 1. Prerequisites * **Node.js**: use Node 22 LTS for the tested full stack. Individual packages declare their own engine ranges; Receptor requires 22 and Enzyme requires at least 20.18.1. * **Git**: `>= 2.30.0` * **SQLite**: Genome uses Node bindings; the SQLite CLI is optional for inspection. ### πŸ€– Install via AI Agent (One-Click Copy) If you are using an AI coding assistant (Cursor, Claude Code, OpenCode, Codex, Antigravity, Windsurf), you can copy and paste this autonomous prompt directly into your agent's chat: ```text Please autonomously install and configure the HeLa Cellular MCP Ecosystem through one profile-aware hela-runtime MCP endpoint: 1. Environment & Harness Detection: Verify Node.js (>= 22.x LTS), Git (>= 2.30.0), and build tools. Identify current client (Cursor, Claude, OpenCode, Antigravity, Zed, Codex). 2. Confirm the profile with the user before installing: Show https://hela.my.id/profiles.html for the quick comparison, and https://hela.my.id/library/docs/profiles.html for detailed persona, workflow, server membership, and prerequisite explanations. Ask which profile best fits the user's work: minimal, dev-workspace, headless-server, research, web-devops, android-testing, 3d-modeling, or all. Wait for the user's choice and call it . If they do not choose, use minimal. Do not run setup until the profile is confirmed. 3. Clone & Install the Managed Runtime: git clone https://github.com/Hela-Ecosystem/hela-mcp-ecosystem.git cd hela-mcp-ecosystem && chmod +x setup.sh update.sh ./setup.sh --profile --client --mode runtime --non-interactive ./setup.sh doctor --profile --mode runtime Safely merge generated client configuration into my active MCP configuration file. Do not deploy or configure each hela-* cell as a separate client server. 4. Synchronize Companion Skills: Link or copy ecosystem companion skills matching from project-mcp/skills, designer-mcp/skills, browser-mcp/skill, and chaining-mcp/skills into ~/.agents/skills/. 5. Load the Runtime Profile Context: - Do not create or copy a static persona prompt into the workspace. - After connecting, read the `hela://profile/context` resource or request the `hela-profile-bootstrap` MCP prompt. - Treat the selected runtime profile as the authority for active organelles and available tools. 6. Final Handshake: Initialize the workspace memory graph through the exposed Genome tool when that organelle is active, and confirm the selected profile and runtime tools. ``` ### 2. Run Diagnostics (`setup.sh doctor`) Clone the source, then select an installation mode: ```bash git clone https://github.com/Hela-Ecosystem/hela-mcp-ecosystem.git cd hela-mcp-ecosystem ./setup.sh --mode runtime --profile dev-workspace --client opencode --non-interactive ./setup.sh doctor --mode runtime --profile dev-workspace ``` ### 3. Interactive Installation & Profile Selection ```bash ./setup.sh ``` ### 4. Non-Interactive One-Liners **Full Developer Desktop (Cursor IDE):** ```bash ./setup.sh --profile dev-workspace --client cursor --non-interactive ``` **Headless Linux Server (Claude Desktop / CLI):** ```bash ./setup.sh --profile headless-server --client claude --non-interactive ``` **Pinned Immutable Release Snapshot:** ```bash ./setup.sh --profile dev-workspace --client cursor --snapshot v1.6.2 --non-interactive ``` **Single-endpoint Runtime (one MCP connection for the selected profile):** ```bash ./setup.sh --profile dev-workspace --client opencode --runtime --non-interactive ``` **Change an existing installation's mode in place:** ```bash ./setup.sh mode --prefix /path/to/prefix --mode docker-runtime --client opencode --non-interactive ``` **Docker cells, Docker runtime, or Nix runtime:** ```bash ./setup.sh --mode docker --profile dev-workspace --client cursor --non-interactive ./setup.sh --mode docker-runtime --profile dev-workspace --client opencode --non-interactive ./setup.sh --mode nix --profile dev-workspace --client codex --non-interactive ``` Installs use private managed prefixes under `${XDG_DATA_HOME:-$HOME/.local/share}/hela/installations/`. Existing repositories and live client files are not overwritten. Review and merge the generated client fragment. Use `--prefix` for an explicit location and pass it to doctor. See [installation modes and doctor](docs/installation.md) for HTTP transport, Compose, Nix GC roots, snapshots, optional model assets, prerequisites, and failure recovery. --- ## Supported AI Clients & Output Formats The installer writes private fragments inside its prefix, never directly into live client files: - Cursor, Claude, Gemini, Antigravity: `mcpServers` JSON. - OpenCode and Kilo: `mcp` JSON with an installed local launcher, or a runtime HTTP URL. - Zed: `context_servers` JSON; preserve unrelated settings when merging. - Codex: `[mcp_servers.*]` TOML, with a launcher or HTTP URL. - Docker: functional `compose.json` for the built image, not speculative per-cell Dockerfiles or stdio port mappings. `--client skip` installs without generating a client fragment. Client authentication and GUI acceptance remain separate. --- ## Available Agent Profiles | Profile ID | Target System | Backbone Included | Servers Included | Focus Area | |---|---|---|---|---| | `minimal` | Any | Mitosis + Genome | Enzyme | Research and memory without GUI dependencies | | `dev-workspace` | Any (GUI recommended) | Mitosis + Genome | Membrane, Nucleus, Ribosome, Enzyme, Phenotype, Cytosol | Full-stack software engineering, testing, web UI | | `headless-server` | Headless Linux | Mitosis + Genome | Membrane, Nucleus, Ribosome, Enzyme, Phenotype | Cloud server administration, CI/CD, headless dev | | `research` | Headless or GUI | Mitosis + Genome | Enzyme, Membrane, Cytosol | Deep literature research, document synthesis, web crawling | | `web-devops` | Headless or GUI | Mitosis + Genome | Membrane, Nucleus, Phenotype, Cytosol | Frontend development, Tailwind styling, DOM verification | | `android-testing` | Device connected | Mitosis + Genome | Nucleus, Receptor, Enzyme | Mobile QA testing, ADB automation, APK validation | | `3d-modeling` | GUI (Blender installed) | Mitosis + Genome | Plastid, Membrane, Nucleus | 3D procedural modeling, materials, rendering | | `all` | Full workstation | Mitosis + Genome | All 10 HeLa MCP servers | Complete full-spectrum AI agent capabilities | > **Single-endpoint serve mode:** add `--runtime` to a profile command. If no profile is selected, the runtime and installer default to `minimal`; choose `dev-workspace` or another profile explicitly. Profiles are installation choices, not machine-specific code paths. All eight pass isolated runtime verification with namespacing off/on (**16 checks**), including exact tool/schema parity and safe read-only routing. Lappy's ten-server `all` roster and servy's eight-cell `dev-workspace` setup remain different by design. See [all-profile verification](docs/profile-verification-2026-11-06.md); run `npm run test:profiles`, or append `-- --profile ` on a partial installation. Runtime discovery now starts **zero cells**; only invoked cells are started. [Generated profile counts](docs/generated-profile-counts.md) come from the inventory/catalog rather than static client-specific totals. `./setup.sh doctor --profile --runtime` checks cold catalog parity as well as versions, paths, and revisions. For complete persona guides and pipeline specifications, see **[Profiles Catalog](docs/profiles.md)**. --- ## Operational Workflows (Workflows A–F) The ecosystem is built for structured multi-server agent workflows: * **Workflow A: Autonomous Feature Engineering**: Genome (restore) β†’ Mitosis (decompose) β†’ Membrane (code) β†’ Nucleus (test) β†’ Genome (persist). * **Workflow B: Deep Research & Architecture Synthesis**: Enzyme (search) β†’ Cytosol (scrape) β†’ Mitosis (synthesize) β†’ Genome (record) β†’ Membrane (write). * **Workflow C: Web Feature with Design & Browser Verification**: Phenotype (tokens) β†’ Membrane (build) β†’ Nucleus (serve) β†’ Cytosol (DOM QA) β†’ Genome (record). * **Workflow D: Mobile App Test Automation**: Genome (issue) β†’ Nucleus (adb) β†’ Receptor (drive UI) β†’ Genome (record pass). * **Workflow E: Autonomous 3D Asset Creation & Render Pipeline**: Genome (spec) β†’ Mitosis (plan) β†’ Plastid (Blender) β†’ Membrane (save) β†’ Genome (record). * **Workflow F: Long-Horizon Complex Refactor with PTY Harness**: Ribosome (PTY) β†’ Nucleus (exec) β†’ Genome (persist). For step-by-step tool invocation sequences, schemas, and diagrams, see **[Workflows & Integration Guide](docs/workflows.md)**. --- ## Project Health & Diagnostics ```bash # Run system and server diagnostic health check npm run doctor # or ./setup.sh doctor # Run 80-combination client configuration checks (not GUI integration) npm run test:matrix # Run master integration test suite (295 tools across all 10 servers) npm test ``` --- ## Documentation Index * **[Beginner's Step-by-Step Guide](docs/beginner-guide.md)**: 3-minute, zero-code onboarding. * **[Keys & Secrets Guide](docs/keys-and-secrets.md)**: API key setup, sign-up URLs, and zero-key offline fallbacks. * **[Profiles Reference](docs/profiles.md)**: Full persona reference and capability mappings. * **[Workflows & Integration Guide](docs/workflows.md)**: Cross-MCP workflow pipelines (Workflows A–F). * **[Security & Reliability Audit](docs/security-audit.md)**: Threat model, sandboxing, and isolation standards. * **[Architecture Guide](docs/architecture.md)**: In-depth cellular architecture and communication topologies. * **[Troubleshooting Guide](docs/troubleshooting.md)**: Common issues, diagnostic codes, and recovery procedures. --- ## License & Attribution Distributed under the MIT License. Underlying repositories remain independently copyrighted by their respective authors. The HeLa project respectfully recognizes **Henrietta Lacks** and the enduring scientific legacy of HeLa cells. --- # Source: RELEASE_NOTES.md URL: https://hela.my.id/library/RELEASE_NOTES.html # HeLa MCP Ecosystem Release Notes ## v1.6.2 β€” Plastid and Receptor dependency refresh Plastid moves to `aa43877` and Receptor to `1b21cb7`, adopting the lockfile updates that had accumulated on their default branches. Both carried open advisories against `@modelcontextprotocol/sdk`; the refreshed locks resolve them, and `npm audit` is clean for Plastid's runtime dependencies while Receptor reports none. Plastid's manifest also declared `"@modelcontextprotocol/sdk": "latest"`. That is why its lockfile drifted without a reviewable diff; it is now `^1.32.2`. Builds and the existing suites pass β€” 12 Plastid regressions and 123 Receptor tests β€” and no cell version changed. Exposure was limited: the SDK advisories concern HTTP transports, body-size limits, and OAuth flows, while Plastid and Receptor run over stdio. Updating still removes the drift and the noise. Hardware, the Blender bridge, GUI clients, and providers remain separate checks. ## v1.6.1 β€” switch deployment modes in place `./setup.sh mode --prefix PATH --mode MODE` converts an existing managed installation to another execution mechanism without a second prefix or a data migration. All five modes are valid targets. Profile, snapshot, workspace, transport, port, and the per-cell `data/` directories carry over; host-mode switches reuse packages already built at the pinned revision with a clean worktree, and Docker modes build or drop their image and `compose.json` accordingly. The command runs the same verification as a fresh installation and generates a new client fragment instead of editing live client settings. Failed verification restores the previous manifest and writes a pending marker so doctor reports the degraded state. Pending or unmanaged prefixes are refused, HTTP targets require a runtime mode, and re-selecting the current mode is an error. Enzyme stays at 4.0.0 and the runtime at 1.2.0; every cell pin is unchanged from 1.6.0. Tests cover host-family round-trips, transport guards, pending markers, and Docker switches. ## v1.6.0 β€” consistent Enzyme search input Pin Enzyme source `eb98982`. `google_search` now takes `query`, matching every other single text search in the cell. The former `q` argument is removed, so a client that still sends it gets an MCP validation error instead of a silent translation; requests that send both fields are rejected as well. Batch tools keep `queries`, and provider HTTP parameters are unaffected internally. Both Enzyme entrypoints share one strict schema: the query is trimmed and must be non-empty, `num` is an integer from 1 to 10, and unknown fields are refused before any provider call. Enzyme's contract tests cover discovery, dispatch, rejection of obsolete input, and provider failure for the shipped and modular servers; 32 contract tests and 111 total Enzyme tests pass with a clean TypeScript build and no lint errors. Enzyme moves to 4.0.0 because this is a breaking argument change. The catalog, generated documentation, and profile counts are rebuilt from the new schema. Counts stay at 24 Enzyme tools, so profile totals do not change. Other cells, the runtime, and every snapshot from v1.0.0 to v1.5.3 are untouched. ## v1.5.3 β€” canonical relation ordering Pin Genome source `9ba1d0e`. Relation links now render in one canonical order regardless of database insertion order, preventing relation-order-only conflicts after a lossless repair. All 19 suites / 264 tests pass; the TypeScript build and zero-warning source lint pass. The published 1.5.2 snapshot remains unchanged, as do all other cell/runtime pins and package versions. ## v1.5.2 β€” replicated vault convergence Pin Genome source `c32ae94`: replicated notes keep the earliest creation timestamp and latest update timestamp, while incoming observation supersets can retain their order without losing database-only facts. The explicit programmatic repair API archives both originals, respects snapshot/lock checks, and permits rejecting a plan before publication. Normal CLI sync does not choose conflict winners automatically. Genome's 19 suites / 263 tests and TypeScript build pass, including regressions reproducing the previous timestamp/order loops and validating SQL bindings, JSON rows and tool arguments. Source lint reports zero errors and warnings, covers top-level files and fails on warnings. Package versions remain 3.0.0 for cells and 1.2.0 for runtime; this source snapshot records the exact fixed Genome commit. Other pins and historical snapshots are unchanged. Real vault repair and MCP reconnection require separate, backed-up operational verification; no private vault data is published here. ## v1.5.1 β€” current documentation and bilingual website Documentation-only refresh: all ten cells remain **3.0.0**, and runtime remains **1.2.0**. The new source snapshot pins the documentation commits without rewriting v1.0.0–v1.5.0. Plastid and Receptor documentation was merged into their default branches without discarding unrelated dependency updates; the snapshot deliberately pins the documentation-only parents, not those dependency changes. The EN/ID website now loads generated versions, canonical tool names, and profile metadata. Configuration previews use real repository directories and Codex `mcp_servers` sections. Source guides cover all eight profiles, cold discovery, optional integrations, safe backup/restore, and the limits of current verification. Generated private configurations may contain supplied credentials; committed examples are regenerated with a sanitized environment. Documentation checks cover 74 regression cases plus local links/anchors and structured metadata; the CLI matrix covers 80 combinations. Browser verification covers 64 visible selections per language and all 16 pages at desktop/mobile widths. These are documentation/UI checks, not new authenticated ACP, provider, Android, or Blender acceptance. Publication does not restart the runtime or change deferred access controls, credentials, databases, or vault conflicts. ## v1.5.0 β€” on-demand runtime and canonical discovery Runtime **1.2.0** starts cells only when invoked, shares concurrent startup attempts, and discovers schemas without spawning cells. Revision/build/config-aware caches reject stale entries; legacy/corrupt caches fall back to a validated generated catalog. Unknown calls no longer start unrelated cells. Standalone servers, all eight profiles, and the `dev-workspace` default are preserved. The canonical inventory drives config generation, doctor/version/profile checks, schema catalogs, and generated documentation counts. Doctor can verify exact runtime discovery with no cell startup via `--runtime`. A new immutable v1.5.0 snapshot pins runtime `9c92dbf`; older versioned snapshots are unchanged. Verification: **32** runtime regressions on both Linux architectures, **16** all-profile namespace-mode checks, **80** client configurations, four probe regressions, and four inventory regressions. Cold/warm measurements are recorded, not treated as universal benchmarks. See [implementation and verification scope](docs/on-demand-runtime.md). ACP authentication, external client reloads, gateway retirement, vault conflict review, hardware/provider integrations, and deferred security remain separate work. **Servy rollout verified:** public/local discovery exposes 236 tools without starting any cells; the first safe Nucleus call starts only Nucleus. Deployed doctor, catalog, and revision checks pass. Fresh backups and rollback material are retained, and all 633 existing conflict archive files are unchanged. See the [rollout evidence](docs/on-demand-runtime.md#verified-servy-rollout). ## v1.4.0 β€” memory safety and runtime verification The v1.4.0 source snapshot pins the published cell revisions and runtime 1.1.0. Older versioned snapshots are unchanged. `latest-stable.json` tracks this source snapshot, not a guarantee that every optional integration or GUI session has been exercised. - Genome: 19 suites / 242 tests with clean lockfile dependencies, including WAL-safe backups, isolated restore, vault conflicts, repeated imports, and exclusive mission claims. - Runtime: 20 isolated fault tests covering hung children, SIGTERM/SIGKILL, actual process exit, one restart, profile/cache boundaries, and shutdown cleanup. - Nix: real Node 22 package builds on x86_64-linux and native aarch64-linux, using pinned inputs and fixed-output npm dependencies. - Dependencies: clean-install Zod 4 build fixes in Genome and Enzyme; Enzyme's 79 tests and Phenotype's 74 tests pass. - Ecosystem: ten isolated standalone MCP handshakes and 80 configuration-generation combinations pass. Codex TOML now uses `mcp_servers` and is accepted by the native parser. These are not authenticated GUI tests. - Discovery: 290 standalone tools with LLM and model-backed agent features disabled; the same isolated `dev-workspace` runtime exposes 230 tools including `hela.pipe`. Feature-enabled deployments can expose additional Mitosis tools and the optional agent alias; query `tools/list` rather than assuming a static total. Known limits: Zed/Codex ACP authenticated-session verification remains pending; duplicate ownership warnings do not establish a connection failure. Existing live vault conflicts remain archived for deliberate review. Android/Blender discovery is not hardware integration. Endpoint authentication and credential rotation remain operator work, not changes included in this release. **Servy deployment verified (2026-11-06):** the rooted ARM Nix package serves the eight-cell `dev-workspace` profile under systemd. Local/public discovery returns 236 live tools, versus 230 in feature-disabled probes; all three Genome mission tools are present. Deployed doctor and strict version/pin checks pass. Existing conflict archives and unrelated client processes were preserved. See [deployment evidence and remaining client/gateway work](docs/deployment-2026-11-06.md). **All-profile follow-up (2026-11-06):** all eight profiles pass runtime startup/discovery, exact tool/schema parity, and safe read-only routing in both namespacing modes (**16/16** checks). All ten standalone cells plus runtime pass strict version/pin verification; the 80 client-configuration combinations and four probe regressions pass. Machine selections and release snapshots are unchanged. See [profile verification](docs/profile-verification-2026-11-06.md). ## Historical v1.0.0 notes We are proud to announce the official **v1.0.0** release of the **HeLa MCP Ecosystem** β€” a modular, immortal cellular AI tooling stack built on the Model Context Protocol (MCP), engineered by Azzar. --- ## Architectural Vision & Metaphor The **HeLa MCP Ecosystem** is named in respectful recognition of **Henrietta Lacks** (1920–1951) and the enduring scientific legacy of HeLa cells. Using a **cellular biology metaphor**, the ecosystem organizes 10 specialized MCP servers into a harmonious organism: * **Cellular Specialization**: Distinct organelles (Nucleus, Membrane, Enzyme, Ribosome, Plastid) perform targeted domains. * **Deterministic Immortality**: Environments can be snapshot-pinned (`config/snapshots/v1.0.0.json`) and restored cleanly on any machine. * **Repository Independence**: Underlying source repositories, technical package names, and Git commit histories remain 100% autonomous. --- ## Key Highlights & Milestones Delivered ### 1. Dual-Backbone Architecture Every profile is grounded by two core backbones: * **HeLa Mitosis (`chaining-mcp`)**: Cellular division and orchestration backbone. Bundled Needle 3 agent runtime (plan β†’ execute β†’ observe, offline-first), Needle-backed sequential reasoning (`sequentialthinking`, `agent_run`), task decomposition, and 40 domain prompts. No external sequential-thinking server. * **HeLa Genome (`Project-Guardian-mcp-server`)**: Living memory and state backbone. SQLite knowledge graph (`memory.db`), entity-relation tracking, cross-session context restoration, and decision memory. ### 2. 10-MCP Component Taxonomy * **HeLa Membrane** (`filesystem-mcp-server`): Sandboxed workspace filesystem operations and search. * **HeLa Nucleus** (`terminal-mcp-server`): Isolated command execution with RTK token optimization. * **HeLa Ribosome** (`menager-mcp-server`): Interactive PTY session multiplexing and Regex hook engine. * **HeLa Enzyme** (`research-assistant-mcp-server`): Unified Google Custom Search + Wikipedia caching. * **HeLa Cytosol** (`Browser-Agent`): Playwright browser automation and DOM accessibility perception. * **HeLa Phenotype** (`the-designer`): UI/UX design tokens, OKLCH palettes, and Tailwind component synthesis. * **HeLa Receptor** (`scrcpy-mcp`): Android mobile automation via ADB bridge. * **HeLa Plastid** (`ll3m-agent`): Autonomous Blender procedural 3D modeling and rendering. ### 3. Diagnostic Health Checker (`setup.sh doctor`) Comprehensive automated diagnostic tool auditing host prerequisites (Node.js >=18, Git, SQLite3), server builds, commit pins, stdio JSON-RPC smoke readiness (<300ms), external runtimes (Playwright, ADB, Blender), and zero-key offline fallback modes. ### 4. 70-Combination Multi-Client Matrix (`npm run test:matrix`) Full verification across all 10 client backends (Cursor, Claude, Gemini, Antigravity, OpenCode, Kilo, Zed, Codex TOML, Docker Compose, Skip) and 7 agent profiles with 100% schema accuracy. ### 5. Master Integration Test Suite (`npm test`) Automated stdio JSON-RPC handshake and tools discovery across all 10 servers (**295 active tools discovered and validated in 2.5s**). ### 6. Interactive Documentation Website (`docs/site/`) Modern, responsive documentation landing site featuring: * Interactive live Client & Profile Configurator. * Video showcases & embedded YouTube demos. * Uploaded Asciinema terminal casts. * Searchable 10-MCP Cellular Taxonomy directory. --- ## Quick Start ```bash git clone https://github.com/Hela-Ecosystem/hela-mcp-ecosystem.git cd hela-mcp-ecosystem ./setup.sh doctor ./setup.sh ``` --- ## Documentation * [Beginner's Step-by-Step Guide](docs/beginner-guide.md) * [Architecture Guide](docs/architecture.md) * [Cross-MCP Workflows A–F](docs/workflows.md) * [Security & Reliability Audit](docs/security-audit.md) * [Troubleshooting Guide](docs/troubleshooting.md) * [Keys & Secrets Matrix](docs/keys-and-secrets.md) --- ## License & Attribution Distributed under the MIT License. Developed by Azzar. The HeLa project respectfully recognizes **Henrietta Lacks** and the enduring scientific legacy of HeLa cells. --- # Source: docs/architecture.md URL: https://hela.my.id/library/docs/architecture.html # HeLa MCP Ecosystem Architecture This document provides a comprehensive architectural reference for the **HeLa MCP Ecosystem**, detailing its cellular design principles, dual-backbone topology, component taxonomies, and cross-MCP communication mechanisms. Current package versions and feature-dependent tool counts are generated in [current versions](current-versions.md). Each of the ten MCP cells has its own version; the ecosystem snapshot and optional runtime have independent versions. ![Blotcat acting as a conductor in front of a modular system of interconnected server blocks](../assets/blotcat-architecture.jpg) --- ## 1. Architectural Philosophy: The Cellular Metaphor The **HeLa MCP Ecosystem** is architected around a cellular biology metaphor, respectfully recognizing **Henrietta Lacks** (1920–1951) and the immortal legacy of HeLa cells in biomedical research: 1. **Cellular Specialization**: In biological systems, organelles perform distinct biochemical functions while cooperating as a unified organism. In the HeLa ecosystem, servers act as specialized cellular components (Nucleus, Membrane, Enzyme, Ribosome, Plastid) coordinated by a dual backbone. 2. **Reproducible source selection**: Commit-pinned snapshots under `config/snapshots/` select known revisions. Platform dependencies and external integrations still require separate validation. 3. **Repository Autonomy**: Underlying repositories, Git histories, and package dependencies remain completely autonomous and uncoupled. --- ## 2. The 4-Tier Naming Architecture To balance brand clarity, backwards compatibility, and technical provenance, the ecosystem enforces a 4-tier naming model: ```mermaid flowchart LR T1["Tier 1: Public Identity
HeLa Genome"] T2["Tier 2: Machine ID
hela-genome"] T3["Tier 3: Technical Repo
project-mcp"] T4["Tier 4: Immutable Commit
72bca15ebe..."] T1 --> T2 --> T3 --> T4 ``` 1. **Tier 1 (Public Identity)**: Clean, uniform human-facing persona name (e.g. *HeLa Mitosis*, *HeLa Genome*, *HeLa Membrane*). 2. **Tier 2 (Machine Identifier)**: Stable hyphenated identifier (`hela-*`) used in configuration files (`mcpServers`), CLI flags, and profile definitions. 3. **Tier 3 (Technical Source Repo)**: Independent Git repository name on GitHub maintaining upstream authorship and commit history. 4. **Tier 4 (Immutable Commit Pin)**: Exact SHA-1 hash recorded in `config/snapshots/` ensuring reproducible builds. --- ## 3. Dual-Backbone Coordination Topology Every deployed profile in the ecosystem is grounded by a dual backbone: ```mermaid flowchart TB Client["AI Client / Orchestrator"] Mitosis["HeLa Mitosis
(hela-mitosis)
- Dynamic Routing
- Step Reasoning
- Task Decomposition
- Prompt Catalog"] Genome["HeLa Genome
(hela-genome)
- Knowledge Graph
- Living SQLite DB
- Entity / Relations
- Milestones & State"] Membrane["HeLa Membrane
(Files)"] Nucleus["HeLa Nucleus
(Exec)"] Ribosome["HeLa Ribosome
(PTY)"] Enzyme["HeLa Enzyme
(Search)"] Cytosol["HeLa Cytosol
(Browser)"] Phenotype["HeLa Phenotype
(Design)"] Client -- "stdio JSON-RPC" --> Mitosis & Genome Mitosis <-->|"Shared Memory"| Genome Mitosis & Genome --> Membrane & Nucleus & Ribosome & Enzyme & Cytosol & Phenotype ``` * **HeLa Mitosis (Routing & Planning Backbone)**: Bundled Needle 3 agent runtime (plan β†’ execute β†’ observe with recorded AgentState), suggests multi-step execution paths, Needle-backed sequential analysis, and serves 40 curated domain prompts. Offline-first; OpenRouter is an escalation backend only. * **HeLa Genome (State & Memory Backbone)**: Maintains the living SQLite knowledge graph (`memory.db`), restores cross-session context, records task states, and manages project milestones. --- ## 4. Component Taxonomy ### 4.1 Core Backbone Servers #### 1. HeLa Mitosis (`hela-mitosis` / `chaining-mcp`) * **Role**: Orchestration, dynamic routing, and Needle-backed sequential reasoning. * **Entrypoint**: `dist/index.js` * **Tools**: `agent_run`, `sequentialthinking`, `analyze_with_sequential_thinking`, `analyze_tools`, `generate_route_suggestions`, `llm_decompose_task`, `llm_suggest_route`, `workflow_orchestrator`, `workflow_status`, `workflow_cancel`, `list_skills`, `search_skills`, `get_skill`, `suggest_skill_chain`, plus prompt/resource, time, and validation tools. * **Zero-Key Behavior**: The bundled Needle 3 agent runs fully offline. Without `OPENROUTER_API_KEY`, escalation hands control back to the calling agent (`handoff: true`) with the full state trail β€” never a fabricated answer. `brainstorming` is the one exception: it needs a generative model and fails honestly without a key. #### 2. HeLa Genome (`hela-genome` / `project-mcp`) * **Role**: Living memory graph, entity-relation-observation state tracking. * **Entrypoint**: `dist/index.js` * **Tools**: `memory_edit` (entity/relation/observation CRUD), `read_graph`, `search_nodes`, `get_session_context`, `sync_central_memory`, `security_scan`, and the three mission tools `create_mission`, `list_missions`, `update_mission`. * **Storage**: Embedded SQLite database (`memory.db`) with FTS5 full-text indexing. --- ### 4.2 Core Capability Servers #### 3. HeLa Membrane (`hela-membrane` / `filesystem-mcp`) * **Role**: Sandboxed workspace filesystem operations and search. * **Entrypoint**: `dist/index.js` * **Tools**: `read_file`, `write_file`, `find_files`, `search_in_files`, `copy_file`, `move_file`, `delete_file`, `archive_files`. #### 4. HeLa Nucleus (`hela-nucleus` / `terminal-mcp`) * **Role**: Isolated command execution and RTK token optimization. * **Entrypoint**: `build/index.js` * **Tools**: `execute_command`, `transfer_file`, `terminal_ls`, `terminal_grep`, `terminal_cat`, `terminal_session_close`, `terminal_session_list`. #### 5. HeLa Ribosome (`hela-ribosome` / `menager-mcp`) * **Role**: Polyglot interactive PTY session multiplexing and Regex hook engine. * **Entrypoint**: `build/index.js` * **Tools**: `session_spawn`, `session_write`, `session_read`, `session_hook`, `session_close`, `session_list`, `session_prune`. #### 6. HeLa Enzyme (`hela-enzyme` / `researcher-mcp`) * **Role**: Unified research platform: zero-key dual-tier web search + arXiv + Google News RSS + Wikipedia caching. * **Entrypoint**: `dist/index.js` * **Tools**: `google_search`, `wikipedia_search`, `wikipedia_get`, `content_summarizer`, `fact_checker`, `keyword_extraction`. #### 7. HeLa Cytosol (`hela-cytosol` / `browser-mcp`) * **Role**: Playwright-based browser automation and DOM accessibility perception. * **Entrypoint**: `src/server.js` * **Tools**: `browser_navigate`, `browser_screenshot`, `browser_click`, `browser_type`, `browser_get_content`. --- ### 4.3 Specialized Capability Servers #### 8. HeLa Phenotype (`hela-phenotype` / `designer-mcp`) * **Role**: UI/UX design tokens, OKLCH palettes, and Tailwind component synthesis. * **Entrypoint**: `dist/index.js` * **Tools**: `design_tokens`, `palette`, `design_audit`, `generate_template`, `logo_workflow`. #### 9. HeLa Receptor (`hela-receptor` / `scrcpy-mcp`) * **Role**: Android mobile device control via ADB bridge. * **Entrypoint**: `dist/server.js` * **Tools**: `start_session`, `ui_dump`, `ui_find_element`, `tap`, `swipe`, `input_text`, `screenshot`. #### 10. HeLa Plastid (`hela-plastid` / `ll3m-mcp`) * **Role**: Autonomous 3D procedural modeling and rendering in Blender. * **Entrypoint**: `dist/index.js` (under `brain/`) * **Tools**: `generate_modeling_plan`, `execute_blender_code`, `render_output`, `save_blend`, `get_fast_feedback`. --- ### 4.4 Canonical Tool Boundaries (v1.2.0) Several organelles expose overlapping capabilities. Descriptions and the Mitosis capability router now enforce a single canonical choice per intent, keeping a restricted alternative only for its niche: | Intent | Canonical | Restricted alternative | Restricted use | |--------|-----------|------------------------|----------------| | Web search | `hela-enzyme:google_search` | `hela-cytosol:browser_search` | Visual browser workflows only | | Content extraction | `hela-enzyme:extract_content` | `hela-cytosol:browser_get_content` | Pages requiring client-side JavaScript | | Local file read | `hela-membrane:read_file` | `hela-nucleus:terminal_cat` | Remote SSH targets only (`host` required) | | Memory-graph inspection | `hela-genome:execute_sql` / `query_data` | `hela-ribosome:opencode_db` | OpenCode session database only | Tool names are unique ecosystem-wide after the Phase 1 rename, so the router matches boundaries by tool name without needing a server field. --- ### 4.5 HeLa Runtime (optional daemon, `hela-runtime`) The optional runtime supervises child MCP processes behind one stdio or Streamable HTTP endpoint. Its generated catalog exposes selected-profile schemas without starting cells. The first invocation starts only its target; concurrent first calls share startup. Unknown tool names do not trigger an all-cell scan. - **Source:** https://github.com/Hela-Ecosystem/hela-runtime - **Entry:** `hela-runtime/dist/index.js` - **Serve mode:** add `--runtime` to any profile, for example `./setup.sh --profile dev-workspace --client opencode --runtime`. Runtime is not a profile; an omitted profile defaults to `minimal`. - **Env:** `HELA_ECOSYSTEM_ROOT`, `HELA_PROFILE`, `HELA_HTTP_PORT`, `HELA_NAMESPACE_TOOLS`. - **Features:** true on-demand ignition for every selected cell, fingerprinted schema caches, bounded crash/timeout recovery, opt-in namespacing, runtime-internal `hela.pipe`, and HTTP `/healthz` liveness. - **Without it:** users keep the individual servers selected by their profile and can use `hela-mitosis:workflow_orchestrator` for cross-cell chaining. - **Details:** [on-demand startup, cache invalidation and deployment evidence](on-demand-runtime.md). ## 5. Security & Isolation Model ```mermaid flowchart TB Host["Host Operating System / Terminal Environment"] Root["HeLa MCP Ecosystem Root"] Sandbox["stdio JSON-RPC Sandbox"] Membrane2["Path Canonicalization
(HeLa Membrane)"] Nucleus2["Explicit CWD & Timeout Limits
(HeLa Nucleus)"] Ribosome2["Process Group Teardown
(HeLa Ribosome)"] Cytosol2["SSRF IP Filtering
(HeLa Cytosol)"] Host --> Root Root --> Sandbox & Membrane2 & Nucleus2 & Ribosome2 & Cytosol2 ``` 1. **Process Boundary**: Each server runs in an isolated Node.js child process communicating exclusively over standard input/output (`stdio`) via JSON-RPC 2.0 messages. 2. **Memory Safety**: SQLite database operations in `hela-genome` use parameterized queries with WAL (Write-Ahead Logging) mode. 3. **Credential handling**: Doctor reports presence, not values. Generated client configurations can contain explicitly configured credentials; treat those files and generator output as private. Process separation is not a security sandbox, and remote endpoint authentication/authorization remain explicitly deferred; see [security status](security-audit.md). --- ## 6. Profile System & Lifecycle Management The ecosystem configuration generator (`scripts/generate-config.mjs`) reads: 1. **`config/inventory.json`**: Authoritative component catalog, entrypoints, Git repositories, and alias mappings. 2. **`config/profiles.json`**: Curated stacks tailored to specific agent personas and hardware targets. The installer matches the selected profile against the inventory and chosen snapshot, then renders client syntax: `mcpServers` JSON, OpenCode/Kilo `mcp`, Zed `context_servers`, or Codex `[mcp_servers.*]` TOML. Runtime installation also refreshes selected-profile schema catalogs. All eight profiles are supported; lappy's full ten-cell roster and servy's eight-cell roster are installation choices, not code forks. --- # Source: docs/beginner-guide.md URL: https://hela.my.id/library/docs/beginner-guide.html # Beginner's Guide: HeLa MCP Ecosystem ![Blotcat beginner setup](../assets/blotcat-beginner.jpg) HeLa connects an AI client to tools for memory, files, commands, research, design, browsers, Android, and Blender. Install only the profile you need. Tools can change files and run commands with the server account's privileges; review your client's permissions before use. Current software versions are listed in [current versions](current-versions.md). Setup time depends on dependencies and downloads; browser and hardware workflows need extra software. ## Requirements - Node.js **22 LTS** is the tested full-stack environment. Enzyme requires at least 20.18.1; Receptor requires 22. Individual packages can declare different standalone engine ranges. - Git and a terminal. Use a POSIX shell on Linux/macOS or WSL on Windows for `setup.sh`. - Optional capabilities: Chromium/Playwright for browser work, ADB and a device for Android, and the Blender bridge for 3D. ## Install a profile ```bash git clone https://github.com/Hela-Ecosystem/hela-mcp-ecosystem.git cd hela-mcp-ecosystem ./setup.sh --mode runtime --profile dev-workspace --client opencode --non-interactive ``` Change the client to `cursor`, `claude`, `gemini`, `antigravity`, `kilo`, `zed`, or `codex` as appropriate. The installer prints its managed prefix and a private client fragment: review and merge that fragment into your client settings. It does not overwrite existing client files or reuse your working repositories. Run `./setup.sh` without flags for interactive profile/mode/client selection. All eight profiles are supported: - `minimal`: three research/memory cells. - `dev-workspace`: eight development/browser/design cells; select it explicitly when you need the broader workstation stack. - `headless-server`: seven cells without browser/device dependencies. - `research`: five research/browser/workspace cells. - `web-devops`: six frontend/browser/design cells. - `android-testing`: five cells including device control. - `3d-modeling`: five cells including Blender. - `all`: all ten cells. See [profiles](profiles.md) for membership. Your selection is independent of other machines: lappy's ten-cell roster and servy's eight-cell roster are examples, not required configurations for everyone. ## One connection or separate servers The installer normally configures separate MCP servers. Add `--runtime` to keep the same profile behind one endpoint: ```bash ./setup.sh --profile dev-workspace --client opencode --runtime --non-interactive ``` Runtime is a serve mode, not a profile named `runtime`. Its catalog advertises schemas without starting cells; a first call starts only its target. [Runtime details](on-demand-runtime.md) explain catalog generation, missing metadata, and recovery. Other mechanisms are `--mode docker` (separate containers), `--mode docker-runtime` (one runtime container), and `--mode nix` (pinned toolchain and packaged runtime). Runtime modes also support `--transport http`. See [installation modes](installation.md) for exact requirements and commands; Docker needs a working daemon, and HTTP listeners are started explicitly. ## Optional keys OpenRouter, GitHub, and Google keys are optional for discovery and keyless capabilities. Keyless does **not** mean every operation is offline: web research and external design services still need network access, and generative-model features require their configured provider or local engine. See [keys and services](keys-and-secrets.md). Generated configuration can contain credentials you explicitly provide. Keep it private, and do not paste the complete file into a chat or issue. ## Verify the selected installation ```bash ./setup.sh doctor --profile dev-workspace # If installed through the runtime: ./setup.sh doctor --profile dev-workspace --runtime npm run test:matrix ``` Doctor checks selected paths, versions, revisions, and actual isolated MCP replies. Runtime checking also verifies catalog parity and zero discovery startups. The configuration matrix checks 80 profile/client combinations; it does not log in to GUI agents or exercise hardware. For an explicit prefix, use `./setup.sh doctor --prefix /path/to/prefix`. For Docker or Nix defaults, select the same `--mode` and profile as installation. `doctor --url http://127.0.0.1:8080/mcp` checks a running HTTP endpoint; it does not inspect remote source revisions. On a full ten-cell checkout you can also run `npm test` and `npm run test:profiles`. On a partial checkout use `npm run test:profiles -- --profile `. Missing unselected hardware repositories are not a reason to change your machine's profile. Reload the relevant client deliberately after reviewing configuration changes. Some clients, including Zed, can auto-reload servers when settings are saved. Do not change live vault hooks or restart unrelated clients merely to silence a warning. See [integration](integration.md) and [troubleshooting](troubleshooting.md). --- # Source: docs/current-versions.md URL: https://hela.my.id/library/docs/current-versions.html # Current versions and tool surfaces Generated from package metadata, inventory, and the schema catalog. Ecosystem **1.6.2**; runtime **1.2.0**. - **HeLa Mitosis** (`hela-mitosis`): server **3.0.0**, 24–29 canonical tools; [source](https://github.com/Hela-Ecosystem/chaining-mcp). - **HeLa Genome** (`hela-genome`): server **3.0.0**, 29 canonical tools; [source](https://github.com/Hela-Ecosystem/project-mcp). - **HeLa Membrane** (`hela-membrane`): server **3.0.0**, 16 canonical tools; [source](https://github.com/Hela-Ecosystem/filesystem-mcp). - **HeLa Nucleus** (`hela-nucleus`): server **3.0.0**, 7 canonical tools; [source](https://github.com/Hela-Ecosystem/terminal-mcp). - **HeLa Ribosome** (`hela-ribosome`): server **3.0.0**, 28 canonical tools; [source](https://github.com/Hela-Ecosystem/menager-mcp). - **HeLa Enzyme** (`hela-enzyme`): server **4.0.0**, 24 canonical tools; [source](https://github.com/Hela-Ecosystem/researcher-mcp). - **HeLa Cytosol** (`hela-cytosol`): server **3.0.0**, 73 canonical tools; [source](https://github.com/Hela-Ecosystem/browser-mcp). - **HeLa Phenotype** (`hela-phenotype`): server **3.0.0**, 28 canonical tools; [source](https://github.com/Hela-Ecosystem/designer-mcp). - **HeLa Receptor** (`hela-receptor`): server **3.0.0**, 46 canonical tools; [source](https://github.com/Hela-Ecosystem/scrcpy-mcp). - **HeLa Plastid** (`hela-plastid`): server **3.0.0**, 15 canonical tools; [source](https://github.com/Hela-Ecosystem/ll3m-mcp). Counts vary with declared features. Runtime adds `hela.pipe` and an agent alias when available. Profiles choose eligible cells, not an eager startup count. Historical release notes/snapshots keep their original versions. --- # Source: docs/deployment-2026-11-06.md URL: https://hela.my.id/library/docs/deployment-2026-11-06.html # Servy deployment verification β€” 2026-11-06 This records the earlier runtime 1.1.0 rollout. The subsequent [runtime 1.2.0 on-demand deployment](on-demand-runtime.md#verified-servy-rollout) supersedes its process/startup state; the evidence below remains historical. The v1.4.0 source release (`c9faa9b`) is deployed to servy's systemd-managed HTTP runtime. This record covers that deployment, not authenticated GUI sessions or live vault reconciliation. ## Published source and builds - Genome: `16fc4f31735e139d690ae0ace8d4feaf1a603563`. - Enzyme: `5399e33c7c8a5b75ad620dc33f66a1cbf49972f7`. - Runtime: `797bad451b45d0d67631eeb8cdb1c93d259f614c`, version **1.1.0**. - Remaining cell pins are in `config/snapshots/v1.4.0.json`. Historical v1.0.0–v1.3.0 snapshots were not modified. Runtime recovery passes **20/20** isolated fault tests on x86_64-linux and native aarch64-linux; all 29 fixture PIDs per run were reaped. Coverage includes hung RPCs, SIGTERM/SIGKILL, exit-before-restart, pipe routing, bounded retries, profile boundaries, and shutdown cleanup. No live service cell was faulted during deployment. Final-source Nix builds use the committed lockfile, fixed-output npm dependencies, production installation, and Node **22.23.4**: - x86_64-linux: `/nix/store/gzxl62xr29nh36yb75c242gp4mnsibsh-hela-runtime-1.1.0`. - aarch64-linux: `/nix/store/y9hqz9kyx860s5xqx3gk23x7acsghis2-hela-runtime-1.1.0`. Genome's clean-install regression suite passes **19 suites / 242 tests**. Enzyme's **79 tests** and Phenotype's **74 tests** pass. Ten isolated standalone MCP handshakes, 80 client-configuration combinations, three probe regressions, and three isolated direct/runtime read-only parity calls pass. These checks do not establish authenticated GUI or hardware integration. ## Controlled promotion All eight selected cells, runtime, and ecosystem checkouts were clean before fast-forward promotion. Validated staged builds were promoted; Genome, Ribosome, Enzyme, and Phenotype received fresh ARM dependency trees. Old build/dependency directories remain in the rollout's `rollback/` directory. All ten deployed checkouts passed `npm ls --depth=0`; source revisions agreed with lappy at source-release verification. Before stopping the service, three online SQLite backups passed integrity checks and the live vault was archived again. Earlier backups were hash-verified. No active database file was replaced or restored. Only `hela-runtime.service` was stopped/restarted. Its old ten processes, including a duplicate Genome child, exited. The new service owns one runtime plus exactly eight direct child cells; all use Nix Node 22.23.4. At verification, systemd reported active state, zero automatic restarts, and successful exit status. The deployed package is rooted by: `/home/ubuntu/.local/state/hela/deployments/todo102-z65w9kzr/runtime` The drop-in `/etc/systemd/system/hela-runtime.service.d/10-nix-package.conf` selects that executable and prepends pinned Node to PATH. The original unit remains intact. Existing profile, vault setting, host, port, and endpoint-security configuration were not changed. ## Discovery and ownership - Default profile: **dev-workspace**, eight cells; no Receptor or Plastid deployment on servy. - Local `/healthz`: HTTP 200, runtime **1.1.0**. - Local and public MCP initialize/tools discovery: **236 unique tools** at `/mcp`, including `create_mission`, `list_missions`, `update_mission`, and `hela.pipe`; hardware-only tools absent. - Public endpoint: `https://hela-runtime.glassgallery.my.id/mcp`. - A local HTTP `terminal_session_list` call passed MCP and payload-level error checks. - Isolated strict package/initialize/inventory/snapshot/pin checks passed for eight cells and runtime; deployed doctor reported **8/8 READY**. The isolated feature-disabled runtime exposes **230 tools**. The live configuration adds `llm_query`, `llm_decompose_task`, `llm_suggest_route`, `llm_summarize`, `agent_run`, and runtime alias `hela.agent.run`. No isolated tools were missing from live discovery. Those additional model-backed tools were discovered, not invoked. The 211 unresolved divergent-note conflicts remain archived. All **633** existing servy conflict archive files retained their pre-rollout hashes. No conflict winner, explicit bulk deduplication, or deletion reconciliation was forced. ## Evidence and retained recovery material Servy rollout directory: `/home/ubuntu/.local/state/hela/deployments/todo102-z65w9kzr/` It contains `manifest.json`, `backup/`, `rollback/`, the runtime GC root, `verify-versions.mjs.log`, `doctor.mjs.log`, `http-verification.json`, and `feature-difference.json`. These are local operational records, not public credential/configuration dumps. Previous backups remain at: - lappy: `/home/azzar/.local/state/hela/backups/pre-10.2-d9nokk5t/`. - servy: `/home/ubuntu/.local/state/hela/backups/pre-10.2-m6j95llu/`. Rollback material is retained, but no live rollback was performed. Any rollback must stop the service, preserve current databases/vaults, inspect compatibility, and select retained code/dependencies deliberately. Do not overwrite active databases or hard-reset repositories. ## Remaining work - Authenticated Zed/Codex ACP session and GUI warning verification remain pending. Direct MCP and isolated Codex discovery passed; credentials were not copied and the optional ACP duplicate-filter override remains unset. - Two older stdio runtimes owned by an active servy OpenCode client were preserved. They require a deliberate client reload; the HTTP service rollout does not update code already loaded in unrelated processes. Local client reload state also remains unverified. - PM2 has no active or saved individual MCP cell entries. It still owns the legacy `mcp-gateway` on port **8010**, with no child cells and seven retired backends on **8011–8017** reporting down. Historical entries remain in `dump.pm2.bak`. Review consumers/routes before retiring this gateway; it does not serve the verified runtime endpoint on **8090**. - Review archived vault conflicts before reconciliation. Deployment is not conflict resolution. - True first-call ignition, full revision/configuration manifest invalidation, optional hardware integrations, and deferred endpoint authentication/credential rotation remain separate work. --- # Source: docs/documentation-refresh-2026-11-06.md URL: https://hela.my.id/library/docs/documentation-refresh-2026-11-06.html # Documentation refresh β€” 2026-11-06 Ecosystem **1.5.1** is a documentation-only source snapshot. The ten MCP cells remain **3.0.0**; runtime remains **1.2.0** at its existing implementation revision. [Current versions](current-versions.md) and [profile counts](generated-profile-counts.md) are generated from canonical metadata. ## Scope - Audited all 12 repositories. Updated the ten cells' README version banners and generated canonical tool references; the runtime's existing 1.2.0 reference was already current. - Completed all 16 English/Indonesian website pages, including current architecture, profiles, requirements, runtime behavior, diagnostics, privacy, and historical showcase labels. - Corrected Codex keys and actual repository paths, including Plastid's `brain` entrypoint. Browser previews intentionally omit private environment values and are not byte-identical installation files. - Regenerated seven committed client examples with a sanitized environment. The older seven-cell Compose file is explicitly a deployment scaffold, not full-profile or transport acceptance evidence. - Preserved v1.0.0–v1.5.0 snapshots, historical release evidence, and independently versioned Blender/HyperFrames/vendor material. ## Verification - Documentation generation is idempotent; `docs:check` and all **74** documentation/configuration regressions pass. These checks include local web links/anchors, unique IDs, JSON-LD, current versions, canonical tool lists, script ordering, and release cache-busting. - CLI matrix: **80/80** profile/backend cases. Probe and inventory regressions: **4/4** each. Strict package/MCP/inventory/snapshot versions and revision pins: **11/11**. - Standalone integration and safe cross-cell checks: **15/15** across ten servers, with no tool-name collisions in the feature-disabled probe environment. - All eight profiles: **16/16** namespace-mode checks pass, with exact schemas, zero discovery startups, and safe read-only routing. - Fresh native ARM probes validate all eight `dev-workspace` cells against the new documentation revisions. Schema parity retains both verified Nucleus build digests; compiled implementation bytes were reused, not rebuilt as a new software release. - Browser checks: **64** visible configurator selections per language; **16** pages at **1200 px** and **390 px** widths without document-level horizontal overflow. Desktop/mobile screenshots were inspected. Canonical search links, successful copy, and denied-clipboard feedback were checked; failed clipboard writes no longer claim success. - Current Markdown file-link scan: **104** references checked, no missing targets. This is not an exhaustive external-link availability guarantee. - Secret scanning found only the pre-existing probe-test sentinel; no new credentials were added. Hardware, providers, and authenticated ACP/GUI sessions were not exercised by this documentation refresh. ## Publication boundaries Plastid and Receptor had unrelated remote dependency updates. Documentation-only commits were merged into their default branches without discarding those updates. Snapshot v1.5.1 deliberately pins the documentation-only parents, not unvalidated dependency changes. The Pages workflow validates generated documentation and its tests before publishing. Source commit: `7f95832b4f0b9e6ba3057ffbb7df84b62e2bcd91`. Published Pages commit: `3077d3f8d02436637b4322407c58621069dfe922`. - [Ecosystem CI](https://github.com/Hela-Ecosystem/hela-mcp-ecosystem/actions/runs/42233639731): successful. - [Validated site build/sync](https://github.com/Hela-Ecosystem/hela-mcp-ecosystem/actions/runs/42233639734): successful. - [GitHub Pages deployment](https://github.com/Hela-Ecosystem/hela-mcp-ecosystem/actions/runs/42233666134): successful. - Public checks at [hela.my.id](https://hela.my.id/) and its Indonesian pages: all **16** pages return HTTP 200 with v1.5.1 and versioned scripts; all **26** discovered internal resources return success. Generated data, app, stylesheet, counts, and the hero image load successfully. - Public browser configurators pass **64 selections per language**, with exact profile membership, current metadata, working canonical search links, and no desktop/mobile document overflow. No live runtime was restarted or reconfigured. Servy's service remained active at PID `715090`, with zero automatic restarts during native ARM catalog verification. Active databases, existing vault conflicts, security settings, credentials, and unrelated client configurations were not changed. Deferred endpoint security, authenticated ACP acceptance, deliberate external-client reloads, legacy gateway retirement, and conflict reconciliation remain separate work. --- # Source: docs/generated-profile-counts.md URL: https://hela.my.id/library/docs/generated-profile-counts.html # Generated profile counts Regenerate with `npm run catalog:generate`; includes `hela.pipe` and the agent alias where enabled. - `minimal`: 3 cells, 78–84 runtime tools. - `dev-workspace`: 8 cells, 230–236 runtime tools. - `headless-server`: 7 cells, 157–163 runtime tools. - `research`: 5 cells, 167–173 runtime tools. - `web-devops`: 6 cells, 178–184 runtime tools. - `android-testing`: 5 cells, 131–137 runtime tools. - `3d-modeling`: 5 cells, 92–98 runtime tools. - `all`: 10 cells, 291–297 runtime tools. --- # Source: docs/installation-acceptance.md URL: https://hela.my.id/library/docs/installation-acceptance.html # Installer acceptance β€” 2026-11-07 Local acceptance of the managed installer on Linux x86_64 with Node 22. This records working-tree changes, not a published release or a live-service rollout. Ecosystem release metadata remains 1.5.1; cells remain 3.0.0 and runtime 1.2.0. ## Real execution - All eight profiles passed all five modes: `individual`, `runtime`, `docker`, `docker-runtime`, and `nix` β€” 40 mode/profile checks. - Doctor verified 269 cell/runtime endpoints across those checks, including 24 private runtime HTTP probes. - All 320 profile/mode/client-format configurations passed structural checks. The generated Cursor-format commands were also executed: 162 actual client connections, including reconnects for persistence. - All 40 cases created an isolated Genome entity, restarted the client connection, and read the entity back. Runtime cases started no cells during discovery and only Genome on the first memory call. - The matrix reused freshly built isolated full-source artifacts, a Nix runtime package, and a full Docker image. These are **not 40 independent cold builds**. Native fixture repositories are linked into temporary prefixes; production installation still refuses symlinked source repositories. Separate real installations passed fresh doctor checks: native individual/minimal, native runtime/all, Nix/minimal with and without the model, Docker-runtime/all with the model, and Docker/minimal without it. The model-free Nix and Docker installations were checked to contain no Needle model. The Docker image default profile was checked as well. Explicitly started native, Nix, and Docker Compose HTTP listeners passed `doctor --url`, then were stopped. Compose attached stdio also passed a real Genome mutation/reconnect/read cycle using named volumes, with no published stdio ports. The isolated Compose projects and their test volumes were removed. No doctor containers remained after acceptance. Nix runtime output links were verified as GC roots. The runtime derivation can be reused from the local Nix store; cell dependencies are still installed from lockfiles and built in their managed source directories. The pinned Needle engine/model completed an actual offline tool-selection smoke test on both the host and the full Docker image, returning a successful `read_graph` call. This supplements engine execution, asset checksums, and license verification; it is not a planner-quality benchmark. ## Regression gates - 52 installer tests: profile/mode plans, isolated fixture installs and reinstalls, malformed options, snapshot/checkout failures and retry, repository origin/dirty/symlink refusal, output preservation, missing interpreters, changed builds, model checksum failures, HTTP protocol errors, and Docker cleanup on failure. - 74 documentation/configurator tests. - 80 standalone profile/client configuration cases. - Four MCP isolation/failure probes. - Documentation metadata consistency, shell syntax, and Git whitespace checks. The secret scan completed; its sole finding was the existing synthetic credential sentinel in the isolation test, not a credential. This is not a container CVE audit. ## Reproduce Build isolated fixtures first using the [installation guide](installation.md). The source fixture must include all ten cells plus runtime; the Docker fixture must contain the full image. Then run: ```bash npm run test:install npm run test:docs npm run test:matrix npm run test:probe npm run docs:check npm run test:install:modes -- \ --source-prefix /path/to/fresh-runtime-all \ --nix-prefix /path/to/fresh-nix-install \ --docker-prefix /path/to/fresh-docker-all \ --out /path/to/modes.json ``` The matrix uses temporary private workspaces/data directories and deletes only its own temporary fixtures. It does not reuse production databases, vaults, or provider credentials. Generated client defaults may advertise more optional tools than doctor's deliberately provider-disabled baseline. ## Boundaries Real installation acceptance here is Linux x86_64 only. The added CI jobs cover clean Docker/Nix installs and fixture regressions, but remote CI has not yet run for these working-tree changes. macOS, ARM64, and WSL cold installs were not repeated in this acceptance pass; native Windows remains untested. Browser executables, Android/Blender bridges, external providers, authenticated GUI/ACP clients, host device/SSH access from containers, and security hardening remain separate checks. `READY` certifies the stated MCP/install checks, not every tool's external integration. Existing services, databases, vault conflicts, and historical release snapshots were not migrated or replaced. --- # Source: docs/installation.md URL: https://hela.my.id/library/docs/installation.html # Installation modes and doctor ![Blotcat assembling a selected profile into a managed runtime](../assets/blotcat-installation.png) The installer supports eight profiles through five modes: `individual`, `runtime`, `docker`, `docker-runtime`, and `nix`. Runtime-based modes support stdio and Streamable HTTP. A mode selects the execution mechanism; a profile selects eligible cells. See [local acceptance evidence](installation-acceptance.md) for the tested mechanisms, real client connections, persistence checks, and platform/integration boundaries. ## Requirements and boundaries - Use Node 22+ and Git. Native modules need Python, make, a C/C++ compiler, and platform headers. `--mode nix` supplies a pinned development toolchain and packages the runtime with Nix. - Docker modes require a working Docker daemon and Compose v2. Their images build the selected cells from pinned source; they do not require host npm dependencies or per-cell Dockerfiles. - Supported shell entry points are Linux, macOS, and Windows through WSL. Native Windows installation is not acceptance-tested; several upstream build scripts require POSIX tools. - The pinned local Needle engine/model is installed by default on Linux x86_64/ARM64 and macOS ARM64. `--without-model` explicitly selects core MCP without that integration; it is needed on platforms without a pinned engine. Assets are fetched from an immutable upstream revision, checksum-verified, and accompanied by their license. - Chromium/browser services, Android devices/ADB, Blender/its bridge, provider credentials, and GUI client authentication remain separate integration requirements. `READY` does not certify those operations or provide an OS sandbox. Installation does not start a persistent service, change system packages, replace existing repositories, or rewrite live client settings. Endpoint security and credential rotation are not changed by this installer. ## Managed layout Default prefix: `${XDG_DATA_HOME:-$HOME/.local/share}/hela/installations/-`. Use `--prefix /absolute/path` to choose another directory. Each prefix contains its own ecosystem metadata, sibling source repositories, verified installation manifest, workspace, private data directories, and generated client fragments. Plastid is cloned at the repository root and built from `ll3m-mcp/brain`. The installer refuses unmanaged nonempty prefixes, dirty repositories, symlinked repositories, origin/pin/version mismatches, failed installs/builds, and existing explicit output files. A failed install retains a pending marker; doctor and launchers will not treat it as ready. Re-running the same installation performs locked dependency installation, rebuilds, and verifies it again. Existing data is not restored, reset, or deleted. ## Individual servers ```bash ./setup.sh --mode runtime --profile dev-workspace --client opencode --non-interactive ./setup.sh doctor --mode runtime --profile dev-workspace ``` Merge the generated private fragment into the client file after review. Native client entries start an installed launcher, which selects the correct executable, workspace, and persistent data directory. Unrelated client/provider settings are preserved because the installer never overwrites them. ## Single stdio runtime ```bash ./setup.sh --mode runtime --profile dev-workspace --client codex --non-interactive ./setup.sh doctor --mode runtime --profile dev-workspace ``` `--runtime` is an alias for `--mode runtime`. `--with-runtime` additionally builds the daemon for an individual installation without switching its client fragment to one connection. The selected-profile catalog is generated from fresh probes. Runtime verification checks exact cold catalog parity and zero cell startup, including its HTTP transport. The first actual cell call starts only its target. ## Docker: separate cells or runtime ```bash ./setup.sh --mode docker --profile dev-workspace --client cursor --non-interactive ./setup.sh doctor --mode docker --profile dev-workspace ./setup.sh --mode docker-runtime --profile dev-workspace --client opencode --non-interactive ./setup.sh doctor --mode docker-runtime --profile dev-workspace ``` `--client docker` remains a shortcut for a Docker installation with Compose output. Use `--runtime` with it for the aggregated daemon. Both Docker modes build one profile image; client entries call Docker directly with the immutable image ID, launching separate cell containers or one runtime container. Those stdio clients do not need a host Node runtime after installation. `compose.json` provides the equivalent Compose services. Filesystem, terminal, and process tools operate inside the container and explicitly mounted workspace. Host SSH keys, device access, external browser engines, and Blender bridges are not silently copied or granted; configure those integrations deliberately. Stdio needs attached stdin, not published ports. Compose services have `stdin_open: true`, no TTY, and persistent named volumes. Use `docker compose -f /path/to/compose.json run --rm --no-deps -T ` for an attached stdio connection; `up -d` alone does not connect an MCP client to stdio. Doctor starts uniquely named temporary containers with no host data/vault mounts or inherited provider keys, verifies actual MCP replies and image source provenance, and removes those containers. It does not stop existing containers or clean global images/volumes. ## Nix runtime ```bash ./setup.sh --mode nix --profile dev-workspace --client opencode --non-interactive ./setup.sh doctor --mode nix --profile dev-workspace ``` Nix supplies the pinned Node/native-build toolchain for cell builds and builds the runtime package. The installation's `nix-runtime` output link is retained as a GC root. This is a packaged runtime plus locked cell builds, not a claim that all ten cells are independent Nix derivations. Keep private files untracked; Git-backed flake references exclude ignored credentials and data from Nix source copies. ## HTTP runtime ```bash ./setup.sh --mode runtime --profile dev-workspace --transport http --port 8080 --client codex --non-interactive # Start the installed launcher explicitly; its path is printed by setup: node /path/to/prefix/hela-mcp-ecosystem/scripts/launch.mjs hela-runtime ./setup.sh doctor --url http://127.0.0.1:8080/mcp --json ``` The same transport flags work with `--mode nix` and `--mode docker-runtime`. HTTP listeners bind to loopback on the host. Docker publishes only `127.0.0.1:`; `compose.json` includes the HTTP command and port mapping. Explicitly start it with Compose `up -d` if desired. HTTP fragments are supported for OpenCode, Kilo, Codex, and Cursor. Other client backends fail clearly rather than emit unverified HTTP syntax; use `--client skip` and configure their MCP URL manually. No listener is auto-started during installation. Doctor's private HTTP probe does not substitute for checking the running URL. ## Snapshots, reconfiguration, and failures ```bash ./setup.sh --mode runtime --profile minimal --snapshot v1.5.1 --client skip --non-interactive ./setup.sh --reconfigure --prefix /path/to/existing/prefix --client zed --non-interactive ./setup.sh doctor --prefix /path/to/existing/prefix --json ``` Snapshots must declare exact commits and server versions. Incomplete historical metadata is rejected, not silently ignored. `--dev` follows recorded branches for host modes and records the resolved revisions/versions; Docker requires pinned snapshots. Optional provider keys are read from environment, not command-line secret flags. Generated fragments can contain those supplied credentials and are written with private permissions. Reconfiguration infers the existing mode/profile/transport from an explicit prefix and only generates another fragment. To change transport or port, rerun installation with the new settings; a stdio fragment must not point at an HTTP-only launcher. ## Switch modes in place `setup.sh mode` converts an existing managed installation to another execution mechanism without creating a second prefix or discarding data: ```bash ./setup.sh mode --prefix /path/to/existing/prefix --mode runtime --non-interactive ./setup.sh doctor --prefix /path/to/existing/prefix --json ./setup.sh mode --prefix /path/to/existing/prefix --mode docker-runtime --client opencode --non-interactive ``` Every mode is a valid target: `individual`, `runtime`, `docker`, `docker-runtime`, and `nix`. The profile, snapshot, workspace, and `data/` directories are preserved; only the artifacts the target mode needs are built. Host-mode switches reuse cells that already sit at the pinned revision with a clean worktree, so repeated conversions take seconds rather than rebuilding every package. Moving into a Docker mode builds the profile image; moving out deletes `compose.json`. Transport and port carry over unless `--transport` or `--port` is passed, and HTTP targets require a runtime mode. Switching to `--mode nix` must run inside Nix, exactly like a fresh Nix install. The command verifies the converted installation with the same doctor checks used after installation and generates a new client fragment when `--client` is supplied; it never edits live client settings. If verification fails, the previous manifest is restored, a pending marker is written, and the command exits nonzero so doctor reports the degraded state. A pending or unmanaged prefix is refused, and re-selecting the current mode is an error rather than a silent no-op. Doctor exits nonzero for missing or incomplete installations, modified builds, wrong revisions/versions, missing images, failed MCP replies, and runtime catalog/HTTP failures. A remote `--url` check verifies MCP initialize/discovery and the runtime version, not remote filesystem pins or hardware. Existing standalone sibling/nested checkouts remain diagnosable when no managed installation is selected. Never overwrite live SQLite files or force vault conflicts to resolve installation warnings. Use validated backups and a deliberate migration if you intend to move existing memory into a new managed prefix. --- # Source: docs/integration.md URL: https://hela.my.id/library/docs/integration.html # MCP client integration ![Blotcat connecting desktop clients](../assets/blotcat-integration.jpg) The canonical inventory and selected profile drive configuration. Do not copy old repository paths or hand-maintain a second list of servers. Current versions and counts are in [current versions](current-versions.md). The installer now creates a managed prefix and private client fragment instead of replacing live client files. Use `--mode individual`, `runtime`, `docker`, `docker-runtime`, or `nix`; see [installation modes](installation.md). Review and merge the generated fragment. Its launcher supplies the installed executable, workspace, data location, and selected profile. ## Generate configuration Use Node 22 LTS and build the selected cells first: ```bash ./setup.sh --mode runtime --profile dev-workspace --client opencode --non-interactive ``` To inspect a generated file without installing it into a client: ```bash node scripts/generate-config.mjs --profile dev-workspace --client opencode \ --root /absolute/path/to/MCPservers/hela-mcp-ecosystem --stdout ``` For manually maintained repositories, `--root` points to the ecosystem checkout and cell directories normally sit beside it. For a managed installation, add `--prefix /path/to/prefix --mode ` to generate a fragment using its verified launchers and metadata. Plastid's package is `ll3m-mcp/brain`, not its Git repository root. Output may contain credentials supplied through environment variables or options. Do not publish generated private configuration. The committed examples use placeholders and no real keys. ## Client formats and locations - **Cursor:** `mcpServers` JSON in `~/.cursor/mcp.json`. - **Claude:** `mcpServers` JSON. Claude Desktop commonly uses `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%/Claude/claude_desktop_config.json` on Windows, and `~/.config/Claude/claude_desktop_config.json` on Linux; CLI integrations can use a different location. Confirm the file used by your installed client. - **Gemini / Antigravity:** `mcpServers` JSON; the installer supports the configured Gemini/Antigravity path. Confirm your client version's actual file before merging. - **OpenCode / Kilo:** `mcp` JSON. Local entries have `type: "local"` and a command array. - **Zed:** `context_servers` JSON in `~/.config/zed/settings.json`. Preserve unrelated settings and shared server definitions. - **Codex:** TOML under **`[mcp_servers.]`**, not `[mcpServers.]`, in `~/.codex/config.toml`. Generate a private output file with `--out ` and review/merge it instead of replacing an existing client configuration blindly. Eight profiles and ten generator backends, including Docker and skip, are checked by the CLI matrix. Browser previews use placeholder paths; the CLI is the installation/configuration source. ## Single-endpoint runtime Keep the selected profile and add the serve-mode flag: ```bash ./setup.sh --profile dev-workspace --client opencode --runtime --non-interactive ``` There is no `runtime` profile. `HELA_PROFILE` selects eligible cells and defaults to `minimal` when unset. Runtime startup and discovery spawn no cells; a call starts only its target. Standalone server definitions remain supported for installations that do not use the runtime. The installer generates the selected-profile schema catalog. After rebuilding a cell: ```bash npm run catalog:generate -- --profile dev-workspace ./setup.sh doctor --profile dev-workspace --runtime ``` See [on-demand runtime](on-demand-runtime.md) for stale-cache refusal and explicit `hela.pipe` bootstrap. A healthy HTTP liveness endpoint alone is not full MCP or external-integration acceptance evidence. ## Zed and Codex ACP ownership Codex-native MCP entries and Zed-forwarded entries can have the same name. A duplicate warning can refer to the forwarded duplicate rather than failure of the native entry. `codex mcp list` inspects configuration; it does not execute servers or prove connectivity. Do not remove shared top-level Zed definitions as a workaround: native Zed and other agents may need them. Native agent-profile permissions are not a per-ACP forwarding switch. Authenticated ACP/GUI warning verification remains separate from isolated MCP discovery. See the adapter-version-specific guidance in [troubleshooting](troubleshooting.md#zed-forwards-a-server-that-codex-already-defines); the optional merge override is not enabled by this guide. ## Keys and optional services GitHub tokens are optional for live remote prompt/catalog operations. Enzyme can use keyless network fallbacks when Google CSE credentials are absent; configured CSE uses `GOOGLE_API_KEY` and **`GOOGLE_CSE_ID`**. Model-backed tools require their configured engine/provider. SQLite remains Genome's base engine; Obsidian and Redis are optional. Read [keys and services](keys-and-secrets.md) and the selected server's generated canonical tool reference. ## Docker installations Use the installer to build and verify a selected-profile image before generating/using its client fragment: ```bash ./setup.sh --mode docker --profile headless-server --client docker --non-interactive ./setup.sh doctor --mode docker --profile headless-server ``` `compose.json` uses the built image ID, actual entrypoints, attached stdio without a TTY, and persistent volumes. `--mode docker-runtime` selects one runtime container. Add `--transport http` only for runtime-based modes; the installer generates loopback-only HTTP settings and leaves listener startup explicit. The older seven-cell `config/docker-compose.yml` is historical scaffolding, not the supported installer path. Hardware and provider integrations are still separate. ## Acceptance and reloads ```bash ./setup.sh doctor --profile dev-workspace --runtime npm run test:matrix npm run docs:check ``` Use `--runtime` only when that runtime is installed. Run full-stack integration/profile tests on a machine with the required cells, or select the installed subset. Reload only the relevant clients after review; some clients auto-reload immediately on settings changes. Back up live databases/vaults before changing synchronization hooks. Do not restore over active SQLite files, force a vault conflict winner, or kill unrelated processes during verification. Powerful filesystem, command, browser, and agent tools run with their server account's privileges. Current verification is not a security sandbox or authenticated-public-endpoint guarantee; see [security status](security-audit.md). --- # Source: docs/keys-and-secrets.md URL: https://hela.my.id/library/docs/keys-and-secrets.html # HeLa MCP Ecosystem: Keys & Secrets Guide ![Blotcat Secrets & Credentials Vault](../assets/blotcat-secrets.jpg) This document explains prerequisites and optional provider credentials. Keyless operation is not the same as offline operation or a guarantee of free/unlimited external services. See [current versions](current-versions.md) for software metadata and [security status](security-audit.md) for unresolved access-control work. --- ## 1. System Prerequisites Before running setup, ensure your system meets the baseline requirements: - **Node.js:** 22 LTS is the tested full-stack environment. Enzyme requires at least 20.18.1 and Receptor requires 22; other packages declare their own standalone ranges. - **npm:** use the version bundled with the selected Node runtime and install locked dependencies with `npm ci`; no global npm upgrade is required by this guide. - **Git:** use a current version (release snapshots specify at least 2.30). - **SQLite:** Genome uses Node SQLite bindings; the SQLite CLI is optional for inspection. Do not replace active database files during upgrades. - **Docker/Compose:** optional, and generated Compose files are scaffolds requiring transport/device/persistence review. --- ## 2. Keys & Secrets Catalog Provider credentials are optional for MCP discovery and keyless capabilities. A selected external operation can still require credentials, network access, an installed local engine, or a live external service. ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ HELA MCP KEY MATRIX β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”‚ Secret Name β”‚ Target Component β”‚ Necessity β”‚ Fallback β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”‚ OPENROUTER_API_KEY β”‚ HeLa Mitosis β”‚ Optional β”‚ Local* β”‚ β”‚ GITHUB_TOKEN β”‚ HeLa Mitosis β”‚ Optional β”‚ Bundled β”‚ β”‚ GOOGLE_API_KEY β”‚ HeLa Enzyme β”‚ Optional β”‚ Wikipedia β”‚ β”‚ GOOGLE_CSE_ID β”‚ HeLa Enzyme β”‚ Optional β”‚ Wikipedia β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` `Local*` depends on the bundled/configured Needle engine and model. The matrix is not a guarantee that every tool can complete without its required provider or hardware. --- ### 1. `OPENROUTER_API_KEY` * **Target Component**: **HeLa Mitosis** (`hela-mitosis` / `chaining-mcp`) * **Purpose**: Powers dynamic LLM intelligence for task decomposition (`llm_decompose_task`), AI route ranking (`llm_suggest_route`), and query routing (`llm_query`). * **Where to get it**: 1. Visit [OpenRouter API Keys](https://openrouter.ai/keys). 2. Create a free account. 3. Generate an API key (`sk-or-v1-...`). 4. Provider model availability, quotas, and pricing can change; check the provider before relying on a free route. * **If you DO NOT have it**: * **Consequence**: Provider-backed calls need some configured provider credentials; another configured provider can still be used when supported. Local planning can work without keys when its engine/model are available. * **Fallback Behavior**: Needle planning/execution and budgeted escalation are separate. Unavailable escalation can hand control back to the caller; `brainstorming` needs a generative model and fails when none is configured. This is not a universal latency, crash-freedom, or offline guarantee. --- ### 2. `GITHUB_TOKEN` * **Target Component**: **HeLa Mitosis** (`hela-mitosis` / `chaining-mcp`) * **Purpose**: Synchronizes the latest community prompt collections, guidelines, and chatmodes from GitHub repositories at runtime. * **Where to get it**: 1. Visit [GitHub Personal Access Tokens](https://github.com/settings/tokens). 2. Generate a token with public read-only access. * **If you DO NOT have it**: * **Consequence**: Live GitHub syncing is disabled. * **Fallback Behavior**: Bundled prompt/instruction catalogs remain available. This does not make unrelated research, browser, provider, or remote-runtime operations offline. --- ### 3. `GOOGLE_API_KEY` & `GOOGLE_CSE_ID` * **Target Component**: **HeLa Enzyme** (`hela-enzyme` / `researcher-mcp`) * **Purpose**: Optional Tier 1 web search queries via the Google Custom Search JSON API. * **Where to get them**: 1. **API Key**: Use [Google Cloud Console](https://console.cloud.google.com/apis/credentials) and check current Custom Search API availability and quotas for your account. 2. **CSE ID**: Create a Search Engine ID at [Programmable Search Engine](https://programmablesearchengine.google.com/controlpanel/all) (set Search the entire web = ON). * **If you DO NOT have them**: * **Consequence**: Configured Google CSE is unavailable; supported keyless network fallbacks may still work. Network failures, rate limits, and provider availability remain possible. * **Fallback Behavior**: Live web search cascades to keyless parallel search (DuckDuckGo, Bing, etc.) and Wikipedia fallback. `academic_search` queries arXiv's public OpenSearch API, `news_monitor` queries Google News RSS feeds, `search_trends` queries Hacker News Algolia, and content extraction falls back to Jina Reader (`r.jina.ai`). --- ## 3. Configuration & Diagnostics ### Initial Setup Run the setup script: ```bash ./setup.sh ``` The installer reads optional provider keys from environment and never prompts for or accepts secret values as CLI flags. Keyless defaults can still use the network. Generated private client fragments can contain supplied credentials; review them before sharing, and merge them into client settings deliberately. ### Reconfiguring Keys Anytime To update keys or change clients on an installed ecosystem: ```bash ./setup.sh --reconfigure ``` ### Safe Diagnostic Health Check To verify your environment and check which fallbacks are active without exposing keys in logs: ```bash ./setup.sh doctor ``` --- # Source: docs/on-demand-runtime.md URL: https://hela.my.id/library/docs/on-demand-runtime.html # On-demand runtime and canonical discovery ![Blotcat waking one selected cell while the other runtime cells sleep](../assets/blotcat-on-demand-runtime.png) Runtime **1.2.0** implements Β§10.3: no cell starts during runtime startup or `tools/list`. The first call starts only its target; concurrent calls share that startup. Cells already started retain the existing crash/timeout supervisor. Standalone MCP servers are unchanged, all eight profiles remain supported, and the runtime/installer default is `minimal` when no profile is selected. The same endpoint owns profile-aware agent instructions. `prompts/list` exposes `hela-profile-bootstrap`, `prompts/get` renders it from the selected profile, and `resources/read` serves `hela://profile/context`. Clients should consume that runtime context instead of copying a static persona prompt or deploying each cell as a separate MCP server. ## One inventory, generated schemas and counts `config/inventory.json` remains the source of cell paths, revisions, versions, environment declarations, and conditional tool features. `config/profiles.json` selects membership. Config generation, doctor, version verification, integration, and profile tests use the same inventory loader/path resolution. The generated `config/tool-catalog.json` contains actual standalone MCP schemas, revision/version metadata, verified build digests, and feature variants. It is a derived artifact, not another server registry. Mitosis currently has four LLM/agent feature combinations; other cells have one schema variant. The generator enables registration flags only for discovery and never invokes model-backed tools. Build outputs can differ between machines even at one source revision. Multiple digests are retained together only if fresh probes return identical schemas for every declared variant. New or changed conditional tool registration must declare its switches under the cell's `toolFeatures`; other relevant settings belong in its `env` list. Configuration changes require a new runtime instance. Run from the ecosystem checkout after building the selected cells and runtime: ```bash npm run catalog:generate -- --profile dev-workspace npm run catalog:check -- --profile dev-workspace ./setup.sh doctor --profile dev-workspace --runtime npm run test:profiles -- --profile dev-workspace ``` The installer refreshes selected-profile catalog entries when installing the runtime. Partial installations do not need unrelated hardware cells. An installation with all cells can omit the profile argument to generate/check all entries. The same generator writes [profile-count documentation](generated-profile-counts.md) and `docs/site/data/tool-counts.json`. Counts include `hela.pipe` and the optional agent alias; they are feature-dependent ranges, not fixed totals copied into each client configuration. ## Cache isolation and stale metadata The format-2 private cache separates ecosystem roots, profiles, and namespace modes. Per-cell fingerprints cover declared and actual revisions, build contents, effective feature flags, and declared environment settings. Cache files contain fingerprints and schemas only, not environment values. Atomic publication prevents partial reads. Legacy, corrupt, and mismatched cache entries are ignored. A valid generated catalog supplies cold schemas without child processes. Missing/stale catalog entries are not advertised. Unknown calls do not scan other cells. Explicit `hela.pipe` routing can start an uncatalogued named cell and learn its schemas; regenerating the catalog restores full cold discovery. Doctor validates selected paths/builds, real isolated MCP handshakes, package/inventory/snapshot versions and revisions, andβ€”when `--runtime` is requestedβ€”exact catalog/tool agreement with zero discovery spawns. Hardware checks are limited to the selected profile and remain separate from MCP readiness. API-key checks report presence, never values or assumed provider readiness. ## Verification scope - **32/32** runtime regressions pass on x86_64 Linux and native ARM, covering timeout recovery, lazy startup, 24 concurrent first calls, cache invalidation, profile/root/namespace switching, legacy/corrupt caches, explicit bootstrap, and shutdown. **41 fixture PIDs** per run were verified reaped. - All eight profiles pass **16/16** namespace-off/on discovery/schema/routing checks. Discovery starts zero cells; only the safe Genome/Nucleus probes start those cells. Cold discovery, cold first-call, and warm-call durations are recorded in JSON output without asserting machine-independent latency limits. - The **80** client-configuration combinations, four probe regressions, and four canonical inventory regressions pass. Default standalone integration now excludes the multiplexing runtime from collision comparisons. - Eight additional runtime discovery checks cover all four Mitosis feature combinations in both namespace modes, without invoking model tools or starting cells. Doctor reports READY with cold catalog parity for all eight profiles. - Reproducible Nix packages use Node 22.23.4 and pinned/fixed-output inputs on both Linux architectures. Runtime versions derive from package metadata. These checks do not authenticate GUI ACP sessions, reconcile live vault conflicts, exercise Android/Blender hardware, invoke model providers, or complete deferred endpoint security. Lappy retains its ten-server roster; servy retains its eight-cell `dev-workspace` selection. ## Verified servy rollout Runtime source `9c92dbf5612db43fe80f1680ba4af97c4b5ea9b0` and ecosystem source release `1c47ca1c202c6a2acea79d7c6fdac5a19ef3c0bf` are deployed. Final-source Nix outputs are: - x86_64-linux: `/nix/store/r15rmywrswf01nj2xrvx753p1fh4f6rh-hela-runtime-1.2.0`. - aarch64-linux: `/nix/store/bhm781bld50yi9brmy2mn74p1ybzdzcy-hela-runtime-1.2.0`. The ARM package is rooted under `/home/ubuntu/.local/state/hela/deployments/todo103-psnzx8x4/runtime`. Promotion fast-forwarded clean source checkouts, retained the old build/drop-in, and took fresh integrity-checked online backups of three databases plus a vault archive. Existing profile, environment, host, port, and security settings were preserved; only the selected runtime executable changed. Local and public HTTP initialize/discovery report runtime **1.2.0**, **236 unique tools**, all three Genome mission tools, and no hardware-only tools. Both discovery checks left the service with **zero child cells**. A safe `terminal_session_list` call started only Nucleus; Genome did not start. Observed Nucleus calls were approximately **471 ms cold** and **13 ms warm** in this one run, including HTTP/MCP overheadβ€”not a portable benchmark. Deployed doctor reports READY, catalog parity is exact, revision checks pass, and the GC root is verified. All previous HTTP-service PIDs exited. All **633** pre-rollout conflict archive files retained their hashes. No database file was restored/replaced, and unrelated client-owned runtimes and the legacy PM2 gateway were not stopped. The rollout directory contains `manifest.json`, `http-verification.json`, `doctor.log`, `versions.log`, `catalog.log`, `backup/`, `rollback-dist/`, and the package GC root. Native committed-source staging/test evidence remains under `/home/ubuntu/.local/state/hela/staging/todo103-release-ah25pauz/`; local test/measurement logs are under `/var/tmp/scratch/opencode/todo103/`. Authenticated ACP, deliberate external-client reloads, gateway consumer review, vault reconciliation, and deferred security remain separate. --- # Source: docs/profile-verification-2026-11-06.md URL: https://hela.my.id/library/docs/profile-verification-2026-11-06.html # All-profile verification β€” 2026-11-06 HeLa changes apply to the shared servers/runtime, not a hardcoded lappy or servy configuration. Each installation keeps its selected profile. The runtime default remains `dev-workspace`; the distribution does not force everyone to `all`. Machine configurations were preserved: - Lappy has all ten standalone HeLa servers, equivalent to the `all` roster. Ten native Codex definitions were confirmed without printing environment values or credentials. This does not mean every client uses a single `HELA_PROFILE=all` runtime. - Servy's systemd HTTP runtime selects `dev-workspace`, eight cells. The profile is not named `dev-workflow`. Receptor and Plastid remain intentionally absent there. - Other installations can select any of the eight profiles in `config/profiles.json`. ## Acceptance checks The new `npm run test:profiles` command passed on lappy for all eight profiles: `minimal`, `dev-workspace`, `headless-server`, `research`, `web-devops`, `android-testing`, `3d-modeling`, and `all`. Each profile runs twice, with namespacing off and on: **16/16 runtime checks**. The verifier obtains actual tool schemas from the ten standalone cells, then checks that each runtime: - Advertises exactly the selected cells. Runtime 1.2.0 starts none during discovery and only starts the safely invoked cells during routing checks; see the [on-demand follow-up](on-demand-runtime.md). - Exposes exactly their tools plus `hela.pipe`, without collisions or out-of-profile tools. - Preserves each tool's input schema, including namespaced tool names. - Includes all three Genome mission tools. - Routes a safe Genome read-only call, plus a Nucleus session-list call where selected. With model-backed features disabled, the `all` runtime exposes **291 tools**: 290 standalone tools plus `hela.pipe`. `dev-workspace` exposes **230** under the same conditions. Servy's feature-enabled live runtime exposes **236**; those feature-dependent differences are not profile failures. Strict package/initialize/inventory/snapshot/revision verification also passes for all ten cells and runtime. The client-generation matrix passes **80/80** profile/client combinations. Probe regressions pass **4/4**, including explicit profile/namespacing isolation from the host environment. All probes use disposable HOME/project/central-memory locations, excluding inherited credentials and live vault hooks. Model, Android, and Blender operations were not invoked. These checks establish MCP startup/discovery/schema/routing support, not hardware integration or authenticated GUI sessions. Published release snapshots were not rewritten to backdate this additional evidence. ## Repeating the checks From the ecosystem checkout, using Node 22: ```bash npm run test:profiles npm run test:profiles -- --json node scripts/verify-versions.mjs --profile all npm run test:matrix npm run test:probe ``` The full matrix requires all ten cells to be installed and built. A machine with only one selected profile can test that profile without installing unrelated hardware cells: ```bash npm run test:profiles -- --profile dev-workspace ``` Missing required builds fail explicitly rather than silently skipping a profile. This command starts isolated test processes; it does not rewrite client configuration, change the live profile, or restart a service. --- # Source: docs/profiles.md URL: https://hela.my.id/library/docs/profiles.html # HeLa MCP Ecosystem β€” Profile & Agent Persona Catalog ![Blotcat Profile Selection & Specialization](../assets/blotcat-profiles.jpg) The HeLa MCP Ecosystem organizes capabilities into **agent-oriented profiles**. Each profile pairs the two foundational backbone servers (**HeLa Mitosis** for orchestration and **HeLa Genome** for persistent state) with a tailored set of specialized capability servers. --- ## The Backbone Foundation Every profile in the ecosystem includes the core dual backbone: * **HeLa Mitosis (`hela-mitosis` / `chaining-mcp`)**: Intelligent tool discovery, Needle-planned routing, Needle-backed sequential thinking, task decomposition, skills catalog, and workflow orchestration. * **HeLa Genome (`hela-genome` / `project-mcp`)**: Living SQLite knowledge graph (`memory.db`), task tracking, architectural decisions, and cross-session context restoration. ![Blotcat carrying runtime memory between context nodes](../assets/blotcat-illustrations/03-project-guardian-memory.jpg) --- ## Profile Catalog There are eight profiles. The canonical membership is `config/profiles.json`; current versions and generated tool counts are in [current versions](current-versions.md) and [profile counts](generated-profile-counts.md). ![Blotcat sorting profile choices between GUI and headless work](../assets/blotcat-illustrations/01-profile-selection.jpg) ### `minimal` β€” HeLa Minimal Three servers: `hela-mitosis`, `hela-genome`, and `hela-enzyme`. This is the smallest research/memory stack; it does not require browser, Android, or Blender dependencies. Keyless research still uses the network. ### 1. `dev-workspace` β€” HeLa Dev Workspace * **Target System:** GUI / Desktop Workstation * **Agent Persona:** Full-Stack Software Engineer & Desktop Workstation Agent * **Purpose:** Complete autonomous software development, testing, UI design, and browser verification. * **Included Servers (8 Servers):** * Backbone: `HeLa Mitosis` (`hela-mitosis`), `HeLa Genome` (`hela-genome`) * Workspace: `HeLa Membrane` (`hela-membrane`), `HeLa Nucleus` (`hela-nucleus`), `HeLa Ribosome` (`hela-ribosome`) * Knowledge: `HeLa Enzyme` (`hela-enzyme`) * Design & Web: `HeLa Phenotype` (`hela-phenotype`), `HeLa Cytosol` (`hela-cytosol`) * **Standard Workflow:** 1. Genome restores project history and open tasks. 2. Mitosis decomposes feature requirements into steps. 3. Membrane and Nucleus inspect code, run builds, and execute tests. 4. Phenotype generates design tokens and Tailwind components. 5. Cytosol validates web UI visually via Playwright. 6. Genome records decisions, test results, and observations. --- ### 2. `headless-server` β€” HeLa Headless Server (Core 7) * **Target System:** Headless Linux Server / CI/CD Runner / Remote VM * **Agent Persona:** Cloud Infrastructure, Headless Server & CI/CD Automation Agent * **Purpose:** Autonomous server management, CI/CD pipeline execution, background harness orchestration, and repository maintenance without requiring display servers. * **Included Servers (7 Servers):** * Backbone: `HeLa Mitosis` (`hela-mitosis`), `HeLa Genome` (`hela-genome`) * Workspace: `HeLa Membrane` (`hela-membrane`), `HeLa Nucleus` (`hela-nucleus`), `HeLa Ribosome` (`hela-ribosome`) * Knowledge: `HeLa Enzyme` (`hela-enzyme`) * Design: `HeLa Phenotype` (`hela-phenotype`) * **Standard Workflow:** 1. Genome restores environment state. 2. Mitosis plans deployment or maintenance sequence. 3. Ribosome spawns and monitors long-running background PTY tasks. 4. Nucleus executes terminal commands and RTK-optimized queries. 5. Enzyme researches technical documentation or package dependencies. 6. Genome tracks task completion. --- ### 3. `research` β€” HeLa Research Terminal * **Target System:** Headless / Desktop * **Agent Persona:** Deep Research Investigator & Technical Knowledge Synthesizer * **Purpose:** Multi-source research, web scraping, literature analysis, fact-checking, and structured documentation generation. * **Included Servers (5 Servers):** * Backbone: `HeLa Mitosis` (`hela-mitosis`), `HeLa Genome` (`hela-genome`) * Knowledge: `HeLa Enzyme` (`hela-enzyme`) * Workspace: `HeLa Membrane` (`hela-membrane`) * Interaction: `HeLa Cytosol` (`hela-cytosol`) * **Standard Workflow:** 1. Genome restores research topic and prior facts. 2. Mitosis constructs research query plan. 3. Enzyme queries Google Search and Wikipedia. 4. Cytosol extracts full article content from web pages. 5. Membrane writes research synthesis to markdown files. 6. Genome stores discovered facts into the knowledge graph. --- ### 4. `web-devops` β€” HeLa Web Dev + Browser Automation * **Target System:** GUI / Desktop * **Agent Persona:** Frontend Engineer & Web Verification Specialist * **Purpose:** Frontend component creation, design token synchronization, automated browser testing, and visual regression checking. * **Included Servers (6 Servers):** * Backbone: `HeLa Mitosis` (`hela-mitosis`), `HeLa Genome` (`hela-genome`) * Workspace: `HeLa Membrane` (`hela-membrane`), `HeLa Nucleus` (`hela-nucleus`) * Design: `HeLa Phenotype` (`hela-phenotype`) * Interaction: `HeLa Cytosol` (`hela-cytosol`) * **Standard Workflow:** 1. Genome restores frontend specifications. 2. Phenotype generates OKLCH tokens and Tailwind configuration. 3. Membrane creates component files. 4. Nucleus starts local development server. 5. Cytosol navigates, interacts, and captures screenshot verification. 6. Genome records UI validation results. --- ### 5. `android-testing` β€” HeLa Android Testing Rig * **Target System:** GUI / Mobile Automation Host (requires `adb` and USB/Wi-Fi connected device) * **Agent Persona:** Mobile QA Tester & Android Device Automation Engineer * **Purpose:** Mobile application testing, UI interaction, ADB automation, and mobile debugging. * **Included Servers (5 Servers):** * Backbone: `HeLa Mitosis` (`hela-mitosis`), `HeLa Genome` (`hela-genome`) * Workspace: `HeLa Nucleus` (`hela-nucleus`) * Mobile: `HeLa Receptor` (`hela-receptor`) * Knowledge: `HeLa Enzyme` (`hela-enzyme`) * **Standard Workflow:** 1. Genome restores issue ticket. 2. Nucleus inspects build outputs and logcat streams. 3. Receptor connects to device, inspects UI XML tree, and executes tap/swipe gestures. 4. Enzyme investigates error codes or crash logs. 5. Genome records reproduction steps and bug resolution. --- ### 6. `3d-modeling` β€” HeLa 3D / Blender Station * **Target System:** GUI / Workstation (requires local Blender 3.6+ installation) * **Agent Persona:** Generative 3D Artist & Blender Scene Architect * **Purpose:** Autonomous 3D modeling, procedural mesh generation, material assignment, scene composition, and rendering in Blender. * **Included Servers (5 Servers):** * Backbone: `HeLa Mitosis` (`hela-mitosis`), `HeLa Genome` (`hela-genome`) * 3D: `HeLa Plastid` (`hela-plastid`) * Workspace: `HeLa Membrane` (`hela-membrane`), `HeLa Nucleus` (`hela-nucleus`) * **Standard Workflow:** 1. Genome restores 3D project requirements. 2. Mitosis breaks down 3D asset generation stages. 3. Plastid generates and executes Python scripts inside Blender. 4. Membrane saves generated `.blend` scene and rendered `.png` images. 5. Genome records asset metadata and scene relations. --- ### 7. `all` β€” HeLa All (Full 10-MCP Stack) * **Target System:** Any / Fully-Equipped Workstation * **Agent Persona:** Complete HeLa Autonomous Engineering Multi-Agent Stack * **Purpose:** Unrestricted access to all 10 servers in the ecosystem. * **Included Servers (10 Servers):** * `hela-mitosis`, `hela-genome`, `hela-membrane`, `hela-nucleus`, `hela-ribosome`, `hela-enzyme`, `hela-cytosol`, `hela-phenotype`, `hela-receptor`, `hela-plastid` ### Runtime serve mode (orthogonal to profiles) The HeLa Runtime is **not a profile** β€” it is a serve method. Any profile can be served through the runtime: ```bash ./setup.sh --profile dev-workspace --client opencode --runtime # builds dev-workspace cells + daemon HELA_PROFILE=minimal node hela-runtime/dist/index.js # run with minimal profile ``` The runtime advertises only the selected cells' schemas and starts each cell only when invoked. Discovery starts none. Use `--runtime` with any profile; `HELA_PROFILE` selects eligible cells and defaults to `minimal` when unset. Standalone servers remain supported. --- ## Profile Compatibility Matrix: | Profile ID | Target System | Total Servers | Backbone Servers | Headless Compatible | Requires External Runtime / Device | |---|---|:---:|:---:|:---:|---| | `minimal` | Any / Headless | 3 | Mitosis + Genome | Yes | Network for online research | | `dev-workspace` | GUI / Desktop | 8 | Mitosis + Genome | Yes (Playwright) | Playwright / Chromium | | `headless-server` | Headless | 7 | Mitosis + Genome | Yes | None | | `research` | Headless / GUI | 5 | Mitosis + Genome | Yes | None | | `web-devops` | GUI / Desktop | 6 | Mitosis + Genome | Yes (Playwright) | Playwright / Chromium | | `android-testing` | Device Host | 5 | Mitosis + Genome | No | `adb` + Android Device | | `3d-modeling` | Workstation | 5 | Mitosis + Genome | No | Blender CLI | | `all` | Full Host | 10 | Mitosis + Genome | Partial | Playwright, `adb`, Blender | --- # Source: docs/security-audit.md URL: https://hela.my.id/library/docs/security-audit.html # Security status and verification scope ![Blotcat placing an API key into a local vault while untrusted inputs stay outside](../assets/blotcat-security-v2.png) This is an operational status document, **not a completed security certification**. Earlier architecture descriptions overstated guarantees about sandboxing, credential isolation, offline operation, and test coverage. A process boundary, a profile, or a passing health endpoint does not establish those guarantees. ## Explicitly deferred work Endpoint authentication, per-client authorization, exposed-credential rotation, public-exposure review, and resource/session limits remain deferred by the operator's development decision. Deferred does not mean implemented or safe for unrestricted public use. The documentation refresh does not change access controls or rotate credentials. Filesystem, shell, PTY, browser, model-agent, and device operations can act with the server account's privileges. Scope and deploy them accordingly. Runtime profiles select eligible cells; they are not a substitute for an authorization policy or an OS sandbox. ## What the current checks establish - Source snapshots pin revisions. Runtime schema catalogs additionally validate versions/build digests and declared feature variants; private caches separate profiles, roots, namespace modes, revisions, builds, and declared configuration. - Isolated tests cover runtime timeouts, process exit before restart, bounded retries, first-call startup, concurrent calls, stale-cache refusal, and shutdown. This is lifecycle/reliability evidence, not complete adversarial testing. - Doctor checks real isolated MCP initialize/discovery, selected paths/versions/revisions, and optional runtime catalog parity. Hardware, provider, and authenticated GUI checks remain separate. - Genome's online backups include committed WAL data and validate integrity; restore refuses existing destinations and sidecars. This does not authorize overwriting an active database. - Vault synchronization preserves divergent notes in conflict archives. Archived conflicts still need deliberate review; transport success does not prove reconciliation. See [runtime verification](on-demand-runtime.md), [profile verification](profile-verification-2026-11-06.md), and each server's current tool reference for exact scope. Do not promote historical benchmark/test totals into current security claims. ## Credentials and generated output Doctor and schema-generation probes do not display credential values; isolated probes exclude inherited keys and live vault hooks. Generated client configuration, however, can contain credentials explicitly supplied by its user. Treat configuration files, generator stdout, backups, and issue attachments as private. Never paste a raw client configuration or process environment into a public issue. Presence of an API key does not prove provider readiness. Keyless research can still make network requests. Needle's local execution depends on its engine/model, and some generative operations need a configured model provider. Optional remote runtime/vault deployment also changes where data is processed and stored. ## Carry-forward validation PTY orphan handling, SSH failures/transfers, browser network boundaries, archive/symlink policies, Android hardware, Blender execution, live search fallbacks, and external design services still need their own targeted checks. Tests for some of these exist, but full coverage is not implied by ecosystem configuration or discovery checks. Current package versions and generated counts are in [current versions](current-versions.md). Historical release notes and immutable snapshots retain their original versions and evidence; they are not current acceptance guarantees. --- # Source: docs/troubleshooting.md URL: https://hela.my.id/library/docs/troubleshooting.html # HeLa MCP Ecosystem Troubleshooting & Diagnostic Guide This guide provides systematic diagnostic procedures, error code explanations, and recovery workflows for the **HeLa MCP Ecosystem**. ![Blotcat wearing a hard hat, looking at a smoking server block while consulting a thick manual](../assets/blotcat-troubleshooting.jpg) --- ## 1. Fast Diagnostic Workflow: `setup.sh doctor` Before manual debugging, always run the automated diagnostic health check: ```bash ./setup.sh doctor # or npm run doctor ``` To run diagnostics against a specific profile: ```bash ./setup.sh doctor --profile dev-workspace ``` To output machine-readable JSON: ```bash ./setup.sh doctor --json ``` For managed installations, select the installed `--mode` and profile, or use an explicit prefix: ```bash ./setup.sh doctor --prefix /path/to/prefix --json ./setup.sh doctor --url http://127.0.0.1:8080/mcp --json ``` The URL form checks an already-running HTTP endpoint, not its remote filesystem. See [installation modes](installation.md) for Docker, Nix, listener startup, and private client fragments. ### Understanding Diagnostic Output * **`READY`**: Managed source/build/image identity and isolated MCP initialize/discovery checks passed. Runtime modes also check cold catalog parity and private HTTP discovery. * **`DEGRADED` / server `ERROR`**: A required check failed; inspect the JSON report for its server/error. Pending installations, changed builds, missing interpreters/images, and bad MCP replies fail readiness and return nonzero. * **Integration scope**: Discovery does not verify Playwright executables, Android/Blender bridges, provider credentials, GUI authentication, or arbitrary workspace access. Legacy unmanaged checkout diagnostics have a different report layout. --- ## 2. Common Issues & Recovery Procedures ### 2.1 Diagnostic Failure: Missing Entrypoint or Build Artifacts **Symptom**: `[ERROR] Entrypoint file missing` or `dist/index.js not found`. **Root Cause**: The TypeScript source code has not been compiled into JavaScript build artifacts. **Fix**: For a managed prefix, rerun the original setup command with the same mode/profile/prefix. Locked dependencies and selected builds are recreated and probed. Preserve dirty working-tree changes rather than resetting them. A pending marker is cleared only after successful verification. For manually maintained sibling checkouts: ```bash # Rebuild all 10 servers automatically npm run build:all # Or build a single server manually cd npm run build ``` --- ### 2.2 Server Stdio JSON-RPC Hang or Crash **Symptom**: `[ERROR] Exited early with code 1` or tool timeouts during execution. **Root Cause**: Node module dependencies are missing, or environment variables are malformed. **Fix**: ```bash # Reinstall dependencies for the failing server cd npm ci npm run build ``` Verify stdio responsiveness manually: ```bash node # The process should listen on stdin without throwing an uncaught exception. Press Ctrl+C to exit. ``` --- ### 2.3 Client Does Not Recognize Configured MCP Servers **Symptom**: Cursor, Claude, Gemini, or Zed reports that tools are not available. **Root Cause**: Configuration file was written to the wrong path, contains relative paths, or the client was not restarted. **Fix**: 1. **Regenerate configuration with absolute paths**: ```bash ./setup.sh --reconfigure --prefix /path/to/prefix --client cursor --non-interactive ``` 2. **Review and merge the printed private fragment into the correct client file**. Setup does not write these live files: * **Cursor IDE**: `cat ~/.cursor/mcp.json` * **Claude Desktop**: `cat ~/.claude.json` * **Gemini / Antigravity**: `cat ~/.gemini/antigravity-cli/mcp_config.json` * **OpenCode**: `cat ~/.config/opencode/opencode.json` * **Kilo CLI**: `cat ~/.config/kilo/config.json` * **Zed Editor**: `cat ~/.config/zed/settings.json` * **Codex / ChatGPT**: `cat ~/.codex/config.toml` 3. **Check reload behavior**: some clients require a restart; Zed can restart context servers immediately when settings are saved. Back up active memory/vault state before changing sync hooks. Never paste raw client configuration containing credentials into an issue or chat. ### Zed forwards a server that Codex already defines The message `MCP server hela-… was not started, because the Codex config already defines an MCP server with this name` refers to the forwarded duplicate. It does not prove that Codex failed to start its native entry. `codex mcp list` inspects configuration, not connectivity; check MCP startup/discovery or an actual safe tool call separately. Zed 1.27.0 forwards project context servers to external agents; native `agent.profiles.*.context_servers` controls are not a per-ACP forwarding switch. Do not remove shared top-level `context_servers` just to silence Codex warnings: native Zed and other agents may need them. The installed codex-acp 2.5.0 supports an optional per-agent environment override: ```json "env": { "DISABLE_MCP_CONFIG_FILTERING": "true" } ``` Place it under `agent_servers.codex-acp` only if deliberately choosing merged forwarded/native ownership. This disables adapter duplicate filtering, **not forwarding**; it can fail when future definitions disagree. Identical definitions passed isolated merge/discovery checks, but authenticated Zed ACP sessions still require verification. Keeping Codex-owned entries and leaving this toggle unset preserves native ownership, with the duplicate warning still possible. Source references: [Zed forwarding](https://github.com/zed-industries/zed/blob/c84af5b99cbc366d675064e52b23664a015b6e35/crates/agent_servers/src/acp.rs#L44-L65), [agent settings schema](https://github.com/zed-industries/zed/blob/c84af5b99cbc366d675064e52b23664a015b6e35/crates/settings_content/src/agent.rs#L842-L904), and [adapter toggle](https://github.com/agentclientprotocol/codex-acp/blob/v2.5.0/src/CodexAcpClient.ts#L1620-L1623). --- ### 2.4 Pinned Snapshot Recovery & Rollback **Symptom**: Upstream repository changes broke a server build or altered expected tool schemas. **Root Cause**: Moving `main`/`master` branch contains unreleased or breaking changes. **Fix**: Restore known-good, audited release snapshot: ```bash ./setup.sh --snapshot v1.5.1 --profile dev-workspace --non-interactive ``` --- ### 2.5 SQLite Database Lock or Corruption (`HeLa Genome`) **Symptom**: `database is locked` or `SQLite error` in `project-mcp`. **Possible causes**: Competing writers, a long transaction, permissions, filesystem failures, or a damaged database. A lock error alone does not prove corruption or missing WAL mode. **Fix**: 1. Identify the actual database path and owning processes. Inspect integrity read-only: ```bash sqlite3 -readonly /absolute/path/to/memory.db "PRAGMA integrity_check;" ``` 2. Take an online, validated backup that includes committed WAL data. Do not copy only the main file while SQLite is active; no daily-backup schedule is implied by the package. 3. Restore only to a new, absent destination with no SQLite sidecars, verify integrity, and review a controlled switchover. Never overwrite an active database. Preserve divergent Obsidian notes and existing conflict archives instead of choosing a winner automatically. --- ### 2.6 External Hardware Driver Issues #### HeLa Receptor (Android / ADB) * **Verify ADB availability**: `adb version` * **Verify device connectivity**: `adb devices` (ensure device is authorized with USB debugging enabled). #### HeLa Cytosol (Browser Automation) * **Install Playwright browsers**: ```bash npx playwright install chromium ``` #### HeLa Plastid (Blender 3D) * **Verify Blender CLI in PATH**: ```bash blender --version ``` * If installed outside standard PATH, create a symlink: ```bash sudo ln -s /path/to/blender /usr/local/bin/blender ``` --- ## 3. Getting Further Support * **Run Integration Tests**: `npm test` discovers the installed cells; use `-- --profile ` for a selected subset. Tool counts depend on enabled features. * **Run Matrix Tests**: `npm run test:matrix` verifies 80 profile/client configuration combinations, not GUI authentication or hardware operations. * **File an Issue**: Open an issue at [`Hela-Ecosystem/hela-mcp-ecosystem/issues`](https://github.com/Hela-Ecosystem/hela-mcp-ecosystem/issues) with reviewed/redacted output from `./setup.sh doctor --json` and the failed check. Do not attach private configs or environments. --- # Source: docs/workflows.md URL: https://hela.my.id/library/docs/workflows.html # HeLa MCP Ecosystem: Workflows & Integration Guide ![Blotcat Workflows Orchestration](../assets/blotcat-workflows.jpg) This document defines the standard operational workflows and cross-MCP coordination patterns enabled by the **HeLa MCP Ecosystem**. --- ## 1. Architectural Foundation: Dual-Backbone Coordination Every profile in the HeLa MCP Ecosystem is anchored by two coordinating backbone servers: ```mermaid flowchart TB Agent["Agent / LLM Orchestrator"] Mitosis["HeLa Mitosis
(Orchestrator)
- Dynamic Routing
- Step Reasoning
- Tool Planning"] Genome["HeLa Genome
(State & Memory)
- Knowledge Graph
- Entities / Relations
- Observations"] Membrane["HeLa Membrane
Workspace FS"] Nucleus["HeLa Nucleus
Command Exec"] Ribosome["HeLa Ribosome
PTY Harness"] Enzyme["HeLa Enzyme
Research / Wiki"] Cytosol["HeLa Cytosol
Browser DOM"] Agent --> Mitosis & Genome Mitosis <-->|"Shared Context"| Genome Mitosis & Genome --> Membrane & Nucleus & Ribosome & Enzyme & Cytosol ``` - **HeLa Mitosis (`hela-mitosis`)**: Acts as the cognitive orchestrator. It decomposes complex prompts, analyzes tool performance, and runs Needle-backed `sequentialthinking` step-by-step logic (each thought is an observe β†’ decide β†’ execute agent step recorded in AgentState). - **HeLa Genome (`hela-genome`)**: Acts as the immutable project memory. It stores entities, relations, observations, and session milestones in `memory.db`. --- ## 2. Canonical Workflows Catalog ### Workflow A: Autonomous Feature Engineering **Primary Profiles**: `dev-workspace`, `headless-server` **Components**: `hela-genome` β†’ `hela-mitosis` β†’ `hela-membrane` β†’ `hela-nucleus` β†’ `hela-genome` ```mermaid sequenceDiagram participant Agent participant Genome as HeLa Genome participant Mitosis as HeLa Mitosis participant Membrane as HeLa Membrane participant Nucleus as HeLa Nucleus Agent->>Genome: get_session_context / search_nodes(task) Genome-->>Agent: Previous architecture & constraints Agent->>Mitosis: analyze_with_sequential_thinking(feature_req) Mitosis-->>Agent: Step-by-step implementation plan Agent->>Membrane: read_file / write_file(source_code) Membrane-->>Agent: Code written to workspace Agent->>Nucleus: execute_command("npm test" / "pytest") Nucleus-->>Agent: Test run output Agent->>Genome: memory_edit(action="add_observations", observations=[…]) ``` #### Step-by-Step Tool Sequence: 1. **Context Restoration**: Call `get_session_context` on `hela-genome` to retrieve active architectural decisions and dependencies. 2. **Decomposition**: Call `llm_decompose_task` or `sequentialthinking` on `hela-mitosis` to generate an execution plan. 3. **Workspace Modification**: Call `read_file` and `write_file` on `hela-membrane` to apply minimal, production-ready code changes. 4. **Validation**: Call `execute_command` on `hela-nucleus` (or `rtk` wrapper) to run automated unit tests. 5. **State Recording**: Call `memory_edit` on `hela-genome` to commit progress to the knowledge graph. --- ### Workflow B: Deep Research & Architecture Synthesis **Primary Profiles**: `research`, `dev-workspace` **Components**: `hela-enzyme` β†’ `hela-cytosol` β†’ `hela-mitosis` β†’ `hela-genome` β†’ `hela-membrane` ```mermaid sequenceDiagram participant Agent participant Enzyme as HeLa Enzyme participant Cytosol as HeLa Cytosol participant Mitosis as HeLa Mitosis participant Genome as HeLa Genome participant Membrane as HeLa Membrane Agent->>Enzyme: wikipedia_search / google_search(query) Enzyme-->>Agent: Structured technical summaries & citations Agent->>Cytosol: browser_navigate(spec_url) -> browser_get_content(format=markdown) Cytosol-->>Agent: Live technical documentation content Agent->>Mitosis: llm_summarize(extracted_data) Mitosis-->>Agent: Synthesized architectural comparison Agent->>Genome: memory_edit(action="create_entities") + memory_edit(action="add_observations") Agent->>Membrane: write_file("docs/architecture/spec-x.md") ``` #### Step-by-Step Tool Sequence: 1. **Knowledge Retrieval**: Query `wikipedia_search` or `google_search` via `hela-enzyme` for background literature and reference APIs. 2. **Live Web Extraction**: Use `browser_navigate` and `browser_get_content(format=markdown)` via `hela-cytosol` to extract documentation from official docs sites. 3. **Synthesis**: Run `llm_summarize` and `analyze_with_sequential_thinking` on `hela-mitosis` to synthesize key architectural trade-offs. 4. **Knowledge Ingestion**: Call `memory_edit` on `hela-genome` linking findings to existing system components. 5. **Artifact Generation**: Save the final report using `write_file` on `hela-membrane`. --- ### Workflow C: End-to-End Web Feature with Design & Browser Verification **Primary Profiles**: `web-devops`, `dev-workspace` **Components**: `hela-phenotype` β†’ `hela-membrane` β†’ `hela-nucleus` β†’ `hela-cytosol` β†’ `hela-genome` ```mermaid sequenceDiagram participant Agent participant Phenotype as HeLa Phenotype participant Membrane as HeLa Membrane participant Nucleus as HeLa Nucleus participant Cytosol as HeLa Cytosol participant Genome as HeLa Genome Agent->>Phenotype: design_tokens(action="theme") / design_tokens(action="tailwind") Phenotype-->>Agent: Design tokens & OKLCH color palette Agent->>Membrane: write_file("tailwind.config.js" & component files) Agent->>Nucleus: execute_command("npm run dev") Nucleus-->>Agent: Local dev server active on port 3000 Agent->>Cytosol: browser_navigate("http://localhost:3000") -> browser_screenshot Cytosol-->>Agent: Rendered visual screenshot & accessibility tree Agent->>Genome: memory_edit(action="add_observations", observations=["Design verified on DOM & visual snapshot"]) ``` #### Step-by-Step Tool Sequence: 1. **Design System Token Generation**: Call `design_tokens`, `palette`, or `logo_workflow` on `hela-phenotype`. 2. **Component Implementation**: Write JSX/Tailwind files using `write_file` on `hela-membrane`. 3. **Dev Server Launch**: Launch background local web server using `execute_command` on `hela-nucleus`. 4. **Visual & Accessibility Verification**: Navigate to `http://localhost:3000` via `browser_navigate` on `hela-cytosol`, verify DOM via `browser_get_content(format=axtree)`, and take visual snapshot with `browser_screenshot`. 5. **Milestone Recording**: Save verification screenshot path and milestone to `hela-genome`. > **Live Production References Generated by HeLa Phenotype (`the-designer`):** > * [Ellis UI Archive / The Collection](https://demo-designer.glassgallery.my.id/) β€” 24 bespoke anti-slop design systems (*Game Boy 8-bit, Top Secret Dossier, Nutrition Facts, Library Card, Gothic Tome, Swiss Archival*). --- ### Workflow D: Mobile App Test Automation & Verification **Primary Profiles**: `android-testing`, `all` **Components**: `hela-genome` β†’ `hela-nucleus` β†’ `hela-receptor` β†’ `hela-genome` ```mermaid sequenceDiagram participant Agent participant Genome as HeLa Genome participant Nucleus as HeLa Nucleus participant Receptor as HeLa Receptor Agent->>Genome: get_session_context (device test suite) Agent->>Nucleus: execute_command("adb devices") Nucleus-->>Agent: Connected device ID detected Agent->>Receptor: start_session(deviceId) -> ui_dump Receptor-->>Agent: XML/axtree hierarchy of active mobile screen Agent->>Receptor: tap(element_id) / input_text("user_input") Receptor-->>Agent: UI transition complete Agent->>Receptor: screenshot("artifacts/test-pass.png") Agent->>Genome: memory_edit(action="add_observations", observations=["Mobile flow X verified on physical Android"]) ``` #### Step-by-Step Tool Sequence: 1. **Device Discovery**: Call `device_list` on `hela-receptor` or `execute_command("adb devices")` on `hela-nucleus`. 2. **Session Initialization**: Call `start_session` on `hela-receptor`. 3. **UI Hierarchy Inspection**: Call `ui_dump` or `ui_find_element` to inspect Android view hierarchy token-efficiently via XML rather than screenshots. 4. **Interaction**: Execute `tap`, `input_text`, `scroll`, or `key_event` to execute test scenario. 5. **Visual Proof & Persistence**: Call `screenshot` and record test result observation in `hela-genome`. --- ### Workflow E: Autonomous 3D Asset Creation & Render Pipeline **Primary Profiles**: `3d-modeling`, `all` **Components**: `hela-genome` β†’ `hela-mitosis` β†’ `hela-plastid` β†’ `hela-membrane` β†’ `hela-genome` ```mermaid sequenceDiagram participant Agent participant Genome as HeLa Genome participant Mitosis as HeLa Mitosis participant Plastid as HeLa Plastid participant Membrane as HeLa Membrane Agent->>Genome: search_nodes("3D Assets") Agent->>Mitosis: generate_route_suggestions("Procedural chair generation") Agent->>Plastid: generate_modeling_plan("Modern lounge chair") Plastid-->>Agent: Phased Python Blender script Agent->>Plastid: execute_blender_code(script) -> render_output Plastid-->>Agent: High-resolution render output PNG Agent->>Plastid: save_blend("assets/chair.blend") Agent->>Genome: memory_edit(action="add_observations", observations=["Generated 3D chair asset and render"]) ``` #### Step-by-Step Tool Sequence: 1. **Asset Requirement Analysis**: Retrieve scene requirements from `hela-genome`. 2. **Plan Synthesis**: Call `generate_modeling_plan` on `hela-plastid`. 3. **Procedural Execution**: Run `execute_blender_code` to generate geometry, apply materials, and setup lights. 4. **Render Output**: Trigger `render_output` and `get_fast_feedback` for visual QA. 5. **Persistence**: Save `.blend` file via `save_blend` and register the asset entity in `hela-genome`. --- ### Workflow F: Long-Horizon Complex Refactor with PTY Harness **Primary Profiles**: `dev-workspace`, `headless-server` **Components**: `hela-ribosome` β†’ `hela-nucleus` β†’ `hela-genome` ```mermaid sequenceDiagram participant Agent participant Ribosome as HeLa Ribosome participant Nucleus as HeLa Nucleus participant Genome as HeLa Genome Agent->>Ribosome: session_spawn("long-build", "mvn clean install -T 4") Ribosome-->>Agent: Session spawned (ID: sess-101) Agent->>Ribosome: session_read("sess-101") (bounded polling) Ribosome-->>Agent: Streamed stdout/stderr chunk Agent->>Nucleus: execute_command("git status") Agent->>Genome: memory_edit(action="add_observations", observations=["Long refactor build verified via PTY session"]) Agent->>Ribosome: session_close("sess-101") ``` #### Step-by-Step Tool Sequence: 1. **Interactive Session Creation**: Call `session_spawn` on `hela-ribosome` for interactive, long-running processes (compilers, debuggers, REPLs). 2. **Session Monitoring**: Read process output with `session_read` or send input with `session_write`. 3. **Session Termination**: Clean up process with `session_close`. 4. **Memory Recording**: Log completed refactor state to `hela-genome`. --- ## 3. Best Practices & Token Economy 1. **Structured Memory Over Raw History**: Always record key findings and milestones to `hela-genome` so subsequent agent turns do not need to re-read thousands of lines of raw logs. 2. **Hierarchy Inspection Over Full Screenshots**: For web (`hela-cytosol`) and mobile (`hela-receptor`), prefer accessibility trees and XML dumps for element location, reserving bitmap screenshots for final visual verification. 3. **Fail-Fast Pre-Validation**: Always verify prerequisite binary availability via `./setup.sh doctor` before launching complex cross-MCP pipelines.