内容
> **⚠️ 已废弃**: 该仓库不再积极维护，请改用 Praxis。如果您需要在 Praxis 之外使用此功能，请使用 [Raptor CLI](https://github.com/Facets-cloud/raptor-releases)。
# Facets 模块 MCP 服务器
Facets 模块的 MCP（模型上下文协议）服务器有助于创建和管理用于基础设施即代码的 Terraform 模块。它与 Facets.cloud 的 FTF CLI 集成，提供安全、强大的工具用于模块生成、验证和管理，以支持云原生基础设施工作流程。
## 主要功能
* **安全文件操作**
限制所有文件操作在工作目录内进行，以确保安全性和完整性。
* **模块化 MCP 工具**
提供全面的工具用于文件列表、读取、写入、模块生成、验证和预览。所有破坏性或不可逆转的命令都需要明确的用户确认，并支持 dry-run 预览。
* **Facets 模块生成**
交互式提示驱动的工作流程促进使用 FTF CLI 生成具有元数据、变量和输入管理的 Terraform 模块。
* **模块分叉**
从 Facets 控制平面分叉现有模块以创建自定义变体。支持发现可用模块、更新元数据和自定义功能，同时保留原始模块结构。
* **补充说明支持**
自动从根级别的 `mcp_instructions` 目录读取额外的项目特定说明，允许团队定义自定义要求、约束和指南，以补充默认模块生成行为。
* **模块预览和测试**
支持模块预览、专用测试项目中的测试和实时部署监控，带有状态检查和日志。您需要一个具有运行环境和已启用资源的测试项目来测试正在测试的模块（需要从 Facets UI 手动完成）。
* **云环境集成**
支持多个云提供商，并自动提取 git 仓库元数据以丰富模块预览。
## 可用的 MCP 工具
| 工具名称 | 描述 |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `FIRST_STEP_get_instructions` | 从 `module_instructions` 目录加载所有模块编写说明，从 `mcp_instructions` 加载补充说明。始终首先调用此命令。 |
| `list_files` | 在指定模块目录内安全地列出工作目录内的所有文件。 |
| `read_file` | 读取工作目录内文件的内容。 |
| `edit_file_block` | 对文件中的特定文本块应用手术编辑。进行精确更改而不重写整个文件。不能编辑 `outputs.tf` 或 `facets.yaml` 文件。 |
| `write_config_files` | 编写和验证 `facets.yaml` 配置文件，带有 dry-run 和 diff 预览。 |
| `write_resource_file` | 安全地编写 Terraform 资源文件（`main.tf`、`variables.tf` 等）。排除 `outputs.tf` 和 `facets.yaml`。 |
| `write_outputs` | 编写具有输出属性和接口的 `outputs.tf` 文件，位于本地块中。 |
| `write_readme_file` | 编写具有 AI 生成内容的模块目录的 `README.md` 文件。 |
| `write_generic_file` | 使用工作目录和文件类型检查通用方式编写文件。路径：`facets_mcp/tools/module_files.py` |
| `generate_module_with_user_confirmation` | 使用 dry-run 预览和用户确认生成新的 Terraform 模块脚手架。 |
| `validate_module` | 使用 FTF CLI 标准和输出类型检查验证 Terraform 模块目录。 |
| `push_preview_module_to_facets_cp` | 通过自动提取 git 上下文，将模块预览推送到控制平面。 |
| `register_output_type` | 在 Facets 控制平面上注册具有接口、属性和提供商的新输出类型。 |
| `get_output_type_details` | 从 Facets 控制平面检索特定输出类型的详细信息。 |
| `find_output_types_with_provider` | 查找包含特定提供商源的所有输出类型，用于模块配置。 |
| `get_local_modules` | 通过递归搜索 `facets.yaml` 来扫描和列出所有本地 Terraform 模块，如果存在，还包括加载 `outputs.tf` 内容。 |
| `search_modules_after_confirmation` | 通过在 `facets.yaml` 文件中筛选字符串来搜索模块，支持分页，并返回具有详细信息的匹配模块。 |
| `list_test_projects` | 检索和返回所有可用的部署测试项目名称。 |
| `test_already_previewed_module` | 通过将模块部署到指定的测试项目来测试已预览的模块。 |
| `check_deployment_status` | 检查部署状态，可选等待完成。 |
| `get_deployment_logs` | 检索特定部署的日志。 |
| `list_modules_for_fork` | 列出可以分叉的所有可用模块，从控制平面显示，方便选择。 |
| `fork_existing_module` | 通过下载和更新元数据（风格和版本）来分叉现有模块。支持 dry-run 预览和用户确认。 |
## 先决条件
MCP 服务器需要 [uv](https://github.com/astral-sh/uv) 进行 MCP 编排。
该软件包在 PyPI 上可用：[facets-module-mcp](https://pypi.org/project/facets-module-mcp/)
#### 使用 Homebrew 安装 `uv`：
```bash
brew install uv
```
有关其他方法，请参阅官方 [uv 安装指南](https://docs.astral.sh/uv/getting-started/installation/).
### 与 Claude 集成
将以下内容添加到您的 `claude_desktop_config.json` 中：
```json
{
"mcpServers": {
"facets-module": {
"command": "uvx",
"args": [
"facets-module-mcp@latest",
"/Path/to/working-directory"
],
"env": {
"FACETS_PROFILE": "default",
"FACETS_USERNAME": "<YOUR_USERNAME>",
"FACETS_TOKEN": "<YOUR_TOKEN>",
"CONTROL_PLANE_URL": "<YOUR_CONTROL_PLANE_URL>"
}
}
}
}
```
对于本地克隆的仓库，请使用：
```json
{
"mcpServers": {
"facets-module": {
"command": "uv",
"args": [
"--directory",
"/path/to/your/cloned/facets-module-mcp/facets_mcp",
"run",
"facets_server.py",
"/path/to/working-directory"
],
"env": {
"PYTHONUNBUFFERED": "1",
"FACETS_PROFILE": "default",
"FACETS_USERNAME": "<YOUR_USERNAME>",
"FACETS_TOKEN": "<YOUR_TOKEN>",
"CONTROL_PLANE_URL": "<YOUR_CONTROL_PLANE_URL>"
}
}
}
}
```
⚠ 替换 `<YOUR_USERNAME>`、`<YOUR_TOKEN>` 和 `<YOUR_CONTROL_PLANE_URL>` 为您的实际身份验证数据。
`uv` 运行器使用 MCP 目录中的 `pyproject.toml` 文件自动管理环境和依赖项设置。
如果您已经登录到 FTF，指定 `FACETS_PROFILE` 就足够了。
---
有关令牌生成和身份验证设置的详细信息，请参阅官方 Facets 文档：
[https://readme.facets.cloud/reference/authentication-setup](https://readme.facets.cloud/reference/authentication-setup)
注意：Cursor 中提供了类似的设置，请在此处阅读 [https://docs.cursor.com/context/model-context-protocol](https://docs.cursor.com/context/model-context-protocol)
## 使用亮点
- 使用核心工具（`list_files`、`read_file`、`edit_file_block`、`write_config_files` 等）进行 Terraform 代码管理。
- 使用 FTF CLI 集成工具进行模块脚手架、验证和预览工作流程。
- 完整的部署流程：使用 `push_preview_module_to_facets_cp` 预览模块，使用 `test_already_previewed_module` 在专用测试项目中测试，并使用 `check_deployment_status` 和 `get_deployment_logs` 监控进度。
- 使用 `generate_new_module` 等 MCP 提示引导模块生成，或使用 `fork_existing_module` 自定义现有模块。
- 所有破坏性操作都需要明确的用户确认和 dry-run 预览。
---
## 模块分叉用例
MCP 服务器现在支持从 Facets 控制平面分叉现有模块。使用 **"分叉现有模块"** 提示访问引导工作流程：
- **安全增强**: 分叉基本模块以添加额外的安全控制或合规要求
- **云提供商适配**: 适配模块以适用于不同的云提供商，同时保持核心功能
- **性能优化**: 创建具有增强配置的现有模块的高性能变体
- **功能自定义**: 为现有模块添加组织特定的功能或集成
- **版本更新**: 使用更新的提供商版本或新的 Terraform 功能现代化旧模块
分叉工作流程保持原始模块结构，同时允许您自定义元数据、变量、资源和输出以满足您的特定要求。
---
## 示例用法
有关如何使用此 MCP 服务器与 Claude 的综合示例，请查看此聊天会话：
[使用 Facets MCP 创建 Terraform 模块](https://claude.ai/share/2ebe981f-48f4-4648-881e-4929ebbf0f59)
此示例演示了从模块生成到测试和部署的完整工作流程。
---
## 📘 附加指南
有关在 Facets 平台上使用 AI 构建安全 S3 存储桶模块的详细、现实世界的演练，请查看
**[GUIDE.md – 使用 AI 构建 Facets 模块：实用指南](./GUIDE.md)**
本指南演示了完整的对话流程 — 需求、设计细化、实施审查、验证、测试和迭代 — 使用针对银行用例的开发人员聚焦示例。
---
## 许可证
该项目根据 MIT 许可证获得许可。您可以在其条款下自由使用、修改和分发它。
