smplkit MCP Server

smplkit MCP 服务

一个托管的、原生支持 Agent 的 Model Context Protocol 服务——它是一个网关，让 AI Agent（Claude Code、Claude Desktop、Cursor、 ……）代表你操作整个 smplkit 平台， 无需离开聊天界面。

一个服务，整个平台：

• 功能标志 — 支持按环境设置值和定向规则的功能标志。
• 配置 — 带键名和类型的配置，支持按环境覆盖。
• 日志 — 按环境更改运行时日志级别。
• 审计 — 搜索审计日志并接入 SIEM 转发器。
• 作业 — 定时 HTTP 作业（cron、一次性或按需），支持捕获响应。

连接后，你可以告诉 Agent “为 prod 中的企业用户启用新的结账功能”， “设置 staging 数据库主机”， “将 prod 中的 SQL 日志记录器级别调高到 DEBUG”， “将审计事件流式传输到 Datadog”， 或 “每天早上 7 点向我的端点发送 POST 请求。” 它会执行更改、验证效果，并直接根据实时状态回答后续问题。

它是一个精简的、无状态 HTTP 客户端，用于调用 smplkit 产品 API——它本身不持有任何凭证。

连接一次

1. 添加服务并登录

服务地址为 https://mcp.smplkit.com/api/mcp。将 MCP 客户端指向此 URL——首次连接时，客户端会打开浏览器供你一次性登录（使用 Google 或 Microsoft 继续，标准 OAuth）。 之后客户端会自动重新连接并刷新访问权限；无需生成、复制或轮换密钥。

Claude Code（命令行）：

claude mcp add --transport http smplkit https://mcp.smplkit.com/api/mcp

……或者在 .mcp.json 中：

{
  "mcpServers": {
    "smplkit": {
      "type": "http",
      "url": "https://mcp.smplkit.com/api/mcp"
    }
  }
}

Cursor（~/.cursor/mcp.json 或项目的 .cursor/mcp.json）：

{
  "mcpServers": {
    "smplkit": {
      "url": "https://mcp.smplkit.com/api/mcp"
    }
  }
}

Claude Desktop（claude_desktop_config.json）——桌面应用通过 mcp-remote 桥接远程服务；它会打开浏览器供你一次性登录，并缓存连接：

{
  "mcpServers": {
    "smplkit": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.smplkit.com/api/mcp"]
    }
  }
}

更倾向于使用静态密钥？

对于非交互式使用场景——CI、脚本、无头客户端，或使用 smplkit SDKs 编写代码——可以跳过浏览器，通过 API 密钥作为 bearer token 进行身份验证。在 https://smplkit.com 注册（使用 Google 或 Microsoft SSO，或通过电子邮件即时验证）， 在控制台中创建 API 密钥，并将其作为 Authorization: Bearer YOUR_SMPLKIT_API_KEY 发送（也接受自定义的 X-Smplkit-Api-Key 标头）。 SDK 从 SMPLKIT_API_KEY 读取相同的密钥。例如，在上述配置中添加一个 headers 块：

{
  "mcpServers": {
    "smplkit": {
      "type": "http",
      "url": "https://mcp.smplkit.com/api/mcp",
      "headers": { "Authorization": "Bearer ${SMPLKIT_API_KEY}" }
    }
  }
}

2. 向 Agent 提问

“创建一个布尔型标志 new-checkout，默认关闭，然后仅为 prod 中的企业用户启用它。”

“列出我的环境，然后将 staging 的 database.host 设置为 db-staging.internal。”

“在我调试期间，将生产环境中的 sqlalchemy.engine 日志记录器级别调高到 DEBUG，然后再重置。”

“测试 https://http-intake.logs.datadoghq.com/... 是否接受示例数据，然后为我们的审计事件创建一个 Datadog 转发器。”

“每天早上纽约时间 7 点向 https://api.example.com/cache/warm 发送 POST 请求，然后立即运行一次以验证效果。”

工具

所有工具都使用意图命名的动词 — list_*、get_*、create_*、set_*、 delete_* — 并将 JSON:API 封套、按环境嵌套以及完整替换式 PUT 封装在部分意图调用后。

能力	工具
标志	create_flag、list_flags、get_flag、set_flag、delete_flag
配置	create_config、list_configs、get_config、set_config_value、delete_config
日志记录	set_log_level、list_loggers、get_logger、reset_logger
审计	query_events、get_event、list_forwarders、create_forwarder、test_forwarder、delete_forwarder
作业	create_job、list_jobs、get_job、update_job、delete_job、run_job、list_runs、get_run
平台	list_environments

几个关键行为：

• set_flag / set_config_value / set_log_level 会先读取、再修改、最后写入。 你可以在一个环境中表达部分更改，工具会保留其余内容。
• list_environments 会告知每个 set_* 工具和作业可用的环境目标（production、staging 等）。
• 先验证，再信任。 run_job 会触发一次作业并返回捕获的响应；test_forwarder 会在保存 SIEM 目标之前进行试运行。
• create_job 会推断类型： cron schedule → 定期作业，run_at 日期时间 → 单次作业，两者都没有 → 手动作业。你无需设置类型。

随附的 SKILL.md 会向 Agent 介绍完整的工具范围。

公网访问限制

smplkit 会从云端调用作业目标和转发器目标，因此这些 URL 必须可从公网访问 — localhost / 私有地址无法触发调用。若要指向本地服务，请使用其部署后的 URL，或通过隧道公开服务（cloudflared tunnel --url http://localhost:PORT 或 ngrok http PORT），并设置机密身份验证标头。

开发

python3.13 -m venv .venv && . .venv/bin/activate
pip install -r requirements-test.txt
pytest                                          # unit tests (acceptance deselected)
ruff check src tests

在本地运行服务：

PYTHONPATH=src uvicorn smplkit_mcp.app:app --host 0.0.0.0 --port 8000
# MCP endpoint:  http://localhost:8000/api/mcp
# Health check:  http://localhost:8000/health

配置（环境变量）— 每个产品的基础主机都可以单独配置，与 SDK 的 base_domain 模式一致：

• JOBS_BASE_DOMAIN / FLAGS_BASE_DOMAIN / CONFIG_BASE_DOMAIN / LOGGING_BASE_DOMAIN / AUDIT_BASE_DOMAIN / APP_BASE_DOMAIN — 各产品 API 的主机（默认为 <product>.smplkit.com；APP_* 为 list_environments 提供支持）。
• *_SCHEME — https（默认）或 http。
• *_BASE_URL — 完整的基础 URL 覆盖值（例如 http://localhost:8002）；优先于 以上两个变量。用于本地平台和测试。

验收测试

tests/test_acceptance.py 会创建一个临时的已验证账户，并针对真实产品 API 端到端地测试完整工具范围 — 创建/设置/获取/删除标志，设置和读取配置值，设置和列出日志级别，查询事件，创建/测试/删除转发器，列出环境，以及 8 个 Jobs 工具 — 然后清理。此类测试需要 smplkit 内部的管理员凭据，因此只有在有管理员密钥时才会运行（ADMIN_API_KEY 环境变量或 ~/.smplkit 中的 [admin] 配置）；外部贡献者可以忽略这些测试；单元测试套件无需凭据。显式运行方式：

pytest -m acceptance
# point at a non-prod platform with <PRODUCT>_BASE_URL=...

架构

• 基于 FastMCP 构建的无状态 Python 服务：不使用数据库，也不持有自己的平台凭据。
• 身份验证按请求进行 — 无论调用方使用 OAuth 登录还是发送 API 密钥，凭据都会按请求验证，并用于访问各个产品 API，且绝不会缓存或记录。
• 每个产品（flags、config、logging、audit、environments）各有一个轻量的 JSON:API HTTP 客户端，并分别指向其可配置的基础主机。
• MCP 端点通过无状态的 JSON 响应传输方式托管在 /api/mcp 下（不使用长连接 SSE），因此即使通过空闲超时较短的代理和负载均衡器，也能正常运行。

许可证

MIT。