Cycloid

Cycloid MCP 服务

一个模型上下文协议（MCP）服务，可与 Cycloid 平台无缝集成，让 AI 助手通过自然语言使用 Cycloid 的基础设施管理功能。

概述

Cycloid MCP 服务在 AI 助手与 Cycloid 强大的基础设施自动化平台之间搭建桥梁。它支持用户：

• 发现和探索可用的蓝图和服务目录
• 使用 Cycloid 的蓝图创建和管理基础设施堆栈
• 通过 AI 助手自然地交互复杂的基础设施工作流
• 借助 Cycloid 在基础设施即代码和自动化方面的专业能力

可用工具

• CYCLOID_BLUEPRINT_LIST：列出所有可用蓝图及其详细信息
• CYCLOID_BLUEPRINT_STACK_CREATE：通过交互式信息收集，根据蓝图创建堆栈
• CYCLOID_STACKFORMS_VALIDATE：验证 StackForms 配置文件
• CYCLOID_CATALOG_REPO_LIST：列出服务目录仓库
• CYCLOID_EVENT_LIST：列出组织事件，可选筛选条件包括（begin、end、severity、type）
• CYCLOID_PIPELINE_LIST：列出 Cycloid 的所有流水线

可用资源

• cycloid://blueprints：访问蓝图信息
• cycloid://service-catalogs-repositories：访问服务目录仓库信息
• cycloid://events：以 JSON 格式访问近期组织事件
• cycloid://pipelines：访问流水线信息

事件筛选条件

• begin/end：界定时间范围的 Unix 时间戳（字符串）
• severity：一个或多个 info、warn、err、crit
• type：一个或多个 Cycloid、AWS、Monitoring、Custom

架构

该服务使用基于 FastMCP 的 MCPMixin 的动态组件注册系统：

• 自动发现：自动从 src/components/ 发现组件
• 基于文件的组织方式：按功能组织组件（catalogs/、stacks/）
• 标准模式：每个组件都遵循 *_tools.py、*_resources.py、*_handlers.py、*_prompts.py 模式
• MCPMixin 集成：使用 FastMCP 内置的 register_all() 方法正确注册工具和资源

HTTP 传输

Cycloid MCP 服务通过 HTTP 传输作为 Web 服务运行。每个请求都通过 HTTP 标头（X-CY-ORG 和 X-CY-API-KEY）提供组织和 API 密钥，以支持多租户使用。

用法： python server.py

快速开始

前提条件

• Python 3.12 或更高版本
• uv 包管理器（推荐）
• Docker（用于生产环境部署）
• 有效的 Cycloid API 凭据

开发环境设置

# Clone and setup
git clone <repository-url>
cd cycloid-mcp-server
make setup

# Run development server
make dev-server

生产环境设置

使用预构建的 Docker 镜像

项目通过 Docker Hub 提供预构建的 Docker 镜像：

# Pull the latest image
docker pull cycloid/cycloid-mcp-server:latest

# Run the server
docker run -p 8010:8010 cycloid/cycloid-mcp-server:latest

本地构建

# Build Docker image
make build

# Run production server
make prod-server

MCP 配置

有关 MCP 服务配置示例的详细信息，请参阅 mcp-examples.md。

可用命令

# Development Environment
make setup          # Setup development environment with uv
make install        # Install dependencies
make help           # Show all available commands
make validate-env   # Validate local environment matches CI

# Development Server
make dev-server     # Run development server using Python virtual environment

# HTTP Server
python server.py  # Run HTTP server

# Production
make build          # Build Docker image
make prod-server    # Run production server using Docker

# Testing and Quality
make test           # Run all tests
make type-check     # Run pyright type checking
make lint           # Run PEP 8 linting with flake8
make format         # Format code with black and isort
make quality-check  # Run all quality checks (tests + type checking + linting)
make simulate-ci    # Validate environment and run quality checks

# Cleanup
make clean          # Clean up development artifacts
make clean-docker   # Clean up Docker artifacts

贡献

有关详细的开发指南，请参阅 CONTRIBUTING.md。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。