agent-trellis 0.1.0

package/schema/servers.example.yaml

@@ -0,0 +1,87 @@
+# .trellis/mcp/servers.yaml — canonical MCP server definitions.
+#
+# Rules (see docs/architecture.md and docs/research.md §"Secrets"):
+#   - `env` values are variable NAMES only. Never a literal secret.
+#   - Real values come from whatever already populates process env
+#     (a plain `.env`-style file, 1Password's `op run`, etc.) — Trellis
+#     does not store or transport secret values itself.
+#   - A server name that a host environment is known to inject at runtime
+#     (see `known_host_injected` below) must not be redefined here — on
+#     Codex this causes the entire process to fail to start, not just that
+#     server. See docs/research.md §"Codex — three hard constraints".
+#   - `agents:` is optional and restricts a server to specific agents; omit
+#     it and the server goes to all four (the default). Unlike skills/
+#     subagents/memories, this scoping lives inline here rather than in
+#     `scope.yaml` — this file is Trellis's own format, never handed to an
+#     agent directly, so there's no risk of an agent rejecting an unknown
+#     field the way Codex does with SKILL.md frontmatter.
+
+servers:
+  # Default shared-memory backend (docs/research.md "Shared memory") —
+  # @modelcontextprotocol/server-memory: zero-dependency, local JSON
+  # knowledge graph, MIT-licensed. Left commented out here because this
+  # exact example ALSO lists "memory" under known_host_injected below —
+  # uncommenting both would self-collide (Trellis's own collision guard
+  # would correctly refuse to write it). Which situation you're actually
+  # in depends on your host:
+  #   - If your host (e.g. mirasim) already injects a runtime connector
+  #     under this name — check with `trellis doctor` — leave this
+  #     commented out and keep "memory" in known_host_injected below;
+  #     you already have it, just not from a static definition.
+  #   - If your host injects nothing under this name, uncomment this
+  #     entry AND remove "memory" from known_host_injected below (it's
+  #     only there as inherited example content, not a fact about your
+  #     environment) — that's what actually wires the default.
+  # mem0/OpenMemory or a totalrecallai-class semantic-search server are
+  # documented opt-in upgrades from this default, not silent defaults —
+  # same section of docs/research.md.
+  # memory:
+  #   transport: stdio
+  #   command: npx
+  #   args: ["-y", "@modelcontextprotocol/server-memory"]
+
+  tanka:
+    transport: stdio
+    command: tanka-mcp
+    env: [TANKA_EMAIL, TANKA_ENV]
+
+  gitlab:
+    transport: stdio
+    command: npx
+    args: ["-y", "@zereight/mcp-gitlab"]
+    env: [GITLAB_PERSONAL_ACCESS_TOKEN, GITLAB_API_URL]
+
+  figma:
+    transport: http
+    url: "https://mcp.figma.com/mcp"
+    auth: oauth
+
+  # Example of a private/agent-specific server: only Claude Code has a use
+  # for this one, so the other three agents never see it defined at all.
+  claude-only-tool:
+    transport: stdio
+    command: node
+    args: ["/path/to/claude-specific-server.js"]
+    agents: [claude-code]
+
+# Names a known host (e.g. mirasim) may inject into an agent process at
+# runtime, independent of this file. Trellis's collision check refuses to
+# generate a local definition under any of these names.
+known_host_injected:
+  - atlassian
+  - sentry
+  - memory
+  - mirasim
+
+# How the servers above reach the four agents. Omit this whole block for
+# direct mode (today's default: every agent gets all N server definitions
+# written straight into its native config).
+#
+# Set it to route every agent through a single HTTP endpoint instead —
+# every adapter then writes exactly ONE entry (this URL), not N. What runs
+# behind the URL is not Trellis's concern: could be a self-hosted
+# github.com/ravitemer/mcp-hub instance, a hosted mcp-router account,
+# anything else speaking MCP over HTTP. No engine/product switch to
+# maintain — see docs/architecture.md "MCP hub mode".
+hub:
+  url: "http://127.0.0.1:37373/mcp"