Enterprise Chaining MCP Server (HeLa Mitosis)

Enterprise Chaining MCP Server (HeLa Mitosis)

Part of the HeLa MCP Ecosystem — this server is HeLa Mitosis (hela-mitosis), the Orchestrator component of the HeLa cellular architecture.

A Model Context Protocol (MCP) server that orchestrates other MCP servers: discovers tools, plans execution with a bundled local tool-calling model (Needle 3), executes through a registry-guarded workflow engine, records reasoning in an agent-state store, and escalates to OpenRouter only when the local model is not confident. Also ships time management, prompt/resource libraries, skills-catalog management, memory graph, monitoring, and security guidance.

Agent Runtime (Needle 3, bundled) — how it actually works

User
 ↓
Mitosis
 ├─ Needle 3 (bundled 121M tool-calling engine, auto-enabled when present)
 │    ↓ structured decision (JSON, grammar-constrained to real tools)
 ├─ state / observation (AgentState: observations, decisions, tool
 │    calls, results, revisions, branches, escalation, termination)
 │    ↓
 ├─ workflow executor (WorkflowOrchestrator: transport-bound, real
 │    retries, cancellation, registry guard, no self-recursion)
 │    ↓
 └─ MCP capabilities (tools + skills + prebuilt prompts)
      ↓ result
   Needle 3 → next decision (…until complete / escalate / limits)

Sequential thinking is built in — there is no external sequential-thinking MCP. sequentialthinking, analyze_with_sequential_thinking, and agent_run all resolve to this one loop on the MCP layer:

Needle 3 (local)
  │  refusal / low-confidence / malformed output / provider failure
  ▼
OpenRouter (escalation layer, auto-detected, budgeted one-way trip, recorded trail)
  │  also fails / unparseable / NO provider key configured
  ▼
the calling agent (last layer) — auto-detected handoff: when no OpenRouter /
OpenAI key is present, Mitosis skips the dead-end call and returns a structured
`handoff` outcome (`decision: escalate`, `handoff: true`, reason + AgentState
trail) so the user's agent takes over directly.

Escalation provider is auto-detected from the environment (OPENROUTER_API_KEY, else OPENAI_API_KEY; AGENT_ESCALATION_ENABLED=false disables). Responses expose escalation: { configured, provider } so the calling agent always knows whether a real backend exists.

What this gives you (verified)

Honest limitations (read before relying on it)

• Small model ceiling. Needle 3 is a 121M tool-calling model (with legacy 45M Needle 2 selectable via NEEDLE_GENERATION=2), not a general reasoner. Multi-hop reasoning, open-ended prose, and creative writing are NOT its job — those are exactly when the escalation layer should fire. Planning is a router: it picks tools and fills args, it does not argue.

• Stochastic variance. Identical prompts can score 0.97 → 0.005 confidence across runs and occasionally refuse outright. Every mitigation (retry-tolerant planner, saturation guard, escalation budget, honest failures) exists because we hit this live. Plan for retries; never assume a deterministic answer.

• Measured planning quality (20-task battery × 3 runs): 18/20 fully valid, mean expected-tool recall 0.825, mean ~1.3s/plan. Known weak phrasing: vague commands refuse ("turn off all the lights", "check disk usage"); 3 two-tool tasks produced partial chains. Sharper phrasing ("dim the living room lights to 30") scores 1.0. Tool descriptions in discovery drive recall more than the model size does.

• Episodic memory & retention with anti-stagnation gates (Oct 2026). Agent planning and turn-1 decisions query memory.db (HeLa Genome) for relevant prior observations. To prevent workflow stagnation:

  1. Pareto upgrade-only rule: A workflow is only retained if it achieves the task in fewer/equal steps or without escalation. Longer, clunkier attempts can never overwrite concise workflows.
  2. Dirty trail filtering: Runs with repeated tool failures or errors (>2) are discarded before retention.
  3. Reference framing: Prior workflows are framed as hints (prefer simpler direct tools if available), enabling Needle 3 to discover single-tool shortcuts rather than being rigidly locked into multi-step historical patterns.

• Profile-Aware System Grounding (assets/needle/profiles/). Needle 3 dynamically resolves its grounding card based on HELA_PROFILE (e.g. dev-workspace, headless-server, research, web-devops, android-testing, 3d-modeling, all), or defaults to assets/needle/hela-system.txt. The model is immediately aware of which organelles and tools are active for that persona, preventing out-of-profile routing attempts.

• Permanent System Grounding Cards in Git. All system cards (assets/needle/hela-system.txt and assets/needle/profiles/*.txt) are checked into git, ensuring zero-configuration grounding immediately upon repository clone.

• Default capability-first two-tier scoping. scopeToolsForTask scopes the full 200+ tool ecosystem to task-relevant organelle capabilities first, preventing context overflow in the 121M model while keeping decisions accurate and calibrated.

• Needle 3 is the default router (Sept 2026). 121M laddered model, 29MB file, ~78MB RAM. Measured here: Mobile Actions-style single calls at confidence 1.0, calibrated uncertainty on vague prompts (0.41 research → escalates under the 0.5 family floor), empty-list refusal instead of guesses. NEEDLE_GENERATION=2 restores the legacy 45M engine. Caveats carry over: stochastic variance, vague commands refuse, descriptions drive recall more than model size.

• Tuned .cact models load via --model on gen 3. NEEDLE_MODEL_PATH is honored by the v3 engine (weights are no longer baked in). Telemetry is force-disabled on every engine spawn (NEEDLE_TELEMETRY=0, DO_NOT_TRACK=1).

• Skills are discoverable, retrievable, and recommended — not executed. A skill is instructions (SKILL.md); running its scripts is the harness's job. suggest_skill_chain attaches deterministic per-step skill hints, labeled as such (the model doesn't fuse them).

• brainstorming needs a generative model. Without OPENROUTER_API_KEY it fails honestly — we removed template ideas with random scores rather than fake them.

• OpenRouter escalation only works with a key — auto-detected. Without OPENROUTER_API_KEY/OPENAI_API_KEY, Mitosis detects the absence and hands control to the calling agent (handoff: true) instead of attempting a doomed call.

• Discovery connectivity fallbacks add known tools for common server types when a server can't be reached — that's network resilience, not cognition.

Prebuilt Prompts & Resource Sets

40 prompts + 12 resource sets, all with bodies of 487–2,284 chars, zero stubs, covering development, debugging, orchestration, MCP-ecosystem workflows, monitoring, analytics, security, and compliance.

They're reachable four ways:

1. Tools: get_prompt / search_prompts / get_resource_set / search_resource_sets
2. Resources: chaining://prompts, chaining://resources, chaining://prompts/overview, chaining://tool-chains, chaining://tool-chains/overview
3. Agent context: task-relevant prompts (keyword + expectedTools overlap, top-2, ≤600 chars) are injected into planning and turn-1 agent context
4. Skills catalog: list_skills / search_skills / get_skill / suggest_skill_chain over the opencode AgentSkills layout

Prebuilt Prompts

• Development: analyze-project-structure, feature-implementation, code-refactoring, security-audit, performance-optimization, debug-error-tracing, dependency-analysis, tool-chaining-basics, memory-knowledge-management, sequential-thinking-workflows, mcp-ecosystem-exploration, cross-server-data-flow, awesome-copilot-integration-workflow, time-sensitive-task-orchestration, multi-server-debugging-orchestration, intelligent-route-optimization, server-capability-mapping, dynamic-workflow-adaptation, knowledge-graph-enhanced-chaining, collaborative-development-orchestration, automated-quality-assurance, intelligent-resource-discovery, predictive-workflow-optimization, enterprise-integration-orchestration
• Advanced chains: comprehensive-project-assessment-chain, full-stack-feature-implementation-chain, production-debugging-orchestration, cross-server-data-pipeline-orchestration, ai-enhanced-development-workflow, enterprise-scale-architecture-orchestration
• Monitoring & Analytics: system-health-monitoring, performance-bottleneck-analysis, tool-usage-analytics, workflow-reliability-assessment, cost-optimization-analysis
• Security & Compliance: security-vulnerability-assessment, compliance-audit-workflow, data-privacy-protection, access-control-audit, incident-response-planning

Resource Sets

development-starter-kit, debugging-toolbox, performance-optimization-kit, tool-chaining-mastery, awesome-copilot-collections, observability-suite, analytics-toolkit, reliability-engineering-kit, security-assessment-suite, compliance-management-suite, privacy-protection-framework, incident-response-playbook

Installation

npm install            # automatically fetches the bundled Needle 3 engine if missing
npm run build          # prebuild also ensures the engine; tsc compiles
npm run needle:fetch   # manual re-fetch / platform override (only needed if auto-fetch failed)

Existing users: git pull then npm install (or npm run build) — the engine is fetched automatically; no manual step. The fetch is non-fatal if offline (warns, install/build still complete; retry later with npm run needle:fetch).

Configuration (minimal opencode example)

{
  "hela-mitosis": {
    "type": "local",
    "enabled": true,
    "command": ["node", "/path/to/chaining-mcp/dist/index.js"],
    "environment": {
      "CHAINING_TOOL_TIMEOUT_MS": "10000",
      "MEMORY_FILE_PATH": "/path/to/chaining-mcp/data/memory.json",
      "AWESOME_COPILOT_ENABLED": "true",
      "RELIABILITY_MONITORING_ENABLED": "true",
      "GITHUB_TOKEN": "ghp_xxxx",
      "OPENROUTER_API_KEY": "sk-or-xxx"
    }
  }
}

Note: Replace /path/to/chaining-mcp, run npm run needle:fetch once. No MITOSIS_AGENT_ENABLED / NEEDLE_* / SEQUENTIAL_THINKING_* needed — the agent auto-enables when the bundled engine is present (MITOSIS_AGENT_ENABLED=false opts out).

Important:

• OPENROUTER_API_KEY: optional — feeds escalation and brainstorming only; the agent runs fully offline without it.
• GITHUB_TOKEN: optional — live Awesome Copilot syncing; local catalog fallback otherwise.

Tools (29, all enabled by default)

Core: list_mcp_servers, analyze_tools, generate_route_suggestions (Needle-planned), analyze_with_sequential_thinking (Needle plan IS the analysis), get_tool_chain_analysis, sequentialthinking (Needle-backed step over AgentState).Awesome Copilot: search_instructions, load_instruction.Agent runtime: agent_run, workflow_status, workflow_cancel.Thinking/generative: brainstorming (OpenRouter-backed, key required), workflow_orchestrator.Time: get_current_time, convert_time. Prompt/resource: get_prompt, search_prompts, get_resource_set, search_resource_sets. Validation: validate_tool_chain, analyze_tool_chain_performance. Skills: list_skills, search_skills, get_skill, suggest_skill_chain.LLM: llm_query, llm_decompose_task (Needle-planned), llm_suggest_route (Needle-planned), llm_summarize — listed by default (CHAINING_LLM_ENABLED defaults true); the keyless llm_* tools fail honestly or fall back to truncation, never fake answers. Set CHAINING_LLM_ENABLED=false to hide them.

Resources (18)

chaining://servers, tools, analysis, prompts, resources, prompts/overview, awesome-copilot/collections, awesome-copilot/instructions, awesome-copilot/status, sequential/state, workflows/status, tool-chains, tool-chains/overview, health, cache/stats, llm/status, llm/usage, agent/status.

Environment Variables

Zero-Key & Offline

Fully offline, zero-key by default: the Needle agent plans, decides, executes, and completes locally. Escalation paths record a budgeted failure without a key; brainstorming fails honestly. No model env vars required.

Development & Verification (honest layer-by-layer)

# Pre-commit gate (installed): tsc build + deterministic mock suite (~95s) on every commit
pre-commit run --all-files          # or just commit; the hook runs it

# Layer 1 — mock suite (no engine, deterministic): 78 tests
node scripts/test-agent.mjs

# Layer 2 — live suite (bundled engine + optional key): 91 tests
NEEDLE_LIVE=1 node scripts/test-agent.mjs

# Layer 3 — planning battery (live, 20 tasks × 3 runs): validity/recall/latency/parallel
NEEDLE_LIVE=1 node scripts/bench-battery.mjs

# Layer 4 — e2e against the SHIPPED dist/ over real MCP stdio (initialize→tools→calls→resources)
OPENROUTER_API_KEY=sk-or-xxx CHAINING_LLM_ENABLED=true node scripts/test-e2e.mjs

What each layer does not prove: the mock suite doesn't touch the engine; the live suite needs the engine fetched; the battery is n=3 (variance bounds want n=20); the e2e needs a network + key for the escalation branch and exercises the shipped build (re-run after every npm run build).

Project Structure

src/
├── index.ts / server.ts             # MCP stdio entry + orchestrator (transport binding, non-reentrancy guard)
├── core/                            # discovery (TTL cache, connectivity fallbacks), optimizer (deterministic validation only)
├── managers/                        # workflow-orchestrator (transport seam, real retries, cancel), time, memory, reliability, llm
├── agent/                           # agent.ts (loop/step/planner/decision), needle-provider, openrouter-provider,
│                                    # state, escalation, workflow bridge, guidance, diagnostics
├── skills/                          # skill-discovery (frontmatter, search, TTL cache, read-only)
├── integrations/                    # awesome-copilot (local catalog)
├── prompts/                         # 40 prompts + 12 resource sets + registry
├── handlers/                        # request-handlers (dispatcher, per-tool timeouts, honest failures)
├── tools/                           # tool schemas (core, agent, skills, time, prompts, validation, llm)
└── resources/                       # 18 chaining:// resources

Integration with Other MCP Servers

Discovery scans your MCP config files, connects to real servers, and executes their tools through the workflow transport.

Sequential thinking needs no external server — the bundled Needle agent provides it. awesome-copilot is an optional dotnet-based server (local catalog used when the binary is absent). Project-Guardian complements this server: Mitosis orchestrates, Project-Guardian owns the database. No heuristic "reasoning" layer exists: every plan, route, decomposition, and thought is model-grounded (Needle → OpenRouter) or a deterministic runtime rule.

License

MIT License — see LICENSE file for details.

Contributing

1. Fork. 2. Branch. 3. Change. 4. Add/update tests (mock + live + battery + e2e as appropriate). 5. pre-commit run --all-files must pass. 6. PR.