MCP Linux System Roles

用于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

设置

1. 克隆/复制此目录 到您想要的位置

1. 更新 .mcphost.yml.example:

- 复制到您的mcphost配置目录或主目录 .mcphost.yml - 替换 `` 包含此目录的完整路径

   command: ["/home/user/mcp-linux-system-roles/server/server.py"]
   system-prompt: "/home/user/mcp-linux-system-roles/system-prompt.md"

1. 更新hooks.yml:

- 在 .mcphost/hooks.yml，更新审批者路径：

   command: "/home/user/mcp-linux-system-roles/approver.py"

1. 使脚本可执行:

   chmod +x server/server.py approver.py

1. 将钩子复制到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执行→ 结果返回。

可用工具

可用的SUSE角色

1. 助手-入侵检测
2. 证书-证书管理
3. 驾驶舱-基于Web的管理界面
4. crypto_policies-系统加密策略
5. 防火墙-防火墙配置
6. ha_cluster-高可用性集群
7. journated-日志配置
8. keytime_server-基于TPM的认证
9. mssql-Microsoft SQL Server
10. podman-集装箱管理
11. postfix-邮件服务器
12. selinux-selinux配置
13. squid-代理服务器
14. ssh-ssh服务器/客户端配置
15. suseconnect-SUSE注册
16. systemd-系统配置
17. 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