6.4. 创建自定义 MCP 服务器角色

流程

1. 创建集合目录结构以及一个新的 Ansible 集合来保存您的自定义 MCP 角色：

   mkdir -p collections/ansible_collections/myorg/mcp_cfn/roles/cfn_mcp/ {defaults,tasks,meta}

   mkdir -p collections/ansible_collections/myorg/mcp_cfn/playbooks

   目录结构类似如下：

   collections/ansible_collections/myorg/mcp_cfn/
   ├── galaxy.yml
   ├── README.md
   ├── LICENSE
   ├── playbooks/
   │   └── install_cfn_mcp.yml
   └── roles/
       └── cfn_mcp/
           ├── defaults/
           │   └── main.yml
           ├── tasks/
           │   └── main.yml
           └── meta/
               └── main.yml

2. 通过在集合的根目录中创建 galaxy.yml 来定义集合元数据：

   # galaxy.yml
   ---
   namespace: myorg
   name: mcp_cfn
   version: 0.7.2
   readme: README.md
   authors:
     - Your Name
   description: Custom MCP role for AWS CloudFormation MCP Server
   license_file: LICENSE
   tags:
     - mcp
     - aws
     - cloudformation
   dependencies:
     ansible.mcp_builder: ">=0.7.2"

   dependencies 字段确保 ansible.mcp_builder 集合与您的集合一同安装。

3. 通过使用 MCP 服务器的 registry 定义创建 roles/cfn_mcp/defaults/main.yml 来定义角色 registry 元数据：

   # roles/cfn_mcp/defaults/main.yml
   ---
   cfn_mcp_registry:
     - name: "awslabs.cfn-mcp-server"
       type: "stdio"
       lang: "pypi"
       args: []
       description: "AWS CloudFormation MCP Server - manage AWS resources via
   Cloud Control API"
   
   cfn_mcp_version: "0.7.2"

   registry 变量必须遵循命名规则 < role_name>_registry。这些字段包括：

   Expand

   字段	必填	Description
   name	是	MCP 服务器的可执行名称或软件包名称。
   type	是	传输类型：用于本地服务器的 stdio，用于远程服务器的 http。
   lang	是	安装方法：pypi、npm 或 go。
   args	否	在启动时传递给服务器的默认参数列表。
   description	是	mcp_manage 列表中显示的人类可读描述。
   package	否	如果与 name 不同（用于 npm 软件包），则软件包名称。

   Show more

   version 变量必须遵循命名规则 < role_name>_version。

   对于从源构建的基于 Go 的服务器，您还需要默认值中的与构建相关的变量，如下所示：

   myrole_build_repo: "https://github.com/example/my-mcp-server.git"
   myrole_build_repo_branch: "main"
   myrole_build_path: "example/build"

4. 通过创建 roles/cfn_mcp/tasks/main.yml 来创建角色任务：

   # roles/cfn_mcp/tasks/main.yml
   ---
   - name: Include install manager tasks
     ansible.builtin.include_role:
       name: ansible.mcp_builder.common
       tasks_from: install_manager
   
   - name: Update MCP servers manifest
     ansible.builtin.include_role:
       name: ansible.mcp_builder.common
       tasks_from: generate_manifest
   
   - name: Verify CloudFormation MCP installation
     ansible.builtin.command:
       cmd: mcp_manage run {{ common_package_name }} --help
     changed_when: false
     register: cfn_mcp_verify_result
     failed_when: false
   
   - name: Display verification status (success)
     ansible.builtin.debug:
       msg: "CloudFormation MCP Server installed and verified successfully."
     when:
       - cfn_mcp_verify_result.rc is defined
       - cfn_mcp_verify_result.rc == 0
   
   - name: Display verification status (failure)
     ansible.builtin.debug:
       msg: "CloudFormation MCP Server verification failed. Check logs for details."
     when:
       - cfn_mcp_verify_result.rc is defined
       - cfn_mcp_verify_result.rc != 0

   这两个 include_role 任务是最低要求。install_manager' 任务读取 registry 元数据，并使用适当的方法安装 MCP 服务器。generate_manifest 任务将服务器添加到 mcpservers.json 清单中。

   验证步骤是可选的，但建议使用。它将确认已安装的服务器可以调用。

5. 通过创建 roles/cfn_mcp/meta/main.yml 来创建角色元数据：

   # roles/cfn_mcp/meta/main.yml
   ---
   galaxy_info:
     role_name: "cfn_mcp"
     author: "Your Name"
     description: "Installs the AWS CloudFormation MCP server"
     license: "GPL-3.0-or-later"
     min_ansible_version: "2.16.0"
     platforms:
       - name: EL
         versions:
           - "9"
     galaxy_tags:
       - mcp
       - aws
       - cloudformation
   
   collections:
     - ansible.mcp_builder

6. 创建安装 playbook playbook/install_cfn_mcp.yml

   # playbooks/install_cfn_mcp.yml
   ---
   - name: Install custom CloudFormation MCP Server
     hosts: localhost
     connection: local
     gather_facts: false
   
     tasks:
       - name: Ensure base functionality
         ansible.builtin.include_role:
           name: ansible.mcp_builder.common
           public: true
   
       - name: Install CloudFormation MCP Server
         ansible.builtin.include_role:
           name: myorg.mcp_cfn.cfn_mcp
   
       - name: Fix ownership of all MCP installations for runtime user
         ansible.builtin.file:
           path: "{{ common_mcp_base_path }}"
           state: directory
           recurse: true
           owner: "{{ common_runtime_user }}"
           group: "{{ common_runtime_user }}"

   重要

   第一项任务必须包含 ansible.mcp_builder.common，其 public: true。这会初始化框架，并使共享变量（如 common_mcp_base_path）可用于后续任务。末尾的所有权修复可确保 MCP 服务器文件可由执行环境中的非 root 运行时用户访问。

   注意

   内置 ansible.mcp_builder.install_mcp playbook 只支持 ansible.mcp_builder 命名空间中的角色。您自己集合命名空间中的自定义角色需要自己的 playbook，如上所示。

7. 将集合构建为可分布式 tarball：

   cd collections/ansible_collections/myorg/mcp_cfn ansible-galaxy collection build --output-path /path/to/output/

   这会生成一个文件，如 myorg-mcp_cfn-0.7.2.tar.gz。