AI导哈

异步CRUD MCP服务器

一个基于FastMCP的Python守护进程服务器，提供带文件锁的异步CRUD操作，专为并发AI代理设计。

  • by RoscoeTheDog
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 RoscoeTheDog/async-crud-mcp

使用说明

异步crud mcp

使用以下组件构建的Python守护进程MCP（模型上下文协议）服务器 FastMCP 它提供了为并发AI代理使用而设计的文件锁定异步CRUD操作。

概述

此服务器通过MCP公开创建、读取、更新和删除工具，并内置文件锁定，以安全地处理来自多个AI代理的并发访问。它作为一个持久的守护进程运行，支持stdio和HTTP（流式HTTP）传输。

特性

  • 异步文件锁定CRUD操作
  • 多个AI代理的安全并发访问
  • 基于FastMCP的MCP服务器（Python 3.12+）
  • 支持Stdio和HTTP传输
  • 带引导服务管理的守护进程模式
  • 特定于平台的服务集成（Windows服务/任务计划程序、macOS launchd、Linux systemd）

安装

先决条件

  • Python 3.12+
  • 紫外线 （手动安装可选）

快速安装（推荐）

特定于平台的设置脚本自动检测Python 3.12+并处理安装：

窗户：

scripts\setup.bat

macOS/Linux：

scripts/setup.sh

脚本会自动执行以下操作：

  1. 检测Python 3.12+安装
  2. 使用安装依赖项 uv
  3. 委托给 installer.py 对于完整配置

后安装一个衬垫

安装后，运行交互式安装向导或使用快速安装：

async-crud-mcp quick-install --yes

手动安装

如果您更喜欢使用手动安装 uv:

# Clone the repository
git clone https://github.com/RoscoeTheDog/async-crud-mcp.git
cd async-crud-mcp

# Install dependencies
uv sync

# Run the server
uv run async-crud-mcp

用法

安装向导（交互式）

启动交互式设置向导以配置MCP服务器：

async-crud-mcp setup

向导提示：

  • 端口号（默认值：3000）
  • 主机地址（默认：localhost）
  • 传输协议（stdio/sse）
  • 日志级别（调试/信息/警告/错误）
  • Daemon安装选项

快速安装（非交互式）

具有合理默认值的完整设置：

# Install with defaults
async-crud-mcp quick-install --yes

# Custom port
async-crud-mcp quick-install --yes --port 8000

# Force reinstall
async-crud-mcp quick-install --yes --force

# Install without starting daemon
async-crud-mcp quick-install --yes --no-start

卸载

停止并删除守护进程：

# Interactive uninstall
async-crud-mcp uninstall

# Non-interactive with config removal
async-crud-mcp uninstall --yes --remove-config

# Remove logs too
async-crud-mcp uninstall --yes --remove-config --remove-logs

配置管理

使用管理配置 config 命令组：

# Initialize new config
async-crud-mcp config init

# Force overwrite existing config
async-crud-mcp config init --force --port 9000

# Show current config
async-crud-mcp config show

# Show config in JSON format
async-crud-mcp config show --json

# Edit config interactively
async-crud-mcp config edit

# Validate config file
async-crud-mcp config validate

# Validate specific username
async-crud-mcp config validate --username admin

守护进程生命周期

控制MCP服务器守护进程：

# Start daemon
async-crud-mcp daemon start

# Start in background (detached)
async-crud-mcp daemon start --background

# Stop daemon
async-crud-mcp daemon stop

# Restart daemon
async-crud-mcp daemon restart

# Check daemon status
async-crud-mcp daemon status

# View daemon logs
async-crud-mcp daemon logs

# Follow logs in real-time
async-crud-mcp daemon logs --follow

Bootstrap服务管理

管理特定于平台的服务集成：

# Install bootstrap service
async-crud-mcp bootstrap install

# Force reinstall
async-crud-mcp bootstrap install --force

# Install with specific username (Unix)
async-crud-mcp bootstrap install --username myuser

# Use Windows Task Scheduler (instead of Service)
async-crud-mcp bootstrap install --use-task-scheduler

# Uninstall bootstrap service
async-crud-mcp bootstrap uninstall

# Start/stop bootstrap service
async-crud-mcp bootstrap start
async-crud-mcp bootstrap stop

# Check bootstrap status
async-crud-mcp bootstrap status

# List all bootstrap services
async-crud-mcp bootstrap list

# List in JSON format
async-crud-mcp bootstrap list --json

建筑

双层设计

这 async-crud-mcp project使用两层架构进行强大的守护进程管理：

┌─────────────────────────────────────────────────────────────┐
│ Layer 1: Bootstrap Daemon (daemon/bootstrap_daemon.py)     │
│ ----------------------------------------------------------- │
│ • Monitors user session state and config changes           │
│ • Manages MCP server process lifecycle (start/stop/restart)│
│ • Platform-specific service integration:                   │
│   - Windows: Service or Task Scheduler                     │
│   - macOS: launchd                                          │
│   - Linux: systemd                                          │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ Layer 2: MCP Server (server.py)                            │
│ ----------------------------------------------------------- │
│ • FastMCP-based server exposing 26 MCP tools (see the          │
│   "Tools" section below): CRUD, batch, transactional           │
│   edits, recycle-bin, shell/search, status, config             │
│ • Supports SSE and stdio transports                         │
│ • Shared core components:                                   │
│   - PathValidator: Safe path resolution                     │
│   - LockManager: File-locking for concurrent access         │
│   - HashRegistry: Content integrity tracking                │
└─────────────────────────────────────────────────────────────┘

每用户守护进程模型

开 视窗, async-crud-mcp 使用单个系统范围的Bootstrap服务与 MultiUserDispatcher （ADR-008）。调度员维护MCP工作人员的用户名密钥映射 通过以下方式处理和培养每个工人 CreateProcessAsUser 对于全过程级隔离：

  • 每个用户都有一个专用的工作进程，它有自己的端口（从用户名哈希值派生，基数8400）
  • 按用户配置(~/.async-crud-mcp/config.toml)日志文件按用户帐户隔离
  • 工作进程在会话登录时启动，仅在用户登录时停止 最后 活动会话结束
  • 全系统服务本身以 LocalSystem 从不直接访问用户文件

开 macOS，Bootstrap守护进程作为 launchd用户代理 (~/Library/LaunchAgents/), launchd为每个登录用户自动启动，不需要全系统服务或调度程序。

开 Linux，守护进程作为 systemd用户服务 (~/.config/systemd/user/)，已激活 按用户 systemd --user --每个用户独立管理自己的守护进程实例。

支持子系统

  • 配置管理：支持TOML的Pydantic设置
  • 健康检查：准备状态和活性终点
  • 优雅关闭：终止时清理资源
  • 配置文件监视器：配置更改时自动重新加载
  • 会话检测：特定于平台的会话状态监控
  • 结构化日志记录：基于loguru的旋转日志记录

关键模块

  • daemon/bootstrap_daemon.py -Bootstrap守护进程
  • daemon/installer.py -特定于平台的服务安装程序
  • server.py -带CRUD工具的FastMCP服务器
  • config.py -配置管理（Pydantic）
  • cli/ -CLI命令组（设置、守护进程、配置、引导、快速安装/卸载）

工具

服务器暴露 26个MCP工具 跨越七个类别。下面的名字是 服务器端工具名称；MCP客户端看到它们带有前缀（例如。 mcp__async-crud-mcp__async_read_tool).

类别 工具
文件CRUD async_read_tool, async_write_tool, async_update_tool, async_delete_tool, async_rename_tool, async_append_tool, async_mkdir_tool, async_list_tool
批次 async_batch_read_tool, async_batch_write_tool, async_batch_update_tool
事务性编辑 async_query_replace_tool, async_commit_tool, async_amend_tool, async_abort_tool, async_txn_status_tool
回收站 async_restore_tool, async_recycle_list_tool, async_recycle_clean_tool
壳牌/搜索 async_exec_tool, async_wait_tool, async_search_tool
状态/健康 async_status_tool, health_tool
配置/项目 crud_activate_project, crud_get_config, crud_update_config

大多数非豁免工具要求首先通过以下方式激活项目 crud_activate_project；激活前的调用失败，具有结构化 NO_PROJECT_ACTIVATED 错误，因此代理可以检测并自激活。

编辑模式：先读后编辑与双重状态危害

async_update_tool 用途 乐观并发控制: expected_hash 是一个 必需的参数，由先前提供 async_read_tool。服务器跟踪 a中的内容完整性 HashRegistry；如果文件在您读取后发生了变化 更新被拒绝，而不是默默地破坏并发代理的写入。 流程为：

  1. async_read_tool(path) → 返回内容 和 其内容哈希。
  2. async_update_tool(path, ..., expected_hash=<hash>) → 仅在以下情况下适用 文件仍然匹配；否则，它将返回争用/哈希不匹配响应-- 重新读取并重试。

对于广泛或有风险的多匹配编辑，请选择 事务性工具 (async_query_replace_tool → async_commit_tool)，概括了本手册 将哈希舞蹈转化为分段查询→commit事务：一个diff预览，一个服务器端 在提交时进行比较和交换，以及 async_amend_tool / async_abort_tool 到 调整或放弃分阶段的更改。

A. 子集提交使事务保持打开状态 比赛尚未结束 舞台化；提交是 全赢或全输的，所以很成功 async_commit_tool 应用 完全符合您请求的匹配项，并将其返回 applied_match_ids （加 remaining_match_ids, ignored_match_ids 对于不再暂存的请求id，以及 ttl_remaining).在不重新查询的情况下决定下一步（这将启动 刷新事务并重新扫描文件），调用只读 async_txn_status_tool: 它根据当前文件重新定位每个仍在进行的匹配，并报告其实时状态 位置和a locatable 用于预测下一次提交是否适用的标志 它或报告它过时了。报告的头寸是乐观的快照——只有 提交时间比较和交换是权威的。

双文件状态规则。 克劳德的故乡 Edit 追踪自己 编辑前读取状态，此服务器通过以下方式跟踪自己的状态 HashRegistry.在任何 给定文件，使用 要么 服务器的工具 或 单一应用的原生工具 突变序列——编辑过程中不要交错排列。CAS承诺 捕获介于查询和提交之间的本机写入，但将两者混合使用 中间序列会导致可避免的哈希不匹配波动。

陈旧的冲突和基础合同。 提交时，服务器会重新读取文件。 如果自查询以来没有变化，则分阶段匹配将应用于捕获的匹配 补偿。如果它发生了变化，则每个选定的匹配项都是 搬迁 通过一个 内容 锚 --匹配的文本加上周围大约48个字符的上下文。 匹配仅适用于该锚点（或者，如果没有锚点，则适用于匹配的文本本身） 发生 恰好一次 在新内容中；任何歧义都表明它已经过时，如果 任何选定的匹配都已过时，整个提交将被拒绝 stale_conflict （未写入任何内容）--重新查询以刷新。实际后果：a “非重叠”外部编辑仅在着陆时自动重新设置基线 在~48个字符的窗口之外 每场比赛 和 匹配的文本将保留 位置独特。编辑接近匹配的标记，或替换重复出现的标记 在其他地方，保守地触发 stale_conflict 而不是风险a 错误的位置编辑。A. 子集提交 保持交易与 剩余的（未申请的）比赛；他们稍后通过相同的重基路径提交， 并且分阶段设置永远不会被重新扫描，因此引入新的替换 模式出现永远不会扩展事务。

出口编辑和回写保护。 读取、搜索、交易 预览和shell输出被扫描，任何看起来像秘密的跨度都被替换 带着一个 <<REDACTED:rule:id>> 离开守护进程之前的占位符-- 响应仍然包含文件的 真实的 散列，因此随时可编辑CAS 工作。因为读取返回 已编辑 文本，直接写回该文本 将保留占位符并销毁真正的秘密。完整内容 写入路径(async_write_tool, async_update_tool 内容模式及其 批处理形式）因此 拒绝 包含编辑占位符的内容 带着一个 REDACTION_MARKERS_PRESENT 错误。通过编辑 补丁 (patches / regex_patches)--它们只携带更改的片段，是 推荐路径或通行证 allow_redaction_markers=true 对于罕见的文件 合法地包含该文字文本。

搜索与列表范围界定。 async_search_tool 荣誉 search.exclude_dirs （例如。 .async-crud-mcp, .git, node_modules)并且从不返回来自的匹配项 因此，回收站中已删除的秘密不会被内容重新找到 搜索。 async_list_tool 是一个 仅元数据 目录列表和do 不 应用 exclude_dirs：递归列表枚举这些目录' 条目（仅限名称和大小，从不包括文件内容）。

许可证

麻省理工学院

相关 MCP