🔌 Itential - MCP Server

🔌 Itential - MCP 服务

一个 Model Context Protocol (MCP) 服务，提供丰富的工具，用于将大模型连接到 Itential Platform。让 AI 助手能够管理网络自动化、编排工作流、监控平台健康状况并执行高级网络操作。

🎯 适用对象

平台工程师

通过 AI 驱动的自动化管理基础设施、监控系统健康状况、配置设备并编排网络操作。

开发人员

构建自动化工作流、与外部系统集成、管理应用生命周期并扩展平台功能。

📒 主要功能

核心能力

• 79 个自动化工具（默认启用 78 个；1 个实验性工具需选择启用）：涵盖 13 个标签类别的全面工具集，满足各种网络自动化需求
• 高级工具选择：通过灵活的标签系统筛选和控制可用工具
• 多种传输方式：支持 stdio 和 HTTP（Streamable HTTP，推荐）传输，并可选 TLS 加密；也提供旧版 SSE 传输，但该方式已弃用
• 动态工具发现：自动发现并注册工具，无需修改代码
• 灵活的身份验证：支持 Itential Platform 的基本身份验证、OAuth 2.0、JWT 和基于角色的访问控制
• 全面的配置方式：支持 CLI 参数、环境变量或配置文件
• 基于角色的访问控制：为平台管理员、网络工程师和开发人员提供量身定制的工具配置

网络自动化与设备管理

• 设备配置：应用配置、备份设备设置并检索当前配置
• 命令执行：通过规则验证，在多个设备上运行单条命令或命令模板
• 设备组：创建和管理逻辑设备集合，简化操作
• 合规性管理：自动执行合规性计划并生成详细报告
• 基准配置：通过版本控制，以分层模板方式管理配置

工作流与编排

• 工作流执行：通过 API 端点启动工作流并监控执行状态
• 作业管理：全面跟踪工作流作业的状态、指标和任务详情
• 工作流开放：将工作流转换为 REST API 端点，供外部调用
• 模板管理：创建、更新并执行 Jinja2 和 TextFSM 模板
• 性能指标：提供详细的作业和任务执行指标，助力优化工作流

平台运维与监控

• 健康状况监控：实时监控平台健康状况，包括系统资源、应用和适配器
• 组件生命周期：启动、停止和重启应用及适配器，并监控其状态
• 集成管理：创建和管理基于 OpenAPI 的集成模型
• 网关服务：通过 Gateway Manager 执行外部服务（Ansible、Python 脚本、OpenTofu）

生命周期与资源管理

• 资源模型：定义基于 JSON Schema 的资源结构及其生命周期工作流
• 实例管理：对资源实例执行完整的 CRUD 操作，并跟踪状态
• 操作执行：运行生命周期操作，并记录完整的执行历史
• 数据验证：基于 Schema 验证资源数据和操作参数

🔍 要求

• Python 3.10 或更高版本
• 可访问 Itential Platform 实例
• 开发 所需：uv 和 make

已测试的 Python 版本

本项目会针对以下 Python 版本自动进行测试：

• Python 3.10
• Python 3.11
• Python 3.12
• Python 3.13

🔧 安装

itential-mcp 应用可以通过 PyPI 安装，也可以直接从源代码运行。

PyPI 安装

要从 PyPI 安装，只需使用 pip：

pip install itential-mcp

本地开发

也可以将仓库克隆到本地环境，以使用 MCP 服务。本项目使用 uv 和 make，因此需要在环境中安装并提供这两个工具。

可以使用以下命令开始操作。

git clone https://github.com/itential/itential-mcp
cd itential-mcp
make build

开发时，可以直接使用 uv 运行服务：

# Run with stdio transport (default)
uv run itential-mcp run

# Run with HTTP transport (Streamable HTTP, recommended for web integration)
uv run itential-mcp run --transport http --host 0.0.0.0 --port 8000

# Run with specific configuration
uv run itential-mcp run --include-tags "health,configuration_manager" --exclude-tags "experimental"

容器用法

从 GitHub Container Registry 拉取

拉取并运行最新版本：

# Pull the latest image
docker pull ghcr.io/itential/itential-mcp:latest

# Run with HTTP transport (Streamable HTTP, recommended)
docker run -p 8000:8000 \
  --env ITENTIAL_MCP_SERVER_TRANSPORT=http \
  --env ITENTIAL_MCP_SERVER_HOST=0.0.0.0 \
  --env ITENTIAL_MCP_SERVER_PORT=8000 \
  --env ITENTIAL_MCP_PLATFORM_HOST=your-platform.example.com \
  --env ITENTIAL_MCP_PLATFORM_USER=your-username \
  --env ITENTIAL_MCP_PLATFORM_PASSWORD=your-password \
  ghcr.io/itential/itential-mcp:latest

# Or with OAuth authentication
docker run -p 8000:8000 \
  --env ITENTIAL_MCP_SERVER_TRANSPORT=http \
  --env ITENTIAL_MCP_SERVER_HOST=0.0.0.0 \
  --env ITENTIAL_MCP_SERVER_PORT=8000 \
  --env ITENTIAL_MCP_PLATFORM_HOST=your-platform.example.com \
  --env ITENTIAL_MCP_PLATFORM_CLIENT_ID=CLIENT_ID \
  --env ITENTIAL_MCP_PLATFORM_CLIENT_SECRET=CLIENT_SECRET \
  ghcr.io/itential/itential-mcp:latest

# Run with stdio transport (for MCP clients)
docker run -i \
  --env ITENTIAL_MCP_PLATFORM_HOST=your-platform.example.com \
  --env ITENTIAL_MCP_PLATFORM_USER=your-username \
  --env ITENTIAL_MCP_PLATFORM_PASSWORD=your-password \
  ghcr.io/itential/itential-mcp:latest

在本地构建容器镜像

从源代码构建并运行：

# Build the container image
make container

# Run the locally built container
docker run -p 8000:8000 \
  --env ITENTIAL_MCP_SERVER_TRANSPORT=http \
  --env ITENTIAL_MCP_SERVER_HOST=0.0.0.0 \
  --env ITENTIAL_MCP_SERVER_PORT=8000 \
  --env ITENTIAL_MCP_PLATFORM_HOST=your-platform.example.com \
  --env ITENTIAL_MCP_PLATFORM_USER=your-username \
  --env ITENTIAL_MCP_PLATFORM_PASSWORD=your-password \
  itential-mcp:devel

🚀 快速开始

1. 安装服务

pip install itential-mcp

2. 配置平台连接

设置你的 Itential Platform 凭据：

export ITENTIAL_MCP_PLATFORM_HOST="your-platform.example.com"
export ITENTIAL_MCP_PLATFORM_USER="your-username"
export ITENTIAL_MCP_PLATFORM_PASSWORD="your-password"

3. 启动服务

# Basic stdio transport (default)
itential-mcp run

# Or with HTTP transport (Streamable HTTP, recommended for web clients)
itential-mcp run --transport http --host 0.0.0.0 --port 8000

4. 配置 MCP 客户端

按照集成指南连接 Claude、Continue.dev 或其他 MCP 客户端。

📝 基本用法

使用默认设置（stdio 传输）启动 MCP 服务：

itential-mcp run

使用 HTTP 传输（Streamable HTTP，推荐用于 Web 集成）启动：

itential-mcp run --transport http --host 0.0.0.0 --port 8000

使用 SSE 传输（已弃用的旧版 HTTP+SSE，建议使用 http）启动：

itential-mcp run --transport sse --host 0.0.0.0 --port 8000

通用选项

全局选项可以放在命令名称之前或之后。

选项	说明	默认值
--config	配置文件路径	无

示例：

# Both of these work identically:
itential-mcp --config config.conf run
itential-mcp run --config config.conf

服务选项

选项	说明	默认值
--transport	传输协议（stdio、sse、http；sse 已弃用，建议使用 http）	stdio
--host	要监听的主机地址	127.0.0.1
--port	要监听的端口	8000
--path	要使用的 HTTP 路径	/mcp
--log-level	日志级别（DEBUG、INFO、WARNING、ERROR、CRITICAL、NONE）	NONE
--include-tags	要包含的已注册工具标签	无
--exclude-tags	要排除的已注册工具标签	experimental,beta

平台配置

选项	描述	默认值
--platform-host	Itential Platform 主机名	localhost
--platform-port	Platform 端口（0 = 自动检测）	0
--platform-disable-tls	禁用平台连接的 TLS	false
--platform-disable-verify	禁用证书验证	false
--platform-timeout	连接超时	30
--platform-user	身份验证用户名	admin
--platform-password	身份验证密码	admin
--platform-client-id	OAuth 客户端 ID	none
--platform-client-secret	OAuth 客户端密钥	none

环境变量

所有命令行选项也可以通过以 ITENTIAL_MCP_SERVER_ 为前缀的环境变量设置。例如：

export ITENTIAL_MCP_SERVER_TRANSPORT=http
export ITENTIAL_MCP_PLATFORM_HOST=platform.example.com
itential-mcp run  # Will use the environment variables

安全注意事项

⚠️ 重要安全提示：

MCP 服务会读取环境变量中的配置，因此必须在可信环境中运行。在共享或多租户环境中，请确保：

1. 环境隔离：服务运行在隔离的容器或专用环境中，用户无法设置任意环境变量
2. 访问控制：只有经授权的管理员才能设置 ITENTIAL_MCP_* 环境变量
3. 动态工具配置：符合 ITENTIAL_MCP_TOOL_* 模式的环境变量可以定义自定义工具绑定。这项功能很强大，但需要设置信任边界
4. 凭据管理：切勿在共享环境中暴露凭据。请使用密钥管理系统（Kubernetes Secrets、HashiCorp Vault 等）

推荐的部署实践：

• 使用容器化（Docker、Kubernetes）来隔离环境变量
• 实施最小权限访问控制
• 定期轮换凭据
• 在生产环境中启用 TLS 和证书验证
• 为 HTTP/SSE 传输启用身份验证（JWT、OAuth）

有关生产环境部署，请参阅我们的安全最佳实践指南。

配置文件

也可以使用配置文件指定服务配置。配置文件可用于传入所有配置参数。若要使用配置文件，只需传入 --config <path> 命令行参数，其中 <path> 指向要加载的配置文件。

配置文件的格式和值请参阅此处。

在多个位置指定配置选项时，将按以下优先级（从高到低）确定所使用的值：

1. 环境变量
2. 命令行选项
3. 配置文件
4. 默认值

🎛️ 工具选择与标签

Itential MCP 服务通过全面的标签系统提供强大的工具筛选功能。您可以根据具体需求和安全要求，自定义可用工具。

基于标签的筛选

使用包含和排除标签控制工具是否可用：

# Include only health and device management tools  
itential-mcp run --include-tags "health,configuration_manager"

# Exclude experimental and beta tools (default behavior)
itential-mcp run --exclude-tags "experimental,beta,lifecycle_manager"

可用的标签组

标签组	工具数量	描述	使用场景
health	1	平台运行状况与监控	平台管理员
configuration_manager	16	设备、合规性和配置管理	网络工程师
operations_manager	9	自动化、工作流和作业管理	自动化开发人员
automation_studio	12	命令模板、项目和模板	网络运营人员
lifecycle_manager	7	资源生命周期和实例管理	产品经理
work_center	2（1 个实验性）	手动任务（工作项）检查和实验性完成	自动化运营人员
workflow_engine	6	工作流执行指标	性能分析师
adapters	4	适配器生命周期管理	集成专家
applications	4	应用生命周期管理	应用负责人
gateway_manager	5	外部服务管理	系统集成商
integrations	3	外部系统集成	API 开发人员
agent_session_manager	5	Agent 会话和令牌用量	AI/Agent 运营人员
inventory_manager	5	库存管理	网络工程师

基于角色的配置

以下基于角色的配置根据具体的工作职能和职责提供定制的工具访问权限：

平台管理员： 平台运行状况监控、组件管理、平台运营

itential-mcp run --include-tags "health,adapters,applications,integrations"

主要工具：平台运行状况监控、适配器/应用生命周期、集成管理

网络工程师： 设备管理、配置、合规性、网络自动化

itential-mcp run --include-tags "configuration_manager,automation_studio"

主要工具：设备配置、合规计划、命令模板、黄金配置管理

自动化开发人员： 工作流构建、性能分析、平台扩展

itential-mcp run --include-tags "operations_manager,workflow_engine,lifecycle_manager,gateway_manager"

主要工具：工作流执行、性能指标、资源生命周期、外部服务集成

平台运营人员： 日常运营、作业监控、报告生成

itential-mcp run --include-tags "operations_manager,configuration_manager"

主要工具：工作流执行、作业监控、设备操作、合规性报告

📚 文档与集成

完整工具参考

可在工具文档中查看全部可用工具列表及详细的标签关联信息。

配置与安全

• MCP 客户端集成 - 配置 Claude、Continue.dev 和其他 MCP 客户端
• TLS 配置 - 使用证书启用安全的 HTTPS 连接
• JWT 身份验证 - 设置 JWT 令牌身份验证
• OAuth 身份验证 - 使用多个提供商进行 OAuth 2.0 身份验证
• 配置示例 - 完整的配置文件参考
• 状态端点 - 生产部署的运行状况监控

高级功能

• 标签系统 - 高级工具筛选和选择策略
• 工作流执行 - 执行和监控 Itential 工作流
• 自定义工具开发 - 创建并集成自定义 MCP 工具

提示词示例

• Claude Desktop 提示词 - 针对 Claude 集成优化的提示词
• GPT 集成提示词 - 针对 GPT 集成优化的提示词

🛠️ 添加新工具

添加新工具很简单：

1. 在 src/itential_mcp/tools/ 目录中创建新的 Python 文件，或在现有文件中添加函数
2. 定义一个带有 Context 参数注解的异步函数：

from fastmcp import Context

async def my_new_tool(ctx: Context) -> dict:
    """
    Description of what the tool does

    Args:
        ctx (Context): The FastMCP Context object

    Returns:
        dict: The response data

    Raises:
        None
    """
    # Get the platform client
    client = ctx.request_context.lifespan_context.get("client")

    # Make API requests
    res = await client.get("/your/api/path")

    # Return JSON-serializable results
    return res.json()

服务启动时会自动发现并注册工具。

运行测试

使用以下命令运行测试套件：

make test

查看测试覆盖率信息：

make coverage

贡献

欢迎贡献！贡献前请阅读我们的行为准则。

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature/my-feature
3. 提交更改：git commit -am 'Add new feature'
4. 推送到分支：git push origin feature/my-feature
5. 提交拉取请求

提交前：

• 运行 make premerge，确保测试通过且代码风格正确
• 为新功能添加文档
• 为新功能添加测试

许可证

本项目采用 GNU General Public License v3.0 许可，详情请参阅 LICENSE 文件。

版权所有 (c) 2025 Itential, Inc