[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M78089KBW286604CTZ8V2NX6":3,"skill-same:01M78089KBW286604CTZ8V2NX6":63},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M78089KBW286604CTZ8V2NX6","effect-v4-mcp",null,"Use when building, wiring, testing or reviewing an MCP server on Effect v4 — effect\u002Fai's McpServer, Tool and Toolkit plus the @effected\u002Fmcp-kit boundary that keeps stdout the JSON-RPC wire and makes tool failures readable to an agent. Also use when: MCP server, McpServer, Tool.make, Toolkit, layerStdio, tools\u002Fcall, server\u002Fdiscover, initialize, Tool.Strict, unknown keys, isError, structuredContent, InvalidParams, MCP resource, mimeType, stdio server exits 130, JSON-RPC on stdout, McpHarness, McpProbe, crash guard, ok false envelope, ToolOutcome, idempotency key, ToolReplay, StdioCapture, library writes to stdout, Exclusive, ProcessScope, chdir per request","spencerbeggs\u002Feffected","spencerbeggs","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F109114?v=4","01M77ZTHB70K5Y2VVTRCFY50A5","C. Spencer Beggs","01M77ZTHCC41NXBT3X906K6QM1",8,"MIT","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fbuilds\u002Fcopilot\u002Fskills\u002Feffect-v4-mcp\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: effect-v4-mcp\ndescription: \"Use when building, wiring, testing or reviewing an MCP server on Effect v4 — effect\u002Fai's McpServer, Tool and Toolkit plus the @effected\u002Fmcp-kit boundary that keeps stdout the JSON-RPC wire and makes tool failures readable to an agent. Also use when: MCP server, McpServer, Tool.make, Toolkit, layerStdio, tools\u002Fcall, server\u002Fdiscover, initialize, Tool.Strict, unknown keys, isError, structuredContent, InvalidParams, MCP resource, mimeType, stdio server exits 130, JSON-RPC on stdout, McpHarness, McpProbe, crash guard, ok false envelope, ToolOutcome, idempotency key, ToolReplay, StdioCapture, library writes to stdout, Exclusive, ProcessScope, chdir per request\"\n---\n\n# Effect v4 MCP servers\n\nCore owns the protocol, tool registration and the wire format:\n`effect\u002Fai`'s `McpServer`, `Tool` and `Toolkit` parse requests,\nserve JSON Schema, and shape a `tools\u002Fcall` result. `@effected\u002Fmcp-kit` owns the\nstdio boundary — keeping every log line and every crash report off stdout,\nwhich is the JSON-RPC wire — plus tool-failure shaping and strict-by-default\nregistration. `@effected\u002Fmcp-kit\u002Ftesting` owns the in-process and spawned test\nclients.\n\n| construct | import | reach for it when |\n| --- | --- | --- |\n| `McpServer`, `Tool`, `Toolkit`, `McpSchema` | `effect\u002Fai` | declaring the server, its tools, and the protocol-level schemas |\n| `McpStdio` | `@effected\u002Fmcp-kit` | launching a stdio server without a stray log line or crash report reaching the wire |\n| `McpToolkit` | `@effected\u002Fmcp-kit` | registering a toolkit strict-by-default; core's strict decode names every bad key and field in one response, and the layer appends each offending level's accepted params |\n| `ToolFailure` | `@effected\u002Fmcp-kit` | folding remediation into a declared failure's message — core sends only `error.message` |\n| `ToolInputSchema` | `@effected\u002Fmcp-kit` | naming unknown keys in a `Tool.dynamic` tool's raw payload, inside its own handler — core never validates a raw JSON Schema |\n| `McpToolkit.unionTool` \u002F `unionHandler` | `@effected\u002Fmcp-kit` | a tool whose parameters are a `Schema.Union` of objects, rejected like a `Tool.make` decode failure |\n| `ToolOutcome` | `@effected\u002Fmcp-kit` | an expected domain error the agent should branch on as data: the `ok: false` envelope on the success channel, where `structuredContent` arrives |\n| `ToolReplay` | `@effected\u002Fmcp-kit` | a write tool whose retried call with the same idempotency key returns the first result instead of running again |\n| `StdioCapture` | `@effected\u002Fmcp-kit\u002Fnode` | an in-process library (a test runner, a bundler) that writes to stdout from inside a handler |\n| `Exclusive` | `@effected\u002Fkit` | handlers that mutate process-global state (cwd, env, a patched stream) must run one at a time, under a timeout |\n| `ProcessScope` | `@effected\u002Fkit` | a `chdir` or an env patch restored when the request's scope closes |\n| `McpGuard` | `@effected\u002Fmcp-kit\u002Fguard` | crash guards installed before the server graph loads, with an exit-before-connect policy |\n| `ProcessGuard` | `@effected\u002Fkit\u002Fguard` | the same guards for a server on another transport (an LSP), which reports `markConnected` itself |\n| `Remediation`, `LaunchContext` | `@effected\u002Fkit` | a structured `{ hint, suggestedTool? }` shape, or resolving an agent-launched project directory |\n| `McpHarness`, `McpProcess`, `McpProbe`, `McpToolAudit` | `@effected\u002Fmcp-kit\u002Ftesting` | testing the server layer in process, a spawned child, a packed install, or auditing what `tools\u002Flist` actually serves |\n\n## Standards\n\n- Launch with `McpStdio.launch` and `NodeRuntime.runMain(program, { teardown: McpStdio.teardown })` — never a bare `Layer.launch`.\n- Register toolkits through `McpToolkit.layer`, not core's `McpServer.toolkit` directly, so every tool is strict unless it opts out.\n- Fold remediation into a declared failure's message with `ToolFailure` at construction — nothing else reaches the agent.\n- Capture a service a handler needs for the server's lifetime in the effect form of `Toolkit.toLayer`; declare a service in `Tool.make`'s `dependencies` only when it varies per request, and meet it with `McpServer.middleware`, or, when a declared service is fixed for the server's lifetime, with `McpToolkit.provideLifetime` — `Layer.provide` cannot — see [Defining a tool](.\u002Freferences\u002Ftools.md#defining-a-tool).\n- Pass the toolkit layer to `McpStdio.layer` as `registrations`, so it builds before the first request with its logs on stderr.\n- Return an expected error the agent branches on through `ToolOutcome.catchAsEnvelope`, written inline in the handler's `pipe`.\n- Test the server layer in process with `McpHarness`; test a **built** bin with `McpProcess`\u002F`McpProbe`.\n\n## Footguns\n\n- Hand-wiring `McpServer.layerStdio` without `McpStdio.layer` leaves a malformed line unanswered — core skips it silently where JSON-RPC requires a `-32700`\u002F`-32600` reply — see [The stdin guard](.\u002Freferences\u002Fserver-wiring.md#stdin-guard).\n- Two stdio servers in one process share one tool registry unless each **whole** bundle (toolkit + server) is wrapped in `Layer.fresh`: merged or nested without it, each lists both servers' tools; `Layer.fresh` around the server alone, toolkit outside, serves no tools — see [`McpStdio.layer`](.\u002Freferences\u002Fserver-wiring.md#mcpstdiolayer).\n- On a serverless host such as Cloudflare Workers, `McpServer.layerHttp` keeps a long-lived server whose fibers and timers outlive the request; serve with `McpServer.layerHttpRequestScoped` instead, which builds one server per POST. Its `protocols` take only sessionless adapters (`McpProtocol.v2026_07_28`) — the type rejects a sessionful one, and the layer fails with `IllegalArgumentError` if one gets through — and it has no subscription or session-termination options.\n- `runMain`'s own failure report runs outside anything the program provides and lands on stdout, the wire — see [`McpStdio.launch`](.\u002Freferences\u002Fserver-wiring.md).\n- Stdin EOF ends the server with exit `0`, even under the default teardown; SIGINT and SIGTERM still exit `130` there — see [`McpStdio.teardown`](.\u002Freferences\u002Fserver-wiring.md).\n- A declared failure reaches the agent as message text only, never `structuredContent`, under either failure mode, so `ToolRefusal.refuse` takes no data argument — see [Failures on the wire](.\u002Freferences\u002Ftools.md#failures-on-the-wire).\n- `injectCrash: { at: \"connected\" }` reports on a later tick, after the first responses a test may read; wait with `McpProcess.stderrUntil`, never one `stderrSoFar` read — see [`McpGuard.run`](.\u002Freferences\u002Fserver-wiring.md#mcpguardrun-packages-both-policies).\n- `InvalidParams` moves to an `isError` tool result on the newer protocol revisions only for a known tool's own bad parameters — an unknown tool or non-object `arguments` stays a JSON-RPC error on every revision — see [Failures on the wire](.\u002Freferences\u002Ftools.md#failures-on-the-wire).\n- A top-level union `parameters` schema dies the server at registration, not at the first call — use `McpToolkit.unionTool` — see [Failures on the wire](.\u002Freferences\u002Ftools.md#failures-on-the-wire).\n- A pattern-keyed `Schema.Record` parameter is served open unless its key RegExp has the `u` flag, while core still rejects a non-matching key — see [Strict input](.\u002Freferences\u002Ftools.md#strict-input).\n- A `Schema.String` success is sent as raw text with no `structuredContent` on the stateful revisions, and as JSON-quoted text plus a string `structuredContent` on `2026-07-28` — see [Failures on the wire](.\u002Freferences\u002Ftools.md#failures-on-the-wire).\n- `ToolOutcome.catchAsEnvelope` bound to a `const` before it is applied loses the piped effect's error type, so a misspelled tag compiles and never matches — see [The `ok: false` envelope](.\u002Freferences\u002Ftools.md#the-ok-false-envelope).\n- A `ToolReplay` key reused with different params replays the first call's result — it compares nothing but the key, and rows never expire — and two concurrent calls with one key both run: it is replay, not exactly-once — see [Idempotent replay](.\u002Freferences\u002Ftools.md#idempotent-replay).\n- `ToolReplay.success` drops the struct's own `.check(...)` refinements; apply checks to its result — see [Idempotent replay](.\u002Freferences\u002Ftools.md#idempotent-replay).\n- `StdioCapture` leaks both ways: a callback registered outside the capture (a child-pipe listener, relayed worker output) still writes to the wire, and a fiber forked inside it keeps writing to the sink after it ends — see [Keeping a library's output off the wire](.\u002Freferences\u002Ftools.md#keeping-a-librarys-output-off-the-wire).\n- `Exclusive.run` is not reentrant: a nested `run` on the same lane waits on its own caller's permit and fails as the outer `ExclusiveTimeout`. `Effect.promise` inside a lane abandons the promise on timeout; use `Exclusive.promise`, and `abandon: true` for a promise that ignores its signal. A boundary test can hold the line: `SourceBoundary.scan({ root, rules: [{ promiseInExclusive: {} }] })` from `@effected\u002Fworkspaces\u002Ftesting` flags either call lexically inside a `lane.run(` body (pass `lanes` for a lane received as a parameter; a helper called from the body is not seen).\n- `Schema.Struct({})` is not `Tool.EmptyParams` — it fails server registration outright — see [Defining a tool](.\u002Freferences\u002Ftools.md#defining-a-tool).\n- Closing stdin does not cancel requests in flight: the server answers them, then stops — so `McpHarness.close` never releases a wait on a request that never completes; `McpHarness.stop` does — see [`McpStdio.teardown`](.\u002Freferences\u002Fserver-wiring.md).\n- A resource read carries its registered `mimeType` for every `content` form, a bare string or bytes included; a full `ReadResourceResult` is sent as written — see [The `mimeType` on a read](.\u002Freferences\u002Fresources.md#the-mimetype-on-a-read).\n- A resource URI template variable cannot span a slash — an id containing one needs a static resource per id, not a template — see [A template variable cannot span a slash](.\u002Freferences\u002Fresources.md#a-template-variable-cannot-span-a-slash).\n- An `Effect.timeout` guard inside `it.effect` never fires — `TestClock` never advances on its own, so the test hangs until vitest's own default timeout kills it instead. Use `it.live` or a real-clock `layer(...)` — see [Timeouts](.\u002Freferences\u002Ftesting.md#timeouts).\n- Code placed after a completed `Effect.provide` of a stdio server never runs — core's stdio protocol interrupts the fiber that built it once the server stops, so a hand-written test provides-then-asserts and silently checks nothing. Use `McpHarness` — see [The in-process harness](.\u002Freferences\u002Ftesting.md#the-in-process-harness).\n\n## Additional resources\n\n- [server-wiring.md](.\u002Freferences\u002Fserver-wiring.md) — the complete `main.ts`, `McpStdio.layer`\u002F`launch`\u002F`teardown`, protocol ordering, crash guards, and launch-context project-directory resolution. Load when: assembling or reviewing a server's `main.ts`, or debugging why a failure or a log line reached the wire.\n- [tools.md](.\u002Freferences\u002Ftools.md) — defining a tool, strict input reporting, failures on the wire, the `ToolOutcome` `ok: false` envelope, `ToolReplay` idempotent replay, and `StdioCapture`. Load when: declaring a `Tool.make`, wiring a `Toolkit`, a client is seeing the wrong failure shape, a write tool needs an idempotency key, or a handler runs a library that writes to stdout.\n- [resources.md](.\u002Freferences\u002Fresources.md) — `McpServer.resource`'s single and URI-template forms, the `mimeType` a read carries, and why a slash-containing id needs a static resource instead of a template. Load when: registering an MCP resource, or a client's read is missing a `mimeType` it expects.\n- [testing.md](.\u002Freferences\u002Ftesting.md) — the in-process harness, the protocol matrix, spawned clients, the packed-install proof, and the tool audit. Load when: writing a test against an MCP server, or choosing between `McpHarness`, `McpProcess`, `McpProbe` and `McpToolAudit`.\n- `effected-packages`' [mcp-kit.md](..\u002Feffected-packages\u002Freferences\u002Fmcp-kit.md) — the `@effected\u002Fmcp-kit` package surface as a routing reference (import table, full API, Usage block). Load when: you need the package-level index rather than the teaching depth here.\n\nAnchors in this skill and its references cite the vendored tag at\n`.repos\u002Feffect\u002Fpackages\u002Feffect\u002Fsrc\u002F`; a consumer without that tree searches\n`node_modules\u002Feffect\u002Fsrc` by symbol name instead of by line number.\n","# Effect v4 MCP servers\n\nCore owns the protocol, tool registration and the wire format:\n`effect\u002Fai`'s `McpServer`, `Tool` and `Toolkit` parse requests,\nserve JSON Schema, and shape a `tools\u002Fcall` result. `@effected\u002Fmcp-kit` owns the\nstdio boundary — keeping every log line and every crash report off stdout,\nwhich is the JSON-RPC wire — plus tool-failure shaping and strict-by-default\nregistration. `@effected\u002Fmcp-kit\u002Ftesting` owns the in-process and spawned test\nclients.\n\n| construct | import | reach for it when |\n| --- | --- | --- |\n| `McpServer`, `Tool`, `Toolkit`, `McpSchema` | `effect\u002Fai` | declaring the server, its tools, and the protocol-level schemas |\n| `McpStdio` | `@effected\u002Fmcp-kit` | launching a stdio server without a stray log line or crash report reaching the wire |\n| `McpToolkit` | `@effected\u002Fmcp-kit` | registering a toolkit strict-by-default; core's strict decode names every bad key and field in one response, and the layer appends each offending level's accepted params |\n| `ToolFailure` | `@effected\u002Fmcp-kit` | folding remediation into a declared failure's message — core sends only `error.message` |\n| `ToolInputSchema` | `@effected\u002Fmcp-kit` | naming unknown keys in a `Tool.dynamic` tool's raw payload, inside its own handler — core never validates a raw JSON Schema |\n| `McpToolkit.unionTool` \u002F `unionHandler` | `@effected\u002Fmcp-kit` | a tool whose parameters are a `Schema.Union` of objects, rejected like a `Tool.make` decode failure |\n| `ToolOutcome` | `@effected\u002Fmcp-kit` | an expected domain error the agent should branch on as data: the `ok: false` envelope on the success channel, where `structuredContent` arrives |\n| `ToolReplay` | `@effected\u002Fmcp-kit` | a write tool whose retried call with the same idempotency key returns the first result instead of running again |\n| `StdioCapture` | `@effected\u002Fmcp-kit\u002Fnode` | an in-process library (a test runner, a bundler) that writes to stdout from inside a handler |\n| `Exclusive` | `@effected\u002Fkit` | handlers that mutate process-global state (cwd, env, a patched stream) must run one at a time, under a timeout |\n| `ProcessScope` | `@effected\u002Fkit` | a `chdir` or an env patch restored when the request's scope closes |\n| `McpGuard` | `@effected\u002Fmcp-kit\u002Fguard` | crash guards installed before the server graph loads, with an exit-before-connect policy |\n| `ProcessGuard` | `@effected\u002Fkit\u002Fguard` | the same guards for a server on another transport (an LSP), which reports `markConnected` itself |\n| `Remediation`, `LaunchContext` | `@effected\u002Fkit` | a structured `{ hint, suggestedTool? }` shape, or resolving an agent-launched project directory |\n| `McpHarness`, `McpProcess`, `McpProbe`, `McpToolAudit` | `@effected\u002Fmcp-kit\u002Ftesting` | testing the server layer in process, a spawned child, a packed install, or auditing what `tools\u002Flist` actually serves |\n\n## Standards\n\n- Launch with `McpStdio.launch` and `NodeRuntime.runMain(program, { teardown: McpStdio.teardown })` — never a bare `Layer.launch`.\n- Register toolkits through `McpToolkit.layer`, not core's `McpServer.toolkit` directly, so every tool is strict unless it opts out.\n- Fold remediation into a declared failure's message with `ToolFailure` at construction — nothing else reaches the agent.\n- Capture a service a handler needs for the server's lifetime in the effect form of `Toolkit.toLayer`; declare a service in `Tool.make`'s `dependencies` only when it varies per request, and meet it with `McpServer.middleware`, or, when a declared service is fixed for the server's lifetime, with `McpToolkit.provideLifetime` — `Layer.provide` cannot — see [Defining a tool](.\u002Freferences\u002Ftools.md#defining-a-tool).\n- Pass the toolkit layer to `McpStdio.layer` as `registrations`, so it builds before the first request with its logs on stderr.\n- Return an expected error the agent branches on through `ToolOutcome.catchAsEnvelope`, written inline in the handler's `pipe`.\n- Test the server layer in process with `McpHarness`; test a **built** bin with `McpProcess`\u002F`McpProbe`.\n\n## Footguns\n\n- Hand-wiring `McpServer.layerStdio` without `McpStdio.layer` leaves a malformed line unanswered — core skips it silently where JSON-RPC requires a `-32700`\u002F`-32600` reply — see [The stdin guard](.\u002Freferences\u002Fserver-wiring.md#stdin-guard).\n- Two stdio servers in one process share one tool registry unless each **whole** bundle (toolkit + server) is wrapped in `Layer.fresh`: merged or nested without it, each lists both servers' tools; `Layer.fresh` around the server alone, toolkit outside, serves no tools — see [`McpStdio.layer`](.\u002Freferences\u002Fserver-wiring.md#mcpstdiolayer).\n- On a serverless host such as Cloudflare Workers, `McpServer.layerHttp` keeps a long-lived server whose fibers and timers outlive the request; serve with `McpServer.layerHttpRequestScoped` instead, which builds one server per POST. Its `protocols` take only sessionless adapters (`McpProtocol.v2026_07_28`) — the type rejects a sessionful one, and the layer fails with `IllegalArgumentError` if one gets through — and it has no subscription or session-termination options.\n- `runMain`'s own failure report runs outside anything the program provides and lands on stdout, the wire — see [`McpStdio.launch`](.\u002Freferences\u002Fserver-wiring.md).\n- Stdin EOF ends the server with exit `0`, even under the default teardown; SIGINT and SIGTERM still exit `130` there — see [`McpStdio.teardown`](.\u002Freferences\u002Fserver-wiring.md).\n- A declared failure reaches the agent as message text only, never `structuredContent`, under either failure mode, so `ToolRefusal.refuse` takes no data argument — see [Failures on the wire](.\u002Freferences\u002Ftools.md#failures-on-the-wire).\n- `injectCrash: { at: \"connected\" }` reports on a later tick, after the first responses a test may read; wait with `McpProcess.stderrUntil`, never one `stderrSoFar` read — see [`McpGuard.run`](.\u002Freferences\u002Fserver-wiring.md#mcpguardrun-packages-both-policies).\n- `InvalidParams` moves to an `isError` tool result on the newer protocol revisions only for a known tool's own bad parameters — an unknown tool or non-object `arguments` stays a JSON-RPC error on every revision — see [Failures on the wire](.\u002Freferences\u002Ftools.md#failures-on-the-wire).\n- A top-level union `parameters` schema dies the server at registration, not at the first call — use `McpToolkit.unionTool` — see [Failures on the wire](.\u002Freferences\u002Ftools.md#failures-on-the-wire).\n- A pattern-keyed `Schema.Record` parameter is served open unless its key RegExp has the `u` flag, while core still rejects a non-matching key — see [Strict input](.\u002Freferences\u002Ftools.md#strict-input).\n- A `Schema.String` success is sent as raw text with no `structuredContent` on the stateful revisions, and as JSON-quoted text plus a string `structuredContent` on `2026-07-28` — see [Failures on the wire](.\u002Freferences\u002Ftools.md#failures-on-the-wire).\n- `ToolOutcome.catchAsEnvelope` bound to a `const` before it is applied loses the piped effect's error type, so a misspelled tag compiles and never matches — see [The `ok: false` envelope](.\u002Freferences\u002Ftools.md#the-ok-false-envelope).\n- A `ToolReplay` key reused with different params replays the first call's result — it compares nothing but the key, and rows never expire — and two concurrent calls with one key both run: it is replay, not exactly-once — see [Idempotent replay](.\u002Freferences\u002Ftools.md#idempotent-replay).\n- `ToolReplay.success` drops the struct's own `.check(...)` refinements; apply checks to its result — see [Idempotent replay](.\u002Freferences\u002Ftools.md#idempotent-replay).\n- `StdioCapture` leaks both ways: a callback registered outside the capture (a child-pipe listener, relayed worker output) still writes to the wire, and a fiber forked inside it keeps writing to the sink after it ends — see [Keeping a library's output off the wire](.\u002Freferences\u002Ftools.md#keeping-a-librarys-output-off-the-wire).\n- `Exclusive.run` is not reentrant: a nested `run` on the same lane waits on its own caller's permit and fails as the outer `ExclusiveTimeout`. `Effect.promise` inside a lane abandons the promise on timeout; use `Exclusive.promise`, and `abandon: true` for a promise that ignores its signal. A boundary test can hold the line: `SourceBoundary.scan({ root, rules: [{ promiseInExclusive: {} }] })` from `@effected\u002Fworkspaces\u002Ftesting` flags either call lexically inside a `lane.run(` body (pass `lanes` for a lane received as a parameter; a helper called from the body is not seen).\n- `Schema.Struct({})` is not `Tool.EmptyParams` — it fails server registration outright — see [Defining a tool](.\u002Freferences\u002Ftools.md#defining-a-tool).\n- Closing stdin does not cancel requests in flight: the server answers them, then stops — so `McpHarness.close` never releases a wait on a request that never completes; `McpHarness.stop` does — see [`McpStdio.teardown`](.\u002Freferences\u002Fserver-wiring.md).\n- A resource read carries its registered `mimeType` for every `content` form, a bare string or bytes included; a full `ReadResourceResult` is sent as written — see [The `mimeType` on a read](.\u002Freferences\u002Fresources.md#the-mimetype-on-a-read).\n- A resource URI template variable cannot span a slash — an id containing one needs a static resource per id, not a template — see [A template variable cannot span a slash](.\u002Freferences\u002Fresources.md#a-template-variable-cannot-span-a-slash).\n- An `Effect.timeout` guard inside `it.effect` never fires — `TestClock` never advances on its own, so the test hangs until vitest's own default timeout kills it instead. Use `it.live` or a real-clock `layer(...)` — see [Timeouts](.\u002Freferences\u002Ftesting.md#timeouts).\n- Code placed after a completed `Effect.provide` of a stdio server never runs — core's stdio protocol interrupts the fiber that built it once the server stops, so a hand-written test provides-then-asserts and silently checks nothing. Use `McpHarness` — see [The in-process harness](.\u002Freferences\u002Ftesting.md#the-in-process-harness).\n\n## Additional resources\n\n- [server-wiring.md](.\u002Freferences\u002Fserver-wiring.md) — the complete `main.ts`, `McpStdio.layer`\u002F`launch`\u002F`teardown`, protocol ordering, crash guards, and launch-context project-directory resolution. Load when: assembling or reviewing a server's `main.ts`, or debugging why a failure or a log line reached the wire.\n- [tools.md](.\u002Freferences\u002Ftools.md) — defining a tool, strict input reporting, failures on the wire, the `ToolOutcome` `ok: false` envelope, `ToolReplay` idempotent replay, and `StdioCapture`. Load when: declaring a `Tool.make`, wiring a `Toolkit`, a client is seeing the wrong failure shape, a write tool needs an idempotency key, or a handler runs a library that writes to stdout.\n- [resources.md](.\u002Freferences\u002Fresources.md) — `McpServer.resource`'s single and URI-template forms, the `mimeType` a read carries, and why a slash-containing id needs a static resource instead of a template. Load when: registering an MCP resource, or a client's read is missing a `mimeType` it expects.\n- [testing.md](.\u002Freferences\u002Ftesting.md) — the in-process harness, the protocol matrix, spawned clients, the packed-install proof, and the tool audit. Load when: writing a test against an MCP server, or choosing between `McpHarness`, `McpProcess`, `McpProbe` and `McpToolAudit`.\n- `effected-packages`' [mcp-kit.md](..\u002Feffected-packages\u002Freferences\u002Fmcp-kit.md) — the `@effected\u002Fmcp-kit` package surface as a routing reference (import table, full API, Usage block). Load when: you need the package-level index rather than the teaching depth here.\n\nAnchors in this skill and its references cite the vendored tag at\n`.repos\u002Feffect\u002Fpackages\u002Feffect\u002Fsrc\u002F`; a consumer without that tree searches\n`node_modules\u002Feffect\u002Fsrc` by symbol name instead of by line number.\n",{"name":5,"description":7},"main","11d6b3ae59538b0e16ad67c315ecb0c25fcb0125","plugin\u002Fbuilds\u002Fcopilot\u002Fskills\u002Feffect-v4-mcp",2,"https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected","https:\u002F\u002Fgithub.com\u002Fspencerbeggs","2026-11-14 07:03:25",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add spencerbeggs\u002Feffected --skill effect-v4-mcp",{"tool":37,"command":38},"bunx","bunx skills add spencerbeggs\u002Feffected --skill effect-v4-mcp",{"tool":40,"command":41},"pnpm","pnpm dlx skills add spencerbeggs\u002Feffected --skill effect-v4-mcp","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fbuilds\u002Fcopilot\u002Fskills\u002Feffect-v4-mcp\u002FSKILL.md",true,[45,51,55,59],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"references\u002Fresources.md","REFERENCE","参考文档",6453,"https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fbuilds\u002Fcopilot\u002Fskills\u002Feffect-v4-mcp\u002Freferences\u002Fresources.md",{"path":52,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":53,"sourceHtmlUrl":54},"references\u002Fserver-wiring.md",28005,"https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fbuilds\u002Fcopilot\u002Fskills\u002Feffect-v4-mcp\u002Freferences\u002Fserver-wiring.md",{"path":56,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":57,"sourceHtmlUrl":58},"references\u002Ftesting.md",28862,"https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fbuilds\u002Fcopilot\u002Fskills\u002Feffect-v4-mcp\u002Freferences\u002Ftesting.md",{"path":60,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":61,"sourceHtmlUrl":62},"references\u002Ftools.md",31447,"https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fbuilds\u002Fcopilot\u002Fskills\u002Feffect-v4-mcp\u002Freferences\u002Ftools.md",[64,71,78,85,92,99],{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":19},"01M780NVTD800KMFV869YNZED6","testing-actions","Use when writing or reviewing tests for @effected\u002Fgithub-actions, @effected\u002Fgithub, @effected\u002Fsbom or @effected\u002Fcommands — stubbing the GitHub API, writing a service's layerTest or makeTest double, testing the pre\u002Fmain\u002Fpost lifecycle through Action.run, or debugging why a test hits the real network or hangs.","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Ftesting-actions\u002FSKILL.md",[],[],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":19},"01M780NPDSGFC0FCP7696NW11J","supply-chain-attestation","Use when generating a CycloneDX SBOM, checking NTIA minimum elements, building an in-toto statement or a SLSA provenance predicate, signing into a Sigstore DSSE bundle, or uploading an attestation to GitHub.","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Fsupply-chain-attestation\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":19},"01M780NGP4QNZDH8T8Q8WZ18SA","structuring-an-action","Use when laying out a new GitHub Action repository on the @effected suite, deciding where a piece of code belongs (an entry point, a step, a shared service, a shim), or reviewing an existing action's file structure against the canonical shape.","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Fstructuring-an-action\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":19},"01M780NCD52H1Y03FS83WJ8BT5","running-commands-and-tools","Use when running a subprocess in Effect v4, spawning a command, capturing stdout\u002Fstderr\u002Fexit code, checking whether a CLI tool is installed or which copy to run, running a package-manager script through the project's launcher, detaching a background process, or redacting a secret from argv or captured output.","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Frunning-commands-and-tools\u002FSKILL.md",[],[],{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":96,"categories":97,"keywords":98,"publishedAt":19},"01M780N823DWNRMSY5X2NT5MSR","release-and-publish","Use when publishing a package to npm, reading the npm registry from Effect v4, checking whether a version is already published, cutting a release tag or GitHub release from an action, applying a release-age gate, or deriving tracking tags for GitHub Actions distribution.","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Frelease-and-publish\u002FSKILL.md",[],[],{"skillNo":100,"name":101,"nameZh":6,"description":102,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":103,"categories":104,"keywords":105,"publishedAt":19},"01M780MXRF6H20KCESTSSFB3HQ","hardening-a-parser-port","Use when porting or writing a recursive-descent parser, lexer, or tree-walker over untrusted text in the @effected monorepo — the class of hardening the cloud reviewer scans for on every migration. Covers stack-overflow depth guards (on EVERY recursion surface, which a facade has N of — not two), numeric bound guards that must reject NaN and non-integers, code-point range checks scoped to formats with wide escapes, prototype-pollution, control-character rejection, and the invariant that malformed input must fail through the typed error channel, never as an unhandled defect.","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Fhardening-a-parser-port\u002FSKILL.md",[],[]]