mcp-kettlelogic

mcp-kettlelogic

Kettle Logicサイトで公開されているコンテンツ（ホワイトペーパー／プレイブック（「インサイト」）や業界ページ）を、MCP 対応のあらゆるエージェント（Claude Desktop、IDE、カスタムオーケストレーター）に提供するModel Context Protocol（MCP）サーバーです。

純粋な読み取り専用の公開ウェブサイトクライアントです。HTTP 経由でコンテンツをリアルタイムに取得し、Python 標準ライブラリで解析します。データベースも API キーも必要なく、バックエンドクラスターや LLM にも依存しません。対象サイトは設定可能なので、独自のデプロイ先や同じ構成の任意のサイトを指定して、検出内容を確認できます。

公式の mcp Python SDK（FastMCP）を基盤とし、標準のstdioトランスポートに加え、コンテナー／Kubernetes でのデプロイ向けにオプションのstreamable-httpトランスポートも提供します。

エンジニアリングノート：このリポジトリは、私たちの開発方法を示すリファレンスも兼ねています。六角形アーキテクチャー、完全に型付けされた OO、依存性注入、そして CI でルールを徹底する一連のラチェット（ARCHITECTURE.mdを参照）を採用しています。pytest はユニットテスト、実際の stdio を使った E2E テスト、ラチェットをまとめて実行します。

---

提供する機能

ツール

ツール	説明
search_articles(query, limit=5)	タイトル／スラッグ／説明文からインサイト記事を検索します。
get_industry_overview(industry)	業界ページから抽出したプレーンテキストの概要を返します。
list_articles()	すべてのインサイト記事の JSON カタログ（タイトル、スラッグ、説明文）を返します。
list_industries()	ガイダンスが掲載された業界の JSON リスト（名前＋スラッグ）を返します。
get_article(slug)	単一のインサイト記事を読みやすいテキスト形式で返します。

リソース

URI	説明
kettlelogic://articles/manifest	すべてのインサイト記事の 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 スキーマに対する検証を行います。

この登録の所有権は GitHub ログインではなく、HTTP ドメインの所有権によって証明されます。レジストリは https://kettlelogic.com/.well-known/mcp-registry-auth（マーケティングサイトで提供される公開鍵チャレンジ。kettlelogic リポジトリ内の web/public/.well-known/mcp-registry-auth）を取得し、私たちの Ed25519 秘密鍵で生成された署名を検証します。

自動（セルフホストのランナー上）

.github/workflows/publish-registry.yml GitHub Release のたびに自動で公開します（手動の Run workflow からも実行できます）。 クラスター内のセルフホストランナー（runs-on: [self-hosted, linux, cluster]）で実行します。GitHub ホストランナーの利用時間はすぐに上限に達するため、この方法なら公開にクォータを消費せず、月間上限に達しても失敗しません。このランナーはクラスター内の Secret から署名キーもマウントするため（/opt/mcp/key-hex）、キーが GitHub Actions のシークレットに保存されることはありません。

通常の手順は、version.py と server.json の version を更新 → GitHub Release を作成するだけで、レジストリが自動で更新されます。

ランナーのセットアップは一度だけ行い、プライベートホームリポジトリの deployments/github-runner/ にあります（README を参照）。ランナーが停止している場合は、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 名前空間での公開を承認します。 キーは3 か所にあります（秘密鍵は意図的に git に含めていません）。

1. ローカル — .secrets/mcp-registry-key.pem（gitignore 対象）。手動で公開する際に便利です。
2. クラスター — github-runner 名前空間の Secret mcp-registry-key（キー key-hex）。自動公開ランナーが使用するもので、正規のバックアップです。
3. 公開鍵 — https://kettlelogic.com/.well-known/mcp-registry-auth で配信されます（kettlelogic リポジトリの web/public/.well-known/mcp-registry-auth としてコミットされています）。

ローカルの .pem を紛失しましたか？ 署名キーをクラスターから直接（hex 形式で）復旧できます。公開に必要なのは hex であり、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、readiness／liveness プローブ、リソース制限、root 以外のユーザーと読み取り専用のルート FS、 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% です。レイヤー構成、リクエストフロー、すべてのラチェットの一覧については、ARCHITECTURE.md を参照してください。

ライセンス

MIT — LICENSE を参照してください。