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.
@@ -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()