feat(#1810): McpClient.resourceSkills() + McpServer resource DSL

Final slice (3/3) of the v0.5.0 MCP-as-skills unification. MCP
resources — URI-addressable data items — become Skills with the
same shape as tool-skills and prompt-skills from earlier slices.
Skill args are ignored at invocation; the resource URI is captured
in the skill's closure.

Server side (McpServer):
- New RegisteredResource internal data class.
- McpServer ctor gains registeredResources list.
- McpExposeBuilder.resource(uri, name, description?, mimeType?,
  content: () -> String) DSL — registers a static resource.
- handleInitialize declares {"resources": {"listChanged": false,
  "subscribe": false}} in capabilities when resources are
  registered.
- New handlers: resources/list and resources/read.
- McpServer.from factory's "must have at least one" requirement
  loosened to: at least one expose() OR prompt() OR resource().

Client side (McpClient):
- listResources(): List<McpResourceInfo> — fetches resources/list.
- readResource(uri): String — calls resources/read, joins text
  content blocks into one string.
- resourceSkills(prefix): each resource wrapped as
  Skill<Map<String, Any?>, String> with implementedBy invoking
  readResource(uri).

TDD red-first: McpResourcesAsSkillsTest registers a
"precision-policy" resource on a loopback server; client fetches
resourceSkills(); caller agent uses it as a primary skill;
invocation returns the policy text verbatim.

After this commit, all three MCP surfaces (tools, prompts,
resources) are exposed as Skills uniformly. The v0.5.0
MCP-as-skills unification is complete: consumer code can build
agents that are thin wrappers over MCP exposure with one DSL
shape across all capability types.

MCP suite stats post-merge: 7 tests, 0 failures, 0 skipped.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Skobeltsyn

src/main/kotlin/agents_engine/mcp/McpClient.kt

@@ -157,6 +157,68 @@ class McpClient internal constructor(private val transport: McpTransport) : Auto
         }
     }
 
+    /**
+     * #1810 — fetch resource listings from the server (`resources/list`).
+     * Returns the raw `McpResourceInfo` records. For the Skill view, use
+     * [resourceSkills].
+     */
+    fun listResources(): List<McpResourceInfo> {
+        val result = post("resources/list", emptyMap<String, Any?>())
+        val resultMap = result as? Map<*, *> ?: return emptyList()
+        val resourcesList = resultMap["resources"] as? List<*> ?: return emptyList()
+        return resourcesList.mapNotNull { raw ->
+            val m = raw as? Map<*, *> ?: return@mapNotNull null
+            val uri = m["uri"] as? String ?: return@mapNotNull null
+            val name = m["name"] as? String ?: return@mapNotNull null
+            McpResourceInfo(
+                uri = uri,
+                name = name,
+                title = m["title"] as? String,
+                description = m["description"] as? String,
+                mimeType = m["mimeType"] as? String,
+                size = (m["size"] as? Number)?.toLong(),
+            )
+        }
+    }
+
+    /**
+     * #1810 — read a resource's content (`resources/read`). Joins all
+     * returned text content blocks into a single string. Binary
+     * (base64-encoded) resources are out of scope for this slice —
+     * extend when needed.
+     */
+    fun readResource(uri: String): String {
+        val result = post("resources/read", mapOf("uri" to uri))
+        val resultMap = result as? Map<*, *>
+            ?: error("resources/read returned non-object: $result")
+        val contents = resultMap["contents"] as? List<*> ?: emptyList<Any?>()
+        return contents.mapNotNull { c ->
+            val m = c as? Map<*, *> ?: return@mapNotNull null
+            m["text"] as? String
+        }.joinToString("\n")
+    }
+
+    /**
+     * #1810 — MCP-as-skills (3/3): expose every server-side resource as
+     * a [Skill]. Skill `name` is the resource's display name (with
+     * optional prefix); `implementedBy` invokes [readResource] with the
+     * captured URI. Skill args are ignored — resources are addressed
+     * by URI, not by call-time parameters.
+     */
+    fun resourceSkills(prefix: String? = null): List<agents_engine.core.Skill<Map<String, Any?>, String>> {
+        return listResources().map { info ->
+            val displayName = if (prefix != null) "$prefix.${info.name}" else info.name
+            agents_engine.core.Skill<Map<String, Any?>, String>(
+                name = displayName,
+                description = info.description ?: "MCP resource ${info.uri}",
+                inType = Map::class,
+                outType = String::class,
+            ).also { skill ->
+                skill.implementedBy { _ -> readResource(info.uri) }
+            }
+        }
+    }
+
     fun call(toolName: String, args: Map<String, Any?>): Any? {
         val result = post("tools/call", mapOf("name" to toolName, "arguments" to args))
         val resultMap = result as? Map<*, *>

src/main/kotlin/agents_engine/mcp/McpServer.kt

@@ -41,12 +41,27 @@ internal data class RegisteredPrompt(
     val render: (Map<String, Any?>) -> String,
 )
 
+/**
+ * #1810 — a server-side resource registration. Mirrors the MCP wire
+ * shape for resources: URI (the addressable handle), display name,
+ * optional description and MIME type, and a `read` closure invoked on
+ * `resources/read` to produce the resource's text content.
+ */
+internal data class RegisteredResource(
+    val uri: String,
+    val name: String,
+    val description: String?,
+    val mimeType: String?,
+    val read: () -> String,
+)
+
 class McpServer private constructor(
     private val agent: Agent<*, *>,
     private val exposedSkills: List<ExposedSkill>,
     private val portRequest: Int,
     private val maxRequestBytes: Long = DEFAULT_MAX_REQUEST_BYTES,
     private val registeredPrompts: List<RegisteredPrompt> = emptyList(),
+    private val registeredResources: List<RegisteredResource> = emptyList(),
 ) {
     private var http: HttpServer? = null
     private val sessionId: String = java.util.UUID.randomUUID().toString()
@@ -118,6 +133,11 @@ class McpServer private constructor(
                     "nextCursor" to null,
                 ))
                 "prompts/get" -> handlePromptGet(id, request)
+                "resources/list" -> jsonRpcResult(id, mapOf(
+                    "resources" to registeredResources.map { it.toMcpDescriptor() },
+                    "nextCursor" to null,
+                ))
+                "resources/read" -> handleResourceRead(id, request)
                 else -> jsonRpcError(id, -32601, "Method not found: $method")
             }
             respond(exchange, 200, response)
@@ -138,12 +158,15 @@ class McpServer private constructor(
                 "Unsupported protocolVersion: \"$requested\". Server speaks: \"$MCP_PROTOCOL_VERSION\".",
             )
         }
-        // #1796: declare prompts capability when prompts are registered.
+        // #1796 / #1810: declare prompts and resources capabilities when registered.
         val capabilities = buildMap<String, Any?> {
             put("tools", mapOf("listChanged" to false))
             if (registeredPrompts.isNotEmpty()) {
                 put("prompts", mapOf("listChanged" to false))
             }
+            if (registeredResources.isNotEmpty()) {
+                put("resources", mapOf("listChanged" to false, "subscribe" to false))
+            }
         }
         return jsonRpcResult(id, mapOf(
             "protocolVersion" to MCP_PROTOCOL_VERSION,
@@ -190,6 +213,35 @@ class McpServer private constructor(
         }
     }
 
+    private fun handleResourceRead(id: Any?, request: Map<*, *>): String {
+        val params = request["params"] as? Map<*, *> ?: emptyMap<Any?, Any?>()
+        val uri = params["uri"] as? String
+            ?: return jsonRpcError(id, -32602, "Missing resource uri")
+        val resource = registeredResources.firstOrNull { it.uri == uri }
+            ?: return jsonRpcError(id, -32601, "Unknown resource uri: $uri")
+        return try {
+            val content = resource.read()
+            jsonRpcResult(id, mapOf(
+                "contents" to listOf(
+                    buildMap<String, Any?> {
+                        put("uri", resource.uri)
+                        resource.mimeType?.let { put("mimeType", it) }
+                        put("text", content)
+                    },
+                ),
+            ))
+        } catch (e: Exception) {
+            jsonRpcError(id, -32603, "Resource '$uri' read failed: ${e.message ?: e.toString()}")
+        }
+    }
+
+    private fun RegisteredResource.toMcpDescriptor(): Map<String, Any?> = buildMap {
+        put("uri", uri)
+        put("name", name)
+        description?.let { put("description", it) }
+        mimeType?.let { put("mimeType", it) }
+    }
+
     private fun handleToolCall(id: Any?, request: Map<*, *>): String {
         val params = request["params"] as? Map<*, *> ?: emptyMap<Any?, Any?>()
         val name = params["name"] as? String
@@ -234,8 +286,12 @@ class McpServer private constructor(
 
         fun from(agent: Agent<*, *>, block: McpExposeBuilder.() -> Unit): McpServer {
             val builder = McpExposeBuilder().apply(block)
-            require(builder.exposedNames.isNotEmpty() || builder.prompts.isNotEmpty()) {
-                "McpServer requires at least one expose(skillName) or prompt(...) registration."
+            require(
+                builder.exposedNames.isNotEmpty() ||
+                    builder.prompts.isNotEmpty() ||
+                    builder.resources.isNotEmpty()
+            ) {
+                "McpServer requires at least one expose(skillName), prompt(...), or resource(...) registration."
             }
             val exposed = builder.exposedNames.map { name ->
                 val skill = agent.skills[name]
@@ -253,6 +309,7 @@ class McpServer private constructor(
                 portRequest = builder.port,
                 maxRequestBytes = builder.maxRequestBytes,
                 registeredPrompts = builder.prompts,
+                registeredResources = builder.resources,
             )
         }
     }
@@ -283,6 +340,28 @@ class McpExposeBuilder internal constructor() {
         }
         prompts += RegisteredPrompt(name, description, arguments, render)
     }
+
+    internal val resources = mutableListOf<RegisteredResource>()
+
+    /**
+     * #1810 — register a server-side resource. [content] is invoked
+     * per `resources/read` call; its String return becomes the
+     * resource's text content. Use a static return for static
+     * resources; pass a closure that reads from disk/db/etc. for
+     * dynamic content.
+     */
+    fun resource(
+        uri: String,
+        name: String,
+        description: String? = null,
+        mimeType: String? = null,
+        content: () -> String,
+    ) {
+        require(resources.none { it.uri == uri }) {
+            "Resource uri \"$uri\" already registered on this McpServer."
+        }
+        resources += RegisteredResource(uri, name, description, mimeType, content)
+    }
 }
 
 internal class ExposedSkill private constructor(

src/test/kotlin/agents_engine/mcp/McpResourcesAsSkillsTest.kt

@@ -0,0 +1,75 @@
+package agents_engine.mcp
+
+import agents_engine.core.agent
+import org.junit.jupiter.api.AfterEach
+import org.junit.jupiter.api.Tag
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+/**
+ * #1810 — slice 3/3 of MCP-as-skills. MCP resources are URI-addressable
+ * data items. `mcp.resourceSkills()` exposes each as a Skill whose
+ * `implementedBy` reads the URI's content. Skill args are ignored —
+ * the URI is captured in the skill's closure at fetch time.
+ */
+class McpResourcesAsSkillsTest {
+
+    private var mcpServer: McpServer? = null
+    private var mcpClient: McpClient? = null
+
+    @AfterEach
+    fun teardown() {
+        mcpClient?.close()
+        mcpServer?.stop()
+    }
+
+    @Tag("live-mcp")
+    @Test
+    fun `mcp resourceSkills returns each MCP resource as a Skill that reads its URI content`() {
+        val placeholderAgent = agent<String, String>("placeholder") {
+            skills {
+                skill<String, String>("noop", "Placeholder skill") {
+                    implementedBy { it }
+                }
+            }
+        }
+
+        val server = McpServer.from(placeholderAgent) {
+            port = 0
+            expose("noop")
+            resource(
+                uri = "policy:///precision-policy.md",
+                name = "precision-policy",
+                description = "Internal policy for math problem precision",
+                mimeType = "text/markdown",
+            ) {
+                "Be precise. Cite sources. Round half-to-even."
+            }
+        }.start().also { mcpServer = it }
+
+        val mcp = McpClient.connect(server.url).also { mcpClient = it }
+
+        // Discovery: every MCP resource returned as a Skill.
+        val resourceSkills = mcp.resourceSkills()
+        assertEquals(1, resourceSkills.size, "expected one resource-skill; got: ${resourceSkills.map { it.name }}")
+        val skill = resourceSkills.single()
+        assertEquals("precision-policy", skill.name)
+        assertTrue(
+            skill.description.contains("precision", ignoreCase = true),
+            "expected MCP resource description; got: ${skill.description}",
+        )
+
+        // Use the MCP-resource-as-skill as a primary skill on a caller agent.
+        val caller = agent<Map<String, Any?>, String>("caller") {
+            skills { +skill }
+        }
+
+        // Args are ignored — the resource URI is captured by the skill's closure.
+        val output = caller(emptyMap())
+        assertTrue(
+            "precise" in output && "sources" in output,
+            "expected resource content; got: \"$output\"",
+        )
+    }
+}