3dc5a9b321
Mined the egirl->cocotte lineage + the prose agentic configs. Per-language standards (py/rust/gd) and general conventions: service_architecture, multi_agent_workflow, error_handling_logging, mcp_server_patterns, naming_conventions, tenancy_patterns (draft), database_patterns. Captures the canonical/latest where versions diverged. 14/14 lint:yaml-valid. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
28 lines
1.2 KiB
YAML
28 lines
1.2 KiB
YAML
apiVersion: conventions/v1
|
|
version: 0.1.0
|
|
updated: "2026-06-29"
|
|
name: mcp_server_patterns
|
|
title: MCP server patterns
|
|
scope: general
|
|
status: active
|
|
summary: MCP servers are thin HTTP shims over a backend API — one tool per capability, types matching the API contract, dual stdio/HTTP transport, stderr-only logging. v2→v4.
|
|
appliesTo: ["**/mcp/**", "**/*-mcp/**"]
|
|
rules:
|
|
- id: thin_shim
|
|
level: must
|
|
text: No business logic in the MCP server; every tool is one call to the backend API. The backend owns the logic.
|
|
- id: one_tool_per_capability
|
|
level: must
|
|
text: "Separate tools per capability (list_x / get_x / create_x), never one `manage` tool with a mode param."
|
|
- id: shared_types
|
|
level: should
|
|
text: Tool types mirror the backend API contract (shared via the feature's shared/ or a published api-client package), not re-invented.
|
|
- id: dual_transport
|
|
level: should
|
|
text: "stdio for dev/testing; HTTP for prod (bind port + Bearer token auth)."
|
|
- id: layout
|
|
level: should
|
|
text: "Reference layout: src/index.ts (tools) + src/client.ts (HTTP wrapper + env config) + logger to stderr."
|
|
- id: stderr_only
|
|
level: must
|
|
text: Never log to stdout (reserved for the MCP protocol) — logger writes to stderr.
|