@smthrs/mcp 0.0.0-stage → 1.0.0-rc.3

package/docs/guides/validate-structured-output.md

@@ -0,0 +1,103 @@
+---
+title: "Validate structured output"
+description: "What the client checks when a tool declares an outputSchema and returns structuredContent: the five supported JSON Schema keywords, what is ignored, and how a violation is reported."
+sidebar:
+  order: 5
+---
+
+A tool may declare an `outputSchema` and answer with `structuredContent`. When
+both are present, this client validates the value against that schema before
+returning it, so a downstream consumer never sees structured output the server's
+own contract rejects.
+
+You do not switch this on. It applies whenever the catalog entry declared a
+schema.
+
+## What is checked
+
+Output schemas are compiled once at catalog load. Type unions use Effect
+Schema, with compatibility checks for exactly five supported keywords:
+
+| Keyword      | Behavior                                                                                                                     |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| `type`       | All seven JSON Schema type names (`null`, `boolean`, `object`, `array`, `number`, `string`, `integer`), and arrays of names. |
+| `required`   | Each named string property must be an own property of the object.                                                            |
+| `properties` | Each declared property present in the value is validated against its subschema.                                              |
+| `items`      | A single schema applied to every element of an array. Tuple form is not supported.                                           |
+| `enum`       | The value must equal one of the declared values, compared by JSON value rather than by reference.                            |
+
+Validation recurses through `properties` and `items`, so a schema three levels
+deep is checked three levels deep. Types, required names, child validators and
+enum membership indexes are retained from the frozen catalog, including
+composite JSON enum values. Compilation and result
+validation yield between bounded work slices so host timers and Effect
+interruption can run during large checks. The request timeout still covers the
+transport request. An outer Effect timeout can also interrupt result validation.
+
+## What is ignored
+
+Every other keyword. `minLength`, `pattern`, `additionalProperties`, `oneOf`,
+`$ref`, and the rest are skipped. `integer` accepts every number for which
+`Number.isInteger` is true, including values outside the safe-integer range.
+This compatibility contract is narrower than a general JSON Schema importer.
+
+This is a deliberate choice, not an oversight: a partial validator that rejected
+data for a constraint it does not implement would be worse than one that admits
+what it cannot judge. A tool whose contract depends on `pattern` should validate
+its own output.
+
+## How a violation is reported
+
+A violation fails with `invalid_response`, naming the expected constraint but
+withholding the property path:
+
+```text
+MCP server "reports" returned structuredContent that its own outputSchema
+rejects: expected number; property path withheld
+```
+
+Neither property names nor values are safe to echo into model-facing errors.
+A trusted host may inspect the path and rejected response through the optional
+[private diagnostic observer](../api.md#diagnostics). Its details are bounded
+and wrapped in `Redacted`, not implicitly logged.
+
+Validation never mutates or replaces the server's value. It either passes it
+through unchanged or fails.
+
+## The shapes a result may take
+
+Three combinations are all valid:
+
+| Result                   | Outcome                                                |
+| ------------------------ | ------------------------------------------------------ |
+| `content` only           | Returned as sent, with `structuredContent: undefined`. |
+| `structuredContent` only | Accepted, and returned with `content: []`.             |
+| Both                     | Both returned.                                         |
+
+A result carrying neither fails with `invalid_response`. A `content` value that
+is not an array, a `content` element that is not an object, an `isError` that is
+not a boolean, or a `structuredContent` that is not a JSON object all fail the
+same way.
+
+Without a declared `outputSchema`, any JSON-object `structuredContent` passes
+through unchanged.
+
+## Reading it downstream
+
+`McpFlows.Result` carries the field through the flow's output schema, so a cell
+sees it directly:
+
+```js
+const report = await ctx.call("mcp/reports/summary", { period: "2026-Q1" })
+const rows = report.structuredContent?.rows ?? []
+```
+
+`structuredContent` is optional on the flow output, so a tool that never sends
+one produces a result with the field absent rather than null.
+
+## Next
+
+- [Handle a failed tool call](./handle-a-failed-tool-call.md): the other
+  failures a call can produce.
+- [Bound an untrusted server](./bound-an-untrusted-server.md): the limits that
+  apply before validation ever runs.

package/docs/installation.md

@@ -0,0 +1,117 @@
+---
+title: "Installation"
+description: "Install @smthrs/mcp, the platform services a stdio connection requires, the import forms, and the packages a host composition adds."
+sidebar:
+  order: 1
+---
+
+## Availability
+
+`@smthrs/mcp` is not published to npm yet. Its source is on
+[GitHub](https://github.com/smithersai/smithers), and the `smthrs` command line
+is the worked example of everything on this page: it composes this package
+behind `--mcp-config`.
+
+Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+## Requirements
+
+- Node.js 26.4.0 or later.
+- [`effect`](https://effect.website) 4.0.0-rc.115, a peer dependency and the
+  version this package is built against. Connection and tool-call operations
+  return an `Effect`, and every schema is an `effect/Schema`. `McpFlows.mcp`
+  is synchronous and returns a `FlowBinding.Source`; `Diagnostics.layer` is a
+  `Layer` constructor.
+
+The package ships as both ESM and CommonJS with TypeScript declarations. The
+`@smthrs/*` packages the adapter composes are ordinary dependencies and install
+with it.
+
+## Provide a process spawner
+
+Every constructor that opens a connection requires two services from the
+caller's environment:
+
+| Requirement           | Why                                                                                     |
+| --------------------- | --------------------------------------------------------------------------------------- |
+| `ChildProcessSpawner` | An MCP server is a subprocess. The spawner is Effect's process port, not a Node import. |
+| `Scope`               | The connection is scoped. Closing the scope tears the server process down.              |
+
+On Node, `@effect/platform-node` provides the spawner:
+
+```bash
+pnpm add @effect/platform-node@4.0.0-rc.115 @effect/platform-node-shared@4.0.0-rc.115
+```
+
+```ts
+import { NodeServices } from "@effect/platform-node"
+import { Effect } from "effect"
+
+const runnable = Effect.provide(Effect.scoped(program), NodeServices.layer)
+```
+
+These are the same services a host already provides for
+`StandardFlows.shell`, so a composition that runs shell commands already has
+them.
+
+## Import forms
+
+The root entry point re-exports every module as a namespace:
+
+```ts
+import { McpClient, McpError, McpFlows } from "@smthrs/mcp"
+```
+
+Each module is also importable from its own subpath, which is the form the
+[API reference](./api.md) uses in its examples:
+
+```ts
+import * as McpClient from "@smthrs/mcp/McpClient"
+import * as McpFlows from "@smthrs/mcp/McpFlows"
+```
+
+`McpError` is a namespace either way. The error class is `McpError.McpError`:
+
+```ts
+import * as McpError from "@smthrs/mcp/McpError"
+
+const failure = new McpError.McpError({ code: "timeout", message: "...", server: "github" })
+```
+
+Two subpath forms are not public: `@smthrs/mcp/internal/*` and
+`@smthrs/mcp/*/index`. Both are blocked in the package's export map, so the
+JSON-RPC codec and the stdio transport are not importable.
+`@smthrs/mcp/package.json` is exported.
+
+## What a host composition adds
+
+The projected `FlowBinding.Source` is only useful to something that composes a
+flow catalog. [`@smthrs/harness`](/api/harness),
+[`@smthrs/capability`](/api/capability), and [`@smthrs/core`](/api/core)
+are runtime dependencies of this package and install with it:
+
+- `@smthrs/harness` owns `FlowBinding`, the contract this package implements.
+  `FlowBinding.catalog` merges this source with the others a host offers. See
+  [Bind flows](/pkg/harness/guides/bind-flows).
+- `@smthrs/capability` owns the action vocabulary `McpFlows.capabilities` is
+  derived from.
+
+What a host adds is the thing that runs the cell loop:
+
+The runtime `@smthrs/*` dependencies of this package are `@smthrs/canonical`,
+`@smthrs/capability`, `@smthrs/core`, `@smthrs/harness`, `@smthrs/journal`,
+and `@smthrs/kernel`. `@smthrs/registry` and `@smthrs/model` are development
+dependencies only. A host that imports any of them directly declares it in its
+own manifest.
+
+[`@smthrs/agent`](/api/agent) takes the projected sources as its `flows` option,
+alongside `StandardFlows.filesystem` and the rest.
+
+The CLI already wires all of this. `smthrs --mcp-config <path>` connects every
+server the file names and adds its flows to a run's catalog; see
+[Configure servers for the CLI](./guides/configure-servers-for-the-cli.md).
+
+## Next step
+
+Connect to a real server and call one of its tools in the
+[Quickstart](./quickstart.md).

package/docs/quickstart.md

@@ -0,0 +1,200 @@
+---
+title: "Quickstart"
+description: "Connect to a real MCP server over stdio, call one of its tools, and read the flows the adapter projects from its catalog."
+sidebar:
+  order: 2
+---
+
+This quickstart connects to a real MCP server in its own process, calls two of
+its tools, and prints the flows the adapter projects from its catalog. Nothing
+is mocked: the server is a separate program speaking newline-delimited JSON-RPC,
+which is the only thing MCP is.
+
+By the end you will have seen both halves of this package. `McpClient` owns the
+session, and `McpFlows` turns that session's catalog into flows a Smithers run
+can call.
+
+## Prerequisites
+
+Node.js 26.4.0 or later, and a project that depends on `@smthrs/mcp`,
+`@effect/platform-node`, and `effect`. See
+[Installation](./installation.md).
+
+## Write the server
+
+Create `quickstart-server.mjs`. It imports nothing, which is the point: the
+process on the other end of an MCP session need not be yours.
+
+```js
+import { createInterface } from "node:readline"
+
+const tools = [
+  {
+    name: "word_count",
+    description: "Counts the words in a piece of text",
+    inputSchema: {
+      type: "object",
+      properties: { text: { type: "string" } },
+      required: ["text"]
+    },
+    outputSchema: {
+      type: "object",
+      properties: { words: { type: "integer" } },
+      required: ["words"]
+    }
+  },
+  {
+    name: "explode",
+    description: "Always reports a tool-level failure",
+    inputSchema: { type: "object", properties: {} }
+  }
+]
+
+const send = (message) => process.stdout.write(`${JSON.stringify(message)}\n`)
+
+createInterface({ input: process.stdin }).on("line", (line) => {
+  const request = JSON.parse(line)
+  if (request.method === "initialize") {
+    send({
+      jsonrpc: "2.0",
+      id: request.id,
+      result: {
+        protocolVersion: "2025-06-18",
+        capabilities: { tools: {} },
+        serverInfo: { name: "quickstart", version: "1.0.0" }
+      }
+    })
+    return
+  }
+  if (request.method === "tools/list") {
+    send({ jsonrpc: "2.0", id: request.id, result: { tools } })
+    return
+  }
+  if (request.method === "tools/call") {
+    if (request.params.name === "explode") {
+      send({
+        jsonrpc: "2.0",
+        id: request.id,
+        result: { content: [{ type: "text", text: "the tool refused" }], isError: true }
+      })
+      return
+    }
+    const text = String(request.params.arguments.text ?? "")
+    const words = text.split(/\s+/u).filter((word) => word.length > 0).length
+    send({
+      jsonrpc: "2.0",
+      id: request.id,
+      result: {
+        content: [{ type: "text", text: String(words) }],
+        structuredContent: { words },
+        isError: false
+      }
+    })
+  }
+})
+```
+
+Two details matter later. The `initialize` result declares a `tools`
+capability, which this client requires: a server that serves no tools is
+refused during the handshake. And `explode` answers a successful JSON-RPC reply
+carrying `isError: true`, which is MCP's way of saying "the tool ran and
+reported a problem", not "the call failed".
+
+## Connect and call
+
+Create `quickstart.ts`. `McpClient.connect` spawns the server, completes the
+handshake, and fetches the tool catalog once, up front:
+
+```ts
+import { NodeServices } from "@effect/platform-node"
+import * as McpClient from "@smthrs/mcp/McpClient"
+import * as McpFlows from "@smthrs/mcp/McpFlows"
+import { Effect } from "effect"
+
+const program = Effect.scoped(Effect.gen(function*() {
+  const client = yield* McpClient.connect({
+    server: "quickstart",
+    command: process.execPath,
+    args: ["quickstart-server.mjs"]
+  })
+
+  const counted = yield* client.callTool("word_count", { text: "durable flows release notes" })
+  const refused = yield* client.callTool("explode", {})
+
+  const source = McpFlows.mcp(client)
+  const bindings = yield* source.bindings()
+
+  return {
+    tools: client.tools.map((tool) => tool.name),
+    counted,
+    refused,
+    sourceName: source.name,
+    flowNames: bindings.map((binding) => binding.descriptor.name)
+  }
+}))
+
+console.log(await Effect.runPromise(Effect.provide(program, NodeServices.layer)))
+```
+
+`Effect.scoped` is what owns the subprocess. When the scope closes, the server
+process is torn down and every request still outstanding fails with
+`connection_closed` rather than hanging.
+
+## Run it
+
+Run the file with a TypeScript runner:
+
+```bash
+npx tsx quickstart.ts
+```
+
+```text
+{
+  tools: [ 'word_count', 'explode' ],
+  counted: {
+    content: [ { type: 'text', text: '4' } ],
+    isError: false,
+    structuredContent: { words: 4 }
+  },
+  refused: {
+    content: [ { type: 'text', text: 'the tool refused' } ],
+    isError: true,
+    structuredContent: undefined
+  },
+  sourceName: 'mcp/quickstart',
+  flowNames: [ 'mcp/quickstart/word_count', 'mcp/quickstart/explode' ]
+}
+```
+
+## What just happened
+
+`connect` spawned the process, negotiated `2025-06-18`, sent
+`notifications/initialized`, and walked `tools/list` to the end of its cursor
+before returning. `client.tools` is that catalog, and it is a snapshot: this
+client never re-polls it.
+
+`callTool("explode", {})` **succeeded**. Its `isError: true` came back in the
+success channel, because a tool that runs and reports a problem is data. Only a
+failure of the session itself, a server that will not start, a closed pipe, a
+reply this client cannot parse, becomes an `McpError`. See
+[Handle a failed tool call](./guides/handle-a-failed-tool-call.md).
+
+`word_count` declared an `outputSchema`, so its `structuredContent` was checked
+against that schema before it was returned. `explode` declared none, so nothing
+was checked. See
+[Validate structured output](./guides/validate-structured-output.md).
+
+`McpFlows.mcp(client)` produced a `FlowBinding.Source` named `mcp/quickstart`
+holding one binding per tool. Each binding's descriptor carries the server's own
+`inputSchema` as its input document, so a model reading the catalog sees
+`{ type: "object", properties: { text: { type: "string" } }, required: ["text"] }`
+rather than this package's permissive record type.
+
+## Next steps
+
+- [A remote tool as a flow](./concepts/tools-as-flows.md): what the projection
+  produces, and why nothing downstream knows the flow is remote.
+- [Grant authority to MCP tools](./guides/grant-authority-to-mcp-tools.md): the
+  one step between a projected source and a cell that can actually call it.
+- [Select the tools a run sees](./guides/select-the-tools-a-run-sees.md): keep a
+  fifty-tool server out of the model's context window.