Agent-VC MCP Server

代理VC MCP服务器

一个专门的MCP服务器，用于AI代理具有持久状态、版本控制和任务管理，使用 化石SCM.

为什么选择VC？

• 持久状态：代理可以将文件存储在结构化、版本化的工作区中。
• 可重复性：每个提交的完整历史记录，允许回滚到任何状态。
• 任务管理：内置工单/任务（通过Fossil的工单系统），无需外部依赖即可跟踪进度。
• 沙盒化的：操作严格限于 ~/.agent-vc/workspace/.

结构和文件管理

核心目录

• ~/.agent-vc/：所有Agent VC数据和配置的根目录。
• ~/.agent-vc/version_control.fossil：Fossil存储库文件。这是一个单一的SQLite数据库，存储您的整个项目历史、版本控制对象和任务/工单数据。
• ~/.agent-vc/workspace/：活动签出目录。代理执行的所有操作都发生在此目录中。这是读取或写入文件的唯一位置。

文件和文件夹映射

Agent VC在共享工作区中使用基于“项目”的组织。这允许代理在单个版本控制的存储库中管理多个逻辑项目或模块。

使用MCP工具

使用时 agent-vc 工具，您可以使用 project 和 subPath 参数。这个抽象直接映射到文件系统：

1. 初始化项目：跑步 vc_init_project(name: "my-app") 创建目录 ~/.agent-vc/workspace/my-app/.
2. 写入文件：跑步 write_file(project: "my-app", subPath: "main.py", content: "...") 写信给 ~/.agent-vc/workspace/my-app/main.py.
3. 嵌套文件夹：您可以在 subPath 要创建嵌套结构，请执行以下操作： write_file(project: "my-app", subPath: "docs/specs/readme.md", ...) 将自动创建 docs/specs/ 如果目录不存在。

\[！注意\] 使用创建的所有文件 write_file 工具会自动添加到Fossil的跟踪中(fossil add).要将这些更改永久记录在历史中，您必须致电 vc_commit.

安装

1. 安装Fossil：

按照上的官方安装说明进行操作 化石网站.

1. 通过npx运行：

您可以直接使用以下命令运行服务器 npx:

   npx agent-vc-mcp

1. 添加到您的MCP配置中（例如。， claude_desktop_config.json 或等效的代理配置）：

{
  "mcpServers": {
    "agent-vc": {
      "command": "npx",
      "args": ["agent-vc-mcp"],
      "env": {
        "AGENT_VC_WORKSPACE": "/path/to/my/project",
        "AGENT_VC_FOSSIL_DB": "/path/to/backup.fossil"
      }
    }
  }
}

环境变量

您可以通过设置以下环境变量来调整Agent VC的行为：

\[！提示\] 设置 AGENT_VC_WORKSPACE 如果您希望代理直接在已使用Fossil SCM初始化的现有本地目录上运行，则此功能非常有用。

工具

版本控制

• vc_init_project(name)：创建项目子文件夹。
• vc_commit(message)：提交工作区中的所有更改。
• vc_status()：获取跟踪和更改的当前状态。
• vc_diff()：查看工作区中的更改。

文件操作（项目范围）

• write_file(project, subPath, content)：写入文件并自动将其添加到Fossil跟踪中。
• read_file(project, subPath)：读取文件。
• list_files(project)：列出项目中的所有文件。

任务管理

• task_create(title, description)：创建项目任务。
• task_list(status?)：列出现有任务。
• task_update(id, status, comment?)：更新任务状态。

使用示例

🏢 初始化项目

在工作区中创建新的项目文件夹结构。

{
  "name": "vc_init_project",
  "arguments": { "name": "chatbot-v1" }
}

💾 编写和提交文件

编写代码并将其提交到历史记录中。

// 1. Write the file
{
  "name": "write_file",
  "arguments": {
    "project": "chatbot-v1",
    "subPath": "index.js",
    "content": "console.log('Hello Agent!');"
  }
}

// 2. Commit the changes
{
  "name": "vc_commit",
  "arguments": { "message": "initial commit for chatbot" }
}

📋 管理任务（化石票）

使用内置的票务系统跟踪工作。

// 1. Create a task
{
  "name": "task_create",
  "arguments": {
    "title": "Add streaming support",
    "description": "Implement chunked response parsing."
  }
}

// 2. List open tasks (to get the Ticket ID)
{
  "name": "task_list",
  "arguments": { "status": "Open" }
}

// 3. Update a task (using the first 7-10 characters of the Ticket ID)
{
  "name": "task_update",
  "arguments": {
    "id": "8d0aa38",
    "status": "Closed",
    "comment": "Work completed and tested."
  }
}

🔍 检查进度和历史

// Check modified files
{ "name": "vc_status", "arguments": {} }

// View code diff
{ "name": "vc_diff", "arguments": {} }

// List all files in a project
{
  "name": "list_files",
  "arguments": { "project": "chatbot-v1" }
}

// Read a specific file
{
  "name": "read_file",
  "arguments": {
    "project": "chatbot-v1",
    "subPath": "index.js"
  }
}

更多文件

有关更高级的Fossil命令和功能（如分支、合并和同步），请参阅官方 Fossil SCM文档.