agentleFS
TheodoreADTheodoreAD/agent-skills/skills/mcp-python-conventions-taudelta/SKILL.md

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.

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
  1. Very specific:

    Not about shipping. Entry points, uv tool install, claude mcp add and scope selection belong to mcp-server-shipping.

    line 13
  2. Very specific:

    Default: never a bare print() in server package code.

    line 22
  3. Very specific:

    Default: at the point an internal exception is about to cross back to the client, decide deliberately what's safe to expose — either …

    line 40
  4. Distinctive:

    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 …

    line 66

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 stdlib logging module, explicitly configured to write to stderr at startup (or defer to FastMCP's own configure_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.ToolError with an explicit, hand-written message, or let a plain exception raise (FastMCP's default already surfaces it, unmasked, to the client). Never assume str(exc) of an arbitrarily caught exception is safe by default, especially inside a broad per-item except 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's SecretStr caveat: a broad safety switch doesn't sanitize text you deliberately choose to expose.
  • Don't: flip mask_error_details=True project-wide as a blanket fix — it suppresses legitimately useful validation detail (a bad argument, a batch-size violation) that plain raise ValueError(...) call sites rely on being visible to the calling agent. Prefer the finer-grained per-message ToolError choice.
  • Model default: overrides. A model doesn't know ToolError exists 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.description an 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-Schema inputSchema itself 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.