Dotfiles Maintainer MCP
An AI-native MCP server for managing configuration files with semantic memory, context awareness, and strict drift detection.
🚀 Key Features
- 🧠 Semantic Memory: Remembers why changes were made, not just what changed.
- 🛡️ Drift Detection: Prevents configuration rot by detecting uncommitted changes at session start.
- 🖥️ Hardware Aware: Adapts suggestions based on system metadata (OS, CPU, Shell).
- 🔒 Secure by Default: Automatically redacts API keys and secrets before storing memories.
- 🔌 Modular & Extensible: Built on
FastMCP(via official SDK) with a plugin-ready architecture.
📦 Installation
Prerequisites
- Python 3.10+
- uv (Fast Python package installer)
If you don't have uv installed:
curl -LsSf https://astral.sh/uv/install.sh | sh
Step-by-Step Installation
-
Clone the repository:
git clone https://github.com/lonlydwolf/dotfiles-maintainer.git cd dotfiles-maintainer
Note: This project also supports Jujutsu (jj) for version control.
-
Install dependencies:
uv sync -
Environment Configuration: The server requires the following environment variables for memory operations:
Variable Description Default DOTFILES_USER_IDUnique ID for memory partitioning Current $USERDOTFILES_LLM_PROVIDERopenai,anthropic,gemini, orollamageminiLLM_KEYAPI Key for the chosen provider (Required) LOG_LEVELLogging level (DEBUG, INFO, etc.) INFO
🛠️ MCP Client Configuration
To use this server with an MCP-compliant client, configure it to run via uv.
Generic Configuration Pattern
Most clients require a configuration similar to this:
Command: uv
Arguments: --directory /absolute/path/to/dotfiles-maintainer run dotfiles-mcp
Environment Variables:
LLM_KEY: your-api-keyDOTFILES_USER_ID: your-username
Implementation Examples
Gemini CLI
Add to your config.yaml or relevant settings:
mcpServers:
dotfiles-maintainer:
command: uv
args: ["--directory", "/path/to/repo", "run", "dotfiles-mcp"]
env:
LLM_KEY: "..."
DOTFILES_USER_ID: "..."
Claude Desktop / Claude Code
Add to your claude_desktop_config.json:
{
"mcpServers": {
"dotfiles-maintainer": {
"command": "uv",
"args": ["--directory", "/path/to/repo", "run", "dotfiles-mcp"],
"env": {
"LLM_KEY": "...",
"DOTFILES_USER_ID": "..."
}
}
}
}
IDE Extensions (Cursor / Continue)
Configure as an "External MCP Server" using the generic command pattern above.
🧪 Testing
We use pytest for unit and integration testing.
# Run all tests
uv run pytest
# Run with coverage report
uv run pytest --cov=dotfiles_maintainer
🔄 Version Control Workflow
This project is managed with Jujutsu (jj), but fully supports standard Git workflows.
- Primary VCS: Jujutsu (jj)
- Compatibility: Fully compatible with
gitcommands.
🏗️ Architecture
The project follows a modular architecture:
src/dotfiles_maintainer/
├── core/ # Shared logic (Memory, Types)
├── tools/ # Individual MCP tools (Drift, History, etc.)
├── prompts/ # System Persona & Workflows
└── utils/ # VCS & Security helpers
💻 Development & Contributing
We welcome contributions! Please check CONTRIBUTING.md for detailed guidelines.
Using Templates
Use the provided templates in the Templates/ directory:
- Tools:
Templates/tool.py.template - Resources:
Templates/resource.py.template - Prompts:
Templates/prompt.py.template
Adding a New Tool
- Copy
Templates/tool.py.templatetosrc/dotfiles_maintainer/tools/your_tool.py. - Implement logic using
MemoryManager. - Register the tool in
src/dotfiles_maintainer/server.py.
🔍 Troubleshooting
uv: command not found: Ensureuvis in your PATH after installation.- Database Errors: Ensure
~/.dotfiles-mcp/qdrantis writable. - Relative Paths: Always use absolute paths in MCP client configurations.
✅ Development Status
Completed:
- Modular Refactoring
- Core Tools Implementation
- Health Check Tool
- Manual Testing CLI
Next Steps:
- Backup & Restore (
export_memory_backup) - Secrets Scanning (
scan_for_uncommitted_secrets)
License: Apache 2.0
Metadata
Release files for dotfiles-maintainer 1.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| dotfiles_maintainer-1.0.1.tar.gz | 345.8 kB | Without provenance | Details for dotfiles_maintainer-1.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| dotfiles_maintainer-1.0.1-py3-none-any.whl | Python 3 | none | any | Details for dotfiles_maintainer-1.0.1-py3-none-any.whl |
Total release size: 402.1 kB
Release files / dotfiles_maintainer-1.0.1.tar.gz
| Download URL | dotfiles_maintainer-1.0.1.tar.gz |
|---|---|
| Size | 345.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c557e336768c56f67265a915fcb0b6e78ac7ae408f5d19181ee4e7410517d0fb
|
|
BLAKE2b-256 checksum How to use checksums |
5310656f1857d03f79bca651044023b74d7a6a5feef824a3aa7ebed1f697edc3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.26 {"installer":{"name":"uv","version":"0.9.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / dotfiles_maintainer-1.0.1-py3-none-any.whl
| Download URL | dotfiles_maintainer-1.0.1-py3-none-any.whl |
|---|---|
| Size | 56.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4d7acc6359eda36a6fa6b8e3c75ae4d44d3711ff5c307c48dc6340d14740c831
|
|
BLAKE2b-256 checksum How to use checksums |
09bfdd42da1fb19c3024d34c00cbf452d541609bc9b11cabcd32f302e0c45521
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.26 {"installer":{"name":"uv","version":"0.9.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for dotfiles-maintainer 1.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.