Skip to content

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

@JoeCardoso13

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.

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