# supanut-p/mcp-linux architecture

> Architecture diagram of the GitHub repository supanut-p/mcp-linux, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/supanut-p/mcp-linux
- Repository: https://github.com/supanut-p/mcp-linux

## Overview

Baitonghub-Linux-mcp is a headless Linux runtime that lets an MCP client perform bounded, policy-controlled work in registered workspaces and on explicitly registered hosts. The main path is MCP transport to server/tool dispatch, then workspace or system-operation services, with results and durable task state returned to the client. The README documents a broad tool surface; unsampled capabilities are represented at their existing subsystem paths. Edges are limited to README statements and shown source references, so some internal tool-to-service wiring is intentionally omitted.

Main entry points: [`packages/workspace/src/workspace-service.ts`](https://github.com/supanut-p/mcp-linux/blob/main/packages/workspace/src/workspace-service.ts) (Workspace roots), [`packages/application/src/file-service.ts`](https://github.com/supanut-p/mcp-linux/blob/main/packages/application/src/file-service.ts) (File operations), [`packages/mcp-server/src/server.ts`](https://github.com/supanut-p/mcp-linux/blob/main/packages/mcp-server/src/server.ts) (MCP server), [`packages/mcp-server/src/stdio.ts`](https://github.com/supanut-p/mcp-linux/blob/main/packages/mcp-server/src/stdio.ts) (STDIO transport)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["MCP interfaces"]
  node_stdio["STDIO transport<br/>[stdio.ts]"]
  node_http["HTTP transport<br/>[http.ts]"]
  node_server["MCP server<br/>[server.ts]"]
  node_registry["Tool registry<br/>[tool-registry.ts]"]
  node_taskproto["Task protocol<br/>[tasks-protocol.ts]"]
end

subgraph group_workspace["Workspace work"]
  node_workspaces["Workspace roots"]
  node_files["File operations<br/>[file-service.ts]"]
  node_search["Search and context<br/>[search-service.ts]"]
  node_tree["Workspace tree"]
  node_snapshots["Workspace snapshots"]
  node_checkpoints["Workspace checkpoints"]
end

subgraph group_operations["Linux and remote operations"]
  node_processes["Owned processes<br/>[process-manager.ts]"]
  node_capabilities["Linux capabilities"]
  node_remote["Remote hosts and rollout"]
  node_extensions["MCP extensions"]
end

subgraph group_governance["State and safeguards"]
  node_database[("Runtime database<br/>[database.ts]")]
  node_backups["Backup bundles<br/>[backup-service.ts]"]
  node_audit["Audit records<br/>[audit-service.ts]"]
  node_permissions["Permission policy"]
  node_workspaceguard["Workspace boundaries"]
end

node_client(("MCP client"))

node_client -->|"connects via"| node_stdio
node_client -->|"connects via"| node_http
node_stdio -.->|"serves requests"| node_server
node_http -.->|"serves requests"| node_server
node_server -->|"uses registry"| node_registry
node_client -->|"submits tasks"| node_taskproto
node_client -->|"registers roots"| node_workspaces
node_client -->|"manages files"| node_files
node_client -->|"searches workspace"| node_search
node_client -->|"inspects tree"| node_tree
node_client -->|"compares snapshots"| node_snapshots
node_client -->|"creates checkpoints"| node_checkpoints
node_client -->|"runs tasks"| node_processes
node_client -->|"uses tools"| node_capabilities
node_client -->|"administers hosts"| node_remote
node_client -.->|"calls extensions"| node_extensions
node_client -->|"manages backups"| node_backups
node_client -->|"queries audit"| node_audit
node_client -->|"explains policy"| node_permissions
node_files -->|"resolves roots"| node_workspaces
node_files -->|"checks paths"| node_workspaceguard
node_search -->|"resolves roots"| node_workspaces
node_tree -->|"resolves roots"| node_workspaces
node_backups -->|"backs up"| node_database

click node_stdio "https://github.com/supanut-p/mcp-linux/blob/main/packages/mcp-server/src/stdio.ts"
click node_http "https://github.com/supanut-p/mcp-linux/blob/main/packages/mcp-server/src/http.ts"
click node_server "https://github.com/supanut-p/mcp-linux/blob/main/packages/mcp-server/src/server.ts"
click node_registry "https://github.com/supanut-p/mcp-linux/blob/main/packages/mcp-server/src/tool-registry.ts"
click node_taskproto "https://github.com/supanut-p/mcp-linux/blob/main/packages/mcp-server/src/tasks-protocol.ts"
click node_workspaces "https://github.com/supanut-p/mcp-linux/blob/main/packages/workspace/src/workspace-service.ts"
click node_files "https://github.com/supanut-p/mcp-linux/blob/main/packages/application/src/file-service.ts"
click node_search "https://github.com/supanut-p/mcp-linux/blob/main/packages/application/src/search-service.ts"
click node_tree "https://github.com/supanut-p/mcp-linux/blob/main/packages/application/src/workspace-query-service.ts"
click node_snapshots "https://github.com/supanut-p/mcp-linux/blob/main/packages/mcp-server/src/workspace-snapshot-service.ts"
click node_checkpoints "https://github.com/supanut-p/mcp-linux/blob/main/packages/mcp-server/src/workspace-checkpoint-service.ts"
click node_processes "https://github.com/supanut-p/mcp-linux/blob/main/packages/process/src/process-manager.ts"
click node_capabilities "https://github.com/supanut-p/mcp-linux/tree/main/packages/capabilities/src"
click node_remote "https://github.com/supanut-p/mcp-linux/blob/main/packages/mcp-server/src/remote-rollout-runtime.ts"
click node_extensions "https://github.com/supanut-p/mcp-linux/blob/main/packages/extensions/src/extensions-service.ts"
click node_database "https://github.com/supanut-p/mcp-linux/blob/main/packages/storage/src/database.ts"
click node_backups "https://github.com/supanut-p/mcp-linux/blob/main/packages/storage/src/backup-service.ts"
click node_audit "https://github.com/supanut-p/mcp-linux/blob/main/packages/audit/src/audit-service.ts"
click node_permissions "https://github.com/supanut-p/mcp-linux/blob/main/packages/permissions/src/permission-engine.ts"
click node_workspaceguard "https://github.com/supanut-p/mcp-linux/blob/main/packages/workspace/src/workspace-path-guard.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_stdio,node_http,node_server,node_registry,node_taskproto,node_client toneBlue
class node_workspaces,node_files,node_search,node_tree,node_snapshots,node_checkpoints toneAmber
class node_processes,node_capabilities,node_remote,node_extensions toneMint
class node_database,node_backups,node_audit,node_permissions,node_workspaceguard toneRose
```

## Components

### MCP interfaces

- [STDIO transport](https://github.com/supanut-p/mcp-linux/blob/main/packages/mcp-server/src/stdio.ts): `packages/mcp-server/src/stdio.ts`
- [HTTP transport](https://github.com/supanut-p/mcp-linux/blob/main/packages/mcp-server/src/http.ts): `packages/mcp-server/src/http.ts`
- [MCP server](https://github.com/supanut-p/mcp-linux/blob/main/packages/mcp-server/src/server.ts): `packages/mcp-server/src/server.ts`
- [Tool registry](https://github.com/supanut-p/mcp-linux/blob/main/packages/mcp-server/src/tool-registry.ts): `packages/mcp-server/src/tool-registry.ts`
- [Task protocol](https://github.com/supanut-p/mcp-linux/blob/main/packages/mcp-server/src/tasks-protocol.ts): `packages/mcp-server/src/tasks-protocol.ts`

### Workspace work

- [Workspace roots](https://github.com/supanut-p/mcp-linux/blob/main/packages/workspace/src/workspace-service.ts): `packages/workspace/src/workspace-service.ts`
- [File operations](https://github.com/supanut-p/mcp-linux/blob/main/packages/application/src/file-service.ts): `packages/application/src/file-service.ts`
- [Search and context](https://github.com/supanut-p/mcp-linux/blob/main/packages/application/src/search-service.ts): `packages/application/src/search-service.ts`
- [Workspace tree](https://github.com/supanut-p/mcp-linux/blob/main/packages/application/src/workspace-query-service.ts): `packages/application/src/workspace-query-service.ts`
- [Workspace snapshots](https://github.com/supanut-p/mcp-linux/blob/main/packages/mcp-server/src/workspace-snapshot-service.ts): `packages/mcp-server/src/workspace-snapshot-service.ts`
- [Workspace checkpoints](https://github.com/supanut-p/mcp-linux/blob/main/packages/mcp-server/src/workspace-checkpoint-service.ts): `packages/mcp-server/src/workspace-checkpoint-service.ts`

### Linux and remote operations

- [Owned processes](https://github.com/supanut-p/mcp-linux/blob/main/packages/process/src/process-manager.ts): `packages/process/src/process-manager.ts`
- [Linux capabilities](https://github.com/supanut-p/mcp-linux/tree/main/packages/capabilities/src): `packages/capabilities/src`
- [Remote hosts and rollout](https://github.com/supanut-p/mcp-linux/blob/main/packages/mcp-server/src/remote-rollout-runtime.ts): `packages/mcp-server/src/remote-rollout-runtime.ts`
- [MCP extensions](https://github.com/supanut-p/mcp-linux/blob/main/packages/extensions/src/extensions-service.ts): `packages/extensions/src/extensions-service.ts`

### State and safeguards

- [Runtime database](https://github.com/supanut-p/mcp-linux/blob/main/packages/storage/src/database.ts): `packages/storage/src/database.ts`
- [Backup bundles](https://github.com/supanut-p/mcp-linux/blob/main/packages/storage/src/backup-service.ts): `packages/storage/src/backup-service.ts`
- [Audit records](https://github.com/supanut-p/mcp-linux/blob/main/packages/audit/src/audit-service.ts): `packages/audit/src/audit-service.ts`
- [Permission policy](https://github.com/supanut-p/mcp-linux/blob/main/packages/permissions/src/permission-engine.ts): `packages/permissions/src/permission-engine.ts`
- [Workspace boundaries](https://github.com/supanut-p/mcp-linux/blob/main/packages/workspace/src/workspace-path-guard.ts): `packages/workspace/src/workspace-path-guard.ts`

### Other components

- **MCP client**

## Connections

- MCP client → STDIO transport: connects via
- MCP client → HTTP transport: connects via
- STDIO transport → MCP server: serves requests
- HTTP transport → MCP server: serves requests
- MCP server → Tool registry: uses registry (evidence: `packages/mcp-server/src/server.ts`)
- MCP client → Task protocol: submits tasks
- MCP client → Workspace roots: registers roots
- MCP client → File operations: manages files
- MCP client → Search and context: searches workspace
- MCP client → Workspace tree: inspects tree
- MCP client → Workspace snapshots: compares snapshots
- MCP client → Workspace checkpoints: creates checkpoints
- MCP client → Owned processes: runs tasks
- MCP client → Linux capabilities: uses tools
- MCP client → Remote hosts and rollout: administers hosts
- MCP client → MCP extensions: calls extensions
- MCP client → Backup bundles: manages backups
- MCP client → Audit records: queries audit
- MCP client → Permission policy: explains policy
- File operations → Workspace roots: resolves roots (evidence: `packages/application/src/file-service.ts`)
- File operations → Workspace boundaries: checks paths (evidence: `packages/application/src/file-service.ts`)
- Search and context → Workspace roots: resolves roots (evidence: `packages/application/src/search-service.ts`)
- Workspace tree → Workspace roots: resolves roots (evidence: `packages/application/src/workspace-query-service.ts`)
- Backup bundles → Runtime database: backs up (evidence: `packages/storage/src/database.ts`)