Sciple Platform

Sciple Platform MCP 服务

MCP 服务，可让本地 Claude 通过 Sciple REST API 填充和管理 Sciple 平台内容——环境、服务、可观测性仪表板、运行手册、项目和工单。工程师可以使用它来初始化租户结构、维护服务目录、构建仪表板、编写运行手册和分类处理工单，而无需离开 AI 编码会话。

分发渠道：

渠道	使用场景	安装方式
PyPI	Claude Code、自定义脚本、CI	uvx sciple-mcp
MCP Registry	任何使用注册表协议的 MCP 客户端	自动解析 io.github.navaganeshr/sciple-mcp
桌面扩展（.dxt）	Claude Desktop	从 GitHub 发布页双击 sciple-mcp-<version>.dxt

• PyPI：https://pypi.org/project/sciple-mcp/
• MCP Registry：https://registry.modelcontextprotocol.io/v0/servers/io.github.navaganeshr%2Fsciple-mcp
• 源代码：https://github.com/navaganeshr/sciple-mcp

安装

# Install uv (one-time, only if you don't have it)
curl -LsSf https://astral.sh/uv/install.sh | sh

uvx sciple-mcp 会从 PyPI 获取最新版本并将其缓存。

身份验证——仅支持 OAuth（v0.7.0+）

sciple-mcp 通过 OAuth 2.0 with PKCE 向 Sciple 平台进行身份验证。CLI 是一个凭据助手：通过 浏览器登录一次，访问令牌和刷新令牌便会写入 ~/.sciple/credentials.json （权限模式为 0600），MCP 服务会从该文件读取令牌并自动刷新。

v0.7.0 已移除对 PAT 的支持。 早期版本接受在环境变量中设置 SCIPLE_API_TOKEN=sciple_pat_…（stdio 模式）。此方式 已被移除——MCP 服务唯一支持的凭据是由 sciple-mcp login 签发的 OAuth JWT。平台上的个人访问令牌不受影响，仍可用于脚本、CI，以及直接调用 /api/v1/* 的 REST 请求。

1. 登录（每个平台仅需一次）

sciple-mcp login --platform-url https://your.sciple.cloud

此命令会打开浏览器；在授权页面点击 Approve 后，CLI 会捕获回调并写入凭据。无需使用 --tenant-id / --scope——JWT 会继承当前仪表板所显示租户中的完整角色权限。

2. 配置 Claude

Sciple 平台现在直接托管 /mcp，因此推荐的方式是通过 Streamable HTTP 直接连接平台：

# Claude Code (HTTP transport — preferred)
claude mcp add-json sciple-platform "$(cat <<EOF
{
  "type": "http",
  "url": "https://your.sciple.cloud/mcp",
  "headers": { "Authorization": "Bearer $(sciple-mcp print-token)" }
}
EOF
)"

对于目前仅支持 stdio MCP 的 Claude Desktop 版本，请使用 stdio 模式——凭据相同，无需 PAT：

{
  "mcpServers": {
    "sciple-platform": {
      "command": "uvx",
      "args": ["sciple-mcp"],
      "env": {
        "SCIPLE_PLATFORM_URL": "https://your.sciple.cloud"
      }
    }
  }
}

SCIPLE_PLATFORM_URL 是可选项——仅当缓存了多个 平台时才需要。stdio 模式会直接读取 ~/.sciple/credentials.json。

3. 管理 / 轮换

sciple-mcp print-token            # current valid JWT (auto-refreshes near expiry)
sciple-mcp logout                 # forget local cache
sciple-mcp logout --revoke        # also revoke the refresh token server-side

你可以随时在仪表板的 个人资料 → 已连接的应用 中撤销授权。

旧版：sciple-mcp serve（本地 HTTP 服务）

对于客户端无法访问平台托管的 /mcp 端点的隔离部署环境， sciple-mcp serve 仍会提供本地 Streamable HTTP MCP 服务，用于针对平台的 JWKS 重新验证 OAuth JWT。 凭据和流程均相同——只有网络连接方式不同。 有关 serve / install / uninstall，请参阅 --help。

工具

云清单（只读）

工具	描述
list_aws_accounts	列出已连接到租户的 AWS 账户（account_id、名称、AWS 编号、区域、付款方标志）
list_cloud_resource_types	列出某个账户中已同步的资源类型及行数，范围为一个 AWS 服务
query_cloud_resources	查询任意已同步 AWS 资源表中的缓存行（支持分页和区域筛选）
list_ec2_instances	汇总一个账户或所有账户的 EC2 实例（状态 / 类型 / ID / 名称 / IP）

这些工具读取平台的最近一次 AWS 同步——它们不会直接调用 AWS， 也不会修改任何内容。凭据必须具有 cloud.view 权限。

示例 — 探索你的 AWS 资产

用自然语言询问 Claude；它会为你串联调用工具：

你： 我们所有 AWS 账户中有哪些 EC2 实例正在运行？

Claude 调用 list_ec2_instances（未提供 account_id → 扫描每个已连接的 账户），并总结：

45 EC2 instances across 4 accounts.

### Production (account_id=LlDZzq) — 13 instances (12 running, 1 shutting-down)
  [running] m5.2xlarge i-047323d5f680e822f portal-apps-ondemand (10.40.2.11)
  [running] t2.micro   i-00fcaed2de8131fd1 prod-nat-instance-1a (10.40.0.9)
  ...

若要深入查看单个账户或其他资源类型，Claude 会先发现已同步的内容， 然后再查询：

你： 显示 Production 账户中的 RDS 数据库。

1. list_aws_accounts                  → Production has account_id "LlDZzq"
2. list_cloud_resource_types(         → aws_rds_db_instance: 4
     account_id="LlDZzq", service="rds")
3. query_cloud_resources(             → 4 rows (engine, class, status, endpoint…)
     account_id="LlDZzq", service="rds",
     resource_type="aws_rds_db_instance")

query_cloud_resources 是用于访问 任意 19 种受支持服务的通用工具 （ec2、rds、s3、vpc、iam、lambda、eks、ecs、ebs、 elasticache、route53、cloudfront、dynamodb、ecr、efs，以及 code* 系列）——传入未知的 service，该工具会返回有效值列表。 使用 region 进行筛选（S3 使用 "global"），并通过 page / page_size（≤500） 遍历大型数据表。

环境

工具	说明
list_environments	列出租户中的所有环境（id、名称、slug、组、默认标记）
create_environment	创建环境，可选指定所属组和默认标记
update_environment	更新环境的名称、描述、组或排序顺序
delete_environment	根据 id 删除环境（不可撤销）
list_environment_groups	列出环境组（id、名称、slug、AWS 账户绑定）
create_environment_group	创建环境组，可选绑定 AWS 账户

服务

工具	说明
list_services	列出租户目录中的所有服务（id、名称、slug）
create_service	在目录中创建服务，并指定类型、语言、SCM 提供商和代码仓库
update_service	更新服务的元数据、生命周期、所有者、标签、链接或环境关联
delete_service	根据 id 从目录中删除服务（不可撤销）

可观测性

工具	说明
list_dashboards	列出租户中的所有可观测性仪表板（id、名称、面板数量）
get_dashboard	获取仪表板的名称、描述和面板列表
create_dashboard	创建新的仪表板，可选添加描述
update_dashboard	替换仪表板的名称和描述（完整 PUT；名称必填）
delete_dashboard	删除仪表板及其所有面板（不可撤销）
add_panel	向仪表板添加面板。端到端支持 5 种形状（选择一种）：PromQL（promql）、CloudWatch 指标（cw_namespace+cw_metric_name+cw_stat，以及可选的 cw_dimensions/cw_period）、ElasticSearch/OpenSearch 日志（es_index，以及可选的 kql_filter）、CloudWatch 日志（cw_log_group，以及可选的 cw_filter_pattern）或文本（text_content，以及可选的 text_background）。日志面板还接受显示选项（log_columns、log_limit、log_wrap_message、log_expandable_rows、log_highlight_by_severity、log_live_tail）。指标和日志面板始终要传入 datasource_id。
delete_panel	从仪表板中删除面板（不可撤销）

运行手册

工具	说明
list_runbooks	列出租户中的所有运行手册，包括生命周期状态和单元格数量
get_runbook	获取运行手册及其单元格（名称、状态、每个单元格的内容预览）
create_runbook	创建处于草稿状态的新运行手册
add_cell	向运行手册添加 markdown / shell / http 单元格，可选指定 k8s/ecs/ec2 目标
update_cell	更新单元格的内容或执行目标
delete_cell	移除运行手册中的单元格
reorder_cells	设置运行手册中所有单元格的执行顺序
promote_runbook	推进运行手册的生命周期：draft → reviewed → standard
deprecate_runbook	将运行手册标记为已弃用

运行手册生命周期：draft → reviewed → standard。从任意状态弃用后都不可逆。

Projects

工具	描述
list_projects	列出租户中的所有项目（id、key、名称、分类）
get_project	获取单个项目的详细信息（所有者、描述、分类）
create_project	创建新项目（名称 + 大写 key，例如 "PLAT"，可选分类 + 所有者）
list_project_members	列出项目成员的 user_ids 和角色（用于查找受派人）
list_project_issue_types	列出项目的问题类型（调用 create_project_ticket 前必须先获取）

工单

工具	描述
list_tickets	列出租户中的工单，支持可选筛选条件（服务、受派人、状态、优先级、类型、标签、全文 q）
get_ticket	获取单个工单的完整详细信息和活动计数（通过内部 id）
create_ticket	创建服务级工单（不绑定到项目）——tickets.manage
update_ticket	PATCH 工单——更改状态、优先级、受派人、日期、标签、父级
comment_on_ticket	为工单添加评论——tickets.comment
link_tickets	关联两个工单（blocks / relates_to / duplicates）
list_project_tickets	列出项目中的工单
get_project_ticket	根据序列号获取项目工单（KEY-NNN 中的 NNN）
create_project_ticket	在项目中创建工单——返回 "KEY-NNN" 格式的显示 id。推荐用于大多数工单创建场景。支持 custom_fields（包含 {field_id: value} 的 JSON 字符串）。需要 tickets.create。

工单状态：open → in_progress → done（也可从任何状态转为 cancelled）。优先级：low / medium / high / urgent。严重程度（可选）：minor / major / critical。类型：epic / story / task / subtask / bug。

安全性

此服务只能执行 PAT 权限范围允许的操作。若尝试在缺少相关 manage 权限的情况下写入，API 将返回 403，并在 Claude 的响应中显示为错误。可随时在 Sciple 控制面板的 Profile → Access tokens 中撤销 PAT——撤销后会立即切断此服务的访问权限，无需更改任何配置。

开发

要开发此服务本身：

git clone https://github.com/navaganeshr/sciple-mcp
cd sciple-mcp
uv sync --all-groups
uv run python -m pytest -q

发布由标签驱动，通过使用 PyPI Trusted Publishing（OIDC）的 GitHub Actions 工作流完成。发布步骤：

1. 在 pyproject.toml 中递增 version。
2. 提交，然后运行 git tag vX.Y.Z && git push origin vX.Y.Z。
3. 在 Actions 界面中批准 pypi 环境部署。