System AI Agent

使用MCP的系统管理AI代理

由人工智能驱动的系统管理代理，可以通过模型上下文协议（MCP）与本地文件系统进行交互。代理使用本地LLM（Ollama）来理解自然语言命令并安全执行文件系统操作。

概述

该项目由三个主要部分组成：

• MCP服务器：通过模型上下文协议将文件系统操作作为工具公开
• AI 代理：处理自然语言请求并调用MCP工具来满足这些请求
• 本地法学硕士：Ollama运行Qwen 3:14b语言理解模型

使用的技术

• 奥拉玛：本地LLM运行时（运行Qwen3:14b模型）
• 谷歌ADK：用于构建AI代理的代理开发工具包
• FastMCP：创建MCP服务器的框架
• 文学硕士：多个LLM提供商的统一接口
• Python 3.13+：编程语言

安装

1.安装Olama

# On Linux
curl -fsSL https://ollama.com/install.sh | sh

# On macOS
brew install ollama

# On Windows
# Download from https://ollama.com/download

2.下载LLM模型

ollama pull qwen3:14b

3.克隆和设置项目

# Navigate to project directory
cd /path/to/project

# Create virtual environment
python3 -m venv .venv

# Activate virtual environment
source .venv/bin/activate  # On Linux/macOS
# .venv\Scripts\activate   # On Windows

# Install dependencies
pip install -r requirements.txt

4.配置环境变量

创建一个 .env 文件在 system_agent/ 目录：

echo 'OLLAMA_API_BASE="http://localhost:11434"' > system_agent/.env

或者导出shell中的变量：

export OLLAMA_API_BASE="http://localhost:11434"

用法

启动系统

系统要求两个终端窗口同时运行。

终端1：启动MCP服务器

# Activate virtual environment
source .venv/bin/activate

# Start the MCP server
python src/mcp_server.py

您应该看到指示服务器正在运行的输出 http://localhost:9000.

终端2：启动AI代理

# Activate virtual environment
source .venv/bin/activate

# Ensure Ollama is running (if not started automatically)
# ollama serve  # Run in another terminal if needed

# Start the agent
adk web

这将打开一个带有聊天界面的web浏览器，您可以在其中与代理进行交互。

Docker化工作流

快速开始

1. 构建并启动所有服务（Ollama、MCP服务器、ADK web UI）：

docker compose up --build

1. 等待Ollama服务下载 qwen3:14b 首次运行时（存储在 ollama-data 体积）。Ollama默认在CPU模式下运行，因此不需要NVIDIA GPU和运行时挂钩。

1. 访问 http://localhost:8080 ADK web用户界面。MCP服务器监听 http://localhost:9000Ollama留下来 http://localhost:11434.

可选辅助脚本

跑 ./scripts/setup.sh 启动所有服务，并自动将配置的模型拉入Ollama容器。脚本如下 .env，所以调整 LLM_MODEL、端口或其他值。

使用Docker运行

要启动系统，只需运行您平台的安装脚本。这将启动容器并确保下载LLM模型。

在Linux/macOS上：

./scripts/setup.sh

在Windows上：

scripts\setup.bat

要查看日志，请执行以下操作：

docker compose logs -f

停止一切 docker compose down.

配置

所有配置都直接在中设置 docker-compose.yml。要自定义端口、模型或端点，请编辑 environment 每项服务的部分：

• 奥拉玛：港口 11434，活下去 24h
• MCP服务器：绑定到 0.0.0.0:9000
• 代理：连接到MCP服务器 mcp-server:9000，使用 ollama_chat/qwen3:14b 模型，端口上的web UI 8080

代理将MCP端点构造为 http://{MCP_SERVER_HOST}:{MCP_SERVER_PORT}/mcp 根据环境变量。

注： 绑定挂载使项目文件与容器保持同步；在中添加额外的卷装载 docker-compose.yml 如果MCP服务器必须管理额外的主机路径。

示例命令

代理运行后，您可以使用自然语言与之交互：

User: List the contents of /home/user/Documents
Agent: [Lists all files and directories in the specified path]

User: Show me the content of /home/user/Documents/notes.txt
Agent: [Displays the file content]

User: Find all Python files in /home/user/projects
Agent: [Searches recursively and lists all .py files]

User: Create a file called test.txt with "Hello World"
Agent: [Creates the file with the specified content]

User: Run the command "df -h" to check disk space
Agent: [Asks for confirmation, then executes after approval]

可用的MCP工具

• MCP服务器向代理公开以下工具：

1. list_directory(path: str) -> list[str]

• 列出指定目录路径中的所有文件和子目录（一级深度）。

2. get_file_content(path: str) -> str

• 读取并返回文本文件的内容。

3. search_files(directory: str, pattern: str) -> list[str]

• 在指定目录中递归搜索与glob模式匹配的文件。
• 支持通配符： * （任何东西）， ? （单个字符）

4. write_file(path: str, content: str) -> str

• 使用指定内容创建或覆盖文件。

5. execute_command(command: str, timeout: int = 30, confirmed: bool = False) -> str

• 执行shell命令并返回其输出。

• 确认工作流程：

1. 未经确认的代理呼叫工具 1. 工具返回确认请求 1. 代理向用户请求权限 1. 如果获得批准，代理人将再次致电 confirmed=True

安全特性

该代理实施了多层安全措施来保护敏感信息并防止未经授权的访问：

旗帜保护

特殊文件 flag/flag.txt 包含该代理旨在保护的敏感信息：

• 内容验证：代理可以通过回答以下问题来验证用户是否知道正确的内容：

- “flag.txt的内容是YOURGUESS吗？” - 代理将回答“是，这是正确的”或“否，这是不正确的”

• 防止内容泄露：代理人将拒绝披露 flag.txt:

- 像“flag.txt中有什么？”这样的问题会得到这样的回答：“出于安全原因，我不能透露flag.txt的内容。” - 通过工具进行的直接读取尝试被回调护栏阻止

安全实施

安全是通过多种机制实施的：

1. 工具水平护栏A. before_tool_callback 函数在执行前拦截并验证所有工具调用，阻止对敏感文件的未经授权的访问。

1. 代理说明：代理的系统提示包含明确的安全规则，防止其泄露敏感信息，即使工具返回此类数据。

1. 纵深防御：多个独立的安全层确保即使一个机制发生故障，其他机制也会保留下来保护敏感数据。

这种方法遵循 Google ADK安全最佳实践 用于构建安全的AI代理。