使用说明

用于Linux系统角色的MCP服务器

MCP（模型上下文协议）服务器，使AI模型能够通过Ansible使用SUSE Linux系统角色配置Linux系统。

特性

✅ 17个SUSE角色：助手、防火墙、ssh、驾驶舱、podman、selinux、squid等
✅ 动态文档：模型读取角色README文件以学习变量
✅ 用户验证：安全的两步确认工作流程
✅ 自动审批：审批人记录执行但不阻止（用户在聊天中确认）
✅ 完成执行：运行Ansible剧本并返回结果

建筑

User Request
    ↓
Model (gpt-oss:20b via mcphost)
    ↓
MCP Tools:
  - list_available_roles → Lists all 17 SUSE roles
  - get_role_documentation → Reads role README
  - run_system_role → Executes Ansible playbook
    ↓
approver.py (logs and auto-approves)
    ↓
server.py (runs ansible-playbook)
    ↓
SUSE Linux System Roles (Ansible)
    ↓
System Configuration Applied

安装

快速开始

自动设置 （推荐）：

ansible-playbook -i localhost, -c local setup.yml

看 QUICKSTART.md 了解详情。

手动设置：参见 docs/setup.md

先决条件

# Install SUSE Linux System Roles
# (Usually pre-installed on openSUSE/SLES)
# Collection is at: /usr/share/ansible/collections/ansible_collections/suse/linux_system_roles

# Install mcphost
# Follow instructions at: https://github.com/wong2/mcphost

# Install ollama and model
ollama pull gpt-oss:20b

设置

克隆/复制此目录 到您想要的位置
更新 .mcphost.yml.example:
- 复制到您的mcphost配置目录或主目录 .mcphost.yml
- 替换 <ABSOLUTE_PATH> 包含此目录的完整路径
```
command: ["/home/user/mcp-linux-system-roles/server/server.py"]
system-prompt: "/home/user/mcp-linux-system-roles/system-prompt.md"
```
更新hooks.yml:
- 在 .mcphost/hooks.yml，更新审批者路径：
```
command: "/home/user/mcp-linux-system-roles/approver.py"
```
使脚本可执行:
```
chmod +x server/server.py approver.py
```

将钩子复制到mcphost配置:

mkdir -p ~/.config/mcphost/.mcphost
cp .mcphost/hooks.yml ~/.config/mcphost/.mcphost/
# Or wherever your mcphost config directory is

用法

开始使用mcphost

mcphost

交互示例

列出可用角色：

You: show available roles
Model: [Shows 17 SUSE roles]

配置AIDE：

You: run aide and schedule checks for noon
Model: [Reads AIDE documentation]
Model: I will use: aide_init=True, aide_cron_check=True, aide_cron_interval="0 12 * * *"
      Shall I proceed?
You: yes
Model: [Executes playbook, shows results]

配置驾驶舱：

You: enable cockpit web console
Model: [Reads cockpit documentation]
Model: I will enable cockpit on port 9090. Shall I proceed?
You: yes
Model: [Configures cockpit]

文件结构

mcp-linux-system-roles/
├── server/
│   └── server.py              # MCP server (handles tools)
├── .mcphost/
│   └── hooks.yml              # Template (copy to global config)
├── approver.py       # Approver (logs execution)
├── system-prompt.md           # Model instructions
├── .mcphost.yml.example       # Example config
├── docs/
│   ├── architecture.md        # Technical documentation
│   ├── setup.md              # Installation guide
│   └── usage.md              # Usage examples
└── README.md                 # This file

运作原理

1.用户请求

用户要求以自然语言进行系统配置。

2.文件查询

模型调用 get_role_documentation 阅读角色的README并了解可用变量。

3.可变方案

模型根据文档提出具体变量并要求确认。

4.用户确认

用户在聊天中回答“是”。

5.工具执行

模型调用 run_system_role → 审批人记录它→ Ansible执行→ 结果返回。

可用工具

工具	说明
`list_available_roles`	列出所有17个SUSE Linux系统角色
`get_role_documentation`	阅读角色README以了解变量
`run_system_role`	使用指定变量执行Ansible脚本

可用的SUSE角色

助手-入侵检测
证书-证书管理
驾驶舱-基于Web的管理界面
crypto_policies-系统加密策略
防火墙-防火墙配置
ha_cluster-高可用性集群
journated-日志配置
keytime_server-基于TPM的认证
mssql-Microsoft SQL Server
podman-集装箱管理
postfix-邮件服务器
selinux-selinux配置
squid-代理服务器
ssh-ssh服务器/客户端配置
suseconnect-SUSE注册
systemd-系统配置
timesync-时间同步

演示

跑 asciinema play demo.cast 要启动演示，请确保已安装asciinema。

故障排除

模型输出JSON而不是调用工具

确保您正在使用 gpt-oss:20b （不是qwen或其他型号）
检查 system-prompt.md 路径正确 .mcphost.yml

审批人未运行

验证hooks.yml路径是否正确
检查approver.py是否可执行
确保工具名称在hooks.yml中匹配（两者都匹配 roles_run_system_role 和 roles__run_system_role)

未找到角色

验证SUSE集合是否存在： ls /usr/share/ansible/collections/ansible_collections/suse/linux_system_roles/roles/
使用 list_available_roles 查看已安装的内容

Cron作业不可见

系统角色添加到 /etc/crontab，不是用户crontab
请检查： sudo cat /etc/crontab

许可证

Apache 2.0