sergebulaev/x-skills / .codex-marketplace/x-skills
x-marketing
VerifiedPlan, draft, audit, and publish posts and threads for X (Twitter). Use when the user wants to write a single tweet or an auto-numbered thread, build a long-form tweetstorm, remove AI tells from a draft, reverse-engineer the hook from a viral tweet, draft a reply or quote tweet, or plan a week of X content. Tweets and threads publish via the Publora API, which auto-splits long content into a numbered thread. User provides notes or a tweet URL, the skill drafts, the user approves, then it publishes.
scripts/check_mcp_mapping.py
View on GitHub#!/usr/bin/env python3
"""The documented MCP read path must match the library it replaces.
A skill reading through the Apify connector gets the actor's raw output and has
only `references/mcp-read-layer.md` to turn it into the records every other
skill expects. If that document drifts from the client, the connector path
starts producing a second, subtly different contract: same field names, one of
them silently absent or fed from the wrong place. Nothing at runtime would
notice, because both shapes are plain dicts.
So it is checked rather than trusted. Three things must agree with the code:
the actor ids, every input key the client sends, and every flat field the
normalizer produces.
Run from the repo root:
python3 scripts/check_mcp_mapping.py
"""
import ast
import importlib
import pathlib
import re
import sys
ROOT = pathlib.Path(__file__).resolve().parent.parent
sys.path.insert(0, str(ROOT))
DOC = ROOT / "references" / "mcp-read-layer.md"
CLIENT = ROOT / "lib" / "apify_client.py"
#: (module, attribute) of every function that flattens an actor row.
NORMALIZERS = (("lib.apify_client", "_tweet"),)
#: Input keys that are near-misses, documented so nobody sends them again.
WARN_ABOUT = ("sort",)
def mentions(doc: str, name: str, extra: str = "") -> bool:
"""A name counts as documented only as a whole word.
`name not in doc` is satisfied by any longer name containing it, so
queryTypeX would silently pass for queryType. Actor ids need `extra` to
cover the characters they are allowed to contain, or a rename to
actor-name-v2 passes as actor-name.
"""
char = "A-Za-z0-9_" + extra
return re.search(rf"(?<![{char}]){re.escape(name)}(?![{char}])", doc) is not None
def actor_ids(tree: ast.AST) -> set[str]:
"""Every string constant in the client that looks like an actor id."""
found = set()
for node in ast.walk(tree):
if isinstance(node, ast.Constant) and isinstance(node.value, str):
if re.fullmatch(r"[A-Za-z0-9_.-]+~[A-Za-z0-9_.-]+", node.value):
found.add(node.value.replace("~", "/"))
return found
def payload_keys(tree: ast.AST) -> set[str]:
"""Keys of every literal dict passed to the actor-running helper."""
keys = set()
for node in ast.walk(tree):
if not isinstance(node, ast.Call):
continue
name = getattr(node.func, "attr", getattr(node.func, "id", ""))
if name not in ("_run", "_run_sync"):
continue
for arg in node.args:
if isinstance(arg, ast.Dict):
keys |= {k.value for k in arg.keys
if isinstance(k, ast.Constant) and isinstance(k.value, str)}
return keys
def per_normalizer_fields() -> list[tuple[str, set[str]]]:
out = []
for module_name, attr in NORMALIZERS:
module = importlib.import_module(module_name)
produced = getattr(module, attr)({})
out.append((attr, {k for k in produced if not k.startswith("_")}))
return out
def flat_fields() -> set[str]:
fields = set()
for _, produced in per_normalizer_fields():
fields |= produced
return fields
def table_for(doc: str, attr: str) -> set[str] | None:
"""Fields of the mapping table that the prose attributes to `attr`.
Matching by name is what makes the check precise: when one shape's fields
are a superset of another's, a "some table covers it" test passes even
after a row is deleted from the right one. Each table must be introduced
with the normalizer it belongs to, e.g. "what `_profile_post` produces".
"""
marker = re.search(r"`" + re.escape(attr) + r"`", doc)
if not marker:
return None
after = doc[marker.end():]
if "| Flat field |" not in after:
return None
body = after.split("| Flat field |", 1)[1].split(chr(10) * 2, 1)[0]
return set(re.findall(r"^\| `([a-z_][a-z0-9_]*)` \|", body, re.M))
def mapping_tables(doc: str) -> list[set[str]]:
"""Field sets of every `| Flat field |` table in the document.
Checked per table, not across the whole file: with two shapes that share
field names, dropping a row from one table still leaves the name present
somewhere else, and a whole-document check would pass.
"""
tables = []
for chunk in doc.split("| Flat field |")[1:]:
body = chunk.split(chr(10) * 2, 1)[0] # to the blank line after the table
tables.append(set(re.findall(r"^\| `([a-z_][a-z0-9_]*)` \|", body, re.M)))
return tables
def main() -> int:
problems = []
if not DOC.is_file():
print(f"{DOC.relative_to(ROOT)} is missing; the connector path is undocumented.")
return 1
doc = DOC.read_text(encoding="utf-8")
tree = ast.parse(CLIENT.read_text(encoding="utf-8"))
for actor in sorted(actor_ids(tree)):
if not mentions(doc, actor, extra=r"./\-"):
problems.append(f"actor {actor} is called by the client and absent from the doc")
keys = payload_keys(tree)
if not keys:
problems.append("no literal actor payload found in the client: has it changed shape?")
for key in sorted(keys):
if not mentions(doc, key):
problems.append(f"input key `{key}` is sent by the client and undocumented")
for key in sorted(WARN_ABOUT):
if not mentions(doc, key):
problems.append(f"the doc does not warn about `{key}`, which is ignored and bills a run")
fields = flat_fields()
if len(fields) < 5:
problems.append("the normalizer produced almost nothing: wrong attribute?")
for field in sorted(fields):
if not re.search(r"`" + re.escape(field) + r"`", doc):
problems.append(f"flat field `{field}` is produced by the client and undocumented")
tables = mapping_tables(doc)
known = set().union(*tables) if tables else set()
for field in sorted(known - fields):
problems.append(f"a mapping table documents `{field}`, which the client never produces")
for attr, produced in per_normalizer_fields():
own = table_for(doc, attr)
if own is None:
problems.append(
f"the doc never names {attr} before a mapping table, so there is no way to "
f"tell which table is its contract")
continue
missing = sorted(produced - own)
if missing:
problems.append(f"the table documented for {attr} is missing: {', '.join(missing)}")
extra = sorted(own - produced)
if extra:
problems.append(f"the table documented for {attr} adds fields it never produces: {', '.join(extra)}")
if "mcp.apify.com?actors=" not in doc:
problems.append("the doc does not give the filtered connector URL")
if "call-actor" not in doc:
problems.append("the doc does not explain why the bare server is not the one to use")
if problems:
print("MCP read-layer mapping:\n" + "\n".join(" " + p for p in problems))
return 1
print(f"OK: {len(actor_ids(tree))} actor(s), {len(keys)} input key(s) and "
f"{len(fields)} flat field(s) all documented in references/mcp-read-layer.md.")
return 0
if __name__ == "__main__":
sys.exit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |