effect-v4-mcp
Use when building, wiring, testing or reviewing an MCP server on Effect v4 — effect/ai's McpServer, Tool and Toolkit plus the @effected/mcp-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/call, server/discover, 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
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 8
- Forks
- 2
01 前言 Front Matter
- name
- effect-v4-mcp
- description
- Use when building, wiring, testing or reviewing an MCP server on Effect v4 — effect/ai's McpServer, Tool and Toolkit plus the @effected/mcp-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/call, server/discover, 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
02 资源文件 4
- 参考文档references/resources.md6.3 KB
- 参考文档references/server-wiring.md27.3 KB
- 参考文档references/testing.md28.2 KB
- 参考文档references/tools.md30.7 KB
03 SKILL.md 正文
Effect v4 MCP servers
Core owns the protocol, tool registration and the wire format:
effect/ai's McpServer, Tool and Toolkit parse requests,
serve JSON Schema, and shape a tools/call result. @effected/mcp-kit owns the
stdio boundary — keeping every log line and every crash report off stdout,
which is the JSON-RPC wire — plus tool-failure shaping and strict-by-default
registration. @effected/mcp-kit/testing owns the in-process and spawned test
clients.
| construct | import | reach for it when |
|---|---|---|
McpServer, Tool, Toolkit, McpSchema |
effect/ai |
declaring the server, its tools, and the protocol-level schemas |
McpStdio |
@effected/mcp-kit |
launching a stdio server without a stray log line or crash report reaching the wire |
McpToolkit |
@effected/mcp-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 |
ToolFailure |
@effected/mcp-kit |
folding remediation into a declared failure's message — core sends only error.message |
ToolInputSchema |
@effected/mcp-kit |
naming unknown keys in a Tool.dynamic tool's raw payload, inside its own handler — core never validates a raw JSON Schema |
McpToolkit.unionTool / unionHandler |
@effected/mcp-kit |
a tool whose parameters are a Schema.Union of objects, rejected like a Tool.make decode failure |
ToolOutcome |
@effected/mcp-kit |
an expected domain error the agent should branch on as data: the ok: false envelope on the success channel, where structuredContent arrives |
ToolReplay |
@effected/mcp-kit |
a write tool whose retried call with the same idempotency key returns the first result instead of running again |
StdioCapture |
@effected/mcp-kit/node |
an in-process library (a test runner, a bundler) that writes to stdout from inside a handler |
Exclusive |
@effected/kit |
handlers that mutate process-global state (cwd, env, a patched stream) must run one at a time, under a timeout |
ProcessScope |
@effected/kit |
a chdir or an env patch restored when the request's scope closes |
McpGuard |
@effected/mcp-kit/guard |
crash guards installed before the server graph loads, with an exit-before-connect policy |
ProcessGuard |
@effected/kit/guard |
the same guards for a server on another transport (an LSP), which reports markConnected itself |
Remediation, LaunchContext |
@effected/kit |
a structured { hint, suggestedTool? } shape, or resolving an agent-launched project directory |
McpHarness, McpProcess, McpProbe, McpToolAudit |
@effected/mcp-kit/testing |
testing the server layer in process, a spawned child, a packed install, or auditing what tools/list actually serves |
Standards
- Launch with
McpStdio.launchandNodeRuntime.runMain(program, { teardown: McpStdio.teardown })— never a bareLayer.launch. - Register toolkits through
McpToolkit.layer, not core'sMcpServer.toolkitdirectly, so every tool is strict unless it opts out. - Fold remediation into a declared failure's message with
ToolFailureat construction — nothing else reaches the agent. - Capture a service a handler needs for the server's lifetime in the effect form of
Toolkit.toLayer; declare a service inTool.make'sdependenciesonly when it varies per request, and meet it withMcpServer.middleware, or, when a declared service is fixed for the server's lifetime, withMcpToolkit.provideLifetime—Layer.providecannot — see Defining a tool. - Pass the toolkit layer to
McpStdio.layerasregistrations, so it builds before the first request with its logs on stderr. - Return an expected error the agent branches on through
ToolOutcome.catchAsEnvelope, written inline in the handler'spipe. - Test the server layer in process with
McpHarness; test a built bin withMcpProcess/McpProbe.
Footguns
- Hand-wiring
McpServer.layerStdiowithoutMcpStdio.layerleaves a malformed line unanswered — core skips it silently where JSON-RPC requires a-32700/-32600reply — see The stdin guard. - 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.fresharound the server alone, toolkit outside, serves no tools — seeMcpStdio.layer. - On a serverless host such as Cloudflare Workers,
McpServer.layerHttpkeeps a long-lived server whose fibers and timers outlive the request; serve withMcpServer.layerHttpRequestScopedinstead, which builds one server per POST. Itsprotocolstake only sessionless adapters (McpProtocol.v2026_07_28) — the type rejects a sessionful one, and the layer fails withIllegalArgumentErrorif one gets through — and it has no subscription or session-termination options. runMain's own failure report runs outside anything the program provides and lands on stdout, the wire — seeMcpStdio.launch.- Stdin EOF ends the server with exit
0, even under the default teardown; SIGINT and SIGTERM still exit130there — seeMcpStdio.teardown. - A declared failure reaches the agent as message text only, never
structuredContent, under either failure mode, soToolRefusal.refusetakes no data argument — see Failures on the wire. injectCrash: { at: "connected" }reports on a later tick, after the first responses a test may read; wait withMcpProcess.stderrUntil, never onestderrSoFarread — seeMcpGuard.run.InvalidParamsmoves to anisErrortool result on the newer protocol revisions only for a known tool's own bad parameters — an unknown tool or non-objectargumentsstays a JSON-RPC error on every revision — see Failures on the wire.- A top-level union
parametersschema dies the server at registration, not at the first call — useMcpToolkit.unionTool— see Failures on the wire. - A pattern-keyed
Schema.Recordparameter is served open unless its key RegExp has theuflag, while core still rejects a non-matching key — see Strict input. - A
Schema.Stringsuccess is sent as raw text with nostructuredContenton the stateful revisions, and as JSON-quoted text plus a stringstructuredContenton2026-07-28— see Failures on the wire. ToolOutcome.catchAsEnvelopebound to aconstbefore it is applied loses the piped effect's error type, so a misspelled tag compiles and never matches — see Theok: falseenvelope.- A
ToolReplaykey 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. ToolReplay.successdrops the struct's own.check(...)refinements; apply checks to its result — see Idempotent replay.StdioCaptureleaks 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.Exclusive.runis not reentrant: a nestedrunon the same lane waits on its own caller's permit and fails as the outerExclusiveTimeout.Effect.promiseinside a lane abandons the promise on timeout; useExclusive.promise, andabandon: truefor a promise that ignores its signal. A boundary test can hold the line:SourceBoundary.scan({ root, rules: [{ promiseInExclusive: {} }] })from@effected/workspaces/testingflags either call lexically inside alane.run(body (passlanesfor a lane received as a parameter; a helper called from the body is not seen).Schema.Struct({})is notTool.EmptyParams— it fails server registration outright — see Defining a tool.- Closing stdin does not cancel requests in flight: the server answers them, then stops — so
McpHarness.closenever releases a wait on a request that never completes;McpHarness.stopdoes — seeMcpStdio.teardown. - A resource read carries its registered
mimeTypefor everycontentform, a bare string or bytes included; a fullReadResourceResultis sent as written — see ThemimeTypeon a read. - 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.
- An
Effect.timeoutguard insideit.effectnever fires —TestClocknever advances on its own, so the test hangs until vitest's own default timeout kills it instead. Useit.liveor a real-clocklayer(...)— see Timeouts. - Code placed after a completed
Effect.provideof 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. UseMcpHarness— see The in-process harness.
Additional resources
- server-wiring.md — the complete
main.ts,McpStdio.layer/launch/teardown, protocol ordering, crash guards, and launch-context project-directory resolution. Load when: assembling or reviewing a server'smain.ts, or debugging why a failure or a log line reached the wire. - tools.md — defining a tool, strict input reporting, failures on the wire, the
ToolOutcomeok: falseenvelope,ToolReplayidempotent replay, andStdioCapture. Load when: declaring aTool.make, wiring aToolkit, 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. - resources.md —
McpServer.resource's single and URI-template forms, themimeTypea 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 amimeTypeit expects. - testing.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,McpProbeandMcpToolAudit. effected-packages' mcp-kit.md — the@effected/mcp-kitpackage 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.
Anchors in this skill and its references cite the vendored tag at
.repos/effect/packages/effect/src/; a consumer without that tree searches
node_modules/effect/src by symbol name instead of by line number.
04 同仓库更多 Skills
testing-actions
Use when writing or reviewing tests for @effected/github-actions, @effected/github, @effected/sbom or @effected/commands — stubbing the GitHub API, writing a service's layerTest or makeTest double, testing the pre/main/post lifecycle through Action.run, or debugging why a test hits the real network or hangs.
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.
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.
running-commands-and-tools
Use when running a subprocess in Effect v4, spawning a command, capturing stdout/stderr/exit 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.
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.
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.