Skip to content
Documentation

Coding guidelines

FieldValue
TypeAgent Reference
Source~/.copilot/agents/_refs/typescript-mcp-expert/guidelines.md
DescriptionNot specified

Source Content

Coding guidelines

Reference for TypeScript MCP Server Expert. Apply to every TypeScript MCP server.

Modules and imports

  • Use ES modules (import/export), never require.
  • Import from specific SDK paths: @modelcontextprotocol/sdk/server/mcp.js (note .js).
  • Set "type": "module" in package.json and "module": "ESNext" / "moduleResolution": "Bundler" (or NodeNext) in tsconfig.json.

Schemas

  • Use zod for every input/output schema — { inputSchema: { param: z.string() } }.
  • Add .describe() on every field; the description ends up in the LLM prompt.
  • Define an outputSchema whenever the tool returns structured data.
  • Validate environment variables at startup with a single zod schema.

API surface

  • Provide a title field on every tool, resource, and prompt — not just name.
  • Names are stable identifiers; titles are human-readable.
  • Tool return values must include both content (display) and structuredContent (data).
  • Use ResourceTemplate for dynamic resource URIs: new ResourceTemplate('resource://{id}', { list: undefined }).

Transport hygiene

  • In stateless HTTP mode, create a new transport instance per request.
  • Always wire res.on('close', () => transport.close()) for HTTP transports.
  • Enable enableDnsRebindingProtection: true for local HTTP servers.
  • Configure CORS and expose Mcp-Session-Id for browser clients.

Errors

  • Wrap implementations in try/catch.
  • On failure, return { isError: true, content: [...] } with a meaningful message.
  • Never let exceptions escape to the transport.

Types

  • Annotate every function parameter and return type.
  • Run tsc --noEmit in CI; fail on any error.
  • Avoid any — use unknown and narrow.

Configuration

  • Read all configuration from environment variables.
  • Document required env vars in the README.
  • Validate env at startup with zod; exit non-zero on failure.

Advanced features

  • Use completable() for argument completion.
  • Use server.server.createMessage() for sampling.
  • Use server.server.elicitInput() for interactive input.
  • Use .enable() / .disable() / .update() / .remove() for dynamic capabilities.

Testing

  • Smoke-test with the MCP Inspector: npx @modelcontextprotocol/inspector.
  • Unit-test tool implementations directly (they are plain functions).
  • Integration-test against a real transport with a test client.