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:
- False positives during verification — grepping for
example/Example/EXAMPLE can match legitimate code comments, documentation text, or strings that aren't placeholders
- Easy to miss — a placeholder like
ExampleClient looks like real code, so both humans and agents can overlook instances
- 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.
Context
The Python and TypeScript templates currently use completely different placeholder conventions:
mcp_example,ExampleClient,ExampleAPIError,EXAMPLE_API_KEY,FastMCP("Example"), etc.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:
example/Example/EXAMPLEcan match legitimate code comments, documentation text, or strings that aren't placeholdersExampleClientlooks like real code, so both humans and agents can overlook instancesThe TypeScript template doesn't have these problems because
YOUR_SERVER_NAMEis 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:
mcp_examplemcp_YOUR_SERVER_NAMEor__MODULE__src/)ExampleClientYOUR_SERVER_NAMEClientor__NAME__ClientExampleAPIErrorYOUR_SERVER_NAMEAPIErroror__NAME__APIErrorEXAMPLE_API_KEYYOUR_API_KEY_ENV_VARYOUR_API_KEY_ENV_VAR@nimblebraininc/example@YOUR_GITHUB_OWNER/YOUR_SERVER_NAME@nimblebraininc/YOUR_SERVER_NAMEFastMCP("Example")FastMCP("YOUR_DISPLAY_NAME")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.