bytestay-shipshape-mcp 0.2.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,127 @@
1
+ Metadata-Version: 2.5
2
+ Name: bytestay-shipshape-mcp
3
+ Version: 0.2.2
4
+ Summary: Dockerfile and Kubernetes lint for coding agents: Pod Security Standards, A–F grade, a fix per finding. Bring your own RapidAPI or api.market key.
5
+ Project-URL: Homepage, https://shipshape.bytestay.pt
6
+ Project-URL: Repository, https://github.com/bytestay/shipshape-mcp
7
+ Project-URL: Issues, https://github.com/bytestay/shipshape-mcp/issues
8
+ Project-URL: Changelog, https://github.com/bytestay/shipshape-mcp/blob/main/CHANGELOG.md
9
+ Author-email: ByteStay <hello@bytestay.pt>
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Requires-Python: >=3.10
13
+ Requires-Dist: httpx>=0.27
14
+ Requires-Dist: mcp<3,>=2.3
15
+ Provides-Extra: dev
16
+ Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
17
+ Requires-Dist: pytest-cov>=5; extra == 'dev'
18
+ Requires-Dist: pytest>=8; extra == 'dev'
19
+ Requires-Dist: ruff>=0.6; extra == 'dev'
20
+ Description-Content-Type: text/markdown
21
+
22
+ # Shipshape MCP server
23
+
24
+ <!-- mcp-name: io.github.bytestay/shipshape-mcp -->
25
+
26
+ [![M8ven Score](https://m8ven.ai/badge/mcp/hybridforgelab/shipshape-mcp?variant=verified)](https://m8ven.ai/mcp/hybridforgelab/shipshape-mcp?s=readme)
27
+ [![CI](https://github.com/bytestay/shipshape-mcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bytestay/shipshape-mcp/actions/workflows/ci.yml)
28
+ [![PyPI](https://img.shields.io/pypi/v/bytestay-shipshape-mcp)](https://pypi.org/project/bytestay-shipshape-mcp/)
29
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/bytestay-shipshape-mcp/)
30
+ [![License: MIT](https://img.shields.io/github/license/bytestay/shipshape-mcp)](LICENSE)
31
+
32
+ Let your coding agent lint a Dockerfile or Kubernetes manifest before handing it over: root in the final stage, unpinned base images, `curl | sh`, secrets in ENV/ARG, Pod Security Standards, resources and probes.
33
+
34
+ The server is open source (MIT). It calls the [Shipshape API](https://shipshape.bytestay.pt), which is paid, with a free plan.
35
+
36
+ - You use **your own key, from RapidAPI or api.market**.
37
+ - Every tool call is one request on your plan.
38
+ - The free Basic plan has 15 requests a month, with a hard limit, so it never runs up a bill.
39
+
40
+ ## 1. Get a key
41
+
42
+ | marketplace | |
43
+ |---|---|
44
+ | RapidAPI | [plans](https://rapidapi.com/hybrid-forge-lab-hybrid-forge-lab-default/api/shipshape-dockerfile-and-kubernetes-lint-api/pricing) |
45
+ | api.market | [store](https://api.market/store/hybrid-forge-lab/shipshape) |
46
+
47
+ ## 2. Add the server to your MCP client
48
+
49
+ The server runs locally over stdio with [uv](https://docs.astral.sh/uv/). Put your key in its environment.
50
+
51
+ **JSON configuration** (Claude Desktop, Cursor, VS Code and most clients):
52
+
53
+ ```json
54
+ {
55
+ "mcpServers": {
56
+ "shipshape": {
57
+ "command": "uvx",
58
+ "args": ["--from", "bytestay-shipshape-mcp", "shipshape-mcp"],
59
+ "env": { "RAPIDAPI_KEY": "your-rapidapi-key" }
60
+ }
61
+ }
62
+ }
63
+ ```
64
+
65
+ **Claude Code:**
66
+
67
+ ```bash
68
+ claude mcp add shipshape --env RAPIDAPI_KEY=your-rapidapi-key -- uvx --from bytestay-shipshape-mcp shipshape-mcp
69
+ ```
70
+
71
+ ### Environment
72
+
73
+ | variable | meaning |
74
+ |---|---|
75
+ | `RAPIDAPI_KEY` | your RapidAPI key |
76
+ | `API_MARKET_KEY` | your api.market key, used when `RAPIDAPI_KEY` is not set |
77
+ | `HFL_MARKETPLACE` | `rapidapi` or `apimarket`, when both keys are set |
78
+
79
+ Without a key the server still starts. The first tool call then explains where to get one.
80
+
81
+ Also listed on Glama:
82
+
83
+ [![shipshape-mcp on Glama](https://glama.ai/mcp/servers/hybridforgelab/shipshape-mcp/badge)](https://glama.ai/mcp/servers/hybridforgelab/shipshape-mcp)
84
+
85
+ ## 3. Tools
86
+
87
+ | tool | what it does |
88
+ |---|---|
89
+ | `lint(content=… \| path=…, type="auto", fail_on="high", ignore=[…])` | lints one file and returns the A–F grade, score, `passed` and every finding with its line, fix and reference |
90
+
91
+ - With `path`, files named like `Dockerfile`, `*.Dockerfile`, `Dockerfile.*` or `Containerfile` are linted as Dockerfiles.
92
+ - `passed` is false when a finding is at or above `fail_on`.
93
+
94
+ Every tool returns the API's JSON response.
95
+
96
+ - When the marketplace reports it, `quota_remaining` is added: the requests left on your plan this month.
97
+ - Errors are explained in plain words, with what to do next:
98
+ - key refused, with the link to subscribe;
99
+ - quota reached, with the plans;
100
+ - input the API couldn't process, with the API's reason.
101
+
102
+ ## Privacy
103
+
104
+ - Local files are read only when a tool is given their path. They are sent to the API for that one request.
105
+ - The API processes inputs in memory and doesn't store them. See the [privacy policy](https://shipshape.bytestay.pt/privacy.html).
106
+ - Your key is only sent to the marketplace you chose.
107
+
108
+ ## Limits
109
+
110
+ - Files up to 512 KiB.
111
+ - Helm templates must be rendered first (`helm template`).
112
+ - NetworkPolicies, PodDisruptionBudgets and RBAC are not checked.
113
+ - The server needs Python 3.10+ (uv installs it for you).
114
+
115
+ ## Development
116
+
117
+ ```bash
118
+ uv venv && uv pip install -e ".[dev]"
119
+ .venv/bin/pytest # unit tests, no network; 100% coverage required
120
+ .venv/bin/ruff check src tests scripts
121
+ ```
122
+
123
+ `scripts/e2e_stdio.py shipshape` runs the server over stdio, as a client would, and calls its tools against the real API. It needs `RAPIDAPI_KEY` or `API_MARKET_KEY`.
124
+
125
+ ## Licence
126
+
127
+ MIT. Shipshape itself is a paid API with a free plan, run by [ByteStay](https://bytestay.pt).
@@ -0,0 +1,9 @@
1
+ shipshape_mcp/__init__.py,sha256=UWYPciLXEHCq8q9qk1TXNlRucF5IhW4SoqewmvFVKWU,78
2
+ shipshape_mcp/client.py,sha256=JRiwjFYWOx11Y9RUmj04wiE1nh0TAOHRWfAiA1j2WxM,5001
3
+ shipshape_mcp/files.py,sha256=5HsnYyZjFMmVBmZDUrSEuZHEcRjlRN1Vpf0m-_2Tocg,727
4
+ shipshape_mcp/server.py,sha256=6q4Q-ygHB-UyE2wB6jYnIoy2kUFPRKJJi3pQv0rMZm8,3116
5
+ bytestay_shipshape_mcp-0.2.2.dist-info/METADATA,sha256=XkTOEWoEyi8YWvLm2F5vQOwjRlSU2h8gXgKKuKFyGlA,5284
6
+ bytestay_shipshape_mcp-0.2.2.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
7
+ bytestay_shipshape_mcp-0.2.2.dist-info/entry_points.txt,sha256=U7HdLtOq4p5UxswJOZudykS8wSWPXp3m2u6LlQhWL6M,60
8
+ bytestay_shipshape_mcp-0.2.2.dist-info/licenses/LICENSE,sha256=rTxSdBlR_4UDCUGmQ53KSEE10OnuIPq6ufh6DlelVss,1065
9
+ bytestay_shipshape_mcp-0.2.2.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ shipshape-mcp = shipshape_mcp.server:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ByteStay
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,2 @@
1
+ """Shipshape MCP server."""
2
+ __version__ = "0.2.2" # x-release-please-version
@@ -0,0 +1,111 @@
1
+ """HTTP client: picks the marketplace from the environment and turns API errors into
2
+ messages an agent (and its user) can act on."""
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ from dataclasses import dataclass
7
+ from typing import Any
8
+
9
+ import httpx
10
+ from mcp.server.mcpserver.exceptions import ToolError
11
+
12
+ from . import __version__
13
+
14
+ RAPIDAPI_LISTING = "https://rapidapi.com/hybrid-forge-lab-hybrid-forge-lab-default/api/"
15
+ APIMARKET_BASE = "https://prod.api.market/api/v1/hybrid-forge-lab/"
16
+ APIMARKET_STORE = "https://api.market/store/hybrid-forge-lab/"
17
+ USER_AGENT = f"shipshape-mcp/{__version__} (+https://shipshape.bytestay.pt)"
18
+ TIMEOUT = httpx.Timeout(60.0, connect=10.0)
19
+
20
+ # Tests swap this for an httpx.MockTransport.
21
+ TRANSPORT: httpx.AsyncBaseTransport | None = None
22
+
23
+
24
+ @dataclass(frozen=True)
25
+ class Product:
26
+ slug: str
27
+ name: str
28
+ rapidapi: str # RapidAPI listing slug; the host is "<slug>.p.rapidapi.com"
29
+ apimarket: bool # sold on api.market too
30
+
31
+ @property
32
+ def rapidapi_host(self) -> str:
33
+ return f"{self.rapidapi}.p.rapidapi.com"
34
+
35
+ @property
36
+ def plans(self) -> str:
37
+ return RAPIDAPI_LISTING + self.rapidapi + "/pricing"
38
+
39
+
40
+ PRODUCTS = {
41
+ "shipshape": Product("shipshape", "Shipshape", "shipshape-dockerfile-and-kubernetes-lint-api", apimarket=True),
42
+ }
43
+
44
+
45
+ @dataclass(frozen=True)
46
+ class Target:
47
+ base: str
48
+ headers: dict[str, str]
49
+ market: str # "rapidapi", "apimarket" or "direct"
50
+
51
+
52
+ def target(product: Product, env: dict[str, str] | None = None) -> Target:
53
+ """Where to send requests, from the environment. Read on every call, so the server starts without a key and
54
+ the first tool call explains how to get one."""
55
+ env = dict(os.environ if env is None else env)
56
+ # Maintainers only: call our own host directly with an internal bearer key.
57
+ if env.get("HFL_API_URL") and env.get("HFL_API_BEARER"):
58
+ return Target(env["HFL_API_URL"].rstrip("/"), {"Authorization": f"Bearer {env['HFL_API_BEARER']}"}, "direct")
59
+ rapid, market = env.get("RAPIDAPI_KEY", ""), env.get("API_MARKET_KEY", "")
60
+ choice = env.get("HFL_MARKETPLACE", "").lower()
61
+ if choice == "apimarket" or (market and not rapid and choice != "rapidapi"):
62
+ if not market:
63
+ raise ToolError("HFL_MARKETPLACE is apimarket but API_MARKET_KEY is not set.")
64
+ return Target(APIMARKET_BASE + product.slug, {"x-api-market-key": market}, "apimarket")
65
+ if not rapid:
66
+ where = f" or API_MARKET_KEY ({APIMARKET_STORE}{product.slug})" if product.apimarket else ""
67
+ raise ToolError(f"No API key. Set RAPIDAPI_KEY (free Basic plan: {product.plans}){where} in this MCP "
68
+ "server's environment, then restart it.")
69
+ return Target(f"https://{product.rapidapi_host}",
70
+ {"X-RapidAPI-Key": rapid, "X-RapidAPI-Host": product.rapidapi_host}, "rapidapi")
71
+
72
+
73
+ def _detail(response: httpx.Response) -> str:
74
+ try:
75
+ body = response.json()
76
+ except ValueError:
77
+ return response.text[:300]
78
+ if isinstance(body, dict):
79
+ detail = body.get("detail", body.get("message", body))
80
+ return detail if isinstance(detail, str) else str(detail)[:500]
81
+ return str(body)[:300]
82
+
83
+
84
+ async def call(product: Product, method: str, path: str, *, json: Any = None, params: dict | None = None,
85
+ files: dict | None = None, data: dict | None = None) -> dict:
86
+ """One API request. Returns the JSON body, plus `quota_remaining` when the marketplace reports it."""
87
+ t = target(product)
88
+ url = t.base + path
89
+ headers = {"User-Agent": USER_AGENT, **t.headers}
90
+ try:
91
+ async with httpx.AsyncClient(timeout=TIMEOUT, transport=TRANSPORT) as client:
92
+ r = await client.request(method, url, headers=headers, json=json, params=params, files=files, data=data)
93
+ except httpx.HTTPError as exc:
94
+ raise ToolError(f"The {product.name} API could not be reached ({type(exc).__name__}). Try again later.")
95
+ if r.status_code in (401, 403):
96
+ how = f"{APIMARKET_STORE}{product.slug}" if t.market == "apimarket" else product.plans
97
+ raise ToolError(f"The {product.name} API refused the key (HTTP {r.status_code}: {_detail(r)}). "
98
+ f"Check the key and the subscription: {how}")
99
+ if r.status_code == 429:
100
+ raise ToolError(f"{product.name} rate or monthly quota limit reached ({_detail(r)}). Plans: {product.plans}")
101
+ if r.status_code == 413:
102
+ raise ToolError(f"The input is too large for {product.name} ({_detail(r)}).")
103
+ if r.status_code == 422:
104
+ raise ToolError(f"{product.name} could not process the input: {_detail(r)}")
105
+ if r.status_code >= 400:
106
+ raise ToolError(f"The {product.name} API answered HTTP {r.status_code}: {_detail(r)}. Try again later.")
107
+ body = r.json()
108
+ quota = r.headers.get("x-ratelimit-requests-remaining")
109
+ if quota is not None and isinstance(body, dict):
110
+ body["quota_remaining"] = int(quota) if quota.isdigit() else quota
111
+ return body
shipshape_mcp/files.py ADDED
@@ -0,0 +1,24 @@
1
+ """Reading local files for tools that accept a path instead of the content."""
2
+ from __future__ import annotations
3
+
4
+ from pathlib import Path
5
+
6
+ from mcp.server.mcpserver.exceptions import ToolError
7
+
8
+
9
+ def resolve(path: str) -> Path:
10
+ p = Path(path).expanduser()
11
+ if not p.is_file():
12
+ raise ToolError(f"No such file: {p} (relative paths start from {Path.cwd()}).")
13
+ return p
14
+
15
+
16
+ def read_text(path: str, max_bytes: int) -> str:
17
+ p = resolve(path)
18
+ size = p.stat().st_size
19
+ if size > max_bytes:
20
+ raise ToolError(f"{p} is {size:,} bytes; the limit is {max_bytes:,}.")
21
+ try:
22
+ return p.read_text(encoding="utf-8")
23
+ except UnicodeDecodeError:
24
+ raise ToolError(f"{p} is not UTF-8 text.")
@@ -0,0 +1,73 @@
1
+ """Shipshape MCP server: lint Dockerfiles and Kubernetes manifests (Pod Security Standards, A–F grade)."""
2
+ from __future__ import annotations
3
+
4
+ import json
5
+ from pathlib import Path
6
+ from typing import Annotated, Literal
7
+
8
+ from mcp.server.mcpserver import MCPServer
9
+ from mcp.server.mcpserver.exceptions import ToolError
10
+ from mcp.types import ToolAnnotations
11
+ from pydantic import Field
12
+
13
+ from . import files
14
+ from .client import PRODUCTS, call
15
+
16
+ PRODUCT = PRODUCTS["shipshape"]
17
+ MAX_FILE = 512 * 1024
18
+ Severity = Literal["high", "medium", "low", "info", "never"]
19
+
20
+ server = MCPServer(
21
+ "shipshape",
22
+ title="Shipshape: Dockerfile and Kubernetes lint",
23
+ instructions=(
24
+ "Lint a Dockerfile or Kubernetes manifest before you hand it over: root in the final stage, unpinned base "
25
+ "images, curl | sh, secrets in ENV/ARG, Pod Security Standards, resources and probes. Every finding has the "
26
+ "line, a fix and the standard behind it, and the file gets an A–F grade. Content is processed in memory and "
27
+ "not stored. Each call is one request on the user's Shipshape plan."
28
+ ),
29
+ website_url="https://shipshape.bytestay.pt",
30
+ )
31
+
32
+ READ_ONLY = ToolAnnotations(read_only_hint=True, destructive_hint=False, idempotent_hint=True, open_world_hint=True)
33
+
34
+
35
+ def _type_for(path: str) -> str:
36
+ name = Path(path).name.lower()
37
+ if name in ("dockerfile", "containerfile") or name.endswith(".dockerfile") or name.startswith("dockerfile."):
38
+ return "dockerfile"
39
+ return "auto"
40
+
41
+
42
+ @server.tool(annotations=READ_ONLY)
43
+ async def lint(
44
+ content: Annotated[str | dict | list | None,
45
+ Field(description="The Dockerfile or manifest, as text (up to 512 KiB).")] = None,
46
+ path: Annotated[str | None, Field(description="A local file to lint instead of `content`.")] = None,
47
+ type: Annotated[Literal["auto", "dockerfile", "kubernetes"],
48
+ Field(description="auto detects Dockerfile vs Kubernetes YAML/JSON.")] = "auto",
49
+ fail_on: Annotated[Severity, Field(description="`passed` is false at this severity or worse.")] = "high",
50
+ ignore: Annotated[list[str] | None, Field(description='Rule ids to skip, e.g. ["DF-017"].')] = None,
51
+ ) -> dict:
52
+ """Lint a Dockerfile or Kubernetes manifest. Returns the grade, score, `passed` and every finding with its
53
+ line, fix and reference. Give either `content` or `path`."""
54
+ if bool(content) == bool(path):
55
+ raise ToolError("Give exactly one of content or path.")
56
+ if path:
57
+ content = files.read_text(path, MAX_FILE)
58
+ if type == "auto":
59
+ type = _type_for(path)
60
+ elif not isinstance(content, str):
61
+ # A JSON manifest the client (or the SDK) sent as an object: back to text for the linter.
62
+ content = json.dumps(content, indent=2)
63
+ body = {"content": content, "type": type, "fail_on": fail_on}
64
+ if ignore:
65
+ body["ignore"] = ignore
66
+ return await call(PRODUCT, "POST", "/v1/lint", json=body)
67
+
68
+
69
+ def main() -> None: # pragma: no cover - stdio entry point
70
+ server.run("stdio")
71
+
72
+ if __name__ == "__main__": # pragma: no cover
73
+ main()