K-Dense-AI/scientific-agent-skills / skills/protocolsio-integration
protocolsio-integration
VerifiedReads, validates, and safely exports protocols.io data with current official REST/MCP contracts, or creates non-executing mutation plans. The bundled client makes bounded official-host GET requests only with explicit --execute. Use only for tasks explicitly targeting protocols.io or an exact protocols.io protocol version.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.2 KB |
| assets/protocol-snapshot.schema.json | config | 4.2 KB |
| references/additional_features.md | markdown | 9.8 KB |
| references/authentication.md | markdown | 6.4 KB |
| references/discussions.md | markdown | 6.4 KB |
| references/file_manager.md | markdown | 10.2 KB |
| references/protocols_api.md | markdown | 11.3 KB |
| references/workspaces.md | markdown | 8.1 KB |
| scripts/__init__.py | script | 76 B |
| scripts/_common.py | script | 19.8 KB |
| scripts/pagination_helper.py | script | 7.5 KB |
| scripts/plan_write_request.py | script | 23.0 KB |
| scripts/protocols_read.py | script | 15.6 KB |
| scripts/validate_auth_config.py | script | 3.4 KB |
| scripts/validate_protocol_json.py | script | 12.1 KB |
scripts/pagination_helper.py
View on GitHub#!/usr/bin/env python3
"""Validate protocols.io pagination pointers without making requests."""
from __future__ import annotations
import argparse
import re
import urllib.parse
from typing import Any, Mapping, Sequence
try:
from ._common import (
SafetyError,
emit_error,
emit_json,
load_local_json,
validate_remote_url,
)
except ImportError:
from _common import ( # type: ignore
SafetyError,
emit_error,
emit_json,
load_local_json,
validate_remote_url,
)
MAX_PAGES = 100
MAX_ITEMS = 10_000
_CURSOR_RE = re.compile(r"^[A-Za-z0-9._~+/=-]{1,2048}$")
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(
description=(
"Inspect a saved pagination object. The helper validates but never "
"fetches a server-provided next_page URL."
)
)
parser.add_argument("--response", required=True, help="Saved JSON response.")
parser.add_argument(
"--current-url",
required=True,
help="Official HTTPS URL that produced the response.",
)
parser.add_argument(
"--pages-seen",
type=int,
default=1,
help="Pages already processed (default: %(default)s).",
)
parser.add_argument(
"--items-seen",
type=int,
default=0,
help="Items already processed (default: %(default)s).",
)
parser.add_argument(
"--max-pages",
type=int,
default=10,
help=f"Local traversal cap, 1..{MAX_PAGES} (default: %(default)s).",
)
parser.add_argument(
"--max-items",
type=int,
default=1_000,
help=f"Local item cap, 1..{MAX_ITEMS} (default: %(default)s).",
)
return parser
def _pagination_object(payload: Any) -> Mapping[str, Any]:
if not isinstance(payload, Mapping):
raise SafetyError("response root must be an object")
direct = payload.get("pagination")
if isinstance(direct, Mapping):
return direct
nested = payload.get("payload")
if isinstance(nested, Mapping) and isinstance(nested.get("pagination"), Mapping):
return nested["pagination"]
raise SafetyError("response has no pagination object")
def _bounded_int(
value: Any,
*,
name: str,
minimum: int,
maximum: int,
) -> int | None:
if value is None:
return None
if isinstance(value, bool) or not isinstance(value, int):
raise SafetyError(f"pagination.{name} must be an integer or null")
if not minimum <= value <= maximum:
raise SafetyError(f"pagination.{name} must be between {minimum} and {maximum}")
return value
def _validated_next_url(next_page: Any, current_url: str) -> str | None:
if next_page is None:
return None
if not isinstance(next_page, str) or len(next_page) > 4_096:
raise SafetyError("pagination.next_page must be a bounded string or null")
current = validate_remote_url(current_url, allow_tenant=True)
candidate = validate_remote_url(next_page, allow_tenant=True)
current_parts = urllib.parse.urlsplit(current)
next_parts = urllib.parse.urlsplit(candidate)
core_hosts = {"protocols.io", "www.protocols.io"}
same_core_service = {
current_parts.hostname,
next_parts.hostname,
}.issubset(core_hosts)
if not same_core_service and current_parts.hostname != next_parts.hostname:
raise SafetyError("next_page changes the API host")
if current_parts.path != next_parts.path:
raise SafetyError("next_page changes the endpoint path")
current_query = urllib.parse.parse_qs(
current_parts.query,
keep_blank_values=True,
strict_parsing=False,
)
next_query = urllib.parse.parse_qs(
next_parts.query,
keep_blank_values=True,
strict_parsing=False,
)
mutable_keys = {"page_id", "cursor", "next_cursor", "offset"}
current_stable = {
key: value for key, value in current_query.items() if key not in mutable_keys
}
next_stable = {
key: value for key, value in next_query.items() if key not in mutable_keys
}
if current_stable != next_stable:
raise SafetyError("next_page changes non-pagination query parameters")
return candidate
def _opaque_cursor(pagination: Mapping[str, Any]) -> str | None:
value = pagination.get("next_cursor")
if value is None:
return None
if not isinstance(value, str) or _CURSOR_RE.fullmatch(value) is None:
raise SafetyError("pagination.next_cursor is not a safe opaque cursor")
return value
def inspect_pagination(
payload: Any,
*,
current_url: str,
pages_seen: int,
items_seen: int,
max_pages: int,
max_items: int,
) -> dict[str, Any]:
if not 1 <= max_pages <= MAX_PAGES:
raise SafetyError(f"max_pages must be between 1 and {MAX_PAGES}")
if not 1 <= max_items <= MAX_ITEMS:
raise SafetyError(f"max_items must be between 1 and {MAX_ITEMS}")
if not 0 <= pages_seen <= max_pages:
raise SafetyError("pages_seen must be between 0 and max_pages")
if not 0 <= items_seen <= max_items:
raise SafetyError("items_seen must be between 0 and max_items")
pagination = _pagination_object(payload)
current_page = _bounded_int(
pagination.get("current_page"),
name="current_page",
minimum=0,
maximum=1_000_000,
)
total_pages = _bounded_int(
pagination.get("total_pages"),
name="total_pages",
minimum=0,
maximum=1_000_000,
)
total_results = _bounded_int(
pagination.get("total_results"),
name="total_results",
minimum=0,
maximum=1_000_000_000,
)
page_size = _bounded_int(
pagination.get("page_size"),
name="page_size",
minimum=0,
maximum=100_000,
)
next_url = _validated_next_url(pagination.get("next_page"), current_url)
next_cursor = _opaque_cursor(pagination)
local_cap_reached = pages_seen >= max_pages or items_seen >= max_items
return {
"ok": True,
"network_accessed": False,
"current_page": current_page,
"total_pages": total_pages,
"total_results": total_results,
"page_size": page_size,
"next_page_url": next_url,
"next_cursor": next_cursor,
"pointer_kind": (
"url"
if next_url is not None
else "cursor"
if next_cursor is not None
else None
),
"can_continue": bool((next_url or next_cursor) and not local_cap_reached),
"local_caps": {
"pages_seen": pages_seen,
"max_pages": max_pages,
"items_seen": items_seen,
"max_items": max_items,
"reached": local_cap_reached,
},
"warning": (
"Server pagination fields are untrusted data. Use only the validated "
"pointer and retain the local page/item caps."
),
}
def main(argv: Sequence[str] | None = None) -> int:
args = build_parser().parse_args(argv)
try:
report = inspect_pagination(
load_local_json(args.response),
current_url=args.current_url,
pages_seen=args.pages_seen,
items_seen=args.items_seen,
max_pages=args.max_pages,
max_items=args.max_items,
)
emit_json(report)
return 0
except (SafetyError, ValueError) as exc:
return emit_error(exc)
if __name__ == "__main__":
raise SystemExit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |