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. Each of the ten MCP cells has its own version; the ecosystem snapshot and optional runtime have independent versions.

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:

flowchart LR
    T1["Tier 1: Public Identity<br/>HeLa Genome"]
    T2["Tier 2: Machine ID<br/>hela-genome"]
    T3["Tier 3: Technical Repo<br/>project-mcp"]
    T4["Tier 4: Immutable Commit<br/>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:

flowchart TB
    Client["AI Client / Orchestrator"]

    Mitosis["HeLa Mitosis<br/>(hela-mitosis)<br/>- Dynamic Routing<br/>- Step Reasoning<br/>- Task Decomposition<br/>- Prompt Catalog"]
    Genome["HeLa Genome<br/>(hela-genome)<br/>- Knowledge Graph<br/>- Living SQLite DB<br/>- Entity / Relations<br/>- Milestones & State"]

    Membrane["HeLa Membrane<br/>(Files)"]
    Nucleus["HeLa Nucleus<br/>(Exec)"]
    Ribosome["HeLa Ribosome<br/>(PTY)"]
    Enzyme["HeLa Enzyme<br/>(Search)"]
    Cytosol["HeLa Cytosol<br/>(Browser)"]
    Phenotype["HeLa Phenotype<br/>(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:

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.

5. Security & Isolation Model

flowchart TB
    Host["Host Operating System / Terminal Environment"]
    Root["HeLa MCP Ecosystem Root"]
    Sandbox["stdio JSON-RPC Sandbox"]
    Membrane2["Path Canonicalization<br/>(HeLa Membrane)"]
    Nucleus2["Explicit CWD & Timeout Limits<br/>(HeLa Nucleus)"]
    Ribosome2["Process Group Teardown<br/>(HeLa Ribosome)"]
    Cytosol2["SSRF IP Filtering<br/>(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.

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.