mcp-python-conventions-taudelta
Skill0 starsChanged 49 days agoMITView on GitHub
Use when writing the Python inside an MCP server and deciding how it should behave — where log output may go when stdout carries JSON-RPC framing and why a stray print breaks the protocol, what an exception at a tool boundary should turn into for the calling model, how much internal detail an error may safely expose, and how to write a tool docstring that the model reads as its instructions rather than as documentation for a human. Scoped to stdio-transport servers. For a server's packaging, installation and registration rather than its code, see the MCP server shipping skill; for general Python design questions, see the Python conventions skill.
In this repository16 other files it gives its agents.
- AGENTS.mdAGENTS.md
- db-defaults-taudeltaSkill
- invoke-task-conventions-taudeltaSkill
- mcp-server-shippingSkill
- plan-conveyorSkill
- polite-mcp-conventions-taudeltaSkill
- python-conventions-taudeltaSkill
- python-refactor-auditSkill
- python-testing-conventions-taudeltaSkill
- release-heraldSkill
- repo-pitchSkill
- research-librarySkill
- session-bash-auditSkill
- session-harvestSkill
- skill-authoring-taudeltaSkill
- skill-fitnessSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 13
Not about shipping. Entry points, uv tool install, claude mcp add and scope selection belong to mcp-server-shipping.
- Very specific: line 22
Default: never a bare print() in server package code.
- Very specific: line 40
Default: at the point an internal exception is about to cross back to the client, decide deliberately what's safe to expose — either …
- Distinctive: line 66
Default: write the docstring to Anthropic's tool-definition bar, not PEP 257's — what the tool does and how it differs from its nearest …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
MCP server code conventions
The Python inside a stdio-transport MCP server. Split out of python-conventions-taudelta on
2026-08-31, which keeps the general design defaults — this skill owns only what is different
because the code is an MCP server, and those differences are not stylistic: two of the three are
protocol correctness.
Not about shipping. Entry points, uv tool install, claude mcp add and scope selection belong to
mcp-server-shipping; this is what the code does once it runs.
MCP-stdio logging discipline
Scope: stdio-transport MCP servers only (the *-polite-mcp family) — not applicable to a repo that
has no MCP server of its own.
- Snippet:
references/snippets/mcp-tool-boundary.py - Default: never a bare
print()in server package code. Route all logging through the stdlibloggingmodule, explicitly configured to write to stderr at startup (or defer to FastMCP's ownconfigure_logging(), which already defaults there). - Why: the MCP stdio spec is unambiguous — a server MUST NOT write anything to stdout that isn't
a valid MCP message; a single stray
print()or a dependency's stdout-bound log handler corrupts the JSON-RPC stream. stderr is the sanctioned outlet for everything, logs included. - Don't: trust that "no
print()in my code" is sufficient — a dependency that logs to stdout on its own initiative isn't caught by explicit stderr configuration of your own logging. The robust check is exercising the real stdio transport end-to-end, not code review alone. - Model default: overrides — sharply, not a style nudge. This is protocol-specific knowledge a
model has no general-Python reason to know; without it, a model reaches for
print()debugging exactly as it would in any other script, silently breaking the server.
Error handling at the MCP tool boundary
Scope: stdio-transport MCP servers only, same as above.
- Snippet:
references/snippets/mcp-tool-boundary.py - Default: at the point an internal exception is about to cross back to the client, decide
deliberately what's safe to expose — either re-raise as
fastmcp.exceptions.ToolErrorwith an explicit, hand-written message, or let a plain exception raise (FastMCP's default already surfaces it, unmasked, to the client). Never assumestr(exc)of an arbitrarily caught exception is safe by default, especially inside a broad per-itemexcept Exception(a legitimate pattern for isolating one bad item in a batch call — just don't let its caught exception's message reach the client unreviewed). - Why: FastMCP's default (
mask_error_details=False) already includes full exception detail in the client-facing response — this isn't an opt-in risk, it's the out-of-the-box behavior. The same shape as this skill'sSecretStrcaveat: a broad safety switch doesn't sanitize text you deliberately choose to expose. - Don't: flip
mask_error_details=Trueproject-wide as a blanket fix — it suppresses legitimately useful validation detail (a bad argument, a batch-size violation) that plainraise ValueError(...)call sites rely on being visible to the calling agent. Prefer the finer-grained per-messageToolErrorchoice. - Model default: overrides. A model doesn't know
ToolErrorexists or that FastMCP unmasks exceptions by default unless told — without this, it either leaves exceptions to propagate as-is (today's actual state in this family) or reaches for a blanket masking flag, both worse than the deliberate per-boundary choice.
MCP tool docstrings
Scope: any function decorated as an MCP tool (@mcp.tool() in this family). A genuinely distinct
concern from general docstring style — no general docstring-content rule exists elsewhere in this
skill to extend.
- Default: write the docstring to Anthropic's tool-definition bar, not PEP 257's — what the tool
does and how it differs from its nearest sibling by name, when to use/not use it, where each
non-obvious parameter's value comes from, response shape/size caveats, at least 3–4 sentences,
more for a complex tool. See
references/rationale.md§11 for the concrete template and this family's own strongest real examples. - Why: the docstring becomes the wire-level
Tool.descriptionan LLM client reads at inference time to decide whether/how to call the tool — a weak one causes wrong-tool-picked, wrong-arguments, or never-invoked failures, a correctness cost paid by every future call, not a comprehension-speed one the way a weak human-facing docstring is. - Escalate to:
Annotated[x, Field(description=...)]for per-parameter descriptions once free-form prose isn't enough (so the JSON-SchemainputSchemaitself carries them);annotations=(readOnlyHint/destructiveHint/etc.) on any tool with real side effects, since clients use it to decide when to skip or require confirmation prompts. - Model default: overrides. A model's default docstring instinct is PEP 257's — a concise one-line summary — which is actively worse here; the entire point of this section is that the bar for an LLM-facing description is different from, not a stricter version of, ordinary docstring style.
Full rationale
See references/rationale.md — the sources for the stdout constraint,
the error-taxonomy reasoning, and the docstring-as-contract argument.
Starter snippet
references/snippets/mcp-tool-boundary.py is a runnable
sketch of the tool-boundary error handling described here.
Editing this skill
This file is copied into ~/.agents/skills/mcp-python-conventions-taudelta at install time, never
symlinked, so editing the deployed copy is local drift — the exact thing this skill exists to
prevent, and it reaches no other machine. Edit the source in the repo this was installed from, push,
and re-run skills add <that source> --global --skill mcp-python-conventions-taudelta to refresh
every project's copy. If you installed it from someone else's repo rather than your own fork, the
source is theirs: open an issue or a pull request there instead.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

