@qilin-agent/mcp-resources 0.0.0-stage → 3.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,64 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/mcp/mcp-resources/README.md
+/:
+  en: 34b851d97ea0313e
+  zh: 2fa00063647b6eee
+/qilin-agent-mcp-resources:
+  en: 6fd173493f20a57e
+  zh: 4d9677fa6aa459da
+/qilin-agent-mcp-resources/summary:
+  en: bce3ffe5fdd801a6
+  zh: 7378d3a526c0043a
+/qilin-agent-mcp-resources/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 725b47765ee8f30b
+/qilin-agent-mcp-resources/use-this-package:
+  en: 1f8d430124c6b30b
+  zh: f8beadb2461b3d91
+/qilin-agent-mcp-resources/use-this-package/server-configuration:
+  en: 40166de24ff78e77
+  zh: 29f269bfea41164a
+/qilin-agent-mcp-resources/use-this-package/discover-and-read:
+  en: f7fb6597acd3c5dc
+  zh: 9c59219fb4ab00d9
+/qilin-agent-mcp-resources/understand-the-implementation:
+  en: fb5ca02328f07491
+  zh: b4392bce3371203e
+/qilin-agent-mcp-resources/further-exploration:
+  en: d1ab183ea9b282a5
+  zh: ed27a99bd03e0c8c
+/qilin-agent-mcp-resources/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/qilin-agent-mcp-resources/model-experience/shared-resource-tools:
+  en: 520e0b6cb35e4285
+  zh: 20a323f87e6d12fc
+/qilin-agent-mcp-resources/model-experience/shared-resource-tools/what-the-model-sees:
+  en: a660f500f0ae911d
+  zh: abffab84afb60121
+/qilin-agent-mcp-resources/model-experience/shared-resource-tools/token-effect:
+  en: 92682e15ca9e90a5
+  zh: 3487ef2adb89c9e4
+/qilin-agent-mcp-resources/model-experience/shared-resource-tools/kv-cache-effect:
+  en: fdb450babcdf877b
+  zh: f013ae46ce9e1125
+/qilin-agent-mcp-resources/model-experience/resource-results:
+  en: f46ae3151a215b4d
+  zh: 8d15019792d3fe61
+/qilin-agent-mcp-resources/model-experience/resource-results/what-the-model-sees:
+  en: 62d0a18c52283474
+  zh: 70b2fbea70c98818
+/qilin-agent-mcp-resources/model-experience/resource-results/token-effect:
+  en: e6fb5043a1ccc6ff
+  zh: d15d2e7b5986d614
+/qilin-agent-mcp-resources/model-experience/resource-results/kv-cache-effect:
+  en: ea0dfc069bf175c0
+  zh: 3e1465e56ff79764
+/qilin-agent-mcp-resources/known-limitations-and-deferred-work:
+  en: 58d13dc99946c11d
+  zh: 4099c46a1ca60512
+/qilin-agent-mcp-resources/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,134 @@
-# Temporary Holding Version
+---
+description: "Discover and read MCP resources on demand with shared tools, explicit server selection, and agent-scoped access."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/mcp-resources
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`qilin-mcp-resources` lets the model discover and read documents from configured MCP servers. Shipped profiles make its three shared tools available automatically when a server is configured in the caller's scope. Each tool requires an explicit server name and reads content only when called. Resource text enters conversation history; binary payloads remain available to programmatic callers and appear as descriptions to the model.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Shipped profiles already mount this package once. Configure only the [MCP client](../mcp-client/README.md) entries for the servers you need.
+
+### Server configuration
+
+Use the [client configuration](../mcp-client/README.md#use-this-package) to add a server in the intended scope. This package has no configuration fields.
+
+A caller with no configured MCP server sees no MCP prompt text or resource tools in native or PTC mode. A configured server enables the three shared resource tools, including when another provider mounts its client or the server has no tools or instructions. Connection failures do not remove the shared tools while the client entry remains active; resource calls report the connection error.
+
+### Discover and read
+
+When system-prompt assembly is mounted, the prompt lists server names visible to the calling agent. Call `list_mcp_resources` or `list_mcp_resource_templates` with one of those names as `server`. Without a cursor, the MCP SDK collects the server’s pages. An explicit `cursor` requests that page; pass a returned `nextCursor` unchanged. Read a listed URI or an expanded template with `read_mcp_resource`, using the same `server` name and an explicit `uri`.
+
+Every operation resolves the server in the calling agent's scope. A missing server argument or unavailable server fails before dispatch. The connection owner handles request cancellation, timeouts, and recovery; a failed request remains a failed tool call.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The [base](../../bundle/base/README.md) and standalone [sdk-minimal](../../bundle/sdk-minimal/README.md) bundles each own this row:
+
+```yaml
+- id: mcp-resources
+  name: '@qilin-agent/mcp-resources'
+```
+
+The first provider in a scope registers its shared tools; removing the last removes those local registrations, while inherited providers and tools remain visible. The resource service owns the shared tool effects independently of the first provider's plugin, so unloading that provider cannot remove tools needed by another server. Provider selection and the server-name prompt use the same scoped registry. Each call resolves its server before dispatch.
+
+Canonical results retain the complete JSON for programmatic callers. The pure text renderer adds server attribution and replaces string-valued `blob` fields with a description of their base64 length; URI, MIME type, and text fields remain in the rendered JSON. The tool pipeline owns recorded results. Server instructions belong to the MCP client and its logged system-prompt section.
+
+| Source | Responsibility |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Scoped provider selection and server-name prompt context |
+| [`src/tools.ts`](src/tools.ts) | Shared resource operations and argument schemas |
+| [`src/render.ts`](src/render.ts) | Attributed text projection without inline binary payloads |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+These pages cover server configuration, execution, and the decisions behind resource access.
+
+- [MCP client](../mcp-client/README.md) — server transports, instructions, and connection lifecycle.
+- [Tools subsystem](../../../docs/subsystems/tools.md) — canonical values and model-visible results.
+- [Resource visibility decision](../../../.agents/notes/implemented/feature/2026-09-13-mcp-resources-in-profiles.md) — shared profile mounting and visibility from configured servers.
+- [Resources and instructions decision](../../../.agents/notes/implemented/feature/2026-09-12-mcp-resources-and-instructions.md) — scope, on-demand access, and excluded mechanisms.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Shared resource tools
+
+#### What the model sees
+
+The [generated tool schemas](../../../docs/tool-catalog.md#qilin-agentmcp-resources) define three tools shared by all caller-visible configured servers. With none, native schemas, PTC declarations and bindings, and the server-name prompt are absent. Connecting, disconnecting, or retrying an active client leaves these shared tool definitions unchanged. When system-prompt assembly is mounted and providers are visible, the `MCP resource servers` section says `Use list_mcp_resources, list_mcp_resource_templates, or read_mcp_resource with one of these names as the server argument: <JSON array>.` The names come from the same scoped registry, including servers with neither tools nor instructions. An empty registry contributes no section.
+
+#### Token effect
+
+With no caller-visible configured servers, this package adds no tool or prompt tokens. Otherwise, three shared definitions contribute a fixed schema cost and the server-name section adds a sorted JSON list of visible names. Resource listings and documents add content only when an operation returns them.
+
+#### KV Cache effect
+
+Adding the first caller-visible server or removing the last changes the next tool schema or PTC declaration prefix. Changes to visible names update the server-name section; replacing a provider under the same name leaves that text unchanged. Connection failures alone do not change the shared definitions or names.
+
+### Resource results
+
+#### What the model sees
+
+A successful result starts with `MCP server: <server>`, followed by a newline and the returned JSON. Each string-valued `blob` becomes `[binary resource: <length> base64 characters; available to programmatic callers]`. Server-provided text, metadata, and continuation cursors remain visible.
+
+#### Token effect
+
+Rendered results add text to tool history. Binary descriptions replace the payload's base64 token cost; this package imposes no separate text-size limit.
+
+#### KV Cache effect
+
+Each result appends to history without rewriting earlier results. Later reads can return changed server content and append a different result; the package does not refresh previously recorded content.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+Resource access is explicit and on demand.
+
+- A configured server without the MCP `resources` capability still appears in the server-name prompt and keeps shared resource tools available. The SDK returns empty resource and template lists; unsupported reads fail.
+- `tools.restrict()` checks names supplied by global or ancestor scopes when the filter is registered. Naming a resource tool absent from those scopes fails as an unknown tool. Resource tools registered in the caller's own scope are outside allow/deny masks.
+- Resource subscriptions and update notifications are unsupported; call the list or read tools again to obtain current content.
+- Binary resources are not projected as native images or audio. Programmatic callers retain their canonical base64 values.
+- The caller must supply a server name. The shared tools do not aggregate different servers; pagination follows the MCP SDK.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,134 @@
+---
+description: "通过共享工具、显式服务器选择和 agent 作用域访问，按需发现与读取 MCP 资源。"
+kind: "package-reference"
+---
+
+# @qilin-agent/mcp-resources
+
+[English](README.md) | 中文
+
+## 概述
+
+`qilin-mcp-resources` 让模型发现和读取已配置 MCP 服务器提供的文档。随附 profile 在调用方作用域中配置了服务器时，自动提供三个共享工具。每个工具都要求显式指定服务器名称，并且仅在调用时读取内容。资源文本进入对话历史；二进制载荷仍可供程序化调用方访问，并以说明文字呈现给模型。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延后工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+随附 profile 已经统一挂载本包一次。你只需为所需服务器配置 [MCP 客户端](../mcp-client/README.zh.md)条目。
+
+### 服务器配置
+
+通过[客户端配置](../mcp-client/README.zh.md#use-this-package)在目标作用域中添加服务器。本包没有配置字段。
+
+调用方没有已配置 MCP 服务器时，在 native 或 PTC 模式下都看不到 MCP 提示词文本或资源工具。配置服务器后会启用三个共享资源工具，包括由其他提供方挂载客户端的服务器，以及没有工具或指令的服务器。只要客户端条目保持激活，连接失败就不会移除共享工具；资源调用会报告连接错误。
+
+### 发现与读取
+
+挂载系统提示词组装服务时，提示词列出调用 agent 可见的服务器名称。将其中一个名称作为 `server` 调用 `list_mcp_resources` 或 `list_mcp_resource_templates`。未提供游标时，MCP SDK 收集服务器的全部分页；显式提供游标时返回一页；将其中的 `nextCursor` 原样作为 `cursor` 传入，以请求下一页。使用相同的 `server` 名称和显式 `uri`，通过 `read_mcp_resource` 读取已列出的 URI 或展开后的模板。
+
+每个操作都在调用 agent 的作用域中解析服务器。缺少服务器参数或服务器不可用时，会在派发前失败。连接所有者负责请求取消、超时与恢复；失败的请求仍表现为失败的工具调用。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现内部细节——点击展开</summary>
+
+[base](../../bundle/base/README.zh.md) 与独立的 [sdk-minimal](../../bundle/sdk-minimal/README.zh.md) bundle 分别拥有以下配置行：
+
+```yaml
+- id: mcp-resources
+  name: '@qilin-agent/mcp-resources'
+```
+
+作用域中的首个提供方注册该作用域的共享工具；移除最后一个提供方会移除本地工具注册，继承的提供方与工具仍然可见。资源服务独立于首个提供方插件拥有共享工具 effect，因此卸载该提供方不会移除其他服务器仍需要的工具。提供方选择与服务器名称提示词使用同一作用域注册表。每次调用都在派发前解析服务器。
+
+规范结果为程序化调用方保留完整 JSON。纯文本渲染器添加服务器归属信息，并将字符串值的 `blob` 字段替换为说明其 base64 长度的文字；URI、MIME 类型与文本字段仍保留在渲染后的 JSON 中。工具流水线负责记录结果。服务器指令归 MCP 客户端及其已记录的系统提示词段落所有。
+
+| 源码 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 作用域提供方选择与服务器名称提示词上下文 |
+| [`src/tools.ts`](src/tools.ts) | 共享资源操作与参数 schema |
+| [`src/render.ts`](src/render.ts) | 带归属信息且不内联二进制载荷的文本投影 |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+以下页面介绍服务器配置、执行机制与资源访问决策。
+
+- [MCP 客户端](../mcp-client/README.zh.md)——服务器传输、指令与连接生命周期。
+- [工具子系统](../../../docs/subsystems/tools.zh.md)——规范值与模型可见结果。
+- [资源可见性决策](../../../.agents/notes/implemented/feature/2026-09-13-mcp-resources-in-profiles.zh.md)——profile 统一挂载及由已配置服务器决定的可见性。
+- [资源与指令决策](../../../.agents/notes/implemented/feature/2026-09-12-mcp-resources-and-instructions.zh.md)——作用域、按需访问及未纳入的机制。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 共享资源工具
+
+#### 模型看到什么
+
+[生成的工具 schema](../../../docs/tool-catalog.zh.md#qilin-agentmcp-resources)定义了调用方可见的所有已配置服务器共享的三个工具。没有这类服务器时，native schema、PTC 声明与绑定以及服务器名称提示词均不存在。激活的客户端连接、断开或重试时，这些共享工具定义保持不变。挂载系统提示词装配且存在可见提供方时，`MCP resource servers` 段落显示 `Use list_mcp_resources, list_mcp_resource_templates, or read_mcp_resource with one of these names as the server argument: <JSON array>.` 名称来自同一作用域注册表，包括既没有工具也没有指令的服务器。注册表为空时不贡献该段落。
+
+#### Token 影响
+
+没有调用方可见的已配置服务器时，本包不增加工具或提示词 token。否则，三个共享定义带来固定的 schema 开销，服务器名称段落增加按序排列的可见名称 JSON 列表。资源列表和文档仅在操作返回后增加内容。
+
+#### KV Cache 影响
+
+添加调用方可见的首个服务器或移除最后一个服务器，会改变后续工具 schema 或 PTC 声明前缀。可见名称变化时更新服务器名称段落；替换同名提供方不会改变该文本。单纯的连接失败不会改变共享定义或名称。
+
+### 资源结果
+
+#### 模型看到什么
+
+成功结果以 `MCP server: <server>` 开头，随后是换行和返回的 JSON。每个字符串值的 `blob` 都变为 `[binary resource: <length> base64 characters; available to programmatic callers]`。服务器提供的文本、元数据与续传游标仍然可见。
+
+#### Token 影响
+
+渲染后的结果向工具历史添加文本。二进制说明文字替代载荷的 base64 token 开销；本包不设置额外的文本大小限制。
+
+#### KV Cache 影响
+
+每个结果追加到历史中，不改写此前的结果。后续读取可以返回已变化的服务器内容并追加不同结果；本包不会刷新此前已记录的内容。
+
+## 已知限制与延后工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+资源访问由显式调用按需发起。
+
+- 不具备 MCP `resources` 能力的已配置服务器仍会出现在服务器名称提示词中，并保持共享资源工具可用。SDK 返回空的资源列表与模板列表；不受支持的读取会失败。
+- `tools.restrict()` 在注册过滤条件时检查全局或祖先作用域提供的名称。引用这些作用域中不存在的资源工具名称会报未知工具错误。注册在调用方自身作用域中的资源工具不受 allow/deny 掩码过滤。
+- 不支持资源订阅与更新通知；再次调用列表或读取工具以获取当前内容。
+- 二进制资源不会投影为原生图片或音频。程序化调用方保留其规范 base64 值。
+- 调用方必须提供服务器名称。共享工具不会聚合不同服务器；分页遵循 MCP SDK。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,181 @@
+import { Service } from "@qilin-agent/kylin";
+import { NamedEntries, ScopedLayers, createScope, scopeOf } from "@qilin-agent/scope";
+import { defineTool } from "@qilin-agent/tools";
+//#region lib/types/render.js
+/**
+* Resource-result projection keeps binary payloads out of model history.
+*
+* @module @qilin-agent/mcp-resources
+*/
+/**
+* Render resource JSON while retaining raw binary data only for programmatic callers.
+* @param server - configured server attribution.
+* @param value - canonical resource result.
+* @returns attributed text with binary payload descriptions.
+*/
+function renderResourceResult(server, value) {
+	return [{
+		type: "text",
+		text: `MCP server: ${server}\n${JSON.stringify(value, (key, item) => {
+			if (key === "blob" && typeof item === "string") return `[binary resource: ${item.length} base64 characters; available to programmatic callers]`;
+			return item;
+		})}`
+	}];
+}
+//#endregion
+//#region lib/types/tools.js
+/**
+* Three shared tools adapt model arguments to scoped resource operations.
+*
+* @module @qilin-agent/mcp-resources
+*/
+const listParameters = {
+	server: {
+		type: "string",
+		required: true,
+		description: "Configured MCP server name."
+	},
+	cursor: {
+		type: "string",
+		description: "Continuation cursor returned by this server."
+	}
+};
+const output = {
+	schema: { type: "json" },
+	render: (args, value) => renderResourceResult(args.server, value)
+};
+/**
+* Register resource operations in the consumer's tool scope.
+* @param ctx - context owning the tool registrations.
+* @param request - caller-aware resource operation.
+* @returns the effect disposer that removes all three tools synchronously.
+*/
+function registerResourceTools(ctx, request) {
+	return ctx.effect(function* () {
+		yield ctx.tools.register(defineTool({
+			name: "list_mcp_resources",
+			description: "List resources available from an MCP server.",
+			parameters: listParameters,
+			output,
+			execute: (args, exec) => request(args.server, {
+				method: "resources/list",
+				...args.cursor === void 0 ? {} : { cursor: args.cursor }
+			}, exec)
+		}));
+		yield ctx.tools.register(defineTool({
+			name: "list_mcp_resource_templates",
+			description: "List parameterized resource URI templates from an MCP server.",
+			parameters: listParameters,
+			output,
+			execute: (args, exec) => request(args.server, {
+				method: "resources/templates/list",
+				...args.cursor === void 0 ? {} : { cursor: args.cursor }
+			}, exec)
+		}));
+		yield ctx.tools.register(defineTool({
+			name: "read_mcp_resource",
+			description: "Read an MCP resource by URI from the named server. Use a listed URI or an expanded resource template.",
+			parameters: {
+				server: listParameters.server,
+				uri: {
+					type: "string",
+					required: true,
+					description: "Resource URI to read."
+				}
+			},
+			output,
+			execute: (args, exec) => request(args.server, {
+				method: "resources/read",
+				uri: args.uri
+			}, exec)
+		}));
+	}, "mcpResources.resourceTools");
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Scoped MCP resource providers and the shared model-facing resource tools.
+*
+* @module @qilin-agent/mcp-resources
+*/
+var ResourceLayer = class {
+	servers = new NamedEntries((name) => /* @__PURE__ */ new Error(`MCP resource server "${name}" is already registered in this scope`));
+	disposeTools;
+	isEmpty() {
+		return this.servers.isEmpty();
+	}
+};
+/** Scoped resource access plus three tools shared by configured MCP servers. */
+var McpResourceRuntime = class extends Service {
+	/** Tool registry required by the resource consumer. */
+	static inject = ["tools"];
+	layers = new ScopedLayers(() => new ResourceLayer(), () => void 0);
+	/** Shared tool registrations outlive any one server's registering context. */
+	selfCtx;
+	constructor(ctx) {
+		super(ctx, "mcpResources");
+		this.selfCtx = ctx;
+		ctx.inject(["systemPrompt"], (inner) => {
+			inner.systemPrompt.section({
+				name: "mcp-resource-servers",
+				order: inner.systemPrompt.getSectionOrder("MCP_SERVERS"),
+				interpolate: false,
+				text: ({ scope }) => {
+					const names = [...this.layers.merge(scope, (layer) => layer.servers).keys()].sort();
+					return names.length === 0 ? "" : `## MCP resource servers
+
+Use list_mcp_resources, list_mcp_resource_templates, or read_mcp_resource with one of these names as the server argument: ${JSON.stringify(names)}.`;
+				}
+			});
+		});
+	}
+	/**
+	* Register one server and expose resource tools while that scope has providers.
+	* @param server - configured server name, unique in this scope.
+	* @param provider - connection-owned resource operations.
+	* @returns the effect disposer for this exact registration.
+	*/
+	register(server, provider) {
+		const ctx = this.ctx;
+		const scope = scopeOf(ctx);
+		return ctx.effect(function* () {
+			let disposal;
+			yield () => disposal;
+			yield this.layers.effect(ctx, (layer) => {
+				const first = layer.servers.isEmpty();
+				const remove = layer.servers.insert(server, provider);
+				try {
+					if (first) layer.disposeTools = this.registerTools(scope);
+				} catch (error) {
+					remove();
+					throw error;
+				}
+				return () => {
+					remove();
+					if (layer.servers.isEmpty()) disposal = layer.disposeTools();
+				};
+			}, { label: `mcpResources.provider(${server})` });
+		}.bind(this), `mcpResources.register(${server})`);
+	}
+	/** Own one scope's tools independently of its configured server plugins. */
+	registerTools(scope) {
+		const ctx = this.selfCtx;
+		return ctx.effect(function* () {
+			let toolCtx = ctx;
+			if (scope !== void 0) {
+				const owned = createScope(ctx, scope);
+				yield owned.rawDispose;
+				toolCtx = owned.ctx;
+			}
+			yield registerResourceTools(toolCtx, (server, request, exec) => this.request(server, request, exec));
+		}.bind(this), "mcpResources.tools");
+	}
+	/** Resolve the caller-visible server before starting any network operation. */
+	request(server, request, exec) {
+		const provider = this.layers.merge(exec.agent, (layer) => layer.servers).get(server);
+		if (!provider) throw new Error(`MCP resource server "${server}" is unavailable in this agent's scope`);
+		return provider.request(request, exec);
+	}
+};
+//#endregion
+export { McpResourceRuntime, McpResourceRuntime as default };

package/lib/types/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Scoped MCP resource providers and the shared model-facing resource tools.
+ *
+ * @module @qilin-agent/mcp-resources
+ */
+import { Service, type Context } from '@qilin-agent/kylin';
+import type { JsonValue } from '@qilin-agent/util-values';
+import type { ToolExecution } from '@qilin-agent/tools';
+declare module '@qilin-agent/kylin' {
+    interface Context {
+        mcpResources: McpResourceRuntime;
+    }
+}
+/** One supported resource operation, with server-owned cursors and URIs. */
+export type McpResourceRequest = {
+    method: 'resources/list' | 'resources/templates/list';
+    cursor?: string;
+} | {
+    method: 'resources/read';
+    uri: string;
+};
+/** One configured server's resource access, owned by its MCP connection plugin. */
+export interface McpResourceProvider {
+    /**
+     * Run an operation against one live connection generation.
+     * @param request - MCP resource method and parameters.
+     * @param exec - caller identity and cancellation for this invocation.
+     * @returns the protocol result as lossless JSON.
+     */
+    request(request: McpResourceRequest, exec: ToolExecution): Promise<JsonValue>;
+}
+/** Scoped resource access plus three tools shared by configured MCP servers. */
+export declare class McpResourceRuntime extends Service {
+    /** Tool registry required by the resource consumer. */
+    static inject: string[];
+    private readonly layers;
+    /** Shared tool registrations outlive any one server's registering context. */
+    private readonly selfCtx;
+    constructor(ctx: Context);
+    /**
+     * Register one server and expose resource tools while that scope has providers.
+     * @param server - configured server name, unique in this scope.
+     * @param provider - connection-owned resource operations.
+     * @returns the effect disposer for this exact registration.
+     */
+    register(server: string, provider: McpResourceProvider): () => void;
+    /** Own one scope's tools independently of its configured server plugins. */
+    private registerTools;
+    /** Resolve the caller-visible server before starting any network operation. */
+    private request;
+}
+export default McpResourceRuntime;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/render.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Resource-result projection keeps binary payloads out of model history.
+ *
+ * @module @qilin-agent/mcp-resources
+ */
+import type { ContentBlock } from '@qilin-agent/llm';
+import type { JsonValue } from '@qilin-agent/util-values';
+/**
+ * Render resource JSON while retaining raw binary data only for programmatic callers.
+ * @param server - configured server attribution.
+ * @param value - canonical resource result.
+ * @returns attributed text with binary payload descriptions.
+ */
+export declare function renderResourceResult(server: string, value: JsonValue): ContentBlock[];
+//# sourceMappingURL=render.d.ts.map

package/lib/types/tools.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Three shared tools adapt model arguments to scoped resource operations.
+ *
+ * @module @qilin-agent/mcp-resources
+ */
+import type { Context } from '@qilin-agent/kylin';
+import { type ToolExecution } from '@qilin-agent/tools';
+import type { JsonValue } from '@qilin-agent/util-values';
+import type { McpResourceRequest } from './index.ts';
+type RequestResource = (server: string, request: McpResourceRequest, exec: ToolExecution) => Promise<JsonValue>;
+/**
+ * Register resource operations in the consumer's tool scope.
+ * @param ctx - context owning the tool registrations.
+ * @param request - caller-aware resource operation.
+ * @returns the effect disposer that removes all three tools synchronously.
+ */
+export declare function registerResourceTools(ctx: Context, request: RequestResource): () => void;
+export {};
+//# sourceMappingURL=tools.d.ts.map

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@qilin-agent/mcp-resources",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Scoped MCP resource discovery and reading through shared model tools",
+  "version": "3.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/mcp/mcp-resources"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/llm": "3.1.4",
+    "@qilin-agent/scope": "3.1.4",
+    "@qilin-agent/tools": "3.1.4",
+    "@qilin-agent/system-prompt": "3.1.4"
+  },
+  "devDependencies": {
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/llm": "3.1.4",
+    "@qilin-agent/ptc-runtime": "3.1.4",
+    "@qilin-agent/scope": "3.1.4",
+    "@qilin-agent/tools": "3.1.4",
+    "@qilin-agent/system-prompt": "3.1.4",
+    "@qilin-agent/agent": "3.1.4"
+  },
+  "dependencies": {
+    "@qilin-agent/util-values": "3.1.4"
+  },
+  "peerDependenciesMeta": {
+    "@qilin-agent/system-prompt": {
+      "optional": true
+    }
+  }
 }