mcp-kettlelogic

mcp-kettlelogic

一个 模型上下文协议（MCP）服务，可向任何支持 MCP 的 Agent（Claude Desktop、IDE、自定义编排器）公开 Kettle Logic 网站发布的内容——白皮书／实战指南（“insights”）和行业页面。

它是一个纯只读的公开网站客户端：通过 HTTP 实时获取内容，并使用 Python 标准库进行解析。无需数据库、API 密钥，也不依赖任何后端集群或大模型。目标网站可配置，因此你可以将其指向自己的部署——或任何结构相同的网站——查看它能发现哪些内容。

基于官方 mcp Python SDK（FastMCP）构建，采用标准 stdio 传输方式（并提供可选的 streamable-http 传输方式，用于容器／Kubernetes 部署）。

工程说明：本仓库也兼作我们构建方式的参考——六边形分层、完整类型标注的面向对象设计、依赖注入，以及一套在 CI 中强制执行规则的 防回退机制（参见 ARCHITECTURE.md）。pytest 会同时运行单元测试、真实 stdio 端到端测试和防回退检查。

---

提供的功能

工具

工具	描述
search_articles(query, limit=5)	按标题／slug／描述搜索 insight 文章。
get_industry_overview(industry)	从行业页面提取纯文本概览。
list_articles()	所有 insight 文章的 JSON 目录（标题、slug、描述）。
list_industries()	提供指导信息的行业 JSON 列表（名称 + slug）。
get_article(slug)	将单篇 insight 文章呈现为易读文本。

资源

URI	描述
kettlelogic://articles/manifest	所有 insight 文章的 JSON 目录。
kettlelogic://industries/list	网站上发现的行业页面 JSON 列表。
kettlelogic://articles/{slug}	将单篇文章呈现为易读文本。

实时发现内容：文章来自网站的 /insights/ 索引，行业信息来自网站的 /llms.txt（若不可用，则通过爬取 /industries/ 获取）。

---

安装与运行

pip install .            # Python >= 3.11; pulls in mcp + httpx
mcp-kettlelogic          # console script (stdio transport by default)

通常由 MCP 客户端启动。若要进行交互式探索：

npx @modelcontextprotocol/inspector mcp-kettlelogic

在 MCP 客户端中使用

{
  "mcpServers": {
    "kettlelogic": {
      "command": "mcp-kettlelogic",
      "env": { "KETTLELOGIC_BASE_URL": "https://kettlelogic.com" }
    }
  }
}

或连接到托管服务（无需安装）

一个经过安全加固的实例通过 streamable-HTTP 实时运行——将任何 MCP 客户端指向它：

{
  "mcpServers": {
    "kettlelogic": { "url": "https://kettlelogic.com/mcp" }
  }
}

发布到 MCP 注册表

此服务已列入公开的 MCP 注册表，名称为 com.kettlelogic/mcp-kettlelogic（品牌：kettlelogic，而非个人 GitHub 用户名）。server.json 是其清单——其中声明了托管的 streamable-HTTP 远程服务，并通过 2025-12-11 架构验证。

该条目通过 HTTP 域名所有权认领，而非 GitHub 登录：注册表会获取 https://kettlelogic.com/.well-known/mcp-registry-auth（由营销网站提供的公开密钥质询——位于 kettlelogic 仓库中的 web/public/.well-known/mcp-registry-auth），并验证使用我们的 Ed25519 私钥生成的签名。

自动化（在可自托管的 runner 上）

.github/workflows/publish-registry.yml 每次 GitHub Release 发布时都会自动发布（也可通过手动 Run workflow 触发）。 它运行在我们集群中的自托管 runner 上（runs-on: [self-hosted, linux, cluster]）——之所以这样选择，是因为 GitHub 托管的运行时长很快就会用完，而这种方式发布不消耗配额，也不会在当月配额耗尽时失败。该 runner 还会从集群内的 Secret 挂载签名密钥（/opt/mcp/key-hex），因此密钥绝不会存放在 GitHub Actions secrets 中。

因此，常规流程是：更新 version.py 和 server.json 中的 version → 创建 GitHub Release → 注册表会自动更新。

Runner 只需设置一次，相关配置位于私有主仓库： deployments/github-runner/（请参阅其中的 README）。如果 runner 宕机，可从 Actions 选项卡重新运行，或使用下面的本地备用方案——它始终可用，无需任何基础设施。

手动

如果需要手动发布：

# 1. Get the CLI (prebuilt binary from the registry releases)
curl -L https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_linux_amd64.tar.gz | tar xz mcp-publisher

# 2. From the repo root (where server.json lives):
./mcp-publisher validate
./mcp-publisher login http --domain kettlelogic.com \
  --private-key "$(openssl pkey -in .secrets/mcp-registry-key.pem -outform DER | tail -c 32 | xxd -p -c 64)"
./mcp-publisher publish

密钥、恢复与轮换

Ed25519 密钥用于授权在 com.kettlelogic 命名空间下发布。它存在于三个位置（私钥有意不放入 git）：

1. 本地 — .secrets/mcp-registry-key.pem（已加入 gitignore）。方便手动发布。
2. 集群 — github-runner 命名空间中的 Secret mcp-registry-key（键 key-hex）。自动发布 runner 使用此密钥，它也是规范备份。
3. 公钥部分 — 托管于 https://kettlelogic.com/.well-known/mcp-registry-auth （已提交到 kettlelogic 仓库，路径为 web/public/.well-known/mcp-registry-auth）。

本地 .pem 丢失了？ 可直接从集群恢复签名密钥（十六进制格式）——发布只需要十六进制密钥，不需要 pem 文件：

KEY_HEX="$(kubectl -n github-runner get secret mcp-registry-key -o jsonpath='{.data.key-hex}' | base64 -d)"
./mcp-publisher login http --domain kettlelogic.com --private-key "$KEY_HEX"
./mcp-publisher publish

轮换密钥（如果密钥泄露）：

openssl genpkey -algorithm Ed25519 -out .secrets/mcp-registry-key.pem   # new key
PUB="$(openssl pkey -in .secrets/mcp-registry-key.pem -pubout -outform DER | tail -c 32 | base64)"
# 1. update the served challenge (in the kettlelogic repo) + redeploy the site:
echo "v=MCPv1; k=ed25519; p=$PUB" > ../kettlelogic/web/public/.well-known/mcp-registry-auth
# 2. update the cluster Secret the runner uses:
kubectl -n github-runner delete secret mcp-registry-key
kubectl -n github-runner create secret generic mcp-registry-key \
  --from-literal=key-hex="$(openssl pkey -in .secrets/mcp-registry-key.pem -outform DER | tail -c 32 | xxd -p -c 64)"
# 3. re-publish (new key must be live at the well-known URL first).

注册表中的版本不可变——不能重新发布已有版本； 请先更新 version.py 和 server.json。

配置

环境变量	默认值	用途
KETTLELOGIC_BASE_URL	https://kettlelogic.com	要读取的目标站点。可将其指向你自己的站点。
KETTLELOGIC_TRANSPORT	stdio	stdio（本地客户端）或 streamable-http（网络/k8s）。
KETTLELOGIC_HTTP_HOST / KETTLELOGIC_HTTP_PORT	0.0.0.0 / 8080	http 传输的绑定地址。
KETTLELOGIC_METRICS_PORT	(未设置)	若已设置，则在 /metrics 提供 Prometheus 指标。
KETTLELOGIC_LOG_LEVEL	INFO	日志级别。日志写入 stderr（stdout 是 MCP 通道）。
KETTLELOGIC_CACHE_TTL_SECONDS / KETTLELOGIC_MAX_ARTICLES / KETTLELOGIC_FETCH_CONCURRENCY / KETTLELOGIC_OVERVIEW_MAX_CHARS	参见 constants.py	调优参数。

容器与 Kubernetes

在网络环境中部署时，服务使用 streamable-http 传输。

docker compose -f deploy/docker/docker-compose.yaml up --build

Kubernetes 清单位于 deploy/k8s/（包含 2 个副本的 Deployment、 就绪/存活探针、资源限制、非 root 用户 + 只读根文件系统、 ClusterIP Service、ConfigMap）。使用以下命令应用：

kubectl apply -k deploy/k8s

可观测性

• 日志记录 — 将结构化日志写入 stderr：操作开始/完成及耗时、 获取结果、缓存命中/未命中、错误。设置 KETTLELOGIC_LOG_LEVEL。
• 指标 — Prometheus /metrics（设置 KETTLELOGIC_METRICS_PORT）： mcp_operations_total、mcp_errors_total、mcp_http_fetches_total、 mcp_http_errors_total、mcp_cache_total{result}、mcp_op_duration_seconds。

开发与测试

pip install -e ".[dev]"
ruff check src tests        # lint + import order
mypy                        # type check (disallow-untyped-defs)
pytest                      # unit + e2e + ratchets, coverage gate (fail-under 90%)

覆盖率约为 99%。有关分层结构、请求流程和完整的 ratchet 列表，请参阅 ARCHITECTURE.md。

许可证

MIT — 请参阅 LICENSE。