Developer guide

Recipes and CI

Ready-made ways to run MCPatch from a terminal, a script or a scheduled job.

#A shell script

Prints the verdict and each step that needs attention, links the report, and exits non-zero when the connector fails. It needs curl and jq.

mcpatch-check.sh
#!/usr/bin/env bash
set -euo pipefail

url="${1:?usage: mcpatch-check.sh https://host/mcp}"
api="https://mcpatch.monster13liar.xyz"
tmp="$(mktemp)"

code=$(curl -sS -o "$tmp" -w '%{http_code}' -X POST "$api/api/check" \
  -H 'content-type: application/json' \
  -d "$(jq -n --arg u "$url" '{url: $u}')")

if [ "$code" != "200" ]; then
  echo "MCPatch answered $code: $(cat "$tmp")" >&2
  exit 2
fi

jq -r '.verdict.headline' "$tmp"
jq -r '.steps[] | select(.status == "fail" or .status == "warn")
  | "\(.status | ascii_upcase)  \(.title)\n    \(.summary)\n    fix: \(.fix)"' "$tmp"
echo "Report: $api/r/$(jq -r '.id' "$tmp")"

[ "$(jq -r '.verdict.status' "$tmp")" != "fail" ]

Exit codes: 0 for a pass or a warning, 1 when a step fails, 2 when MCPatch itself could not be reached or refused the request (for example the free limit).

#Node.js

check.mjs
const url = process.argv[2]
const res = await fetch('https://mcpatch.monster13liar.xyz/api/check', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ url }),
})
if (!res.ok) throw new Error(`MCPatch answered ${res.status}: ${await res.text()}`)

const r = await res.json()
console.log(r.verdict.headline)
for (const s of r.steps.filter((x) => x.status === 'fail' || x.status === 'warn')) {
  console.log(`${s.status.toUpperCase()}  ${s.title}\n  ${s.summary}\n  fix: ${s.fix}`)
}
console.log(`Report: https://mcpatch.monster13liar.xyz/r/${r.id}`)
process.exit(r.verdict.status === 'fail' ? 1 : 0)

#A scheduled GitHub Actions job

Runs the script once a day and on demand. The job fails when the connector fails, so GitHub emails you.

.github/workflows/mcp-check.yml
name: MCP connector check
on:
  workflow_dispatch:
  schedule:
    - cron: '0 7 * * *'

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: bash scripts/mcpatch-check.sh https://mcp.example.com/mcp

#After a deploy

Run the script as the last step of your deploy pipeline, after the new version is live. A failing step tells you the deploy broke the connection before your users find out. Because a deploy can change your tools, the same run also reports tool changessince the previous check.

#Servers behind a token

Add token (and headerName if it is not Authorization) to the request body. Keep the token in a secret of your CI system, never in the repository. It is sent over HTTPS, used for that one run and not stored.

bash
jq -n --arg u "$URL" --arg t "$MCP_TOKEN" '{url: $u, token: $t}' | curl -sS -X POST "$api/api/check" \
  -H 'content-type: application/json' -d @-