expose read-only MCP summary resources

Author: Eilen6316

CHANGELOG.md

@@ -16,6 +16,9 @@ Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - `linuxagent check` now reports MCP and Skill status and fails fast when Skill
   manifests are missing, invalid, or contain read-only runbooks rejected by
   policy.
+- MCP now exposes configurable read-only resources for runbook and Skill
+  summaries without returning command strings, full guidance bodies, or
+  execution handles.
 - Workspace tool activity now includes concise evidence snippets from completed
   `read_file`, `list_dir`, and `search_files` calls. No-change file-plan
   answers also include the cited evidence so operators can see which file lines

configs/default.yaml

@@ -80,6 +80,9 @@ mcp:
   tools:
     - linuxagent.policy.classify
     - linuxagent.audit.verify
+  resources:
+    - linuxagent://runbooks/summary
+    - linuxagent://skills/summary
 
 skills:
   enabled: false

configs/example.yaml

@@ -176,6 +176,9 @@ mcp:
   tools:
     - linuxagent.policy.classify
     - linuxagent.audit.verify
+  resources:
+    - linuxagent://runbooks/summary
+    - linuxagent://skills/summary
 
 skills:
   # Declarative local YAML manifests only. No Python hooks, shell hooks, remote

docs/design/mcp-server.md

@@ -13,6 +13,9 @@ This design follows the MCP tool model: the server declares a `tools`
 capability, clients discover tools with `tools/list`, and clients invoke tools
 with `tools/call`.
 
+It also exposes bounded read-only resources for public capability summaries.
+Resources are not execution handles.
+
 ## Threat Model
 
 An MCP client is model-facing software. Tool calls may be triggered by model
@@ -39,11 +42,14 @@ mcp:
   tools:
     - linuxagent.policy.classify
     - linuxagent.audit.verify
+  resources:
+    - linuxagent://runbooks/summary
+    - linuxagent://skills/summary
 ```
 
-`transport` currently accepts only `stdio`. `tools` is an explicit allowlist:
-unknown tool names fail config validation, and tools omitted from the list are
-not returned by `tools/list` or callable through `tools/call`.
+`transport` currently accepts only `stdio`. `tools` and `resources` are explicit
+allowlists: unknown names fail config validation, and entries omitted from the
+list are not returned by list methods or callable/readable by clients.
 
 The default config enables the stdio server with both read-only tools. Setting
 `mcp.enabled: false` makes `linuxagent mcp` fail closed instead of starting a
@@ -61,6 +67,17 @@ capabilities, matched rules, approval requirement, and whitelist eligibility.
 Audit verification returns validity, record count, tamper line, reason, and the
 configured audit path.
 
+## Exposed Resources
+
+| Resource | Behavior | State mutation |
+|---|---|---|
+| `linuxagent://runbooks/summary` | Returns runbook ids, titles, and step purpose/read-only flags | None |
+| `linuxagent://skills/summary` | Returns Skill name/version/description/permissions/guidance presence/runbook ids | None |
+
+Resources intentionally return summaries. They do not expose command strings,
+planner guidance bodies, execution results, raw audit logs, config secrets, or
+filesystem content.
+
 ## Non-Exposed Capabilities
 
 These remain intentionally unavailable over MCP:
@@ -70,6 +87,8 @@ These remain intentionally unavailable over MCP:
 - file patch application
 - SSH cluster execution
 - raw audit record search
+- runbook command-string export
+- full Skill planner guidance export
 - raw secrets, provider keys, config values, or environment values
 
 If execution is added later, it must call the same graph/service path as the
@@ -103,10 +122,13 @@ The server supports:
 - `notifications/initialized`
 - `tools/list`
 - `tools/call`
+- `resources/list`
+- `resources/read`
 - `shutdown`
 
-Unknown methods and unknown tools return JSON-RPC errors. Business validation
-failures inside a known tool return a tool result with `isError: true`.
+Unknown methods, tools, and resources return JSON-RPC errors. Business
+validation failures inside a known tool return a tool result with
+`isError: true`.
 
 ## Future Slices
 

src/linuxagent/cli.py

@@ -181,7 +181,14 @@ def _cmd_mcp(args: argparse.Namespace) -> int:
         print("error: mcp.enabled is false", file=sys.stderr)
         return 1
     container = Container(cfg)
-    server = McpServer(container.policy_engine(), cfg.audit.path, tools=cfg.mcp.tools)
+    server = McpServer(
+        container.policy_engine(),
+        cfg.audit.path,
+        tools=cfg.mcp.tools,
+        resources=cfg.mcp.resources,
+        runbooks=container.runbook_engine().runbooks,
+        skills=container.skill_manifests(),
+    )
     return serve_stdio(server)
 
 

src/linuxagent/config/models.py

@@ -21,7 +21,12 @@
     model_validator,
 )
 
-from ..mcp_tools import MCP_READ_ONLY_TOOL_NAMES, McpToolName
+from ..mcp_tools import (
+    MCP_READ_ONLY_RESOURCE_URIS,
+    MCP_READ_ONLY_TOOL_NAMES,
+    McpResourceUri,
+    McpToolName,
+)
 from ..sandbox.models import SandboxNetworkPolicy, SandboxProfile, SandboxRunnerKind
 
 _FROZEN = ConfigDict(frozen=True, extra="forbid")
@@ -392,6 +397,7 @@ class McpConfig(BaseModel):
     enabled: bool = True
     transport: Literal["stdio"] = "stdio"
     tools: tuple[McpToolName, ...] = MCP_READ_ONLY_TOOL_NAMES
+    resources: tuple[McpResourceUri, ...] = MCP_READ_ONLY_RESOURCE_URIS
 
     @field_validator("tools")
     @classmethod
@@ -400,6 +406,15 @@ def _reject_duplicate_tools(cls, value: tuple[McpToolName, ...]) -> tuple[McpToo
             raise ValueError("mcp.tools cannot contain duplicate entries")
         return value
 
+    @field_validator("resources")
+    @classmethod
+    def _reject_duplicate_resources(
+        cls, value: tuple[McpResourceUri, ...]
+    ) -> tuple[McpResourceUri, ...]:
+        if len(set(value)) != len(value):
+            raise ValueError("mcp.resources cannot contain duplicate entries")
+        return value
+
 
 class SkillsConfig(BaseModel):
     model_config = _FROZEN

src/linuxagent/mcp_server.py

@@ -11,9 +11,20 @@
 from . import __version__
 from .audit import verify_audit_log
 from .interfaces import CommandSource
-from .mcp_tools import AUDIT_TOOL_NAME, MCP_READ_ONLY_TOOL_NAMES, POLICY_TOOL_NAME, McpToolName
+from .mcp_tools import (
+    AUDIT_TOOL_NAME,
+    MCP_READ_ONLY_RESOURCE_URIS,
+    MCP_READ_ONLY_TOOL_NAMES,
+    POLICY_TOOL_NAME,
+    RUNBOOKS_SUMMARY_RESOURCE,
+    SKILLS_SUMMARY_RESOURCE,
+    McpResourceUri,
+    McpToolName,
+)
 from .policy import PolicyEngine
+from .runbooks import Runbook
 from .security import redact_record
+from .skills import SkillManifest
 
 PROTOCOL_VERSION = "2025-06-18"
 SERVER_NAME = "linuxagent-mcp"
@@ -49,6 +60,20 @@
         },
     },
 }
+_RESOURCE_DEFINITIONS: dict[McpResourceUri, JsonObject] = {
+    RUNBOOKS_SUMMARY_RESOURCE: {
+        "uri": RUNBOOKS_SUMMARY_RESOURCE,
+        "name": "LinuxAgent Runbook Summary",
+        "description": "Read-only summary of configured LinuxAgent runbooks.",
+        "mimeType": "application/json",
+    },
+    SKILLS_SUMMARY_RESOURCE: {
+        "uri": SKILLS_SUMMARY_RESOURCE,
+        "name": "LinuxAgent Skill Summary",
+        "description": "Read-only summary of configured LinuxAgent Skill manifests.",
+        "mimeType": "application/json",
+    },
+}
 
 JsonObject = dict[str, Any]
 
@@ -58,6 +83,9 @@ class McpServer:
     policy_engine: PolicyEngine
     audit_path: Path
     tools: tuple[McpToolName, ...] = MCP_READ_ONLY_TOOL_NAMES
+    resources: tuple[McpResourceUri, ...] = MCP_READ_ONLY_RESOURCE_URIS
+    runbooks: tuple[Runbook, ...] = ()
+    skills: tuple[SkillManifest, ...] = ()
 
     def handle(self, request: JsonObject) -> JsonObject | None:
         method = request.get("method")
@@ -81,6 +109,10 @@ def _handle_request(self, method: str, request_id: Any, params: Any) -> JsonObje
             return _result(request_id, {"tools": list(_tools(self.tools))})
         if method == "tools/call":
             return self._call_tool(request_id, params)
+        if method == "resources/list":
+            return _result(request_id, {"resources": list(_resources(self.resources))})
+        if method == "resources/read":
+            return self._read_resource(request_id, params)
         if method == "shutdown":
             return _result(request_id, {})
         return _error(request_id, -32601, f"unknown method: {method}")
@@ -100,6 +132,18 @@ def _call_tool(self, request_id: Any, params: Any) -> JsonObject:
             return _result(request_id, _tool_result(self._verify_audit()))
         return _error(request_id, -32602, f"unknown tool: {name}")
 
+    def _read_resource(self, request_id: Any, params: Any) -> JsonObject:
+        if not isinstance(params, dict):
+            return _error(request_id, -32602, "resources/read params must be an object")
+        uri = params.get("uri")
+        if uri not in self.resources:
+            return _error(request_id, -32602, f"unknown or disabled resource: {uri}")
+        if uri == RUNBOOKS_SUMMARY_RESOURCE:
+            return _result(request_id, _resource_result(uri, _runbook_summary(self.runbooks)))
+        if uri == SKILLS_SUMMARY_RESOURCE:
+            return _result(request_id, _resource_result(uri, _skill_summary(self.skills)))
+        return _error(request_id, -32602, f"unknown resource: {uri}")
+
     def _classify(self, arguments: JsonObject) -> JsonObject:
         command = arguments.get("command")
         if not isinstance(command, str) or not command:
@@ -173,7 +217,10 @@ def _initialize_result(params: Any) -> JsonObject:
         protocol_version = str(params["protocolVersion"])
     return {
         "protocolVersion": protocol_version,
-        "capabilities": {"tools": {"listChanged": False}},
+        "capabilities": {
+            "tools": {"listChanged": False},
+            "resources": {"subscribe": False, "listChanged": False},
+        },
         "serverInfo": {"name": SERVER_NAME, "version": __version__},
     }
 
@@ -182,6 +229,59 @@ def _tools(names: tuple[McpToolName, ...]) -> tuple[JsonObject, ...]:
     return tuple(_TOOL_DEFINITIONS[name] for name in names)
 
 
+def _resources(uris: tuple[McpResourceUri, ...]) -> tuple[JsonObject, ...]:
+    return tuple(_RESOURCE_DEFINITIONS[uri] for uri in uris)
+
+
+def _resource_result(uri: str, payload: JsonObject) -> JsonObject:
+    text = json.dumps(redact_record(payload), ensure_ascii=False, sort_keys=True)
+    return {
+        "contents": [
+            {
+                "uri": uri,
+                "mimeType": "application/json",
+                "text": text,
+            }
+        ]
+    }
+
+
+def _runbook_summary(runbooks: tuple[Runbook, ...]) -> JsonObject:
+    return {
+        "runbooks": [
+            {
+                "id": runbook.id,
+                "title": runbook.title,
+                "steps": [
+                    {
+                        "purpose": step.purpose,
+                        "read_only": step.read_only,
+                    }
+                    for step in runbook.steps
+                ],
+            }
+            for runbook in runbooks
+        ]
+    }
+
+
+def _skill_summary(skills: tuple[SkillManifest, ...]) -> JsonObject:
+    return {
+        "enabled": bool(skills),
+        "skills": [
+            {
+                "name": skill.name,
+                "version": skill.version,
+                "description": skill.description,
+                "permissions": list(skill.permissions),
+                "has_planner_guidance": bool(skill.planner_guidance),
+                "runbooks": [runbook.id for runbook in skill.runbooks],
+            }
+            for skill in skills
+        ],
+    }
+
+
 def _tool_result(payload: JsonObject) -> JsonObject:
     return {
         "content": payload["content"],

src/linuxagent/mcp_tools.py

@@ -1,18 +1,29 @@
-"""MCP tool name constants shared by config and server code."""
+"""MCP surface constants shared by config and server code."""
 
 from __future__ import annotations
 
 from typing import Literal
 
 McpToolName = Literal["linuxagent.policy.classify", "linuxagent.audit.verify"]
+McpResourceUri = Literal["linuxagent://runbooks/summary", "linuxagent://skills/summary"]
 
 POLICY_TOOL_NAME: McpToolName = "linuxagent.policy.classify"
 AUDIT_TOOL_NAME: McpToolName = "linuxagent.audit.verify"
 MCP_READ_ONLY_TOOL_NAMES: tuple[McpToolName, ...] = (POLICY_TOOL_NAME, AUDIT_TOOL_NAME)
+RUNBOOKS_SUMMARY_RESOURCE: McpResourceUri = "linuxagent://runbooks/summary"
+SKILLS_SUMMARY_RESOURCE: McpResourceUri = "linuxagent://skills/summary"
+MCP_READ_ONLY_RESOURCE_URIS: tuple[McpResourceUri, ...] = (
+    RUNBOOKS_SUMMARY_RESOURCE,
+    SKILLS_SUMMARY_RESOURCE,
+)
 
 __all__ = [
     "AUDIT_TOOL_NAME",
+    "MCP_READ_ONLY_RESOURCE_URIS",
     "MCP_READ_ONLY_TOOL_NAMES",
     "POLICY_TOOL_NAME",
+    "RUNBOOKS_SUMMARY_RESOURCE",
+    "SKILLS_SUMMARY_RESOURCE",
+    "McpResourceUri",
     "McpToolName",
 ]

tests/unit/test_cli_and_container.py

@@ -267,20 +267,36 @@ def test_audit_verify_command_reports_tamper(
 
 
 def test_mcp_command_starts_stdio_server(monkeypatch: pytest.MonkeyPatch) -> None:
-    cfg = AppConfig.model_validate({"mcp": {"tools": ["linuxagent.policy.classify"]}})
+    cfg = AppConfig.model_validate(
+        {
+            "mcp": {
+                "tools": ["linuxagent.policy.classify"],
+                "resources": ["linuxagent://skills/summary"],
+            },
+            "telemetry": {"enabled": False, "exporter": "none"},
+        }
+    )
     calls: list[tuple[str, Path]] = []
 
     monkeypatch.setattr(cli, "load_config", lambda **_: cfg)
     monkeypatch.setattr(
         cli,
         "serve_stdio",
-        lambda server: calls.append(("serve", server.audit_path, server.tools)) or 0,
+        lambda server: calls.append(("serve", server.audit_path, server.tools, server.resources))
+        or 0,
     )
 
     code = cli.main(["mcp"])
 
     assert code == 0
-    assert calls == [("serve", cfg.audit.path, ("linuxagent.policy.classify",))]
+    assert calls == [
+        (
+            "serve",
+            cfg.audit.path,
+            ("linuxagent.policy.classify",),
+            ("linuxagent://skills/summary",),
+        )
+    ]
 
 
 def test_mcp_command_rejects_disabled_server(