Add MCP skill registry install support by evalstate · Pull Request #815 · evalstate/fast-agent

evalstate · 2026-05-29T23:26:50Z

Summary

implement the first SEP-2640 Skills over MCP slice as MCP-server-backed skill registries for installation
add /skills registry selection, /skills add support, MCP provenance metadata, and MCP status/autocomplete updates
add docs page and regenerated tmux/asciinema demo showing registry selection and install

Scope

This PR intentionally does not expose MCP-served skill resources directly to the model. That deeper runtime work is split into the follow-up PR.

Tests

uv run pytest tests/unit/fast_agent/skills/test_mcp_registry.py tests/unit/fast_agent/commands/test_skills_mcp_registry_handlers.py tests/unit/fast_agent/commands/test_command_discovery.py tests/unit/fast_agent/skills/test_command_support.py tests/unit/fast_agent/commands/test_mcp_runtime_handlers.py tests/unit/fast_agent/ui/test_agent_completer.py tests/unit/fast_agent/ui/test_agent_info.py tests/unit/fast_agent/ui/test_mcp_display.py -q
uv run scripts/lint.py
uv run scripts/typecheck.py
uv run scripts/docs.py cast-check

Calfskin wallet

I would not use it; I would prefer a non-animal alternative.

cloudflare-workers-and-pages · 2026-05-29T23:28:48Z

Deploying fast-agent with Cloudflare Pages

Latest commit:	`91e7d7f`
Status:	✅ Deploy successful!
Preview URL:	https://b9a975b7.fast-agent.pages.dev
Branch Preview URL:	https://feat-sep2640-mcp-skill-regis.fast-agent.pages.dev

View logs

Implements the first SEP-2640 Skills over MCP slice by treating capable MCP servers as install registries for skill-md entries. Adds registry discovery, installation with MCP provenance, slash-command selection, MCP status display, docs, and the tmux/asciinema demo. Co-authored-by: olaservo <olahungerford@gmail.com>

Reset skills-repo to the commit used by main so Cloudflare can clone submodules during the docs build.

Copilot

Pull request overview

Adds initial SEP-2640 “Skills over MCP” support by treating connected MCP servers as installable skill registries (without exposing MCP-served skill resources directly to the model at runtime yet).

Changes:

Implement MCP-backed skill registry discovery + installation flow (/skills registry, /skills add) with MCP provenance metadata.
Update TUI surfaces (MCP status display, agent info, autocompletion) to reflect MCP skills/registries.
Add documentation + demo assets for “Skills over MCP”.

Reviewed changes

Copilot reviewed 23 out of 24 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/unit/fast_agent/ui/test_mcp_display.py	Adds coverage asserting SEP-2640 hint placement in `/mcp` status output.
tests/unit/fast_agent/ui/test_agent_info.py	New tests for MCP surface counting and child-agent summary ordering.
tests/unit/fast_agent/ui/test_agent_completer.py	Adds tests for MCP registry completions in `/skills registry`.
tests/unit/fast_agent/skills/test_mcp_registry.py	New tests for capability gating, registry scanning, and MCP install provenance.
tests/unit/fast_agent/commands/test_skills_mcp_registry_handlers.py	New tests for listing/selecting MCP registries and browsing MCP skills.
tests/unit/fast_agent/commands/test_command_discovery.py	Updates command usage text to mention `mcp-server` option.
src/fast_agent/ui/prompt/completer.py	Adds MCP registry completion support for `/skills registry`.
src/fast_agent/ui/prompt/agent_info.py	Refactors agent surface counts; uses MCP aggregator for MCP agents.
src/fast_agent/ui/mcp_display.py	Adds “Sk” capability + a SEP-2640 hint line when MCP skills are enabled.
src/fast_agent/skills/provenance.py	Extends skill provenance schema/formatting/parsing for MCP-installed skills.
src/fast_agent/skills/operations.py	Treats MCP-sourced managed skills as non-comparable for updates.
src/fast_agent/skills/models.py	Adds `mcp` to `SkillSourceOrigin` and MCP provenance fields.
src/fast_agent/skills/mcp_registry.py	New MCP registry module: capability detection, index parsing, install.
src/fast_agent/skills/command_support.py	Updates `/skills` usage help to mention MCP registry selection.
src/fast_agent/mcp/mcp_aggregator.py	Exposes `list_mcp_skill_registries()` and records `mcp_skills_enabled` in status.
src/fast_agent/commands/handlers/skills.py	Adds MCP-aware registry selection, marketplace listing, and install flow.
src/fast_agent/commands/handlers/mcp_runtime.py	Extends attach/reconnect summaries to optionally show skill counts.
src/fast_agent/commands/command_catalog.py	Updates usage string to include MCP server selection option.
scripts/docs_assets.py	Adds a new terminal cast scenario and tweaks env cleanup for docs demos.
docs/zensical.toml	Adds “Skills over MCP” doc page to MCP nav.
docs/social_cards/contact-sheet.html	Updates social card sheet count + adds MCP skills card entry and adjusts xAI label.
docs/docs/mcp/skills-over-mcp.md	New documentation page describing scope and usage.
docs/docs/assets/tui/skills-over-mcp.cast	New asciinema cast demonstrating MCP registry selection and install.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

            partial,
            configured_urls=configured_urls,
            display_formatter=format_marketplace_display_url,
        )
+        yield from self._complete_mcp_skill_registries(partial, offset=len(configured_urls))


+async def list_mcp_skill_registries(
+    aggregator: McpSkillRegistryStatusClient, server_names: Iterable[str]
+) -> list[McpSkillRegistry]:
+    registries: list[McpSkillRegistry] = []
+    for server_name in server_names:
+        server_version = await _server_version(aggregator, server_name)
+        registry = await scan_mcp_skill_registry(
+            aggregator, server_name, server_version=server_version
+        )
+        if registry is not None:
+            registries.append(registry)
+    return registries


evalstate · 2026-06-02T15:24:53Z

Thanks @olaservo -- great work! let's continue the experiments with auto-loading etc. on #816 or a new branch :)

Bring fast-agent's SEP-2640 host support up to two Working Group decisions that landed after the initial registry implementation (PR evalstate#815). Index schema (ADR 2026-06-05): parse the verbatim `frontmatter` object and a per-skill `archives[]` array (`{url, mimeType, digest}`) instead of the old flat `type`/`name`/`description` entries. An entry must supply a usable `url`, a non-empty `archives`, or both; old `type`-based entries are no longer parsed. Install prefers an archive when offered, else the direct SKILL.md; archive extraction routes by media type with a URL-suffix fallback. resources/directory/read (ADR 2026-06-09): add `directoryRead` capability detection, a `read_directory()` client-session method + aggregator routing, and use it at install time to materialize a direct-entry skill's supporting files (best-effort, with the existing path-traversal/size-bomb guards). Split the install client protocol (`McpSkillInstallClient`) from the narrow scan client. Tests rewritten to the new schema with added coverage for frontmatter/archives parsing, skip rules, capability detection, and the directory walk. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…ad (#825) * Update Skills-over-MCP host to current SEP-2640 Bring fast-agent's SEP-2640 host support up to two Working Group decisions that landed after the initial registry implementation (PR #815). Index schema (ADR 2026-06-05): parse the verbatim `frontmatter` object and a per-skill `archives[]` array (`{url, mimeType, digest}`) instead of the old flat `type`/`name`/`description` entries. An entry must supply a usable `url`, a non-empty `archives`, or both; old `type`-based entries are no longer parsed. Install prefers an archive when offered, else the direct SKILL.md; archive extraction routes by media type with a URL-suffix fallback. resources/directory/read (ADR 2026-06-09): add `directoryRead` capability detection, a `read_directory()` client-session method + aggregator routing, and use it at install time to materialize a direct-entry skill's supporting files (best-effort, with the existing path-traversal/size-bomb guards). Split the install client protocol (`McpSkillInstallClient`) from the narrow scan client. Tests rewritten to the new schema with added coverage for frontmatter/archives parsing, skip rules, capability detection, and the directory walk. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * Bound directory-read walk and note supporting-file trust model Cap the SEP-2640 resources/directory/read walk so a buggy or hostile server cannot hang an install: limit total pages (the never-terminating nextCursor case), total entries, and nesting depth via a shared _WalkLimits counter and an explicit depth parameter. Limit breaches raise and are swallowed by the existing best-effort handler, leaving the valid single-file skill in place. Document that walked supporting files carry no per-file digests and are written on the server's word alone, unlike the digest-verified SKILL.md and archive artifacts. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * Harden MCP skill supporting-file walk and dedup index validation Self-review fixes for the SEP-2640 directory-read install path: - Reject Windows path separators and drive anchors in _validate_archive_name. A PurePosixPath-only check let server-supplied names like "..\..\evil.md" escape install_dir on Windows (AnyUrl preserves backslashes while it collapses forward-slash "../"). - Skip the verified SKILL.md case-insensitively so an unverified sibling named "skill.md"/"SKILL.MD" cannot clobber the digest-checked file on case-insensitive filesystems. - Log dropped resources (outside the skill root, or a file-branch resource with no bytes from an untagged directory) so an incomplete install is diagnosable instead of silent. - Materialize supporting files into a staging dir and merge into install_dir only on full success, so a mid-walk failure leaves the valid single-file skill intact rather than a half-written tree. - Extract _validate_url_and_digest shared by direct entries and archives, removing the duplicated non-empty / non-file:// / sha256 checks. Adds tests for backslash/drive rejection, no-clobber of SKILL.md, and partial-write rollback. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * Harden and dedup SEP-2640 supporting-file walk Self-review fixes for the directory-walk / install path: - Cap each supporting file at MAX_SUPPORTING_FILE_BYTES so a single oversized resource cannot be decoded into memory before the cumulative budget rejects it. - Promote the "resource returned no content" drop from debug to warning so an untagged directory silently omitting its children is diagnosable. - Normalize the skill root URI through AnyUrl (matching how child resource URIs arrive) so a dot-segment/encoding difference no longer silently drops children. - Match the "/SKILL.md" suffix case-insensitively so a "/skill.md" url still triggers supporting-file materialization. - read_directory now requires an explicit server_name instead of fanning out across servers (which could read a same-named URI off the wrong server and mask real errors). - Dedup _get_resource_from_server / _read_directory_from_server behind a shared _execute_resource_read helper; directory reads now emit the READING_RESOURCE progress event they previously lacked. - Make the validated archive mimeType authoritative in _archive_strategy and drop the legacy .zip URL-suffix guess. Adds regression tests for the per-resource cap and the case-insensitive root. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * Trim verbose comments in SEP-2640 skills-over-MCP host Condense multi-paragraph docstrings and inline comments across the registry, aggregator, and client session to the essential rationale. Also correct the MAX_SUPPORTING_FILE_BYTES comment, which overstated memory protection; it bounds per-file size under the cumulative budget. Comments only -- no behavior change. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

evalstate mentioned this pull request May 29, 2026

Add MCP-served skill runtime support #816

Draft

evalstate force-pushed the feat/sep2640-mcp-skill-registries branch from 840e486 to 37284da Compare May 29, 2026 23:30

evalstate force-pushed the feat/sep2640-mcp-skill-registries branch from 37284da to 023b657 Compare May 29, 2026 23:37

evalstate added 2 commits May 30, 2026 00:39

Update skills repo pointer

189e64d

fix ux regression

ce5d80f

evalstate force-pushed the feat/sep2640-mcp-skill-registries branch from f3b10e1 to ce5d80f Compare May 29, 2026 23:48

Restore fetchable skills submodule pointer

fb7ecba

Reset skills-repo to the commit used by main so Cloudflare can clone submodules during the docs build.

evalstate requested a review from Copilot May 30, 2026 00:00

Copilot started reviewing on behalf of evalstate May 30, 2026 00:00 View session

Copilot AI reviewed May 30, 2026

View reviewed changes

olaservo mentioned this pull request May 31, 2026

Add Skills-over-MCP SEP support to host olaservo/fast-agent#1

Closed

evalstate added 4 commits June 2, 2026 12:48

attach_media in-line display

d64a757

version/lock bump

575fb1d

Merge branch 'dev/0.7.15' into feat/sep2640-mcp-skill-registries

0c2c97f

sha check, .tar.gz handling, docs

7834edf

olaservo mentioned this pull request Jun 2, 2026

Experimental/skills over mcp v2 base #810

Closed

evalstate added 2 commits June 2, 2026 16:15

social cards, test fix

6ddff23

attribution

91e7d7f

evalstate marked this pull request as ready for review June 2, 2026 15:20

evalstate merged commit 10a996b into main Jun 2, 2026
12 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add MCP skill registry install support#815

Add MCP skill registry install support#815
evalstate merged 10 commits into
mainfrom
feat/sep2640-mcp-skill-registries

evalstate commented May 29, 2026

Uh oh!

cloudflare-workers-and-pages Bot commented May 29, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

evalstate commented Jun 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

evalstate commented May 29, 2026

Summary

Scope

Tests

Calfskin wallet

Uh oh!

cloudflare-workers-and-pages Bot commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying fast-agent with Cloudflare Pages

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

evalstate commented Jun 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cloudflare-workers-and-pages Bot commented May 29, 2026 •

edited

Loading