mc8yp (Schplitt)

mc8yp-人工智能代理的完全累积API访问

mc8yp是一款 模型上下文协议（MCP） 允许AI代理访问的服务器 API全堆积度表面 通过紧凑的代码模式接口。

它支持本项目暴露的两个捆绑的Cumulocity API家族：

• 核心api
• API DTM

mc8yp没有将代理限制在一组固定的预构建工具中，而是通过两个代码模式工具为他们提供了对Cumulocity的广泛访问：

• query --检查捆绑的Core+DTM OpenAPI规格
• execute -调用实时Cumulocity API

其结果是MCP集成，代理可以在更广泛的Cumulocity平台上工作，而运营商仍然保持 细粒度控制 关于运行时实际允许的内容。

mc8yp有两种模式：

• 累积微服务模式 用于生产 AI代理管理器
• CLI模式 用于本地调试、测试和开发

为什么选择mc8yp

为代理商提供全面的API能力

mc8yp的构建是为了让代理访问 通过捆绑的核心和DTM规格提供完整的API表面，而不是一小部分精心策划的行动。

这意味着代理不会仅仅因为特定端点从未被包装为自定义MCP工具而被阻止。

首先为AI Agent Manager构建

主要生产部署模型为 累积微服务模式.

将mc8yp部署为Cumulocity微服务并公开 /mcp 到 AI代理管理器，因此代理可以在平台内使用广泛的Cumulocity API功能。

全功率、受控访问

广泛的能力确实如此 不 必须意味着不受限制的访问。

mc8yp允许您通过以下方式限制API的实时使用：

• 限制 拒绝特定的方法或路径
• 允许规则 定义允许列表
• 捆绑的OpenAPI禁用 用于选定的API系列
• 沙盒执行 以及租户主机网络边界
• 正常 累积权限 来自经过身份验证的用户或服务用户

这使得这样的设置成为可能：

• 只读代理
• 非破坏性生产剂
• 代理人仅限于 库存, 警报，或其他选定的API系列
• 代理只允许写入一小部分经过批准的端点

令牌效率来自小的MCP表面

该代理在不需要大量固定工具库存的情况下获得了广泛的API覆盖范围。mc8yp没有使用许多特定于端点的工具，而是保持了MCP表面的紧凑性，并让模型对捆绑的OpenAPI规范进行推理。

运作原理

1. 代理人使用 query 检查捆绑的Cumulocity OpenAPI规范。
2. 代理决定它需要哪个Core或DTM端点。
3. 代理人使用 execute 以调用实况Cumulocity API。
4. mc8yp在发送请求之前强制执行配置的限制和允许规则。

部署模式

1.累积微服务模式（推荐）

专为内部部署而设计 累积物联网.

在此模式下，mc8yp在以下位置公开HTTP MCP端点 /mcp 并且旨在与以下设备一起使用 AI代理管理器.

• 通过Cumulocity微服务打包进行部署
• 与...整合 AI代理管理器
• 自动使用服务用户的权限
• 配置每个连接的MCP策略，包括限制、允许规则和捆绑的OpenAPI禁用

2.CLI模式（本地开发）

CLI模式非常适合：

• 本地调试
• 测试代理提示和工作流
• 部署前验证访问策略设置
• 使用MCP客户端，如Claude Desktop

凭据存储在操作系统的安全凭据管理器中。

快速入门：AI代理管理器/微服务

1. 从下载最新版本包
2. 上传 .zip 在 应用程序管理
3. 在租户中订阅应用程序
4. 将您的代理工作流连接到：

https://.cumulocity.com/service/mc8yp-server/mcp

在微服务模式下不需要额外的租户凭据设置。微服务使用Cumulocity的部署环境和请求身份验证模型。

示例：生产安全只读微服务连接

您可以向代理公开广泛的API知识，同时只允许在运行时进行安全的读取访问。

MCP端点配置模式示例：

/mcp?allow=GET:/inventory/**&allow=GET:/alarm/**&allow=GET:/measurement/**

或者使用标题：

POST /mcp HTTP/1.1
mc8yp-allow: GET:/inventory/**
mc8yp-allow: GET:/alarm/**
mc8yp-allow: GET:/measurement/**

快速入门：本地CLI

# Run directly (recommended)
pnpm dlx mc8yp

# Pick a specific bundled OpenAPI build for query
pnpm dlx mc8yp --spec 2025

# Or install globally
npm install -g mc8yp
mc8yp

凭据存储

互动 mc8yp creds add flow使用掩码密码输入，并将凭据存储在操作系统的安全凭据管理器中。

• macOS：钥匙扣
• 视窗：凭证库
• Linux：特勤局API（libsecret）

管理凭据

# Add credentials (prompts for tenant URL, username, and a masked password)
pnpm dlx mc8yp creds add

# List stored credentials
pnpm dlx mc8yp creds list

# Remove stored credentials
pnpm dlx mc8yp creds remove

连接本地MCP客户端

对于Claude Desktop或任何MCP客户端，请添加：

{
  "servers": {
    "mc8yp": {
      "type": "stdio",
      "command": "pnpm",
      "args": ["dlx", "mc8yp"]
    }
  }
}

只读访问规则示例：

{
  "servers": {
    "mc8yp": {
      "type": "stdio",
      "command": "pnpm",
      "args": [
        "dlx",
        "mc8yp",
        "-a",
        "GET:/inventory/**",
        "-a",
        "GET:/alarm/**",
        "-a",
        "GET:/measurement/**"
      ]
    }
  }
}

捆绑的OpenAPI覆盖范围

这 query 该工具公开了此项目包含的捆绑OpenAPI快照：

• 核心 快照： release, 2026, 2025，以及 2024
• 数字地形模型 快照：与每个支持的核心构建捆绑在一起

在CLI模式下，使用 --spec 或 -s 选择哪个捆绑 核心 OpenAPI快照 query 暴露：

# Default: latest bundled release build
mc8yp

# Explicitly use the 2025 bundled build
mc8yp --spec 2025

# Short form
mc8yp -s 2024

这只会改变捆绑的OpenAPI数据 query 看到。这 execute 工具仍然调用所选租户或部署的服务环境的实时Cumulocity API。

工具和提示

工具

两种代码模式工具都在沙盒运行时中运行(安全执行).

• query 返回JSON文本，以便更轻松地检查OpenAPI数据。
• execute 返回函数成功的结果 Toon格式。如果执行被阻止或失败，它将返回一条纯文本消息。

提示

执行输入形状

这 execute 工具需要一个异步函数表达式，而不是具有的模块源代码 export default.

推荐形状：

async () => {
  return await cumulocity.request({
    method: 'GET',
    path: '/inventory/managedObjects?pageSize=5',
  })
}

您还可以在返回最终值之前执行中间处理：

async () => {
  const devices = await cumulocity.request({
    method: 'GET',
    path: '/inventory/managedObjects?pageSize=20&withTotalPages=true',
  })

  return devices.managedObjects?.map((device) => ({ id: device.id, name: device.name }))
}

API访问策略

mc8yp支持两种连接规则类型：

• 限制 -拒绝阻止匹配API操作的规则
• 允许规则 -允许列出允许匹配API操作的规则，并在配置了至少一个允许规则时阻止其他所有操作

如果两者都适用于同一操作， 限制优先.

这使得可以在保持代理的同时公开广泛的API功能 只读 或以其他方式 无损的 操作模式。

示例：允许 /inventory/** 但限制 /inventory/managedObjects 静止块 /inventory/managedObjects.

两种规则类型使用相同的语法。

限制

限制是阻止特定API操作的拒绝规则。

允许规则

允许规则与限制相反。他们定义了什么是允许的。当配置了一个或多个允许规则时，任何与至少一个允许规则不匹配的操作都会被阻止。

规则格式

限制或允许规则可以用以下任一形式编写：

:

• 没有方法前缀 --匹配所有HTTP方法以匹配路径
• 带有方法前缀 --仅匹配该方法（例如 GET:, DELETE:, POST:)
• 这 : 分隔符仅在提供方法前缀时存在
• 支持的方法 — DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, TRACE，或 *
• 解析时方法名称不区分大小写(get:/inventory/** 成为 GET:/inventory/**)

路径模式语法

模式与请求相匹配 路径名.

• 查询字符串和片段是 规则模式中不允许
• 传入的请求查询字符串将被忽略以进行匹配，因此 /inventory/** 还匹配以下请求 /inventory?pageSize=5
• 模式必须从以下内容开始 /
• 匹配是路径段感知的： / 分离分段

支持的通配符：

• * --通配符 在单个路径段内。它匹配除以下字符之外的任何字符 /
• ** --递归通配符跨 零个或多个完整路径段. ** 必须是它自己的完整部分

路径模式示例

常见规则示例

重要说明

• /inventory/** 已匹配 /inventory 本身，你也一样 不 两者都需要 /inventory 和 /inventory/**
• /i** 是 无效 因为 ** 必须是自己的一部分。使用 /i*/** 如果你想匹配以以下开头的第一段 i 以及它下面的一切
• *:/inventory/** 是允许的，意思与 /inventory/**
• 捆绑的Core和DTM规范中的根路径被有意视为不相交的，因此基于路径的限制和允许规则足以执行请求
• 规则模式不能包含空段(//), . 或 .. 段、查询字符串或片段

命令行接口命令模式

将限制和允许规则作为CLI参数传递。

重复 -r, --restrict，或 --restriction 对于拒绝规则：

# Block all inventory access
mc8yp -r "/inventory/**"

# Block deletes on inventory and all alarm access
mc8yp -r "DELETE:/inventory/**" -r "/alarm/**"

# Same thing using the long alias
mc8yp --restrict "/user/**"

重复 -a, --allow，或 --allowed 对于允许规则：

# Only permit inventory access
mc8yp -a "/inventory/**"

# Permit GET inventory access and POST alarms
mc8yp --allow "GET:/inventory/**" --allowed "POST:/alarm/**"

# Allow inventory broadly, but still block one path with a restriction
mc8yp -a "/inventory/**" -r "/inventory/managedObjects"

要禁止一个或多个捆绑的OpenAPI部分执行策略，请重复 --disable-openapi （或 -d)在CLI模式下。 query 仍然可以看到所有捆绑的规格，并可以进行检查 specsEnabled 要了解哪些规范族仍然支持执行策略：

# Disable bundled DTM APIs for execute policy on this CLI connection
mc8yp -d dtm

# Disable multiple bundled specs if more are added in the future
mc8yp -d dtm -d core

微服务模式（HTTP）

通行证限制如下 restriction, restrict，或 r 查询MCP端点URL上的参数。 通行证允许规则如下 allowed, allow，或 a 查询参数。 要禁止捆绑的OpenAPI部分用于执行策略，请传递 openapi-disabled 查询参数。 您还可以发送项目范围的HTTP标头，以避免与众所周知的标头冲突：

• mc8yp-restriction 拒绝规则
• mc8yp-allow 对于允许列表规则
• mc8yp-openapi-disabled 用于捆绑OpenAPI部件禁用

这两个标头都接受重复的标头实例或逗号分隔的值列表。查询参数和标头可以在同一连接上组合。

/mcp?restriction=/inventory/**&restrict=DELETE:/alarm/**
/mcp?r=/inventory/**&r=DELETE:/alarm/**
/mcp?allow=/inventory/**&allowed=POST:/alarm/**
/mcp?openapi-disabled=dtm
/mcp?openapi-disabled=dtm&openapi-disabled=core

POST /mcp HTTP/1.1
Authorization: Bearer 
mc8yp-restriction: /inventory/**
mc8yp-restriction: DELETE:/alarm/**
mc8yp-allow: GET:/measurement/**
mc8yp-openapi-disabled: dtm

访问策略的工作原理

1. 查询可见性：The query 该工具公开了当前MCP连接的原始捆绑OpenAPI规范。捆绑的规范不会被隐藏或重写，查询沙箱会暴露 specsEnabled 因此，模型可以看到为执行策略启用了哪些规范族。

1. 沙盒请求执行：The execute 该工具检查生成的沙盒请求助手中的限制和允许规则，其中实际的HTTP方法和规范化路径都是可用的。匹配拒绝规则先阻止。如果配置了任何允许规则，则请求也必须至少匹配一个允许规则。

1. 捆绑规格禁用：当连接禁用捆绑的OpenAPI部件时，例如 dtm, query 仍然显示所有捆绑的规格，而服务器将该选择扩展为其他限制，因此 execute 保持基于路径和方法。

1. 网络边界：安全执行权限层独立限制对配置的租户主机的网络访问。其他网络操作被拒绝。

当A execute 请求被MCP连接策略阻止，该工具返回解释性文本，说明该操作是被限制拒绝还是被阻止，因为它在配置的允许列表之外，没有向Cumulocity发送请求，通过同一连接重试将无济于事。

构建和包装

该存储库捆绑了多个OpenAPI规范供CLI使用，并为每个配置的构建版本构建了一个微服务服务器捆绑包。

构建输出

pnpm build 生产：

• CLI捆绑包中 dist/
• 版本化的服务器捆绑在 .output/release/, .output/2026/, .output/2025/，以及 .output/2024/

构建矩阵由以下因素驱动 openapi-builds.json.核心快照实时显示 openapi/core/，DTM快照实时 openapi/dtm/，每个服务器捆绑包都包含该版本的配置组合。

发布包装

使用专用打包命令 pnpm build 要创建基于Docker的Cumulocity发布压缩包：

打包步骤在下面写入临时生成的Dockerfile .c8y/，将选定的版本化服务器捆绑包复制到 /app/server/，并在将其复制到运行时阶段之前，使用pnpm在Linux映像中安装生产依赖关系。这避免了在macOS上构建发布工件但部署为 linux/amd64 微服务。

部署的HTTP传输仅使用POST流式HTTP(GET /mcp 故意返回 405)因为一些反向代理和微服务入口层没有保持可选的长期SSE通知通道足够稳定，无法进行可靠的MCP工具调用。

pnpm package:microservices

该命令在存储库根目录中为每个捆绑的服务器变体创建一个zip，例如：

• mc8yp-core-release-dtm-v1.2.3.zip
• mc8yp-core-2026-dtm-v1.2.3.zip
• mc8yp-core-2025-dtm-v1.2.3.zip
• mc8yp-core-2024-dtm-v1.2.3.zip

GitHub发布工作流在构建标记的发布时使用该打包命令。

发展

先决条件

• Node.js≥24.0.0
• pnpm

设置

pnpm install
pnpm lint
pnpm typecheck
pnpm build

测试

# Run tests
pnpm test:run

# Run benchmarks
pnpm test:bench

从源代码本地运行

首先构建，然后将MCP客户端指向已编译的CLI：

pnpm build

然后添加到本地MCP客户端配置中：

{
  "servers": {
    "local_mc8yp": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/your/project/dist/cli.mjs"]
    }
  }
}

许可证

麻省理工学院