convention.sh

What is convention.sh?

convention.sh is a hosted toolkit for teaching coding agents to produce more consistent, production-ready TypeScript. It provides a library of hand-tuned TypeScript conventions that agents can fetch on demand rather than relying on a static, prompt-sized ruleset.

The core purpose is to reduce sloppy TypeScript output by giving agents concrete conventions—such as stricter typing patterns and runtime validation approaches—delivered through a standard interface.

Key Features

• Hosted MCP server for conventions: convention.sh runs as a hosted Model Context Protocol (MCP) server that an agent can query for the convention snippets it needs.
• On-demand snippet retrieval (27 conventions): instead of embedding a wall of rules into every prompt, agents pull only the relevant snippets from a library of 27 conventions when requested.
• Conventions aimed at TypeScript correctness: the listed conventions emphasize strict typing (avoiding any), using Zod to validate untrusted input, and preferring discriminated unions over optional fields.
• Model-context integration via MCP: works with any agent that supports the Standard Model Context Protocol by dropping the MCP endpoint into the agent configuration.
• Always up to date without redeploys: because the conventions are served from the hosted MCP endpoint, changes are picked up on subsequent requests rather than requiring prompt rewrites or application redeploys.

How to Use convention.sh

1. Add the MCP endpoint in your agent using the provided terminal command, which registers the hosted endpoint: claude mcp add conventiondotsh --transport http https://mcp.convention.sh.
2. Start running your usual TypeScript tasks in your coding agent.
3. Let the agent request conventions as needed: during a task, the agent asks for the specific convention snippet(s) from the convention.sh server when it needs them.

If you’re using a different MCP-capable agent than the example shown, configure it to call the same hosted MCP endpoint described by convention.sh.

Use Cases

• Refactoring TypeScript modules with consistent style: when generating or updating TypeScript code, request conventions so the agent applies the same patterns for typing and input validation.
• Validating untrusted input in API handlers: use conventions that recommend Zod validation to keep input checking explicit and consistent.
• Avoiding optional-field ambiguity: when designing data shapes, prefer discriminated unions over optional fields to make variant handling clearer in generated code.
• Reducing prompt bloat for longer coding sessions: keep agent prompts focused by having the agent pull the specific convention snippets only when required.
• Teams standardizing agent output: serve the same convention snippets from a shared hosted endpoint so agents applying the MCP integration stay aligned across machines (updates are picked up on next requests).

FAQ

• What does “on demand” mean here? The conventions are delivered via a hosted MCP server, and the agent requests only the needed snippet(s) from a library of 27 conventions during a task rather than receiving a full ruleset every time.

• Do I need to build or host anything myself? The website describes convention.sh as a hosted MCP server, so you add the endpoint to your agent rather than hosting the convention library yourself.

• How do I integrate it with my coding agent? Use the MCP integration flow: configure an MCP-capable agent to use the hosted endpoint at https://mcp.convention.sh. The page includes an example command for adding the MCP server.

• What kinds of TypeScript rules are included? The page lists example conventions focused on strict typing (no any), validating untrusted input with Zod, and preferring discriminated unions over optional fields.

• Will I need to update prompts when conventions change? No—because the conventions are served from the hosted MCP endpoint, the agent picks up new rules on the next request rather than requiring redeploys or stale copies across machines.

Alternatives

• Static prompt rule lists or wikis: you can include TypeScript guidelines directly in each prompt, but this tends to add prompt bulk and can still lead to inconsistent application.
• Local linting/formatting toolchains (e.g., TypeScript ESLint): these tools help enforce style and catch issues after the fact, whereas convention.sh provides conventions during code generation through MCP.
• Other retrieval-based agent context tools: if you already use RAG or tool-based context fetching for coding, you could build a similar “fetch conventions as needed” workflow, though this would require maintaining the convention library and retrieval logic yourself.