内容
# Dotfiles Maintainer MCP
[](https://github.com/lonlydwolf/dotfiles-maintainer/actions/workflows/ci.yml)
[](https://pypi.org/project/dotfiles-maintainer/)
[](https://codecov.io/gh/lonlydwolf/dotfiles-maintainer)
[](LICENSE)
[](pyproject.toml)
**一款用于管理配置文件的人工智能原生MCP服务器，具有语义记忆、上下文感知和严格的偏移检测功能。**
---
## 🚀 主要功能
* **🧠 语义记忆：** 记录更改的原因，而不仅仅是记录更改的内容。
* **🛡️ 偏移检测：** 通过在会话开始时检测未提交的更改，防止配置腐烂。
* **🖥️ 硬件感知：** 根据系统元数据（操作系统、CPU、Shell）调整建议。
* **🔒 默认安全：** 在存储记忆之前自动编辑API密钥和机密。
* **🔌 模块化和可扩展：** 基于`FastMCP`（通过官方SDK）构建，具有插件就绪的架构。
---
## 📦 安装
### 先决条件
* **Python 3.10+**
* **uv** （快速Python包安装程序）
如果您尚未安装`uv`：
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
### 逐步安装
1. **克隆仓库：**
```bash
git clone https://github.com/lonlydwolf/dotfiles-maintainer.git
cd dotfiles-maintainer
```
*注意：该项目还支持[Jujutsu (jj)](https://github.com/martinvonz/jj)用于版本控制。*
2. **安装依赖项：**
```bash
uv sync
```
3. **环境配置：**
服务器需要以下环境变量才能进行内存操作：
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `DOTFILES_USER_ID` | 内存分区的唯一ID | 当前 `$USER` |
| `DOTFILES_LLM_PROVIDER` | `openai`, `anthropic`, `gemini`, 或 `ollama` | `gemini` |
| `LLM_KEY` | 所选提供商的API密钥 | （必填） |
| `LOG_LEVEL` | 日志级别（DEBUG, INFO等） | `INFO` |
---
## 🛠️ MCP客户端配置
要将此服务器与MCP兼容的客户端一起使用，请配置它通过`uv`运行。
### 通用配置模式
大多数客户端需要类似以下配置：
**命令：** `uv`
**参数：** `--directory /absolute/path/to/dotfiles-maintainer run dotfiles-mcp`
**环境变量：**
* `LLM_KEY`: 您的API密钥
* `DOTFILES_USER_ID`: 您的用户名
### 实现示例
#### Gemini CLI
将以下内容添加到您的`config.yaml`或相关设置中：
```yaml
mcpServers:
dotfiles-maintainer:
command: uv
args: ["--directory", "/path/to/repo", "run", "dotfiles-mcp"]
env:
LLM_KEY: "..."
DOTFILES_USER_ID: "..."
```
#### Claude Desktop / Claude Code
将以下内容添加到您的`claude_desktop_config.json`：
```json
{
"mcpServers": {
"dotfiles-maintainer": {
"command": "uv",
"args": ["--directory", "/path/to/repo", "run", "dotfiles-mcp"],
"env": {
"LLM_KEY": "...",
"DOTFILES_USER_ID": "..."
}
}
}
}
```
#### IDE扩展（Cursor / Continue）
使用上述通用命令模式配置为“外部MCP服务器”。
---
## 🧪 测试
我们使用`pytest`进行单元测试和集成测试。
```bash
# 运行所有测试
uv run pytest
# 运行并生成覆盖率报告
uv run pytest --cov=dotfiles_maintainer
```
---
## 🔄 版本控制工作流
该项目使用**Jujutsu (jj)**进行管理，但完全支持标准的Git工作流。
* **主要VCS：** [Jujutsu (jj)](https://github.com/martinvonz/jj)
* **兼容性：** 与`git`命令完全兼容。
---
## 🏗️ 架构
该项目遵循模块化架构：
```
src/dotfiles_maintainer/
├── core/ # 共享逻辑（内存、类型）
├── tools/ # 单个MCP工具（偏移检测、历史记录等）
├── prompts/ # 系统角色和工作流
└── utils/ # 版本控制系统和安全助手
```
---
## 💻 开发与贡献
我们欢迎贡献！请查看[CONTRIBUTING.md](./CONTRIBUTING.md)获取详细指南。
### 使用模板
使用`Templates/`目录中的模板：
* **工具：** `Templates/tool.py.template`
* **资源：** `Templates/resource.py.template`
* **提示：** `Templates/prompt.py.template`
### 添加新工具
1. 将`Templates/tool.py.template`复制到`src/dotfiles_maintainer/tools/your_tool.py`。
2. 使用`MemoryManager`实现逻辑。
3. 在`src/dotfiles_maintainer/server.py`中注册该工具。
---
## 🔍 故障排除
* **`uv: command not found`：** 确保`uv`已安装并在您的PATH中。
* **数据库错误：** 确保`~/.dotfiles-mcp/qdrant`可写入。
* **相对路径：** 在MCP客户端配置中始终使用**绝对路径**。
---
## ✅ 开发状态
**已完成：**
- [x] 模块化重构
- [x] 核心工具实现
- [x] 健康检查工具
- [x] 手动测试CLI
**下一步：**
- [ ] 备份和恢复 (`export_memory_backup`)
- [ ] 机密扫描 (`scan_for_uncommitted_secrets`)
---
**许可证：** Apache 2.0
