@dual-os/sdk 0.0.0-stage → 0.8.0-next.0

package/src/Mcp.ts

@@ -0,0 +1,299 @@
+/**
+ * A Model Context Protocol client over Streamable HTTP: the session generated plugins call tools
+ * through and the CLI lists them with.
+ *
+ * @since 0.0.0
+ */
+import {
+  Array,
+  Boolean,
+  Effect,
+  MutableRef,
+  Number,
+  Option,
+  Ref,
+  Result,
+  Schema,
+  Stream,
+  String,
+  pipe,
+} from "effect";
+import type { Record } from "effect";
+
+import * as Sse from "effect/encoding/Sse";
+import { HttpClient, HttpClientRequest } from "effect/http";
+import type { HttpClientResponse } from "effect/http";
+
+/**
+ * A JSON-RPC error, SSE parsing error, or request that got no response.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export class McpError extends Schema.TaggedError<McpError>()("McpError", {
+  cause: Schema.optional(Schema.Defect()),
+  message: Schema.String,
+}) {}
+
+const protocolVersion = "2025-06-18";
+
+/**
+ * A server's or client's name and version.
+ *
+ * @since 0.0.0
+ * @category schemas
+ */
+export type Implementation = typeof Implementation.Type;
+export const Implementation = Schema.Struct({
+  name: Schema.String,
+  title: Schema.optionalKey(Schema.String),
+  version: Schema.String,
+});
+
+/**
+ * A tool a server lists: its name, description and the JSON Schemas of its arguments and, when it
+ * declares one, its structured output.
+ *
+ * @since 0.0.0
+ * @category schemas
+ */
+export type Tool = typeof Tool.Type;
+export const Tool = Schema.Struct({
+  annotations: Schema.optionalKey(Schema.Struct({ title: Schema.optionalKey(Schema.String) })),
+  description: Schema.optionalKey(Schema.String),
+  inputSchema: Schema.Record(Schema.String, Schema.Unknown),
+  name: Schema.String,
+  outputSchema: Schema.optionalKey(Schema.Record(Schema.String, Schema.Unknown)),
+  title: Schema.optionalKey(Schema.String),
+});
+
+type ListToolsResult = typeof ListToolsResult.Type;
+const ListToolsResult = Schema.Struct({
+  nextCursor: Schema.optionalKey(Schema.String),
+  tools: Schema.Array(Tool),
+});
+
+type ContentBlock = typeof ContentBlock.Type;
+const ContentBlock = Schema.StructWithRest(
+  Schema.Struct({ text: Schema.optionalKey(Schema.String), type: Schema.String }),
+  [Schema.Record(Schema.String, Schema.Unknown)],
+);
+
+/**
+ * What a tool call returns: its content blocks and, when it declares an output schema, its
+ * structured content.
+ *
+ * @since 0.0.0
+ * @category schemas
+ */
+export type CallToolResult = typeof CallToolResult.Type;
+export const CallToolResult = Schema.Struct({
+  content: Schema.Array(ContentBlock),
+  isError: Schema.optionalKey(Schema.Boolean),
+  structuredContent: Schema.optionalKey(Schema.Unknown),
+});
+
+type InitializeResult = typeof InitializeResult.Type;
+const InitializeResult = Schema.Struct({
+  protocolVersion: Schema.String,
+  serverInfo: Implementation,
+});
+
+type Message = typeof Message.Type;
+const Message = Schema.Struct({
+  error: Schema.optionalKey(Schema.Struct({ message: Schema.String })),
+  id: Schema.optionalKey(Schema.Unknown),
+  result: Schema.optionalKey(Schema.Unknown),
+});
+
+const responseTo = Effect.fnUntraced(function* (
+  id: number,
+  method: string,
+  response: HttpClientResponse.HttpClientResponse,
+) {
+  const payloads = Boolean.match(
+    pipe(response.headers["content-type"] ?? "", String.startsWith("text/event-stream")),
+    {
+      onFalse: () => Stream.fromEffect(response.text),
+      onTrue: () =>
+        Stream.unwrap(
+          Effect.sync(() => {
+            const events = MutableRef.make(Array.empty<string>());
+            const parser = Sse.makeParser(event => {
+              if (event._tag === "Event") MutableRef.update(events, Array.append(event.data));
+            });
+            return pipe(
+              response.stream,
+              Stream.decodeText(),
+              Stream.mapEffect(chunk => {
+                const error = parser.feed(chunk);
+                if (error !== undefined) {
+                  return Effect.fail(McpError.make({ cause: error, message: error.message }));
+                }
+                const ready = MutableRef.get(events);
+                MutableRef.set(events, Array.empty());
+                return Effect.succeed(ready);
+              }),
+              Stream.flatMap(Stream.fromIterable),
+            );
+          }),
+        ),
+    },
+  );
+  const found = yield* pipe(
+    payloads,
+    Stream.filterMap(payload =>
+      Result.fromOption(
+        Option.filter(
+          Schema.decodeOption(Schema.fromJsonString(Message))(payload),
+          message =>
+            message.id === id && (message.result !== undefined || message.error !== undefined),
+        ),
+        () => payload,
+      ),
+    ),
+    Stream.runHead,
+  );
+  return yield* Effect.fromOption(found, () =>
+    McpError.make({ message: `${method} got no response` }),
+  );
+});
+
+/**
+ * Opens a session with the server at `endpoint`: initializes it and returns its information and a
+ * `request` that sends one JSON-RPC request and returns its result. Closing the scope ends the
+ * session. `headers` carries the credentials the server asks for.
+ *
+ * @since 0.0.0
+ * @category constructors
+ */
+export const connect = Effect.fn("Mcp.connect")(function* (
+  client: HttpClient.HttpClient,
+  endpoint: string,
+  headers: Record.ReadonlyRecord<string, string>,
+) {
+  const checked = HttpClient.filterStatusOk(client);
+  const post = Effect.fnUntraced(function* (
+    version: string,
+    session: Option.Option<string>,
+    body: Record.ReadonlyRecord<string, unknown>,
+  ) {
+    return yield* checked.execute(
+      pipe(
+        HttpClientRequest.post(endpoint),
+        HttpClientRequest.setHeaders({
+          ...headers,
+          accept: "application/json, text/event-stream",
+          "mcp-protocol-version": version,
+          ...Option.match(session, {
+            onNone: () => ({}),
+            onSome: id => ({ "mcp-session-id": id }),
+          }),
+        }),
+        HttpClientRequest.bodyJsonUnsafe({ jsonrpc: "2.0", ...body }),
+      ),
+    );
+  });
+  const call = Effect.fnUntraced(function* (
+    version: string,
+    session: Option.Option<string>,
+    id: number,
+    method: string,
+    params: Record.ReadonlyRecord<string, unknown>,
+  ) {
+    const response = yield* post(version, session, { id, method, params });
+    const message = yield* responseTo(id, method, response);
+    if (message.error !== undefined) {
+      return yield* McpError.make({ message: `${method}: ${message.error.message}` });
+    }
+    return {
+      result: message.result,
+      session: Option.orElse(
+        Option.fromNullishOr(response.headers["mcp-session-id"]),
+        () => session,
+      ),
+    };
+  });
+
+  const negotiatedVersion = yield* Ref.make(protocolVersion);
+  const initialized = yield* Effect.acquireRelease(
+    call(protocolVersion, Option.none(), 0, "initialize", {
+      capabilities: {},
+      clientInfo: { name: "dual", version: "1" },
+      protocolVersion,
+    }),
+    opened =>
+      Option.match(opened.session, {
+        onNone: () => Effect.void,
+        onSome: id =>
+          Effect.flatMap(Ref.get(negotiatedVersion), version =>
+            Effect.ignore(
+              client.execute(
+                pipe(
+                  HttpClientRequest.delete(endpoint),
+                  HttpClientRequest.setHeaders({
+                    ...headers,
+                    "mcp-protocol-version": version,
+                    "mcp-session-id": id,
+                  }),
+                ),
+              ),
+            ),
+          ),
+      }),
+  );
+  const server = yield* Schema.decodeUnknownEffect(InitializeResult)(initialized.result);
+  if (server.protocolVersion !== protocolVersion && server.protocolVersion !== "2025-03-26") {
+    return yield* McpError.make({
+      message: `Unsupported MCP protocol version ${server.protocolVersion}`,
+    });
+  }
+  yield* Ref.set(negotiatedVersion, server.protocolVersion);
+  yield* post(server.protocolVersion, initialized.session, { method: "notifications/initialized" });
+  const ids = yield* Ref.make(1);
+  const request = Effect.fn("Mcp.request")(function* (
+    method: string,
+    params: Record.ReadonlyRecord<string, unknown>,
+  ) {
+    const called = yield* call(
+      server.protocolVersion,
+      initialized.session,
+      yield* Ref.getAndUpdate(ids, Number.increment),
+      method,
+      params,
+    );
+    return called.result;
+  });
+  return { request, server: server.serverInfo };
+});
+
+/**
+ * Lists every tool of the server at `endpoint`, following its pages, in a session of its own.
+ *
+ * @since 0.0.0
+ * @category constructors
+ */
+export const listTools = Effect.fn("Mcp.listTools")(function* (
+  client: HttpClient.HttpClient,
+  endpoint: string,
+  headers: Record.ReadonlyRecord<string, string>,
+) {
+  const session = yield* connect(client, endpoint, headers);
+  const tools = yield* Stream.runCollect(
+    Stream.paginate(
+      {},
+      Effect.fnUntraced(function* (params: { cursor?: string }) {
+        const page = yield* Schema.decodeUnknownEffect(ListToolsResult)(
+          yield* session.request("tools/list", params),
+        );
+        return [
+          page.tools,
+          Option.map(Option.fromUndefinedOr(page.nextCursor), cursor => ({ cursor })),
+        ] as const;
+      }),
+    ),
+  );
+  return { server: session.server, tools };
+}, Effect.scoped);
+
+export * as Mcp from "./Mcp.ts";

package/src/OAuth2TokenRefresher.ts

@@ -0,0 +1,22 @@
+/**
+ * Host service that refreshes OAuth2 tokens for SDK auth execution.
+ *
+ * @since 0.0.0
+ */
+import { Context, type Effect } from "effect";
+
+import type * as AuthMethod from "./AuthMethod.ts";
+
+/** @since 0.0.0 @category services */
+export class Service extends Context.Service<
+  Service,
+  {
+    readonly refresh: (input: {
+      readonly method: AuthMethod.Any;
+      readonly setup: unknown;
+      readonly refreshToken: string;
+    }) => Effect.Effect<AuthMethod.OAuth2TokenResponse, unknown>;
+  }
+>()("@dual-os/sdk/AuthMethod/OAuth2TokenRefresher") {}
+
+export * as OAuth2TokenRefresher from "./OAuth2TokenRefresher.ts";