kaitencloud-mcp 0.2.0__tar.gz

kaitencloud_mcp-0.2.0/.github/CODEOWNERS

@@ -0,0 +1,6 @@
+# Every change to this repository needs the approval of a member of @kaitencloud/engineering.
+#
+# The default-branch ruleset requires a review from a code owner. With this file, that means an
+# approval from one of the team's members -- never from a GitHub App or a workflow's token,
+# which cannot belong to a team, and never from the pull request's own author.
+* @kaitencloud/engineering

kaitencloud_mcp-0.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,21 @@
+## What does this PR change?
+
+<!-- Describe the change. -->
+
+## Why?
+
+<!-- Explain the motivation. -->
+
+## Testing
+
+<!-- Explain how this was tested. -->
+
+## Checklist
+
+- [ ] I have read `CONTRIBUTING.md`.
+- [ ] Every commit in this PR includes a valid DCO `Signed-off-by` line.
+- [ ] I have the right to submit all material in this PR.
+- [ ] I have not included secrets or confidential data.
+- [ ] I have updated tests where appropriate.
+- [ ] I have updated documentation where appropriate.
+- [ ] I have preserved required third-party licenses and attributions.

kaitencloud_mcp-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,142 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+    tags: ["v*"]
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+# The job names are the checks the default-branch ruleset requires: lint, test and build.
+jobs:
+  lint:
+    name: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "0.9.1"
+          enable-cache: true
+
+      - name: Install
+        run: uv sync --locked
+
+      - name: Lint
+        run: uv run ruff check . && uv run ruff format --check .
+
+  test:
+    name: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "0.9.1"
+          enable-cache: true
+
+      - name: Install
+        run: uv sync --locked
+
+      # The e2e suite needs a live Kaiten and is deselected by default; these
+      # drive every tool's wiring through the real SDK over a mocked API.
+      - name: Test
+        run: uv run pytest
+
+  # A pull request builds the image so a broken Dockerfile fails here; main and
+  # tags publish it to GHCR as ghcr.io/kaitencloud/kaiten-mcp. The package is
+  # created by this repository's first publish and linked to it by the image's
+  # source label, so it takes this repository's visibility: publish only once the
+  # repository is public. (`mcp` is a different, older package, linked to
+  # kaiten-internal, that this repository's token cannot write.)
+  build:
+    name: build
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    permissions:
+      contents: read
+      packages: write
+    env:
+      IMAGE: ghcr.io/${{ github.repository_owner }}/kaiten-mcp
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+
+      # Logged in on every run of this repository, pull requests included: the
+      # build cache lives in the registry and is read through this login. A pull
+      # request from a fork gets a read-only token, which still reads the cache.
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.IMAGE }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=sha
+
+      # The cache is a tag of the image's own package, not the GitHub Actions cache:
+      # that one is read-only on re-runs of an old pull request, and failed this
+      # job's build with "failed to reserve cache". Only main and tags write it.
+      - name: Build
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: ${{ github.event_name == 'push' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=registry,ref=${{ env.IMAGE }}:buildcache
+          cache-to: ${{ github.event_name == 'push' && format('type=registry,ref={0}:buildcache,mode=max', env.IMAGE) || '' }}
+
+  # A `v*` tag publishes the Python package to PyPI as kaitencloud-mcp, once lint,
+  # test and the image build have passed on it. Trusted publishing: no token is
+  # stored; PyPI trusts this workflow, in the `pypi` environment, to publish the
+  # project (see CONTRIBUTING.md, "Releasing").
+  publish:
+    name: publish
+    runs-on: ubuntu-latest
+    needs: [lint, test, build]
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "0.9.1"
+
+      - name: The tag is the project's version
+        run: |
+          version=$(uv version --short)
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match pyproject.toml's version $version"
+            exit 1
+          fi
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

kaitencloud_mcp-0.2.0/.github/workflows/dco.yml

@@ -0,0 +1,126 @@
+name: DCO
+
+# Every commit of a pull request must be signed off by its author, as DCO.md and
+# CONTRIBUTING.md ask: a `Signed-off-by: Name <email>` trailer naming the commit's author.
+# Require the `DCO` check on main; this workflow is the source of truth.
+#
+# pull_request_target runs the workflow as it is on main, never as a pull request edits it,
+# so a contributor cannot change the check that judges their own commits. It is safe because
+# nothing here checks out or runs the pull request's code: the check below reads the commits'
+# metadata from the API, and it needs no other file, so it can be copied to any repository.
+on:
+  pull_request_target:
+    branches: ["main"]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  dco:
+    name: DCO
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Every commit is signed off by its author
+        shell: python
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_COMMIT_COUNT: ${{ github.event.pull_request.commits }}
+        run: |
+          """Fail when a commit of the pull request is not signed off by its author (DCO 1.1)."""
+
+          import json
+          import os
+          import re
+          import subprocess
+          import sys
+          import urllib.request
+
+          SIGN_OFF = re.compile(
+              r"^Signed-off-by:[ \t]*(?P<name>.+?)[ \t]*<(?P<email>[^<>]+)>[ \t]*$", re.M
+          )
+          FIX = (
+              "Sign commits off with `git commit -s`. To fix this pull request:\n\n"
+              "    git commit --amend --signoff --no-edit    # the latest commit\n"
+              "    git rebase --signoff origin/main          # every commit of the branch\n"
+              "    git push --force-with-lease\n\n"
+              "See CONTRIBUTING.md and DCO.md."
+          )
+
+
+          def problem(commit):
+              """Why a commit, as the API lists a pull request's commits, fails; None if it passes.
+
+              A commit passes when one of its Signed-off-by trailers names its author, by name and
+              by email, ignoring case. Merge commits can contain conflict resolutions and must be
+              signed off too. A bot account certifies nothing, so it is not checked.
+              """
+              if (commit.get("author") or {}).get("type") == "Bot":
+                  return None
+              author = commit["commit"]["author"]
+              # Parse only the final trailer block, not quoted sign-offs in the message body.
+              trailers = subprocess.run(
+                  ["git", "interpret-trailers", "--parse"],
+                  input=commit["commit"]["message"], text=True, capture_output=True, check=True,
+              ).stdout
+              signoffs = [(m["name"], m["email"]) for m in SIGN_OFF.finditer(trailers)]
+              if any(
+                  name.lower() == author["name"].lower() and email.lower() == author["email"].lower()
+                  for name, email in signoffs
+              ):
+                  return None
+              expected = f"{author['name']} <{author['email']}>"
+              if not signoffs:
+                  return f"no Signed-off-by; expected {expected}"
+              found = ", ".join(f"{name} <{email}>" for name, email in signoffs)
+              return f"signed off by {found}, not by its author: expected {expected}"
+
+
+          def commits():
+              """Every commit of the pull request, page by page."""
+              api = os.environ.get("GITHUB_API_URL", "https://api.github.com")
+              repository, number = os.environ["GITHUB_REPOSITORY"], os.environ["PR_NUMBER"]
+              page = 1
+              while True:
+                  request = urllib.request.Request(
+                      f"{api}/repos/{repository}/pulls/{number}/commits?per_page=100&page={page}",
+                      headers={
+                          "Accept": "application/vnd.github+json",
+                          "Authorization": f"Bearer {os.environ['GITHUB_TOKEN']}",
+                          "X-GitHub-Api-Version": "2022-11-28",
+                      },
+                  )
+                  with urllib.request.urlopen(request, timeout=30) as response:
+                      batch = json.load(response)
+                  yield from batch
+                  if len(batch) < 100:
+                      return
+                  page += 1
+
+
+          def main():
+              # GitHub's pull-request commits endpoint is capped at 250, even with pagination.
+              expected = int(os.environ["PR_COMMIT_COUNT"])
+              if expected > 250:
+                  print("::error title=DCO::Pull requests over 250 commits must be split for DCO verification.")
+                  return 1
+              listed = list(commits())
+              if len(listed) != expected:
+                  print("::error title=DCO::Commit count changed or the API returned an incomplete list; rerun the check.")
+                  return 1
+              failed = [(commit, why) for commit in listed if (why := problem(commit)) is not None]
+              for commit, why in failed:
+                  subject = commit["commit"]["message"].splitlines()[0]
+                  print(f"::error title=DCO::{commit['sha']} {subject}: {why}")
+              if failed:
+                  print(f"\n{len(failed)} of {len(listed)} commits are not signed off by their author.")
+                  print(f"\n{FIX}")
+                  return 1
+              print(f"All {len(listed)} commits are signed off by their author.")
+              return 0
+
+
+          if __name__ == "__main__":
+              sys.exit(main())

kaitencloud_mcp-0.2.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/

kaitencloud_mcp-0.2.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-10-22
+
+The first public release of the Kaiten MCP server. It replaces the server that turned every operation
+of the Kaiten API into a tool of its own, which was never released.
+
+### Added
+
+- 31 intent-level tools over the Kaiten API, built on the official Python SDK (`kaitencloud`):
+  orientation and search, customers and instances, usage, the catalog and Licenses, feature flags,
+  releases and deployment zones, access and audit, settings, and a deletion that previews its blast
+  radius until confirmed.
+- The stdio transport, with the token in `KAITEN_API_TOKEN`, and Streamable HTTP at `/mcp`, where
+  each request brings its own `Authorization: Bearer ksh_...` header.
+- A read-only mode (`KAITEN_MCP_READ_ONLY=true` or `--read-only`) that registers the 15 read tools
+  only.
+- `GET /health`: the server's version, and whether Kaiten's gateway answers.
+- The package on PyPI, [`kaitencloud-mcp`](https://pypi.org/project/kaitencloud-mcp/), and the image
+  `ghcr.io/kaitencloud/kaiten-mcp`.
+
+[0.2.0]: https://github.com/kaitencloud/mcp/releases/tag/v0.2.0

kaitencloud_mcp-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,101 @@
+# Contributing to the Kaiten MCP server
+
+Thank you for contributing to the Kaiten MCP server.
+
+This project is licensed under the Apache License, Version 2.0.
+
+## Developer Certificate of Origin
+
+Kaiten uses the Developer Certificate of Origin 1.1 (DCO) for contributions.
+
+Every commit must include a `Signed-off-by` trailer matching the commit author.
+
+Use:
+
+```bash
+git commit -s -m "Describe your change"
+```
+
+This produces:
+
+```text
+Signed-off-by: Jane Doe <jane@example.com>
+```
+
+`git commit -s` is a **DCO sign-off**: it certifies the contribution under
+[DCO.md](./DCO.md). `git commit -S`, with a capital S, is a **cryptographic
+commit signature** made with a GPG or SSH key. They are not the same thing, and
+the sign-off is what this project requires. There is nothing to install.
+
+### Fixing a missing sign-off
+
+A check named **DCO** verifies every commit of every pull request, and it is the
+final word. If it fails, it names the commits to fix.
+
+For the latest commit:
+
+```bash
+git commit --amend --signoff --no-edit
+git push --force-with-lease
+```
+
+For several commits, sign off every commit of your branch at once:
+
+```bash
+git rebase --signoff origin/main
+git push --force-with-lease
+```
+
+## Before you open a pull request
+
+```bash
+uv sync
+uv run ruff check . && uv run ruff format --check .
+uv run pytest
+```
+
+Every Python file opens with the project's license notice, and the tests check it:
+
+```python
+# Copyright 2026 KAITEN INC
+# SPDX-License-Identifier: Apache-2.0
+```
+
+## Contribution rules
+
+Please:
+
+- keep pull requests focused;
+- add or update tests when behavior changes;
+- update documentation when relevant;
+- do not include secrets, customer data, or confidential information;
+- do not submit code or assets that you do not have the right to contribute;
+- preserve required third-party license and attribution notices.
+
+Accepted contributions are contributed under Apache-2.0.
+
+## Releasing
+
+Releases are made by maintainers. A merge to `main` publishes the container image
+`ghcr.io/kaitencloud/kaiten-mcp:main`. To release a version, set `version` in
+`pyproject.toml`, merge it, and push the tag:
+
+```bash
+git tag v0.3.0
+git push origin v0.3.0
+```
+
+CI then publishes the image as `:0.3.0` and `:0.3`, and the Python package to PyPI as
+[`kaitencloud-mcp`](https://pypi.org/project/kaitencloud-mcp/). The `publish` job refuses a
+tag that does not match `pyproject.toml`'s version.
+
+PyPI publishing uses trusted publishing, so no token is stored: the project's publisher on
+PyPI must name this repository, the `CI` workflow (`ci.yml`) and the `pypi` environment.
+The image's package is created by the first publish and takes the repository's visibility,
+so the repository must be public before then.
+
+## Security
+
+Do not report unpatched vulnerabilities in public issues.
+
+See [SECURITY.md](./SECURITY.md).

kaitencloud_mcp-0.2.0/DCO.md

@@ -0,0 +1,37 @@
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+1 Letterman Drive
+Suite D4700
+San Francisco, CA, 94129
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.

kaitencloud_mcp-0.2.0/Dockerfile

@@ -0,0 +1,30 @@
+# Kaiten MCP server.
+#
+#   docker run -p 8000:8000 -e KAITEN_API_BASE_URL=https://kaiten.example.com/api ghcr.io/kaitencloud/kaiten-mcp
+#       Streamable HTTP at /mcp; each request authenticates with its own bearer token.
+#   docker run -i --rm -e KAITEN_API_BASE_URL=... -e KAITEN_API_TOKEN=ksh_... ghcr.io/kaitencloud/kaiten-mcp stdio
+#       stdio, for a local client that spawns the server.
+
+ARG PYTHON_BASE=3.13-slim
+
+FROM python:$PYTHON_BASE AS builder
+COPY --from=ghcr.io/astral-sh/uv:0.9.1 /uv /uvx /bin/
+ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy
+WORKDIR /app
+# Dependencies first, so a source change does not reinstall them.
+COPY pyproject.toml uv.lock ./
+RUN uv sync --locked --no-dev --no-install-project
+COPY README.md LICENSE NOTICE ./
+COPY src ./src
+RUN uv sync --locked --no-dev --no-editable
+
+FROM python:$PYTHON_BASE
+WORKDIR /app
+COPY --from=builder --chown=1000:1000 /app/.venv /app/.venv
+USER 1000
+ENV PATH="/app/.venv/bin:$PATH" PYTHONUNBUFFERED=1 MCP_PORT=8000
+EXPOSE 8000
+HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
+    CMD python -c "import os, urllib.request; urllib.request.urlopen(f'http://127.0.0.1:{os.environ[\"MCP_PORT\"]}/health', timeout=5)" || exit 1
+ENTRYPOINT ["kaiten-mcp"]
+CMD ["http"]