Ellmos Controlcenter MCP Server

ellmos ControlCenter MCP

DE Deutsche Version

Part of the ellmos-ai family.

[!NOTE] LLM / AI Agent Integration: This repository provides an llms.txt index file for context optimization, RAG discovery, and agent navigation.

---

Quick Navigation

Installation • Target Personas • Comparative Matrix • System Architecture • Control & Gateway Flow • Governance Invariants • Status • Tools (34) • Gateway • Capability Bundles • Profile Switching • Host Registers • Dashboard • Third-Party Licenses • Documentation • Security Policy • llms.txt Context • Ecosystem Matrix

---

An advanced Model Context Protocol (MCP) administration server and policy-gated gateway for local MCP stacks. ControlCenter discovers local MCP servers, reads MCP profile files, groups servers into capability bundles, recommends profiles for a task, builds catalogs, probes real MCP tool lists from local repositories or profiles, assigns tools to capability bundles, provides host-level register mirrors (locks, permissions, resources, governance), and provides an optional local dashboard.

Architecture & Dual Role — Control Plane + Policy-Gated Gateway: ControlCenter combines two complementary operational surfaces:

1. Control Plane (Administration & Configuration): Inventories local servers, resolves profiles, manages capability bundles, mirrors system governance/locks, and generates configurations (controlcenter_switch_profile, controlcenter_build_catalog).
2. Policy-Gated Gateway (On-Demand Tool Invocation): Via controlcenter_invoke and controlcenter_list_available_tools, agents can list and invoke tools on backend MCP servers that the host agent has not loaded into its active context — strictly bounded by pattern-based policy rules (data/gateway-policy.json), argument auditing, and secret scrubbing.

Administration and discovery are local-first with no telemetry or background egress. An explicitly configured gateway call may contact a remote HTTPS backend; redirects are refused and an optional host allowlist can narrow the destination set. Lock and permission tools fail closed when their authority sources cannot be verified.

Provider note: ControlCenter works with any MCP-capable client (Claude Code, Codex, Gemini, or any stdio-based MCP host). The profile management tools default to Claude Code's profile directory (~/.claude/profiles) but accept any directory via ELLMOS_PROFILE_ROOT. The skill and plugin inventory tools are scoped to Claude Code conventions by default; see the environment variables below for override options.

ControlCenter provides discovery, profile visibility, dashboard workflows, capability bundles, profile-aware tool-list probes, tool-bundle assignments, internationalization, policy audits, host register mirrors (locks, permissions, resources, plans), and the policy-gated gateway (controlcenter_invoke). Hardened for multi-OS deployment with a 48-hour security response SLA.

Target Personas & Discoverability

Discovery Keywords & High-Intent Topic Tags: mcp-control-plane, model-context-protocol, mcp-gateway, claude-code-profiles, policy-gated-execution, no-telemetry, local-first-ai, secret-scrubber, multi-agent-coordination, capability-bundles, fail-closed-security, mcp-audit-logging, developer-tools.

---

Comparative Matrix vs Alternatives

---

System Architecture

graph TD
    A["Clients (Claude Code, Codex, Gemini, stdio Hosts)"] -->|MCP stdio / JSON-RPC| B["ellmos ControlCenter MCP Server"]
    
    subgraph Core ["Control Plane Modules"]
        B --> C["Catalog Scanner (catalog.ts)"]
        B --> D["Profile Resolver (profiles.ts)"]
        B --> E["Bundle Manager (bundles.ts)"]
        B --> F["Tool Prober (toolCatalog.ts)"]
        B --> G["Policy Auditor (policy.ts)"]
        B --> H["Context Packer (contextPack.ts)"]
        B --> I["i18n Engine (src/i18n)"]
    end
    
    subgraph Storage ["Local System & Environment"]
        C -->|Scans| S1["Local repo clones (configured root)"]
        D -->|Reads / Resolves| S2["Claude Profiles (~/.claude/profiles)"]
        E -->|Loads & Maps| S3["Capability Bundles (data/capability-bundles.json)"]
        F -->|stdio Probes| S4["Local & Profile MCP Servers"]
        G -->|Audits| S5["Policy Rules & Security Risks"]
    end
    
    subgraph UI ["Management Interface"]
        B <-->|"HTTP / WebSocket (127.0.0.1:3737)"| J["Local Dashboard (dashboard.ts)"]
    end

Visual Architecture Topology (ASCII Four-View Projection)

====================================================================================================
               ELLMOS CONTROLCENTER MCP — FOUR-VIEW ARCHITECTURAL TOPOLOGY
====================================================================================================

[VIEW 1: CLIENT RUNTIMES, LOCAL DASHBOARD & MCP HOST INTERFACES]
+--------------------------------------------------------------------------------------------------+
| MCP Hosts & Agents: Claude Code | Codex CLI | Antigravity (Gemini) | Custom Stdio Transports     |
|   |                              |                         |                       |             |
|   +------------------------------+-------------------------+-----------------------+             |
|                                  | JSON-RPC 2.0 stdio (34 Tools)                                 |
|                                  v                                                               |
|   +------------------------------------------------------------------------------------------+   |
|   | ellmos-controlcenter-mcp (Node.js >= 20.0.0 / TypeScript / ESM / RunAsInvoker)           |   |
|   +------------------------------------------------------------------------------------------+   |
|                                  ^                                                               |
|                                  | HTTP / WebSocket (127.0.0.1:3737 - Loopback Only)            |
|   +------------------------------+-----------------------------------------------------------+   |
|   | Local Web Dashboard: Server Catalog | Profile Switcher | Real-Time Tool Inspector        |   |
+--------------------------------------------------------------------------------------------------+

[VIEW 2: CONTROLCENTER SOVEREIGN CORE ENGINE & RESOLUTION SUBSYSTEMS]
+--------------------------------------------------------------------------------------------------+
| +-------------------------+ +-------------------------+ +--------------------------------------+ |
| | Catalog & Tool Scanner  | | Profile Resolver Engine | | Dynamic Capability Bundles           | |
| | - catalog.ts / mcps     | | - profiles.ts           | | - bundles.ts                         | |
| | - toolCatalog.ts        | | - Inheritance Chains    | | - data/capability-bundles.json       | |
| | - Concurrency: 1-32     | | - Config Generation     | | - 11 Core Functional Bundles         | |
| +-------------------------+ +-------------------------+ +--------------------------------------+ |
|              |                           |                                 |                     |
|              v                           v                                 v                     |
| +----------------------------------------------------------------------------------------------+ |
| | Context Packer & Dynamic Orchestrator (contextPack.ts / semanticRouting.ts)                  | |
| | - Manifest-Only Handoffs | Semantic Expert Routing | Multi-Language i18n (src/i18n)          | |
| +----------------------------------------------------------------------------------------------+ |
+--------------------------------------------------------------------------------------------------+

[VIEW 3: POLICY-GATED GATEWAY, EPHEMERAL DISPATCH & HARDENED SECRET SCRUBBER]
+--------------------------------------------------------------------------------------------------+
| controlcenter_invoke / controlcenter_list_available_tools (On-Demand Backend Execution)         |
|                                  |                                                               |
|                                  v                                                               |
| +----------------------------------------------------------------------------------------------+ |
| | Gateway Policy Guard (data/gateway-policy.json) [INV-GATE-02]                                | |
| | - Fail-Closed Evaluation | Allowed Patterns | Server/Tool Whitelisting                       | |
| +----------------------------------------------------------------------------------------------+ |
|        | (Allowed)                                                  | (Denied / Invalid)         |
|        v                                                            v                            |
| +---------------------------------------+                 +------------------------------------+ |
| | Ephemeral Connect-Per-Call Lifecycle  |                 | Structured Refusal Dispatcher      | |
| | - Stdio Subprocess (Terminates post)  |                 | - Omit argument values in audit    | |
| | - Remote HTTPS (Explicit, No-Redirect)|                 | - Fail-closed error contract       | |
| +---------------------------------------+                 +------------------------------------+ |
|        |                                                            |                            |
|        v                                                            v                            |
| +----------------------------------------------------------------------------------------------+ |
| | Hardening, Budgets & Sanitization Pipeline [INV-SCRUB-04]                                    | |
| | - 256 KiB Request / 1 MiB Response Budgets | Recursive Key Redaction & Credential Scrubbing   | |
| | - Untrusted Data Marking | Append-Only Audit Trail (gateway-audit.jsonl)                     | |
| +----------------------------------------------------------------------------------------------+ |
+--------------------------------------------------------------------------------------------------+

[VIEW 4: GOVERNANCE MIRROR, MULTI-AGENT LOCK BOUNDARIES & SYSTEM PERIMETER]
+--------------------------------------------------------------------------------------------------+
| Host Registers & Local Safety Governance (Read-Only Mirroring / Zero-Mutation Guarantee)         |
|                                                                                                  |
|   [INV-LOCK-06] Canonical Multi-Agent Locks        [INV-PERM-07] Hierarchical Permissions        |
|   - controlcenter_list_locks                       - controlcenter_evaluate_permission          |
|   - controlcenter_check_lock (LOCK*.txt / until)   - Recursive LOCK.permissions.json Evaluation |
|                                                                                                  |
|   [INV-GOV-08] Host Governance Federation          [INV-LOCAL-01] Local-First Storage            |
|   - Decisions: controlcenter_list_decisions        - Inventory Mirror: inventory.db (Read-Only)  |
|   - Policies & Plans: controlcenter_list_governance- Resources: controlcenter_list_resources    |
|                                                                                                  |
|   [INV-PRIV-05] Non-Elevation: Unprivileged User Space | [INV-SLA-10] 48h Security Response SLA   |
+--------------------------------------------------------------------------------------------------+
====================================================================================================

Control Plane & Gateway Lifecycle

sequenceDiagram
    autonumber
    actor Agent as MCP Client (Claude / Codex / Gemini)
    participant CC as ControlCenter MCP Server
    participant Res as Profile & Capability Resolver
    participant Gate as Gateway Policy Guard
    participant Backend as Backend MCP Server (Unloaded)
    participant Scrub as Hardening & Secret Scrubber
    participant Audit as Audit Logger (JSONL)
    participant Lock as Host Governance & Lock Guard

    Note over Agent,CC: 1. Administration & Profile Discovery
    Agent->>CC: controlcenter_suggest_profile / resolve_profile
    CC->>Res: Inspect ~/.claude/profiles & extends chains
    Res-->>CC: Resolved MCP Configuration & Bundles
    CC-->>Agent: Suggested Profile & --mcp-config flags

    Note over Agent,CC: 2. Policy-Gated Gateway Execution
    Agent->>CC: controlcenter_invoke(server, tool, args)
    CC->>Gate: Evaluate data/gateway-policy.json
    alt Policy Denied or Missing
        Gate-->>CC: Policy Refusal (Fail-Closed)
        CC->>Audit: Log refusal (names only, 0 values)
        CC-->>Agent: Error: Tool / Server denied by policy
    else Policy Allowed
        Gate-->>CC: Dispatch Approved
        CC->>Backend: Connect-per-call (stdio / Streamable HTTP)
        Backend-->>CC: Raw Tool Output / Response
        CC->>Backend: Terminate process / Close transport
        CC->>Scrub: Recursive Secret Redaction & Finite Budgets
        Scrub-->>CC: Sanitized Payload & Truncation Status
        CC->>Audit: Append structured audit event (gateway-audit.jsonl)
        CC-->>Agent: Safe Tool Result wrapped with Data Banners
    end

    Note over Agent,CC: 3. Host Governance & Canonical Lock Verification
    Agent->>CC: controlcenter_check_lock(path) / evaluate_permission(action, path)
    CC->>Lock: Traverse nearest LOCK.user.* / LOCK.until.* / LOCK.permissions.json
    alt Lock Active or Unverified Authority
        Lock-->>CC: Fail-Closed Denial (Read-Only Enforced)
        CC-->>Agent: Lock Status: LOCKED (INV-LOCK-06 / INV-PERM-07)
    else Unlocked & Authorized
        Lock-->>CC: Confirmed Clear & Scope Authorized
        CC-->>Agent: Lock Status: UNLOCKED (Proceed)
    end

Governance & Runtime Invariants

ControlCenter enforces 10 architectural and runtime invariants to guarantee local-first administration, explicit outbound boundaries, fail-closed policy loading, and multi-agent coordination resilience across environments:

Status

• Phase: Alpha
• Version: 0.7.4
• Repository: ellmos-ai/ellmos-controlcenter-mcp
• npm: ellmos-controlcenter-mcp
• CI checks: npm run test and npm run build
• Goal: Make local MCP stacks visible, inspectable, and reproducibly configurable
• Focus: Catalogs, profile overview, profile recommendation, bundle recommendation, profile-aware tool-list probes, tool-bundle assignments, i18n, early audits, and read-only host governance metadata

Tools

Gateway: reaching servers the host has not loaded

A session that loads eleven MCP servers pays for all of their tools at once. The gateway lets the loaded profile stay small — for example FileCommander, ControlCenter, open-compute — while the remaining servers stay reachable on demand.

// what is out there, without loading it
{ "name": "controlcenter_list_available_tools", "arguments": { "profile": "full" } }

// run one of those tools; no prior listing required when the name is known
{ "name": "controlcenter_invoke", "arguments": {
    "server": "ellmos-clatcher-mcp", "tool": "fix_umlauts",
    "args": { "path": "C:/tmp/notes.md" } } }

Scope. Only servers declared by the configured MCP root (ELLMOS_MCP_ROOT) or by the profile named in profile can be addressed. That set is the gateway's primary boundary — there is no way to point it at an arbitrary command.

Lifecycle. The connection is opened for the call and closed afterwards. On Windows, configure ELLMOS_PROCESS_SUPERVISOR with the local Job-Object supervisor to bind descendants as well as the direct stdio child. The cost is roughly 200–500 ms per call on a cold stdio server; the result is bounded cleanup instead of an unverified direct-child-only kill.

Failure modes are kept apart. Four different things can go wrong, and they mean different things:

A listing over several servers states at the top when some of them could not be asked, so a partial result is never mistaken for a complete one.

Policy. data/gateway-policy.json (override with ELLMOS_GATEWAY_POLICY):

{
  "schema": "ellmos.controlcenter.gateway-policy.v1",
  "mode": "open",
  "deny": [{ "server": "*", "tool": "*_delete_*", "reason": "Deletion stays manual." }],
  "allow": []
}

mode: "open" allows every tool of an addressable server; mode: "allowlist" requires a matching allow rule. deny always wins, and * is a wildcard in both fields. A malformed or schema-foreign policy file refuses every invocation rather than falling back to allow-all.

Audit. Every invocation, including refused ones, is appended as one JSON line to ~/.ellmos/controlcenter/gateway-audit.jsonl (ELLMOS_GATEWAY_AUDIT_LOG; set it to off to disable). The entry holds argument names and count — never argument values — plus the masked connection command or URL, outcome, duration and content-block count, never result content. The tool output reports whether the write succeeded, so a failed audit is visible; set ELLMOS_GATEWAY_AUDIT_REQUIRED=1 to turn a failed write into a refused call.

Hardening. Forwarded payloads are foreign data, so the invoke path is bounded on every axis:

Not included. Connection pooling, streaming and progress pass-through, sampling, elicitation, backend resources and prompts, and risk-class policies derived from tool annotations. Opaque session-bound capabilities have no counterpart yet, because no session is held and no capability handle is issued. Only the MCP adapter exists; module, stack and folder adapters remain open.

Catalog discovery

ControlCenter reads three hand-curated catalogs instead of hard-coding individual paths. Each root is configurable, and each catalog is optional.

The MCP catalog contributes what a directory scan cannot see: mcp_kind (tool, adapter, stack, control-plane), whether a server keeps persistent state, which component owns that state per namespace, and optional declared capability tags. A tag block is versioned as capability_tags: {"schema":"ellmos.capability-tags.v1","tags":["catalog","read-only"]}; tags are normalized to lower case, sorted, and treated as metadata only. Duplicate, mistyped, or malformed tags make the catalog explicitly invalid instead of silently dropping data. The directory scan stays the source for what is actually installed, so both directions are reported: a scanned server without a catalog entry keeps empty catalog fields, and a catalog entry without a directory is listed separately rather than dropped. Entries are joined on the catalog id first and on the npm package name second, because a server may publish under a different name than its directory.

A missing, unreadable, foreign-schema, or structurally invalid catalog never fails a tool call. The enriched fields degrade to empty and the output names the reason, so an absent catalog is distinguishable from a server that genuinely holds no state. An unreadable MCP root is likewise reported as unreadable instead of as an empty result.

Host registers: locks, permissions, decisions, governance, resources

The seven tools above answer a different question from the rest of this server: not "what can I configure?" but "what applies on this machine right now?" They read six host-local registers — project locks, an agent-neutral permission register, a pending decision list, a policy registry, the strategic-plan index, and a resource inventory of systems and installed software.

controlcenter_list_governance composes the generated decision index, the existing ellmos.plans-register/1 strategic-plan index, and an explicitly configured ellmos.policy-registry.v1 file. The policy registry is validated only through the canonical PolicyRegistry.load() API. Every source reports available, unconfigured, unreadable, or invalid; partial data never claims completeness, and a valid registry with zero BYUM candidates reports an honest zero. Plan paths, notes and host variants remain in _PLANS; BYUM rows remain pending advisory pointers without adoption or execution authority.

controlcenter_list_resources and controlcenter_describe_resource are a read-only mirror of .SYNC/_inventory/inventory.db. Register authority sits with the ControlRoom programme's own resources.inventory resolver role, not with this server — this mirror can go stale between syncs and never claims otherwise.

They are read-only. No lock is created, renewed or released; no decision is answered. LOCK.user.* locks in particular are removed by the user alone, and nothing here can touch them.

They fail closed. If a register is unconfigured, a path is unreadable, the interpreter is missing or a check errors, the verdict is unknown and safe to proceed is no — never a reassuring "clear". A lock checker that guesses in the reassuring direction is more dangerous than none at all.

Inheritance is respected. A LOCK.txt in a parent directory locks everything beneath it, so controlcenter_check_lock walks the whole ancestor chain and reports the effective lock with its distance, not just a file sitting in the same folder.

Lock semantics are not reimplemented here. A small bridge script delegates every rule — expiry, protected lock types, scope parsing, permission precedence deny > ask > allow > default — to the host's canonical Python modules. A second implementation would drift from the spec on the next change to it. This is the one place where the server calls Python; if no interpreter is available the tools fail closed like any other unmet precondition.

Configuration

These tools are inert until configured, because these registers do not exist on a machine that has not set them up:

Documentation truncated — see the full README on GitHub.