agentskills-mcp-extension 0.8.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- agentskills_mcp_extension-0.8.0/PKG-INFO +245 -0
- agentskills_mcp_extension-0.8.0/README.md +217 -0
- agentskills_mcp_extension-0.8.0/agentskills_mcp_extension/__init__.py +51 -0
- agentskills_mcp_extension-0.8.0/agentskills_mcp_extension/__main__.py +179 -0
- agentskills_mcp_extension-0.8.0/agentskills_mcp_extension/client.py +221 -0
- agentskills_mcp_extension-0.8.0/agentskills_mcp_extension/config.py +232 -0
- agentskills_mcp_extension-0.8.0/agentskills_mcp_extension/native.py +521 -0
- agentskills_mcp_extension-0.8.0/agentskills_mcp_extension/py.typed +0 -0
- agentskills_mcp_extension-0.8.0/pyproject.toml +37 -0
|
@@ -0,0 +1,245 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: agentskills-mcp-extension
|
|
3
|
+
Version: 0.8.0
|
|
4
|
+
Summary: Publish and consume the official MCP Skills extension (https://agentskills.io)
|
|
5
|
+
License: MIT
|
|
6
|
+
Author: Pratik Panda
|
|
7
|
+
Requires-Python: >=3.12,<4.0
|
|
8
|
+
Classifier: Development Status :: 3 - Alpha
|
|
9
|
+
Classifier: Intended Audience :: Developers
|
|
10
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
16
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
17
|
+
Provides-Extra: fs
|
|
18
|
+
Provides-Extra: http
|
|
19
|
+
Requires-Dist: agentskills-core (>=0.8.0,<1.0)
|
|
20
|
+
Requires-Dist: agentskills-fs (>=0.8.0,<1.0) ; extra == "fs"
|
|
21
|
+
Requires-Dist: agentskills-http (>=0.8.0,<1.0) ; extra == "http"
|
|
22
|
+
Requires-Dist: mcp (>=2.2,<3)
|
|
23
|
+
Requires-Dist: pydantic (>=2.0)
|
|
24
|
+
Project-URL: Homepage, https://agentskills.io
|
|
25
|
+
Project-URL: Repository, https://github.com/pratikxpanda/agentskills-sdk
|
|
26
|
+
Description-Content-Type: text/markdown
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
title: agentskills-mcp-extension
|
|
30
|
+
description: Native MCP Skills publication and origin-preserving client helpers.
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
Publish and consume the official MCP Skills extension with immutable, lossless resources.
|
|
34
|
+
|
|
35
|
+
## Native Skills Only
|
|
36
|
+
|
|
37
|
+
The native Skills API requires MCP SDK `>=2.2,<3`. It serves the official
|
|
38
|
+
`io.modelcontextprotocol/skills` extension on protocol `2026-07-28` through
|
|
39
|
+
`skills/list`, `skills/get`, and canonical `skill://` resources. Clients on older
|
|
40
|
+
protocol revisions see the same `skill://` files as ordinary resources and cannot
|
|
41
|
+
call the Skills methods. See the
|
|
42
|
+
[breaking-change guide](https://github.com/pratikxpanda/agentskills-sdk/blob/main/docs/mcp-migration.md).
|
|
43
|
+
|
|
44
|
+
## Install
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
pip install "agentskills-mcp-extension[fs]"
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
The `[http]` extra adds the HTTP provider. Publisher verification needs
|
|
51
|
+
`agentskills-core[verification]` and OpenTelemetry export needs
|
|
52
|
+
`agentskills-core[telemetry]`. Use an isolated server environment
|
|
53
|
+
when a host framework pins a different MCP SDK version.
|
|
54
|
+
|
|
55
|
+
## Serve a Folder
|
|
56
|
+
|
|
57
|
+
Prepare `skills/incident-response/SKILL.md` with valid `name` and `description` frontmatter.
|
|
58
|
+
The [filesystem guide](https://github.com/pratikxpanda/agentskills-sdk/blob/main/packages/providers/agentskills-fs/README.md#usage)
|
|
59
|
+
includes a complete sample skill. The Python example publishes that folder over stdio:
|
|
60
|
+
|
|
61
|
+
```python
|
|
62
|
+
import asyncio
|
|
63
|
+
from pathlib import Path
|
|
64
|
+
|
|
65
|
+
from agentskills_core import Skill
|
|
66
|
+
from agentskills_fs import LocalFileSystemSkillProvider
|
|
67
|
+
from agentskills_mcp_extension import create_mcp_server
|
|
68
|
+
|
|
69
|
+
provider = LocalFileSystemSkillProvider(Path("./skills"))
|
|
70
|
+
server = asyncio.run(create_mcp_server([Skill("incident-response", provider)]))
|
|
71
|
+
server.run(transport="stdio")
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
`create_mcp_server` is async and accepts a `SkillRegistry` or a sequence of raw
|
|
75
|
+
`Skill` handles. Raw handles avoid imposing registry-specific parsing restrictions
|
|
76
|
+
before publication. Discovery is metadata-only, including for a single skill.
|
|
77
|
+
|
|
78
|
+
The factory captures complete immutable file sets before serving. It preserves
|
|
79
|
+
original `SKILL.md` bytes, frontmatter, supporting directories, and binary files.
|
|
80
|
+
Each manifest contains raw-byte SHA-256 digests and sizes. A file whose bytes are
|
|
81
|
+
valid UTF-8 without NUL is read as `text` and every other file as `blob`. Both
|
|
82
|
+
forms return the exact captured bytes. Programmatic servers
|
|
83
|
+
support `await server.refresh()` and `server.health()`.
|
|
84
|
+
Server-provided hashes establish consistency, not publisher identity or safety.
|
|
85
|
+
Programmatic callers own provider cleanup and must keep providers open for refresh.
|
|
86
|
+
Optional `publication_policy` verifies detached signatures, pins content, and
|
|
87
|
+
applies reject/redact/annotate hooks before manifests are generated. See the
|
|
88
|
+
[trust and operability guide](https://github.com/pratikxpanda/agentskills-sdk/blob/main/docs/trust-and-operability.md)
|
|
89
|
+
for publisher configuration, token limits, verified stale policy, telemetry,
|
|
90
|
+
and authenticated remote HTTP deployment.
|
|
91
|
+
|
|
92
|
+
## Consume Skills
|
|
93
|
+
|
|
94
|
+
Save the configuration example below as `server.json` and prepare its filesystem skill folder.
|
|
95
|
+
Activate the environment where this package is installed so `agentskills-mcp` is on `PATH`.
|
|
96
|
+
This example uses the official SDK to start a stdio subprocess, create a session, and close it
|
|
97
|
+
when finished. `McpSkillsClient` wraps that session and leaves transport ownership with the host:
|
|
98
|
+
|
|
99
|
+
```python
|
|
100
|
+
import asyncio
|
|
101
|
+
import os
|
|
102
|
+
|
|
103
|
+
from mcp import Client, StdioServerParameters
|
|
104
|
+
|
|
105
|
+
from agentskills_mcp_extension import McpSkillsClient
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
async def main() -> None:
|
|
109
|
+
parameters = StdioServerParameters(
|
|
110
|
+
command="agentskills-mcp",
|
|
111
|
+
args=["--config", "server.json"],
|
|
112
|
+
env={"PYTHONPATH": os.environ.get("PYTHONPATH", "")},
|
|
113
|
+
)
|
|
114
|
+
async with Client(parameters) as connection:
|
|
115
|
+
client = McpSkillsClient(connection.session, origin="incident-runbooks")
|
|
116
|
+
skills = await client.list_skills()
|
|
117
|
+
if not skills:
|
|
118
|
+
print("No skills published")
|
|
119
|
+
return
|
|
120
|
+
skill = await client.get_skill(skills[0].identity.uri)
|
|
121
|
+
print(await client.read_resource(skill, skill.identity.uri))
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
asyncio.run(main())
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
The example forwards `PYTHONPATH` so a subprocess can find checkout-based packages. With the
|
|
128
|
+
package installed in the selected Python environment, that `env` argument can be omitted.
|
|
129
|
+
|
|
130
|
+
References retain both the supplied origin identity and canonical `skill://` URI. Reads verify
|
|
131
|
+
the manifest's size and SHA-256 digest. The client does not implement `SkillProvider` or insert
|
|
132
|
+
remote content into a `SkillRegistry`, since registration validates by reading bodies eagerly.
|
|
133
|
+
It also keeps no shared response cache, so separate server origins remain isolated.
|
|
134
|
+
|
|
135
|
+
To compose two sources, keep both SDK `Client` connections open using the pattern above and
|
|
136
|
+
pass them to this helper. The caller creates and closes the connections:
|
|
137
|
+
|
|
138
|
+
```python
|
|
139
|
+
from mcp import Client
|
|
140
|
+
|
|
141
|
+
from agentskills_mcp_extension import McpSkillReference, McpSkillsCollection, McpSkillsClient
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
async def collect_skills(runbooks: Client, security: Client) -> list[McpSkillReference]:
|
|
145
|
+
catalog = McpSkillsCollection([
|
|
146
|
+
McpSkillsClient(runbooks.session, origin="incident-runbooks"),
|
|
147
|
+
McpSkillsClient(security.session, origin="security-guides"),
|
|
148
|
+
])
|
|
149
|
+
return await catalog.list_skills()
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Identity remains `(origin, URI)`. The collection does not rehost or forward content, which avoids
|
|
153
|
+
loops and keeps approval and session state with the application.
|
|
154
|
+
|
|
155
|
+
## Prompt Shortcut
|
|
156
|
+
|
|
157
|
+
Hosts that support MCP prompts can opt in to one user-invoked `use-skill` prompt. It requires the
|
|
158
|
+
canonical `skill://` URI and reads the current published snapshot when requested. It is disabled
|
|
159
|
+
by default and does not grant tool permissions:
|
|
160
|
+
|
|
161
|
+
```python
|
|
162
|
+
server = await create_mcp_server(skills, skill_prompt_shortcuts=True)
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
Set `"skill_prompt_shortcuts": true` in server config to enable the same prompt. The host
|
|
166
|
+
remains responsible for prompt approval and whether the returned skill content is used.
|
|
167
|
+
|
|
168
|
+
## Configuration
|
|
169
|
+
|
|
170
|
+
```json
|
|
171
|
+
{
|
|
172
|
+
"name": "Skills Server",
|
|
173
|
+
"skills": [
|
|
174
|
+
{"id": "incident-response", "provider": "fs", "options": {"root": "./skills"}}
|
|
175
|
+
]
|
|
176
|
+
}
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
```bash
|
|
180
|
+
agentskills-mcp --config server.json --check
|
|
181
|
+
agentskills-mcp --config server.json
|
|
182
|
+
agentskills-mcp --config server.json --transport streamable-http
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
The distribution installs the short `agentskills-mcp` command. The Python module entry point
|
|
186
|
+
is equivalent when you need to select an interpreter explicitly:
|
|
187
|
+
|
|
188
|
+
```bash
|
|
189
|
+
python -m agentskills_mcp_extension --config server.json --check
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
JSON and YAML are supported. `${VAR}` placeholders resolve from the environment.
|
|
193
|
+
Unknown top-level keys are rejected. The CLI closes owned provider clients after
|
|
194
|
+
capture, including on failure.
|
|
195
|
+
|
|
196
|
+
| Field | Default | Meaning |
|
|
197
|
+
| --- | --- | --- |
|
|
198
|
+
| `name` | Required | Server display name |
|
|
199
|
+
| `skills` | Required, nonempty | IDs, provider types, and constructor options |
|
|
200
|
+
| `instructions` | `null` | Optional server-level instructions |
|
|
201
|
+
| `skill_paths` | `{}` | Registry ID to canonical publication path |
|
|
202
|
+
| `listed_skill_ids` | `null` | Optional listing subset, not authorization |
|
|
203
|
+
| `page_size` | `100` | Maximum entries per discovery page |
|
|
204
|
+
| `max_skills` | `128` | Publication skill-count ceiling |
|
|
205
|
+
| `max_total_bytes` | `67108864` | Total captured source byte ceiling |
|
|
206
|
+
|
|
207
|
+
Filesystem options include `root` and `max_file_bytes`. HTTP options include
|
|
208
|
+
`base_url`, `headers`, `params`, `file_manifest`, `resource_manifest`, and
|
|
209
|
+
`max_response_bytes`. HTTP native publication requires `file_manifest: true` and
|
|
210
|
+
a public destination by default. Internal destinations require explicit
|
|
211
|
+
`allow_private_network: true`. Redirects are always rejected. Configure
|
|
212
|
+
`require_tls`, `timeout`, and retry limits as needed. Publication requires
|
|
213
|
+
a complete per-skill file index. See the
|
|
214
|
+
[HTTP provider](https://github.com/pratikxpanda/agentskills-sdk/blob/main/packages/providers/agentskills-http/README.md).
|
|
215
|
+
|
|
216
|
+
The extension enforces 512 files and 16 MiB per skill. Directory reads are not
|
|
217
|
+
advertised. Nested skills require explicit publication and separate host approval.
|
|
218
|
+
Listed subsets never restrict direct lookup of a published skill. Supply only
|
|
219
|
+
skills authorized for the server audience.
|
|
220
|
+
|
|
221
|
+
The package-specific `--check` option verifies local construction, manifests, and provider
|
|
222
|
+
readiness without listening. It does not certify transport, authentication, or host behavior.
|
|
223
|
+
|
|
224
|
+
## Client Support and Boundaries
|
|
225
|
+
|
|
226
|
+
Tests exercise MCP 2.2.0 `Client` in-process, over stdio, and over real loopback
|
|
227
|
+
Streamable HTTP. CI also checks mcpc 0.7.0 discovery, aliases, pagination, and exact
|
|
228
|
+
resource bytes. Use SDK 2 `Client` for extension negotiation, not its older
|
|
229
|
+
`ClientSession` compatibility API. Ordinary tools/resources connectivity does not
|
|
230
|
+
establish Skills support.
|
|
231
|
+
|
|
232
|
+
Hosts own selection, manifest verification, origin visibility,
|
|
233
|
+
per-skill consent, context injection, session tracking, image rendering, and
|
|
234
|
+
execution policy. Resource reads never execute scripts or grant `allowed-tools`.
|
|
235
|
+
|
|
236
|
+
Production HTTP deployments must supply TLS, MCP authorization, audience isolation,
|
|
237
|
+
and appropriate origin/host validation. Do not pass client bearer tokens to upstream
|
|
238
|
+
providers. Local tests are not production deployment certification.
|
|
239
|
+
|
|
240
|
+
## Benchmarks
|
|
241
|
+
|
|
242
|
+
The [benchmark guide](https://github.com/pratikxpanda/agentskills-sdk/blob/main/docs/mcp-benchmarks.md)
|
|
243
|
+
describes native discovery and progressive reads over bounded synthetic catalogs.
|
|
244
|
+
It does not measure model quality or production network performance.
|
|
245
|
+
|
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: agentskills-mcp-extension
|
|
3
|
+
description: Native MCP Skills publication and origin-preserving client helpers.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Publish and consume the official MCP Skills extension with immutable, lossless resources.
|
|
7
|
+
|
|
8
|
+
## Native Skills Only
|
|
9
|
+
|
|
10
|
+
The native Skills API requires MCP SDK `>=2.2,<3`. It serves the official
|
|
11
|
+
`io.modelcontextprotocol/skills` extension on protocol `2026-07-28` through
|
|
12
|
+
`skills/list`, `skills/get`, and canonical `skill://` resources. Clients on older
|
|
13
|
+
protocol revisions see the same `skill://` files as ordinary resources and cannot
|
|
14
|
+
call the Skills methods. See the
|
|
15
|
+
[breaking-change guide](https://github.com/pratikxpanda/agentskills-sdk/blob/main/docs/mcp-migration.md).
|
|
16
|
+
|
|
17
|
+
## Install
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
pip install "agentskills-mcp-extension[fs]"
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
The `[http]` extra adds the HTTP provider. Publisher verification needs
|
|
24
|
+
`agentskills-core[verification]` and OpenTelemetry export needs
|
|
25
|
+
`agentskills-core[telemetry]`. Use an isolated server environment
|
|
26
|
+
when a host framework pins a different MCP SDK version.
|
|
27
|
+
|
|
28
|
+
## Serve a Folder
|
|
29
|
+
|
|
30
|
+
Prepare `skills/incident-response/SKILL.md` with valid `name` and `description` frontmatter.
|
|
31
|
+
The [filesystem guide](https://github.com/pratikxpanda/agentskills-sdk/blob/main/packages/providers/agentskills-fs/README.md#usage)
|
|
32
|
+
includes a complete sample skill. The Python example publishes that folder over stdio:
|
|
33
|
+
|
|
34
|
+
```python
|
|
35
|
+
import asyncio
|
|
36
|
+
from pathlib import Path
|
|
37
|
+
|
|
38
|
+
from agentskills_core import Skill
|
|
39
|
+
from agentskills_fs import LocalFileSystemSkillProvider
|
|
40
|
+
from agentskills_mcp_extension import create_mcp_server
|
|
41
|
+
|
|
42
|
+
provider = LocalFileSystemSkillProvider(Path("./skills"))
|
|
43
|
+
server = asyncio.run(create_mcp_server([Skill("incident-response", provider)]))
|
|
44
|
+
server.run(transport="stdio")
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
`create_mcp_server` is async and accepts a `SkillRegistry` or a sequence of raw
|
|
48
|
+
`Skill` handles. Raw handles avoid imposing registry-specific parsing restrictions
|
|
49
|
+
before publication. Discovery is metadata-only, including for a single skill.
|
|
50
|
+
|
|
51
|
+
The factory captures complete immutable file sets before serving. It preserves
|
|
52
|
+
original `SKILL.md` bytes, frontmatter, supporting directories, and binary files.
|
|
53
|
+
Each manifest contains raw-byte SHA-256 digests and sizes. A file whose bytes are
|
|
54
|
+
valid UTF-8 without NUL is read as `text` and every other file as `blob`. Both
|
|
55
|
+
forms return the exact captured bytes. Programmatic servers
|
|
56
|
+
support `await server.refresh()` and `server.health()`.
|
|
57
|
+
Server-provided hashes establish consistency, not publisher identity or safety.
|
|
58
|
+
Programmatic callers own provider cleanup and must keep providers open for refresh.
|
|
59
|
+
Optional `publication_policy` verifies detached signatures, pins content, and
|
|
60
|
+
applies reject/redact/annotate hooks before manifests are generated. See the
|
|
61
|
+
[trust and operability guide](https://github.com/pratikxpanda/agentskills-sdk/blob/main/docs/trust-and-operability.md)
|
|
62
|
+
for publisher configuration, token limits, verified stale policy, telemetry,
|
|
63
|
+
and authenticated remote HTTP deployment.
|
|
64
|
+
|
|
65
|
+
## Consume Skills
|
|
66
|
+
|
|
67
|
+
Save the configuration example below as `server.json` and prepare its filesystem skill folder.
|
|
68
|
+
Activate the environment where this package is installed so `agentskills-mcp` is on `PATH`.
|
|
69
|
+
This example uses the official SDK to start a stdio subprocess, create a session, and close it
|
|
70
|
+
when finished. `McpSkillsClient` wraps that session and leaves transport ownership with the host:
|
|
71
|
+
|
|
72
|
+
```python
|
|
73
|
+
import asyncio
|
|
74
|
+
import os
|
|
75
|
+
|
|
76
|
+
from mcp import Client, StdioServerParameters
|
|
77
|
+
|
|
78
|
+
from agentskills_mcp_extension import McpSkillsClient
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
async def main() -> None:
|
|
82
|
+
parameters = StdioServerParameters(
|
|
83
|
+
command="agentskills-mcp",
|
|
84
|
+
args=["--config", "server.json"],
|
|
85
|
+
env={"PYTHONPATH": os.environ.get("PYTHONPATH", "")},
|
|
86
|
+
)
|
|
87
|
+
async with Client(parameters) as connection:
|
|
88
|
+
client = McpSkillsClient(connection.session, origin="incident-runbooks")
|
|
89
|
+
skills = await client.list_skills()
|
|
90
|
+
if not skills:
|
|
91
|
+
print("No skills published")
|
|
92
|
+
return
|
|
93
|
+
skill = await client.get_skill(skills[0].identity.uri)
|
|
94
|
+
print(await client.read_resource(skill, skill.identity.uri))
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
asyncio.run(main())
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
The example forwards `PYTHONPATH` so a subprocess can find checkout-based packages. With the
|
|
101
|
+
package installed in the selected Python environment, that `env` argument can be omitted.
|
|
102
|
+
|
|
103
|
+
References retain both the supplied origin identity and canonical `skill://` URI. Reads verify
|
|
104
|
+
the manifest's size and SHA-256 digest. The client does not implement `SkillProvider` or insert
|
|
105
|
+
remote content into a `SkillRegistry`, since registration validates by reading bodies eagerly.
|
|
106
|
+
It also keeps no shared response cache, so separate server origins remain isolated.
|
|
107
|
+
|
|
108
|
+
To compose two sources, keep both SDK `Client` connections open using the pattern above and
|
|
109
|
+
pass them to this helper. The caller creates and closes the connections:
|
|
110
|
+
|
|
111
|
+
```python
|
|
112
|
+
from mcp import Client
|
|
113
|
+
|
|
114
|
+
from agentskills_mcp_extension import McpSkillReference, McpSkillsCollection, McpSkillsClient
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
async def collect_skills(runbooks: Client, security: Client) -> list[McpSkillReference]:
|
|
118
|
+
catalog = McpSkillsCollection([
|
|
119
|
+
McpSkillsClient(runbooks.session, origin="incident-runbooks"),
|
|
120
|
+
McpSkillsClient(security.session, origin="security-guides"),
|
|
121
|
+
])
|
|
122
|
+
return await catalog.list_skills()
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Identity remains `(origin, URI)`. The collection does not rehost or forward content, which avoids
|
|
126
|
+
loops and keeps approval and session state with the application.
|
|
127
|
+
|
|
128
|
+
## Prompt Shortcut
|
|
129
|
+
|
|
130
|
+
Hosts that support MCP prompts can opt in to one user-invoked `use-skill` prompt. It requires the
|
|
131
|
+
canonical `skill://` URI and reads the current published snapshot when requested. It is disabled
|
|
132
|
+
by default and does not grant tool permissions:
|
|
133
|
+
|
|
134
|
+
```python
|
|
135
|
+
server = await create_mcp_server(skills, skill_prompt_shortcuts=True)
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Set `"skill_prompt_shortcuts": true` in server config to enable the same prompt. The host
|
|
139
|
+
remains responsible for prompt approval and whether the returned skill content is used.
|
|
140
|
+
|
|
141
|
+
## Configuration
|
|
142
|
+
|
|
143
|
+
```json
|
|
144
|
+
{
|
|
145
|
+
"name": "Skills Server",
|
|
146
|
+
"skills": [
|
|
147
|
+
{"id": "incident-response", "provider": "fs", "options": {"root": "./skills"}}
|
|
148
|
+
]
|
|
149
|
+
}
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
agentskills-mcp --config server.json --check
|
|
154
|
+
agentskills-mcp --config server.json
|
|
155
|
+
agentskills-mcp --config server.json --transport streamable-http
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
The distribution installs the short `agentskills-mcp` command. The Python module entry point
|
|
159
|
+
is equivalent when you need to select an interpreter explicitly:
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
python -m agentskills_mcp_extension --config server.json --check
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
JSON and YAML are supported. `${VAR}` placeholders resolve from the environment.
|
|
166
|
+
Unknown top-level keys are rejected. The CLI closes owned provider clients after
|
|
167
|
+
capture, including on failure.
|
|
168
|
+
|
|
169
|
+
| Field | Default | Meaning |
|
|
170
|
+
| --- | --- | --- |
|
|
171
|
+
| `name` | Required | Server display name |
|
|
172
|
+
| `skills` | Required, nonempty | IDs, provider types, and constructor options |
|
|
173
|
+
| `instructions` | `null` | Optional server-level instructions |
|
|
174
|
+
| `skill_paths` | `{}` | Registry ID to canonical publication path |
|
|
175
|
+
| `listed_skill_ids` | `null` | Optional listing subset, not authorization |
|
|
176
|
+
| `page_size` | `100` | Maximum entries per discovery page |
|
|
177
|
+
| `max_skills` | `128` | Publication skill-count ceiling |
|
|
178
|
+
| `max_total_bytes` | `67108864` | Total captured source byte ceiling |
|
|
179
|
+
|
|
180
|
+
Filesystem options include `root` and `max_file_bytes`. HTTP options include
|
|
181
|
+
`base_url`, `headers`, `params`, `file_manifest`, `resource_manifest`, and
|
|
182
|
+
`max_response_bytes`. HTTP native publication requires `file_manifest: true` and
|
|
183
|
+
a public destination by default. Internal destinations require explicit
|
|
184
|
+
`allow_private_network: true`. Redirects are always rejected. Configure
|
|
185
|
+
`require_tls`, `timeout`, and retry limits as needed. Publication requires
|
|
186
|
+
a complete per-skill file index. See the
|
|
187
|
+
[HTTP provider](https://github.com/pratikxpanda/agentskills-sdk/blob/main/packages/providers/agentskills-http/README.md).
|
|
188
|
+
|
|
189
|
+
The extension enforces 512 files and 16 MiB per skill. Directory reads are not
|
|
190
|
+
advertised. Nested skills require explicit publication and separate host approval.
|
|
191
|
+
Listed subsets never restrict direct lookup of a published skill. Supply only
|
|
192
|
+
skills authorized for the server audience.
|
|
193
|
+
|
|
194
|
+
The package-specific `--check` option verifies local construction, manifests, and provider
|
|
195
|
+
readiness without listening. It does not certify transport, authentication, or host behavior.
|
|
196
|
+
|
|
197
|
+
## Client Support and Boundaries
|
|
198
|
+
|
|
199
|
+
Tests exercise MCP 2.2.0 `Client` in-process, over stdio, and over real loopback
|
|
200
|
+
Streamable HTTP. CI also checks mcpc 0.7.0 discovery, aliases, pagination, and exact
|
|
201
|
+
resource bytes. Use SDK 2 `Client` for extension negotiation, not its older
|
|
202
|
+
`ClientSession` compatibility API. Ordinary tools/resources connectivity does not
|
|
203
|
+
establish Skills support.
|
|
204
|
+
|
|
205
|
+
Hosts own selection, manifest verification, origin visibility,
|
|
206
|
+
per-skill consent, context injection, session tracking, image rendering, and
|
|
207
|
+
execution policy. Resource reads never execute scripts or grant `allowed-tools`.
|
|
208
|
+
|
|
209
|
+
Production HTTP deployments must supply TLS, MCP authorization, audience isolation,
|
|
210
|
+
and appropriate origin/host validation. Do not pass client bearer tokens to upstream
|
|
211
|
+
providers. Local tests are not production deployment certification.
|
|
212
|
+
|
|
213
|
+
## Benchmarks
|
|
214
|
+
|
|
215
|
+
The [benchmark guide](https://github.com/pratikxpanda/agentskills-sdk/blob/main/docs/mcp-benchmarks.md)
|
|
216
|
+
describes native discovery and progressive reads over bounded synthetic catalogs.
|
|
217
|
+
It does not measure model quality or production network performance.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
"""MCP server integration for Agent Skills.
|
|
2
|
+
|
|
3
|
+
This package bridges :mod:`agentskills_core` and the `Model Context
|
|
4
|
+
Protocol <https://modelcontextprotocol.io>`_ Skills extension, providing:
|
|
5
|
+
|
|
6
|
+
* :func:`create_mcp_server` -- asynchronously builds a native Skills server from a
|
|
7
|
+
:class:`~agentskills_core.SkillRegistry`. Useful when you have
|
|
8
|
+
registry or raw skill handles. No tools or catalog resources are served.
|
|
9
|
+
* :class:`McpSkillsClient` -- consumes native Skills through a caller-owned MCP
|
|
10
|
+
client session without registering or eagerly reading skill bodies.
|
|
11
|
+
* Optional ``skill_prompt_shortcuts`` -- exposes one user-invoked ``use-skill``
|
|
12
|
+
prompt without granting tools or execution permissions.
|
|
13
|
+
* CLI entry-point (``agentskills-mcp --config server.json``)
|
|
14
|
+
for zero-code server startup.
|
|
15
|
+
|
|
16
|
+
Quick start (programmatic)::
|
|
17
|
+
|
|
18
|
+
from agentskills_core import SkillRegistry
|
|
19
|
+
from agentskills_mcp_extension import create_mcp_server
|
|
20
|
+
|
|
21
|
+
registry = SkillRegistry()
|
|
22
|
+
await registry.register("incident-response", my_custom_provider)
|
|
23
|
+
server = await create_mcp_server(registry, name="My Agent")
|
|
24
|
+
server.run() # stdio by default
|
|
25
|
+
|
|
26
|
+
CLI::
|
|
27
|
+
|
|
28
|
+
agentskills-mcp --config server.json
|
|
29
|
+
|
|
30
|
+
Install::
|
|
31
|
+
|
|
32
|
+
pip install agentskills-mcp-extension
|
|
33
|
+
"""
|
|
34
|
+
|
|
35
|
+
from agentskills_mcp_extension.client import (
|
|
36
|
+
McpSkillIdentity,
|
|
37
|
+
McpSkillReference,
|
|
38
|
+
McpSkillsClient,
|
|
39
|
+
McpSkillsClientError,
|
|
40
|
+
McpSkillsCollection,
|
|
41
|
+
)
|
|
42
|
+
from agentskills_mcp_extension.native import create_mcp_server
|
|
43
|
+
|
|
44
|
+
__all__ = [
|
|
45
|
+
"McpSkillIdentity",
|
|
46
|
+
"McpSkillReference",
|
|
47
|
+
"McpSkillsClient",
|
|
48
|
+
"McpSkillsClientError",
|
|
49
|
+
"McpSkillsCollection",
|
|
50
|
+
"create_mcp_server",
|
|
51
|
+
]
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
"""Run an Agent Skills MCP server from a config file.
|
|
2
|
+
|
|
3
|
+
Usage::
|
|
4
|
+
|
|
5
|
+
agentskills-mcp --config server.json
|
|
6
|
+
agentskills-mcp --config server.yaml
|
|
7
|
+
agentskills-mcp --config server.json --transport streamable-http
|
|
8
|
+
|
|
9
|
+
The equivalent Python module entry point is ``python -m agentskills_mcp_extension``.
|
|
10
|
+
|
|
11
|
+
The config file is a JSON or YAML document conforming to
|
|
12
|
+
:class:`~agentskills_mcp_extension.config.ServerConfig`.
|
|
13
|
+
|
|
14
|
+
Example ``server.json``::
|
|
15
|
+
|
|
16
|
+
{
|
|
17
|
+
"name": "My Skills Server",
|
|
18
|
+
"skills": [
|
|
19
|
+
{
|
|
20
|
+
"id": "incident-response",
|
|
21
|
+
"provider": "fs",
|
|
22
|
+
"options": {"root": "./skills"}
|
|
23
|
+
},
|
|
24
|
+
{
|
|
25
|
+
"id": "cloud-runbooks",
|
|
26
|
+
"provider": "http",
|
|
27
|
+
"options": {
|
|
28
|
+
"base_url": "https://cdn.example.com/skills",
|
|
29
|
+
"headers": {"Authorization": "Bearer ${API_TOKEN}"},
|
|
30
|
+
"params": {"sv": "2020-08-04", "sig": "${SAS_TOKEN}"}
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
]
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
String values may contain ``${VAR}`` placeholders that are resolved
|
|
37
|
+
from environment variables at load time. This lets you keep secrets
|
|
38
|
+
out of the config file.
|
|
39
|
+
|
|
40
|
+
MCP client integration (stdio transport)::
|
|
41
|
+
|
|
42
|
+
{
|
|
43
|
+
"command": "agentskills-mcp",
|
|
44
|
+
"args": ["--config", "server.json"]
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
MCP client integration (streamable-http transport)::
|
|
48
|
+
|
|
49
|
+
{
|
|
50
|
+
"url": "http://127.0.0.1:8000/mcp"
|
|
51
|
+
}
|
|
52
|
+
"""
|
|
53
|
+
|
|
54
|
+
from __future__ import annotations
|
|
55
|
+
|
|
56
|
+
import argparse
|
|
57
|
+
import asyncio
|
|
58
|
+
import json
|
|
59
|
+
import sys
|
|
60
|
+
from contextlib import AsyncExitStack
|
|
61
|
+
from importlib.metadata import version
|
|
62
|
+
from pathlib import Path
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def main() -> None:
|
|
66
|
+
"""Parse CLI arguments, load config, and start the MCP server."""
|
|
67
|
+
parser = argparse.ArgumentParser(
|
|
68
|
+
prog="agentskills-mcp",
|
|
69
|
+
description="Start an Agent Skills MCP server from a config file.",
|
|
70
|
+
)
|
|
71
|
+
parser.add_argument(
|
|
72
|
+
"--config",
|
|
73
|
+
required=True,
|
|
74
|
+
type=Path,
|
|
75
|
+
help="Path to a JSON or YAML configuration file.",
|
|
76
|
+
)
|
|
77
|
+
parser.add_argument(
|
|
78
|
+
"--transport",
|
|
79
|
+
default="stdio",
|
|
80
|
+
choices=["stdio", "streamable-http"],
|
|
81
|
+
help="MCP transport type (default: stdio).",
|
|
82
|
+
)
|
|
83
|
+
parser.add_argument(
|
|
84
|
+
"--check",
|
|
85
|
+
action="store_true",
|
|
86
|
+
help="Check provider readiness and publication, then print JSON without listening.",
|
|
87
|
+
)
|
|
88
|
+
args = parser.parse_args()
|
|
89
|
+
|
|
90
|
+
# ------------------------------------------------------------------
|
|
91
|
+
# Load config file
|
|
92
|
+
# ------------------------------------------------------------------
|
|
93
|
+
config_path: Path = args.config
|
|
94
|
+
if not config_path.exists():
|
|
95
|
+
print(
|
|
96
|
+
f"Error: config file not found: {config_path}",
|
|
97
|
+
file=sys.stderr,
|
|
98
|
+
)
|
|
99
|
+
sys.exit(1)
|
|
100
|
+
|
|
101
|
+
raw = config_path.read_text(encoding="utf-8")
|
|
102
|
+
|
|
103
|
+
if config_path.suffix in (".yaml", ".yml"):
|
|
104
|
+
try:
|
|
105
|
+
import yaml # type: ignore[import-untyped]
|
|
106
|
+
except ImportError:
|
|
107
|
+
print(
|
|
108
|
+
"Error: YAML config files require pyyaml. Install with: pip install pyyaml",
|
|
109
|
+
file=sys.stderr,
|
|
110
|
+
)
|
|
111
|
+
sys.exit(1)
|
|
112
|
+
data = yaml.safe_load(raw)
|
|
113
|
+
else:
|
|
114
|
+
data = json.loads(raw)
|
|
115
|
+
|
|
116
|
+
# ------------------------------------------------------------------
|
|
117
|
+
# Resolve ${VAR} environment variable placeholders
|
|
118
|
+
# ------------------------------------------------------------------
|
|
119
|
+
from agentskills_mcp_extension.config import resolve_env_vars
|
|
120
|
+
|
|
121
|
+
data = resolve_env_vars(data)
|
|
122
|
+
|
|
123
|
+
# ------------------------------------------------------------------
|
|
124
|
+
# Build and run
|
|
125
|
+
# ------------------------------------------------------------------
|
|
126
|
+
from agentskills_core import Skill
|
|
127
|
+
from agentskills_mcp_extension import create_mcp_server
|
|
128
|
+
from agentskills_mcp_extension.config import ServerConfig, _resolve_provider
|
|
129
|
+
|
|
130
|
+
config = ServerConfig(**data)
|
|
131
|
+
|
|
132
|
+
async def _build() -> object:
|
|
133
|
+
async with AsyncExitStack() as stack:
|
|
134
|
+
handles = []
|
|
135
|
+
for skill_cfg in config.skills:
|
|
136
|
+
provider = _resolve_provider(skill_cfg.provider, skill_cfg.options)
|
|
137
|
+
if close := getattr(provider, "aclose", None):
|
|
138
|
+
stack.push_async_callback(close)
|
|
139
|
+
handles.append(Skill(skill_cfg.id, provider))
|
|
140
|
+
return await create_mcp_server(
|
|
141
|
+
handles,
|
|
142
|
+
name=config.name,
|
|
143
|
+
instructions=config.instructions,
|
|
144
|
+
skill_paths=config.skill_paths,
|
|
145
|
+
listed_skill_ids=config.listed_skill_ids,
|
|
146
|
+
skill_prompt_shortcuts=config.skill_prompt_shortcuts,
|
|
147
|
+
page_size=config.page_size,
|
|
148
|
+
max_skills=config.max_skills,
|
|
149
|
+
max_total_bytes=config.max_total_bytes,
|
|
150
|
+
publication_policy=config.build_publication_policy(),
|
|
151
|
+
)
|
|
152
|
+
|
|
153
|
+
server = asyncio.run(_build())
|
|
154
|
+
if args.check:
|
|
155
|
+
print(
|
|
156
|
+
json.dumps(
|
|
157
|
+
{
|
|
158
|
+
"status": "ready",
|
|
159
|
+
"scope": "localServerConstruction",
|
|
160
|
+
"mcpSdkVersion": version("mcp"),
|
|
161
|
+
"skillCount": len(config.skills),
|
|
162
|
+
"providerTypes": sorted({skill.provider for skill in config.skills}),
|
|
163
|
+
"requiresProtocol": "2026-07-28",
|
|
164
|
+
"requiresExtension": "io.modelcontextprotocol/skills",
|
|
165
|
+
"directoryRead": False,
|
|
166
|
+
"transportTested": False,
|
|
167
|
+
"authenticationTested": False,
|
|
168
|
+
"hostBehaviorTested": False,
|
|
169
|
+
"clientGuidance": "Requires a host implementing the native Skills extension.",
|
|
170
|
+
},
|
|
171
|
+
indent=2,
|
|
172
|
+
)
|
|
173
|
+
)
|
|
174
|
+
return
|
|
175
|
+
server.run(transport=args.transport)
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
if __name__ == "__main__":
|
|
179
|
+
main()
|