Netskope NPA MCP Server

Netskope NPA MCP 服务

通过 AI 驱动的自动化管理 Netskope Private Access（NPA）基础设施的综合 MCP（Model Context Protocol）服务。

📚 完整文档

本项目包含丰富的文档，结构清晰，便于查阅：

👉 从完整文档开始 - 概览和导航指南

快速访问链接

类别	描述	链接
🏗️ 架构	服务设计和模式	服务架构
🛠️ 工具参考	完整的工具文档	Publisher 工具、Private App 工具、Policy 工具
🔄 工作流	常见的自动化模式	常见工作流
💼 实际示例	完整的使用场景	真实案例

工具概览

MCP 服务在 10 个类别中提供 84 个专用工具：

类别	工具数	主要使用场景
Publishers	9 个工具	基础设施部署和管理
Private Apps	15 个工具	应用生命周期和配置
Local Brokers	7 个工具	网络连接和路由
Policy Management	6 个工具	访问控制和安全规则
SCIM Integration	5 个工具	身份和用户管理
Upgrade Profiles	7 个工具	自动化维护计划
Steering	3 个工具	流量路由和关联
Alerts	2 个工具	事件监控和通知
Search	2 个工具	资源发现和查询
Validation	2 个工具	配置合规性

实际使用示例

🏢 “为我们新的伦敦办公室搭建完整的 NPA 基础设施”

AI 响应：执行全面的部署工作流

• ✅ 创建带有自动升级配置的 publisher
• ✅ 配置用于内部路由的 local broker
• ✅ 设置核心业务应用（CRM、ERP、File Server）
• ✅ 创建访问策略，并验证 SCIM 组
• ✅ 为办公网络启用监控和发现
• ✅ 生成用于现场部署的注册令牌

🚨 “紧急：发生安全事件——立即锁定 HR/Finance 应用”

AI 响应：紧急安全响应工作流

• ✅ 自动识别所有 HR/Finance 应用
• ✅ 创建优先级最高的紧急策略组
• ✅ 阻止所有用户访问，但事件响应团队除外
• ✅ 加强对安全事件的监控
• ✅ 为应用添加事件跟踪标签

📊 “对我们的 NPA 环境进行全面合规审计”

AI 响应：自动化合规性评估

• ✅ 审计所有 publisher 的版本合规性
• ✅ 识别没有访问策略的应用
• ✅ 验证策略中的 SCIM 组引用
• ✅ 生成合规性评分和修复计划
• ✅ 按优先级生成详细的发现报告

快速开始

1. 环境设置

   export NETSKOPE_BASE_URL="https://your-tenant.goskope.com"
   export NETSKOPE_TOKEN="your-api-token"
   

2. 安装并运行

   npm install
   npm run build
   npm start
   

3. 通过 MCP 客户端连接

   {
     "mcpServers": {
       "netskope-npa": {
         "command": "node",
         "args": ["/path/to/privateaccess-mcp/build/index.js"],
         "env": {
           "NETSKOPE_BASE_URL": "https://your-tenant.goskope.com",
           "NETSKOPE_TOKEN": "your-api-token"
         }
       }
     }
   }
   

主要特性

🤖 AI 原生设计

• 工具专为与大模型交互而设计，描述清晰
• 自动验证和转换参数
• 提供丰富的错误上下文，便于排查问题

🔄 工作流编排

• 工具之间自动协作
• 内置重试逻辑和错误恢复机制
• 尽可能执行事务性操作

🛡️ 可用于生产环境

• 使用 Zod schema 进行全面的输入验证
• 速率限制和 API 配额管理
• 详细的日志记录和监控

🔗 集成模式

• 通过 SCIM 集成解析身份
• 通过搜索工具发现资源
• 通过验证工具检查合规性

安装选项

NPM 包

npm install @johnneerdael/ns-private-access-mcp

本地开发

git clone https://github.com/johnneerdael/privateaccess-mcp.git
cd privateaccess-mcp
npm install
npm run build

通用 JSON 客户端配置

适用于接收 JSON 映射的客户端（Cursor、Windsurf、自定义主机）：

{
  "mcpServers": {
    "netskope": {
      "url": "https://YOUR-MCP-HOST.example.com/mcp",
      "headers": {
        "X-Netskope-Tenant": "https://YOUR-TENANT.goskope.com",
        "Authorization": "Bearer YOUR_NETSKOPE_API_TOKEN"
      }
    }
  }
}

自托管

更倾向于运行自己的实例？项目附带两个 compose 文件：

文件	用途	命令
docker-compose.yml	运行来自 GHCR 的预构建多架构镜像。	docker compose up -d
docker-compose.build.yml	从本地源代码构建（用于开发）。	docker compose -f docker-compose.build.yml up --build

不使用 compose 的单行命令：

# Prebuilt image from GHCR
docker run --rm -p 3000:3000 ghcr.io/johnneerdael/privateaccess-mcp:latest

# Build and run from a local checkout
docker build -t netskope-mcp:local .
docker run --rm -p 3000:3000 netskope-mcp:local

# Or just run the Node entry directly
npm run build && PORT=3000 node dist/cli-http.js

容器开放 /mcp（可流式传输的 HTTP）和 /healthz（存活状态）。

实用环境变量：

变量	用途
PORT / HOST	绑定地址（默认值为 0.0.0.0:3000）。
PUBLIC_URL	规范的公共源站（例如 https://YOUR-MCP-HOST.example.com）。显示在 /healthz 和启动日志中；为未来的 OAuth/知名元数据预留。可以安全省略。
CORS_ORIGIN	以逗号分隔的允许列表，适用于基于 浏览器 的 MCP 客户端（例如 https://claude.ai）。默认为 *。与命令行客户端（Claude Code、Codex、Cursor）无关；如果运行在不需要 CORS 的反向代理后，也与其无关。
NETSKOPE_BASE_URL / NETSKOPE_API_TOKEN	可选的 回退 凭据，仅在客户端未提供标头时使用。单租户部署请同时设置这两项；多租户自托管时请将两项都留空（共享自托管部署推荐此设置）。

架构亮点

工具组合

工具通过定义明确的接口协同工作：

// Example: Creating a private app with validation and tagging
1. validateName() -> Check app name compliance
2. searchPublishers() -> Find target publisher
3. createPrivateApp() -> Create the application  
4. createPrivateAppTags() -> Add organizational tags
5. updatePublisherAssociation() -> Associate with publishers

架构驱动的校验

每个工具都使用 Zod 架构确保类型安全并进行校验：

const createAppSchema = z.object({
  app_name: z.string().min(1).max(64),
  host: z.string().url(),
  protocols: z.array(protocolSchema),
  clientless_access: z.boolean()
});

错误恢复能力

内置常见问题处理模式：

• 自动从 MCP 对象中提取参数
• 使用指数退避的重试逻辑
• 对部分故障进行平稳降级

致谢

• John Neerdael（Netskope Private Access 产品经理）
• Mitchell Pompe（Netskope 荷兰首席解决方案工程师）

获取帮助

• 文档问题：在 GitHub 上提交 issue
• 功能请求：创建功能请求 issue
• 错误报告：使用错误报告模板
• 安全问题：请参阅 SECURITY.md

---

此 MCP 服务将复杂的 Netskope NPA 管理转化为简单、由 AI 驱动的对话。