-
Notifications
You must be signed in to change notification settings - Fork 0
Open
Description
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/EXAMPLEcan match legitimate code comments, documentation text, or strings that aren't placeholders - Easy to miss — a placeholder like
ExampleClientlooks 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.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
No labels