effect 4.0.0-beta.10 → 4.0.0-beta.12

package/src/unstable/ai/McpSchema.ts

@@ -240,6 +240,11 @@ export class ClientCapabilities extends Schema.Class<ClientCapabilities>(
    * Experimental, non-standard capabilities that the client supports.
    */
   experimental: optional(Schema.Record(Schema.String, Schema.Struct({}))),
+  /**
+   * Optional extensions capabilities advertised by the client.
+   * Keys are extension identifiers following <vendor-prefix>/<extension-name> (e.g. "io.modelcontextprotocol/ui").
+   */
+  extensions: optional(Schema.Record(Schema.TemplateLiteral([Schema.String, "/", Schema.String]), Schema.Unknown)),
   /**
    * Present if the client supports listing roots.
    */
@@ -272,6 +277,11 @@ export class ServerCapabilities extends Schema.Opaque<ServerCapabilities>()(Sche
    * Experimental, non-standard capabilities that the server supports.
    */
   experimental: optional(Schema.Record(Schema.String, Schema.Struct({}))),
+  /**
+   * Optional extensions capabilities advertised by the server.
+   * Keys are extension identifiers following <vendor-prefix>/<extension-name> (e.g. "io.modelcontextprotocol/ui").
+   */
+  extensions: optional(Schema.Record(Schema.TemplateLiteral([Schema.String, "/", Schema.String]), Schema.Unknown)),
   /**
    * Present if the server supports sending log messages to the client.
    */
@@ -321,8 +331,8 @@ export class ServerCapabilities extends Schema.Opaque<ServerCapabilities>()(Sche
  * @since 4.0.0
  * @category errors
  */
-export class McpError extends Schema.Class<McpError>(
-  "@effect/ai/McpSchema/McpError"
+export class McpErrorBase extends Schema.Class<McpErrorBase>(
+  "@effect/ai/McpSchema/McpErrorBase"
 )({
   /**
    * The error type that occurred.
@@ -371,7 +381,7 @@ export const PARSE_ERROR_CODE = -32700 as const
  * @category errors
  */
 export class ParseError extends Schema.ErrorClass<ParseError>("effect/ai/McpSchema/ParseError")({
-  ...McpError.fields,
+  ...McpErrorBase.fields,
   _tag: Schema.tag("ParseError"),
   code: Schema.tag(PARSE_ERROR_CODE)
 }) {}
@@ -381,7 +391,7 @@ export class ParseError extends Schema.ErrorClass<ParseError>("effect/ai/McpSche
  * @category errors
  */
 export class InvalidRequest extends Schema.ErrorClass<InvalidRequest>("effect/ai/McpSchema/InvalidRequest")({
-  ...McpError.fields,
+  ...McpErrorBase.fields,
   _tag: Schema.tag("InvalidRequest"),
   code: Schema.tag(INVALID_REQUEST_ERROR_CODE)
 }) {}
@@ -391,7 +401,7 @@ export class InvalidRequest extends Schema.ErrorClass<InvalidRequest>("effect/ai
  * @category errors
  */
 export class MethodNotFound extends Schema.ErrorClass<MethodNotFound>("effect/ai/McpSchema/MethodNotFound")({
-  ...McpError.fields,
+  ...McpErrorBase.fields,
   _tag: Schema.tag("MethodNotFound"),
   code: Schema.tag(METHOD_NOT_FOUND_ERROR_CODE)
 }) {}
@@ -401,7 +411,7 @@ export class MethodNotFound extends Schema.ErrorClass<MethodNotFound>("effect/ai
  * @category errors
  */
 export class InvalidParams extends Schema.ErrorClass<InvalidParams>("effect/ai/McpSchema/InvalidParams")({
-  ...McpError.fields,
+  ...McpErrorBase.fields,
   _tag: Schema.tag("InvalidParams"),
   code: Schema.tag(INVALID_PARAMS_ERROR_CODE)
 }) {}
@@ -411,13 +421,26 @@ export class InvalidParams extends Schema.ErrorClass<InvalidParams>("effect/ai/M
  * @category errors
  */
 export class InternalError extends Schema.ErrorClass<InternalError>("effect/ai/McpSchema/InternalError")({
-  ...McpError.fields,
+  ...McpErrorBase.fields,
   _tag: Schema.tag("InternalError"),
   code: Schema.tag(INTERNAL_ERROR_CODE)
 }) {
   static readonly notImplemented = new InternalError({ message: "Not implemented" })
 }
 
+/**
+ * @since 4.0.0
+ * @category errors
+ */
+export const McpError = Schema.Union([
+  ParseError,
+  InvalidRequest,
+  MethodNotFound,
+  InvalidParams,
+  InternalError,
+  McpErrorBase
+])
+
 // =============================================================================
 // Ping
 // =============================================================================
@@ -615,7 +638,14 @@ export class Resource extends Schema.Class<Resource>(
    * This can be used by Hosts to display file sizes and estimate context
    * window usage.
    */
-  size: optional(Schema.Number)
+  size: optional(Schema.Number),
+  /**
+   * Optional additional metadata for the client.
+   *
+   * This parameter name is reserved by MCP to allow clients and servers to
+   * attach additional metadata to resources.
+   */
+  _meta: optional(Schema.Record(Schema.String, Schema.Unknown))
 }) {}
 
 /**
@@ -656,7 +686,12 @@ export class ResourceTemplate extends Schema.Class<ResourceTemplate>(
   /**
    * Optional annotations for the client.
    */
-  annotations: optional(Annotations)
+  annotations: optional(Annotations),
+
+  /**
+   * Optional additional metadata for the client.
+   */
+  _meta: optional(Schema.Record(Schema.String, Schema.Unknown))
 }) {}
 
 /**
@@ -673,7 +708,11 @@ export class ResourceContents extends Schema.Opaque<ResourceContents>()(Schema.S
   /**
    * The MIME type of this resource, if known.
    */
-  mimeType: optional(Schema.String)
+  mimeType: optional(Schema.String),
+  /**
+   * Optional additional metadata for the client.
+   */
+  _meta: optional(Schema.Record(Schema.String, Schema.Unknown))
 })) {}
 
 /**
@@ -1183,7 +1222,14 @@ export class Tool extends Schema.Class<Tool>(
   /**
    * Optional additional tool information.
    */
-  annotations: optional(ToolAnnotations)
+  annotations: optional(ToolAnnotations),
+  /**
+   * Optional additional metadata for the client.
+   *
+   * This parameter name is reserved by MCP to allow clients and servers to
+   * attach additional metadata to resources.
+   */
+  _meta: optional(Schema.Record(Schema.String, Schema.Unknown))
 }) {}
 
 /**

package/src/unstable/ai/McpServer.ts

@@ -9,6 +9,7 @@ import * as Layer from "../../Layer.ts"
 import * as Option from "../../Option.ts"
 import * as Queue from "../../Queue.ts"
 import * as RcMap from "../../RcMap.ts"
+import { CurrentLogLevel } from "../../References.ts"
 import * as Schema from "../../Schema.ts"
 import * as AST from "../../SchemaAST.ts"
 import * as ServiceMap from "../../ServiceMap.ts"
@@ -548,6 +549,7 @@ export const registerToolkit: <Tools extends Record<string, Tool.Any>>(
   >)
   const services = yield* Effect.services<never>()
   for (const tool of Object.values(built.tools)) {
+    const toolMeta = ServiceMap.getOrUndefined(tool.annotations, Tool.Meta)
     const mcpTool = new McpTool({
       name: tool.name,
       description: Tool.getDescription(tool),
@@ -561,7 +563,8 @@ export const registerToolkit: <Tools extends Record<string, Tool.Any>>(
         destructiveHint: ServiceMap.get(tool.annotations, Tool.Destructive),
         idempotentHint: ServiceMap.get(tool.annotations, Tool.Idempotent),
         openWorldHint: ServiceMap.get(tool.annotations, Tool.OpenWorld)
-      }
+      },
+      _meta: toolMeta
     })
     yield* registry.addTool({
       tool: mcpTool,
@@ -1075,6 +1078,7 @@ const layerHandlers = (serverInfo: {
   ClientRpcs.toLayer(
     Effect.gen(function*() {
       const server = yield* McpServer
+      let currentLogLevel = yield* CurrentLogLevel
 
       return ClientRpcs.of({
         // Requests
@@ -1105,17 +1109,51 @@ const layerHandlers = (serverInfo: {
               : LATEST_PROTOCOL_VERSION
           })
         },
-        "completion/complete": server.completion,
-        "logging/setLevel": () => InternalError.notImplemented.asEffect(),
-        "prompts/get": server.getPromptResult,
+        "completion/complete": (r) =>
+          server.completion(r).pipe(
+            Effect.provideService(CurrentLogLevel, currentLogLevel)
+          ),
+        "logging/setLevel": ({ level }) =>
+          Effect.sync(() => {
+            switch (level) {
+              case "notice":
+              case "info":
+                currentLogLevel = "Info"
+                break
+              case "error":
+                currentLogLevel = "Error"
+                break
+              case "debug":
+                currentLogLevel = "Debug"
+                break
+              case "warning":
+                currentLogLevel = "Warn"
+                break
+              case "critical":
+              case "alert":
+              case "emergency":
+                currentLogLevel = "Fatal"
+                break
+            }
+          }),
+        "prompts/get": (r) =>
+          server.getPromptResult(r).pipe(
+            Effect.provideService(CurrentLogLevel, currentLogLevel)
+          ),
         "prompts/list": () => Effect.sync(() => new ListPromptsResult({ prompts: server.prompts })),
         "resources/list": () => Effect.sync(() => new ListResourcesResult({ resources: server.resources })),
-        "resources/read": ({ uri }) => server.findResource(uri),
+        "resources/read": ({ uri }) =>
+          server.findResource(uri).pipe(
+            Effect.provideService(CurrentLogLevel, currentLogLevel)
+          ),
         "resources/subscribe": () => InternalError.notImplemented.asEffect(),
         "resources/unsubscribe": () => InternalError.notImplemented.asEffect(),
         "resources/templates/list": () =>
           Effect.sync(() => new ListResourceTemplatesResult({ resourceTemplates: server.resourceTemplates })),
-        "tools/call": server.callTool,
+        "tools/call": (r) =>
+          server.callTool(r).pipe(
+            Effect.provideService(CurrentLogLevel, currentLogLevel)
+          ),
         "tools/list": () => Effect.sync(() => new ListToolsResult({ tools: server.tools })),
 
         // Notifications

package/src/unstable/ai/Tool.ts

@@ -1661,6 +1661,21 @@ export const getJsonSchemaFromSchema = <S extends Schema.Top>(schema: S, options
  */
 export class Title extends ServiceMap.Service<Title, string>()("effect/ai/Tool/Title") {}
 
+/**
+ * Annotation for providing tool metadata for MCP.
+ *
+ * @example
+ * ```ts
+ * import { Tool } from "effect/unstable/ai"
+ *
+ * const myCalculatorUi = Tool.make("calculator_ui", {})
+ *   .annotate(Tool.Meta, { ui: { resourceUri: "ui://example/calculator-ui" } })
+ * ```
+ * @since 1.0.0
+ * @category annotations
+ */
+export class Meta extends ServiceMap.Service<Meta, Record<string, unknown>>()("effect/ai/Tool/Meta") {}
+
 /**
  * Annotation indicating whether a tool only reads data without making changes.
  *

package/src/unstable/cli/CliOutput.ts

@@ -499,14 +499,53 @@ const formatHelpDocImpl = (doc: HelpDoc, colors: ColorFunctions): string => {
 
   // Subcommands section
   if (doc.subcommands && doc.subcommands.length > 0) {
-    sections.push(colors.bold("SUBCOMMANDS"))
+    const ungrouped = doc.subcommands.find((group) => group.group === undefined)
+
+    if (ungrouped) {
+      sections.push(colors.bold("SUBCOMMANDS"))
+      sections.push(renderTable(
+        ungrouped.commands.map((sub) => ({
+          left: colors.cyan(sub.name),
+          right: sub.shortDescription ?? sub.description
+        })),
+        20
+      ))
+      if (doc.subcommands.length > 1) {
+        sections.push("")
+      }
+    }
 
-    const subcommandRows: Array<Row> = doc.subcommands.map((sub) => ({
-      left: colors.cyan(sub.name),
-      right: sub.description
-    }))
+    for (const group of doc.subcommands) {
+      if (group.group === undefined) continue
+      sections.push(colors.bold(`${group.group}:`))
+      sections.push(renderTable(
+        group.commands.map((sub) => ({
+          left: colors.cyan(sub.name),
+          right: sub.shortDescription ?? sub.description
+        })),
+        20
+      ))
+      sections.push("")
+    }
+  }
 
-    sections.push(renderTable(subcommandRows, 20))
+  // Examples section
+  if (doc.examples && doc.examples.length > 0) {
+    sections.push(colors.bold("EXAMPLES"))
+
+    let first = true
+    let previousHadDescription = false
+    for (const example of doc.examples) {
+      if (example.description) {
+        if (!first) sections.push("")
+        sections.push(`  ${colors.dim(`# ${example.description}`)}`)
+      } else if (previousHadDescription) {
+        sections.push("")
+      }
+      sections.push(`  ${colors.cyan(example.command)}`)
+      first = false
+      previousHadDescription = !!example.description
+    }
     sections.push("")
   }