Skip to content

Standardize placeholder style to use explicit markers (match TypeScript template) #6

Description

@JoeCardoso13

Context

The Python and TypeScript templates currently use completely different placeholder conventions:

  • Python: natural-looking names — mcp_example, ExampleClient, ExampleAPIError, EXAMPLE_API_KEY, FastMCP("Example"), etc.
  • TypeScript: explicit markers — YOUR_SERVER_NAME, YOUR_DISPLAY_NAME, YOUR_REPO_NAME, YOUR_API_KEY_ENV_VAR, etc.

Problem

The Python template's natural-looking placeholders cause issues during the bootstrap phase:

  1. False positives during verification — grepping for example/Example/EXAMPLE can match legitimate code comments, documentation text, or strings that aren't placeholders
  2. Easy to miss — a placeholder like ExampleClient looks like real code, so both humans and agents can overlook instances
  3. Ambiguity — when the agent encounters the word "example" in a docstring, it has to decide whether it's a placeholder or genuine prose

The TypeScript template doesn't have these problems because YOUR_SERVER_NAME is unambiguously a placeholder — it can never appear in real code.

Proposal

Adopt an explicit, grep-friendly placeholder convention in the Python template, aligned with what TypeScript already uses. For example:

Current (Python) Proposed TypeScript equivalent
mcp_example mcp_YOUR_SERVER_NAME or __MODULE__ n/a (flat src/)
ExampleClient YOUR_SERVER_NAMEClient or __NAME__Client n/a
ExampleAPIError YOUR_SERVER_NAMEAPIError or __NAME__APIError n/a
EXAMPLE_API_KEY YOUR_API_KEY_ENV_VAR YOUR_API_KEY_ENV_VAR
@nimblebraininc/example @YOUR_GITHUB_OWNER/YOUR_SERVER_NAME @nimblebraininc/YOUR_SERVER_NAME
FastMCP("Example") FastMCP("YOUR_DISPLAY_NAME") n/a

The exact marker style (YOUR_*, __PLACEHOLDER__, {{placeholder}}) is open for discussion — the key property is that placeholders should be unambiguously not real code and trivially greppable with a single pattern.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions