dotfiles-ubuntu MCP server
Commit Nov 11, 2026Manages Ubuntu 26.04 LTS systems and provides a contextual MCP server for human-AI governance using declarative manifests and rcap1 capsules.
Also known as mtwuser/dotfiles-ubuntu
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 11, 2026
- License
- MIT
What is dotfiles-ubuntu MCP?
dotfiles-ubuntu manages Ubuntu 26.04 LTS systems and provides a contextual MCP server for human-AI governance using declarative manifests and rcap1 capsules.
Summary generated from the project's README
About dotfiles-ubuntu MCP server
Managing Ubuntu 26.04 LTS systems and establishing human-AI governance is what dotfiles-ubuntu enables through declarative manifests and rcap1 capsules. This tool serves solo developers and multi-layer organizations by providing a structured way to manage system backups, dotfile symlinks via GNU Stow, and distributed programming workflows. It operates locally on Ubuntu workstations, using a zero-dependency Python 3.14 environment to execute deterministic lifecycle hooks and manage system drift.
Users can deploy the server in several modes, ranging from individual workstation setups to complex organizational hierarchies. The system utilizes a contextual MCP server that indexes Markdown layers into signed capsules for efficient information transfer. It integrates with environments like Google Antigravity 2.0, Gemini, VS Code, and Claude Code to provide specialized skills across academic, scientific, and corporate stacks. By using plain files and Git, it ensures that every governed directory maintains a verifiable history of rules and tasks.
What you can do with it
- 1Ubuntu system recoveryA developer can rebuild a machine from scratch by using manifests that snapshot APT packages, Snaps, and GNOME settings.
- 2Automated dotfile managementYou can manage shell and Git configurations using GNU Stow while keeping sensitive information in local overrides.
- 3Contextual AI skill deploymentAn AI client can access specialized task skills like academic tutoring or security audits through the MCP server.
- 4Organizational layer orchestrationTeams can organize work from a root level down to specific projects using a hierarchical Git subtree structure.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 16, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablemtwuser/dotfiles-ubuntu is public and reachablegithub.com/mtwuser/dotfiles-ubuntu ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-11github.com/mtwuser/dotfiles-ubuntu ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubdotfiles-ubuntu
[!IMPORTANT] 🚀 Architectural Succession & Permanent Historical Freeze (
dotfiles-ubuntu v5.0.0$\rightarrow$ZeroCloudGravity v1.0.0) With thev5.0.0milestone,dotfiles-ubuntureaches its permanent historical freeze. Active development has been succeeded byZeroCloudGravity(zero-cloud-gravityv1.0.0+) (zcgCLI +zcg-mcp), which cleanly decouples the agnostic Open-Source Zero-Cloud Node & Contextual MCP Engine (~/zero-cloud-gravity) from each operator's sovereign personalRoot 0workstation repository (~/<user-pc>). New installations and multi-layer organizations should adoptzero-cloud-gravity.
Declarative system manager, dotfile engine, and Distributed Human-AI Governance ("pAIr programming") Platform for Ubuntu 26.04 LTS ("Resolute Raccoon") and Google Antigravity 2.0 / Gemini (directly extrapolable to VS Code & GitHub Copilot, Cursor, and Claude Code).
This repository is modular and grounded in one unified fractal pattern (every governed directory combines a manifest, Markdown rules/skills, and task ledgers across Root 0 -> Department (1..N) -> Project using 4 Universal Human-AI Bases (human-stack) $\times$ 3 Specialization Stack Rings ({context,framework,plugin}-stack), executed deterministically via plain files, Git, and zero-dependency Python 3.14):
- Ubuntu System Backup, Audit & Restore (
backup.sh,audit.sh,bootstrap.sh) — snapshot installed APT packages, Snaps, NPM globals, external recipes, and GNOME desktop settings into plain-textsystem/*manifests, audit system drift, or rebuild a machine from scratch. - Dotfile Symlink Management (
bash/,git/) — manage~/.bashrc,~/.profile, and~/.gitconfigvia GNU Stow while keeping personal identity and secrets in untracked local overrides (~/.bashrc.local,~/.gitconfig.local). - Local Antigravity 2.0 Governance (
antigravity/,templates/) — composableAGENTS.mdbaselines (human-stack:universal-base,academic-base,science-base,business-base), 4 deterministic Python 3.14 lifecycle hooks (PreToolUse,PostToolUse,PostInvocation,Stop), 26 reusable skills (8globalhuman-stack+7context-stack+7framework-stack+4plugin-stackacross/sopen,/sclose,/continue,/release,/enrich,/review,/audit,oss-contribute,academic-tutor,ledger-surface-audit,fastapi-testing,angular-testing,django-testing,nist-csf-audit,corporate-web-ops,corporate-backend-ops,layer-hub-ops,secops-mcp-orchestration, etc.), and 3 specialization stack rings completing the4 × 4 = 16Template Stack Matrix:context-stack(academic-curriculum,scientific-methodology,software-engineering,corporate-operations),framework-stack(fastapi-hexagonal,angular-frontend,django-fullstack,nist-csf-security), andplugin-stack(corporate-web-portal,corporate-admin-api,layer-hub-portal,secops-mcp-guardian). - Multi-Layer Orchestrator & Contextual MCP Server (
scripts/layer-config.sh,scripts/layer-subtree.sh,scripts/dotfiles_mcp_server.py) — deterministic file/Git/SHA-256 orchestrator (bootstrap-workspace,apply-project,make sync,make delegate,make task,make complete,make promote) plus a zero-dependencystdioJSON-RPC MCP server indexing layer Markdown into signedrcap1(zlib + HMAC-SHA256) capsules (make consult).
| Progressive Adoption Mode | Who It Is For | What Executes on Disk (0 External Servers Required) |
|---|---|---|
| Mode 1 — Individual Workstation | Solo developer or manager on Ubuntu | ./bootstrap.sh --workstation + set-global-profile symlinks ~/.gemini/config/ and keeps $HOME synced via dotfiles-sync. |
| Mode 2 — Standalone Project + Stack | Any single software, ops, or research repo | ./scripts/layer-config.sh apply-project <dir> --template <stack> projects .agents/rules/ and .agents/skills/ with SHA-256 drift tracking. |
| Mode 3 — Multi-Layer Organization | Root 0 -> Department (1..N) -> Project |
bootstrap-workspace + layers/<child>/ (git subtree) + make delegate / make complete / make consult (rcap1 capsules). |
Mode 4 — Engine Contributor (oss-dev) |
Maintaining or extending dotfiles-ubuntu |
make setup-dev + make verify runs the 8-stage deterministic verification gate (100% isolated 1:1 branch coverage). |
Objective Engineering Virtues & Live Empirical Benchmarks (
100%Python 3.14 Stdlib ·0External Dependencies):
- Deterministic $O(N)$ Structural Compaction (
rcap1L0/L1+ 2D Geometry): Enforcing< 465lines/file,H1..H4hierarchy, 1-line lead sentences, and> *"...*"mandate quotes turns Markdown specs into pre-indexed ASTs — achieving88.7%(L0,522vs.4,622tok) and67.0%(L1,1,523vs.4,622tok) compaction across130k+tokens in~16 ms(0LLM summarization calls,0vector DBs, and-76.3%single-envelopezlib-first capsule size at518–577chars/capsule). SeeArchitecture 04 §2.9.- Content-Addressable Merkle Provenance (
citation_receipt): Every section is pinned by<layer>::<file>#<slug>@<sha256_16>:<E3..E0>, enabling $O(1)$ cryptographic drift detection (CITATION_DRIFT_DETECTED),E3 > E2 > E1 > E0monotonicity proofs (verify_epistemic_context_claims), andQ1..Q4lifecycle telemetry.- Zero-Checkout C-Backed Git Plumbing (
DMCP&GRCC): Multi-branch context projection readsgit ls-tree/git cat-filedirectly from.git/objects(zero_checkout: true,0working-tree mutations) and chains encrypted capsules underrefs/capsules/*without pollutingrefs/heads/*.- Mathematically Verified
1:1:1Architecture:37production modules (25executable inscripts/dotfiles_mcp/) $\leftrightarrow$371:1:1test suites (100.00%isolated unit line and branch coverage,< 2s) $\leftrightarrow$6normative architecture specifications (< 465lines/file).
1. Navigation & Progressive Disclosure (docs/)
The documentation hub is organized into 3 progressive-disclosure tiers so humans and AI agents locate exact specifications in $O(1)$:
| Tier | What You Will Find | Guide / Specification |
|---|---|---|
| Tier 1 (Gateway) | Quick-Start paths, repository tree, CLI cheat-sheet, and subsystem lookup map. | README.md (this file) · docs/README.md |
| Tier 2 (Human Guides) | GNU Stow tree unfolding, system/* manifests & external recipes, daily usage, all bootstrap.sh & audit.sh modes, multi-machine setup/migration, Phase 0 Linear $HOME Control Tower Onboarding (Case 1), portability matrix, and uninstallation. |
docs/guides/01_ubuntu_system_and_multi_machine_guide.md |
| Tier 2 (Hierarchical Workflows) | 4 Universal Human-AI Bases (human-stack: universal-base, academic-base, science-base, business-base), 26-skill matrix across 4 Universal Bases + 3 Specialization Stack Rings (context-stack, framework-stack, plugin-stack), scoped antigravity-agents workspaces, Root 0 -> Department -> Case/Unit/Squad -> Project setup blueprints, M1 -> M4 Personal Tutor Showcase & 4-Phase Customizable Kickoff Prompts (Cases 1–5), Git email authority gates, 1-hop horizon radar, and upward PR promotion. |
docs/guides/02_hierarchical_layers_and_team_workflows.md |
| Tier 3A (Normative Specs) | 1:1:1 source-test-spec contracts (Specification:) for the Ubuntu engine, lifecycle hooks, MCP server, rcap1 compaction, surface weaver, ephemeral Department Bots, and layer governance/promotion engines. |
01: System & Stow · 02: Governance & Hooks · 03: Contextual MCP · 04: Compaction & Weaver · 05: Ephemeral Bots · 06: Layer Governance |
| Tier 3B (Reference) | Enterprise "pAIr programming" playbook, Cross-Departmental (0..80) & Human-Stack (85..95) Matrix, Docker/SSH MCP orchestration, and maintainer extension workflows. |
Enterprise Governance · Cross-Dept & Human-Stack · Contextual MCP Mesh · Maintainer Guide |
2. Quick Start: 3 Main Ways to Use This Repository
Choose one of the three adoption paths below depending on whether you need standalone Antigravity governance, full Ubuntu workstation management, or multi-layer enterprise orchestration.
2.1. Path 1: Google Antigravity 2.0 Setup & Usage (Standalone)
Install global rules (~/.gemini/config/AGENTS.md), deterministic lifecycle hooks (hooks.json + scripts/), 8 universal global skills (~/.gemini/config/skills/), and desktop launchers without changing your shell, Git config, or Ubuntu packages:
git clone https://github.com/mtwuser/dotfiles-ubuntu.git ~/dotfiles-ubuntu
cd ~/dotfiles-ubuntu
./bootstrap.sh --workstation # Sets up read-only runtime, boot auto-sync & dotfiles-sync command
# (or ./bootstrap.sh --antigravity for standalone Antigravity links only)
# Install/upgrade Antigravity Agents + agy CLI (Recommended; --ide is optional):
./scripts/antigravity-install.sh --agents # or --cli (CLI only) / --ide (optional IDE) / --all
# Any time in terminal: pull latest release, re-apply global profile & re-stow
dotfiles-sync # or ./scripts/workstation-sync.sh --status
2.2. Path 2: Fork & Manage YOUR Own Ubuntu 26.04 System
Turn a fork of this repository into your personal Ubuntu 26.04 backup, audit, and recovery engine — ./backup.sh overwrites system/* with your machine's packages and GNOME settings:
# Phase A — Initialize your fork from your current Ubuntu 26.04 workstation
git clone https://github.com/<your-user>/dotfiles-ubuntu.git ~/dotfiles-ubuntu
cd ~/dotfiles-ubuntu
./backup.sh # Captures YOUR APT, Snap, NPM, external recipes & GNOME settings
./audit.sh # Verifies 0 drift between your workstation and system/* manifests
./bootstrap.sh --stow # Symlinks bash/, git/, and antigravity/ (preserves ~/.gitconfig.local)
# Phase B — Restore or provision a fresh Ubuntu 26.04 PC from your fork
./bootstrap.sh # Interactive mode (or ./bootstrap.sh --all for unattended restore)
# Granular flags: --antigravity, --stow, --packages, --external, --nvm, --gnome
📖 Full details on GNU Stow tree unfolding, .audit-ignore, multi-machine migration, and uninstallation: docs/guides/01_ubuntu_system_and_multi_machine_guide.md.
2.3. Path 3: Enterprise & Multi-Tier Human-AI Governance (With or Without MCP)
Orchestrate Human-AI governance across Open Source (oss-dev / oss-readonly-appliance) $\leftrightarrow$ Root 0 (corporate-root: Public Administration 1..2 | Company 10) $\leftrightarrow$ Department (3..60, recursive 1..N: Statutory/Policy 3..9, Functional 15..40, Sub-Department / Unit / Squad 40..60) $\leftrightarrow$ Project / Case (project 80) (Mode A — Without MCP via pure Git + Stow + layer-config.sh static projection, or Mode B — With MCP via scripts/dotfiles_mcp_server.py and layers/* git subtree mounts):
flowchart TD
SUB["Intrinsic Runtime Substrate\n(C-Backed Python Stdlib · PEP 7 · Ubuntu 26.04 Core)"]
OSS["Open Source Upstream & Contributor Clone\n(operating_state: oss-dev · DOTFILES_DEV_REPO_DIR)"]
APP["Local Workstation Appliance\n(operating_state: oss-readonly-appliance · ~/dotfiles-ubuntu)"]
CORP["Level 1: Root 0 (Public Admin 1..2 | Enterprise Company 10 | Individual 90)\n(operating_state: corporate-root | individual-root · role: corporate · business-base)"]
DEPT["Level 2: Statutory & Functional Departments\n(operating_state: domain-policy [3..9] | department [15..40] · {context,framework,plugin}-stack)"]
SQUAD["Level 3: Sub-Departments, Operational Units, Tutors & Delivery Squads\n(role: department | squad · precedence: 40..60 | 86..89 · {context,framework,plugin}-stack)"]
PROJ["Level 4: Application, Case & Service Projects\n(operating_state: project · precedence: 80 · Contextual Human-Stack 85..95)"]
SUB <-->|"C-Backed Primitives &\nOSS-to-OSS Contributions"| OSS
OSS -->|"workstation-sync.sh --sync\n(Read-Only $HOME Runtime)"| APP
OSS <-->|"Downward: sync-upstream\nUpward: Anonymized PR (/enrich)"| CORP
CORP <-->|"Downward: make delegate & make sync\nUpward: make complete & make promote"| DEPT
DEPT <-->|"Downward: make delegate & make sync\nHorizontal: make consult (Ephemeral)"| SQUAD
SQUAD <-->|"Downward: apply-project & make task\nUpward: make complete & /enrich (1-Hop PR)"| PROJ
📖 Step-by-step multi-tier commands, authority gates, 26-skill matrix, M1 -> M4 Personal Tutor Showcase, 4-Phase Customizable Kickoff Prompts (Cases 1–5), and scoped antigravity-agents workspace containment: docs/guides/02_hierarchical_layers_and_team_workflows.md and docs/reference/enterprise_pair_programming_governance.md.
2.3.1. Real-World Business View: 1 Company, 3 Departments & Specialized Squad Members
Imagine a company with Corporate Direction (Root 0) and 3 core departments (Legal, Engineering/Tech, and Brand/Marketing). Instead of working in isolated silos, each department defines its rules once (precedence: 0..100, where lower numbers carry higher authority), and any squad member combines the exact specialties their task requires inside Google Antigravity:
flowchart TD
CORP["🏢 Company Direction (Root 0 · Precedence 10)\nShared identity, security & Single Source of Truth (SSoT) ledgers"]
subgraph Depts["3 Core Departments (Each Owns Its Specialty Rules)"]
LEG["⚖️ Dept 1: Legal & IP (Precedence 5)\nPrivacy (GDPR), IP & Contract Gates, Call Consent & Evidence-Backed Claims"]
TECH["⚙️ Dept 2: Engineering / Tech (Precedence 25)\nClean Architecture, 100% Automated Tests & API Security"]
MKT["🎨 Dept 3: Brand & Marketing (Precedence 30..35)\nVisual Identity, Tone of Voice, Campaigns & Social Channels"]
end
CORP --> LEG & TECH & MKT
subgraph Workspaces["How Squad Members Combine Specialties for Real Tasks (via Antigravity)"]
CASE1["👩⚖️ Case 1: LegalTech Member\n(Builds a Contract & Compliance Auditor MCP)\nOrder: Legal (5) -> Corp (10) -> Tech (25)\nResult: 100% tested code that never leaks a trade secret"]
CASE2["📣 Case 2: Growth & Social Media Member\n(Builds an Automated Social Campaign Hub)\nOrder: Legal (5) -> Corp (10) -> Tech (25) -> Brand (30) -> Mkt (35)\nResult: Fast social publishing with OAuth safety, Brand lock & Evidence-Backed Claims"]
CASE3["📞 Case 3: Transversal VoIP Service Team\n(Builds Company-Wide Telephony & Voice AI)\nOrder: Legal (5, call recording consent) -> Tech (25, SIP/SLA)\nResult: Shared VoIP service safely reusable by Legal, Sales & Support"]
end
LEG & TECH -->|"Combined in"| CASE1
LEG & TECH & MKT -->|"Combined in"| CASE2
LEG & TECH -->|"Combined in"| CASE3
CASE3 -.->|"Consumed back as a governed capability by"| LEG & MKT
2.3.2. Comparing Outcomes: Traditional Silos vs. Cross-Departmental Composition
When a business need crosses specialties (for example, Legal needs a software tool or Marketing needs a social media bot), organizations can compare what happens across approaches:
| Approach | How the Task Is Executed | What Happens in Practice (Functional Outcome) |
|---|---|---|
| ❌ Traditional Way A: Hand Off to IT Silo | Business writes a PDF specification and waits for IT to build it. | Slow & Context-Blind: Weeks of alignment meetings; IT delivers working code that misses subtle legal, IP, or brand rules. |
| ❌ Traditional Way B: Unmanaged "Shadow IT" | Legal or Marketing builds a script/bot on their own with generic AI prompts. | Fragile & Risky: Solves the immediate business goal, but with zero tests, hardcoded API keys, and high security/compliance risk. |
✅ dotfiles-ubuntu Way 1: Business-Led (apply-project --parent-dir <dept> or make apply-template) |
A specialist inside Legal or Marketing builds the tool in their workspace while injecting Tech (25) rules. |
Domain-Driven & Engineered: The business department keeps full ownership and speed, while Antigravity enforces 100% tests, clean architecture, and security automatically. |
✅ dotfiles-ubuntu Way 2: Tech-Led (layer-subtree.sh add <dept>) |
The Engineering squad builds the tool (or a transversal service like VoIP) while mounting Legal (5) and Brand (30) rules. |
Platform-Grade & Compliant: Engineers build scalable infrastructure where Antigravity blocks any code change that violates Legal (5) or Brand (30) rules before commit. |
2.3.3. Summary of the 6 Reusable Organizational Patterns
Every cross-departmental workflow resolves to one of six composable governance patterns along the 0..100 Lex Superior spectrum:
| Business / Functional Need | Who Owns the Workspace | Combined Rule Order (0..100 Lex Superior) |
How It Activates (1 Command) |
Effective Antigravity Agent Profile |
|---|---|---|---|---|
| 1. Pure Departmental Governance (Contracts, IP Registries, Ledgers, SOPs) | Root 0 or Department (Legal, Finance) |
universal-base + business-base (10) + <dept> (5..20) |
bootstrap-workspace / make sync |
Normative & SSoT Ledger Auditor (workspace_mode: business) |
| 2. In-Department Automation (Scripts/tools inside a business repo) | Department (Legal, Finance, Ops) |
<dept> (5..20) + business-base (10) + science-base + software-engineering (25) |
make apply-template (reversible via make sync) |
In-Situ Domain Automation Engineer (workspace_mode: hybrid) |
| 3. Department-Owned Tech Product (e.g., LegalTech Contract/IP MCP) | Legal (5) or Embedded Tech Squad |
Legal (5) $\rightarrow$ Corp (10) $\rightarrow$ Tech + FastAPI (25..50) |
apply-project <app> --parent-dir <dept> --template <stack> |
Software Architect Subordinated to Statutory/IP Law (hybrid) |
| 4. Multi-Departmental Solution (e.g., Marketing + Social Media Hub) | Marketing / Growth Squad (35) |
Legal/GDPR (5) $\rightarrow$ Corp (10) $\rightarrow$ Tech (25) $\rightarrow$ Brand (30) $\rightarrow$ Marketing (35) |
--parent-dir dept-marketing + layer-subtree.sh add (legal, brand) |
Full-Stack Growth Engineer Governed by Legal, Brand & Security |
5. Transversal Enterprise Platform (e.g., Company-Wide VoIP Service) |
Platform service-node / squad (25) |
Inward: Legal (5, call consent) $\rightarrow$ Ops (20, SLA) $\rightarrow$ Tech/VoIP (25)Outward: Exports templates/voip-pack + federated_mcps |
Any department mounts layers/voip-platform or applies voip-pack |
Critical Infrastructure Provider (inward) / Governed Capability (outward) |
| 6. Punctual Cross-Departmental Audit (e.g., Design checks IP/Contract Gate with Legal) | Any consumer layer | Active workspace + Ephemeral rcap1 Capsule (kr: true) |
make consult LAYER=dept-legal QUERY="..." |
Zero-Residue Read-Only Inter-Departmental Advisor (inter-layer) |
dotfiles-ubuntu MCP questions
What is the purpose of the dotfiles-ubuntu repository?
It serves as a declarative system manager, dotfile engine, and Distributed Human-AI Governance platform for Ubuntu 26.04 LTS.
Does this server require external dependencies?
No, it is built using zero-dependency Python 3.14 and uses plain files and Git for execution.
How does the MCP server handle data?
It is a zero-dependency stdio JSON-RPC MCP server that indexes layer Markdown into signed rcap1 capsules.