mcp-server-development-standards

MCP Server Development Standards

Apply these rules to all MCP server work in this repository.

Core Rules

• Build tools with explicit input schemas (zod) and clear output shapes.
• Keep tool names, descriptions, and argument fields stable and backward compatible.
• Return actionable errors: explain what failed, why, and how to recover.
• Never hardcode secrets; read credentials from environment variables.
• Add timeout, retry, and graceful failure handling for external API calls.
• Keep side effects explicit; avoid hidden writes, deletions, or irreversible actions.
• Validate and sanitize any user-provided or remote data before use.
• Log enough context for debugging, but never log secrets or sensitive payloads.

TypeScript Standards

• Use TypeScript for all runtime and server code; do not introduce plain .js source files.
• Keep strict typing on (strict: true) and avoid any; prefer unknown plus narrowing.
• In catch blocks, narrow error safely before reading message/details.
• Add explicit types for exported APIs and shared helper boundaries.
• Prefer import type for type-only imports to keep runtime output clean.

Implementation Pattern (TypeScript)

// ❌ BAD: no schema, weak error context
server.tool("sendSms", async (args) => provider.send(args));

// ✅ GOOD: schema + safe error mapping
server.tool(
  "send_sms",
  "Send an SMS through EngageLab",
  { phone: z.string().min(6), content: z.string().min(1).max(500) },
  async ({ phone, content }) => {
    try {
      return await provider.send({ phone, content });
    } catch (error) {
      throw new Error(`send_sms failed: provider request was rejected`);
    }
  }
);

Quality Gate

• For every new tool, include one success path test and one failure path test.
• Keep name/version metadata accurate when behavior changes.