@skillit/target-mcp-protocol 2.0.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,90 @@
+# @skillit/target-mcp-protocol
+
+> Default invocation-target adapter for `@skillit/mcp`. Emits `mcp:` frontmatter for agent harnesses that speak MCP natively.
+
+Pairs with [`@skillit/mcp`](../mcp/) — when a host extracts or bundles an MCP server, this adapter renders a SKILL.md whose frontmatter is consumed directly by MCP-native harnesses (OpenCode, Codex, Cursor, Claude Code) so the harness can wire up the server without a separate connect step.
+
+This is the **default** adapter — when you don't pass `--invocation`, this is what runs.
+
+---
+
+## Install
+
+This adapter ships as a runtime dependency of `@skillit/mcp`. You do not need to install it explicitly. It's listed here for clarity:
+
+```bash
+npm install --save-dev @skillit/target-mcp-protocol
+```
+
+---
+
+## When to pick this target
+
+Pick `mcp-protocol` (or omit `--invocation` entirely) when **the agent harness speaks the MCP protocol natively** — i.e., it can hold an MCP session and dispatch `tools/call`, `resources/read`, and `prompts/get` requests against the server.
+
+This covers most modern agent harnesses:
+
+- Claude Code (Anthropic CLI)
+- Codex
+- Cursor
+- OpenCode
+- Any IDE plugin that wires `mcp:` config into its agent
+
+Don't pick it for shell-only harnesses (those need `cli:mcpc` or `cli:fastmcp` — see the sibling target packages).
+
+---
+
+## What it emits
+
+`SKILL.md` frontmatter is augmented with an `mcp:` block:
+
+```yaml
+---
+name: filesystem
+description: 'Secure file system access scoped to /tmp...'
+license: MIT
+mcp:
+  filesystem:
+    command: npx
+    args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp']
+---
+```
+
+For HTTP transports the block uses `url` + `headers` instead of `command` + `args`. The host (`@skillit/mcp`) decides which form via `AdapterRenderContext.httpEndpoint` vs `.launchCommand`.
+
+The body of the SKILL.md (Quick Reference, References section, tool/resource/prompt content) comes from the default core renderer — this adapter does not override `skipDefaultFunctionsRef`. It only injects `additionalFrontmatter`.
+
+---
+
+## Adapter contract
+
+| Field                        | Value                                         |
+| ---------------------------- | --------------------------------------------- |
+| `target`                     | `'mcp-protocol'`                              |
+| `fingerprint.adapter`        | `'@skillit/target-mcp-protocol'`              |
+| `fingerprint.version`        | This package's `version` from `package.json`. |
+| `fingerprint.targetCliRange` | _absent_ (this target invokes no CLI).        |
+
+Unlike the CLI-as-proxy adapters (`@skillit/target-mcpc`, `@skillit/target-fastmcp`), this adapter does **not** emit a `generated-by:` frontmatter block. The freshness audit (M5) tracks adapter-version drift only for CLI adapters — the `mcp-protocol` adapter has no upstream CLI shape to compare against, so the `fingerprint` is exposed only via the programmatic API (`McpProtocolAdapter.fingerprint`) for consumers that want to record it themselves.
+
+---
+
+## Programmatic use
+
+```ts
+import McpProtocolAdapter from '@skillit/target-mcp-protocol';
+import { renderSkill } from '@skillit/core';
+
+const rendered = await renderSkill(skill, { invocation: McpProtocolAdapter });
+```
+
+---
+
+## Further reading
+
+- [`@skillit/mcp` README](../mcp/README.md) — host package, CLI usage, programmatic API.
+- [`docs/adapter-authoring.md`](../mcp/docs/adapter-authoring.md) — building your own invocation adapter.
+
+## License
+
+MIT

package/dist/frontmatter.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Frontmatter composition for the `mcp-protocol` invocation target.
+ *
+ * @remarks
+ * MCP-native agent harnesses (OpenCode, Codex, Cursor) discover MCP server
+ * launch parameters from a `mcp:` frontmatter block in `SKILL.md`. This module
+ * builds the structured object that the core renderer's `additionalFrontmatter`
+ * mechanism serializes via the `yaml` package.
+ *
+ * Per research.md §7, the shape is one of:
+ *
+ * Stdio (command-based):
+ *
+ * ```yaml
+ * mcp:
+ *   <skillName>:
+ *     command: npx
+ *     args:
+ *       - -y
+ *       - "@modelcontextprotocol/server-filesystem"
+ *     env:
+ *       FOO: bar
+ * ```
+ *
+ * HTTP (url-based):
+ *
+ * ```yaml
+ * mcp:
+ *   <skillName>:
+ *     url: https://example.com/mcp
+ *     headers:
+ *       Authorization: Bearer test
+ * ```
+ *
+ * @module frontmatter
+ */
+/**
+ * Stdio launch shape — what the agent harness should spawn to talk to this server
+ * over stdio.
+ */
+export interface McpStdioLaunchCommand {
+    /** Executable to spawn (e.g. `npx`, `node`, `uvx`). */
+    readonly command: string;
+    /** Argument vector. Omitted from emitted YAML when empty/undefined. */
+    readonly args?: readonly string[];
+    /** Environment variables. Omitted from emitted YAML when empty/undefined. */
+    readonly env?: Readonly<Record<string, string>>;
+}
+/**
+ * HTTP endpoint shape — used when the MCP server speaks Streamable HTTP/SSE
+ * rather than stdio. Conventional shape supported by Claude Desktop / OpenCode
+ * for HTTP-transport servers.
+ */
+export interface McpHttpLaunchCommand {
+    /** HTTP(S) URL of the MCP endpoint. */
+    readonly url: string;
+    /** Optional headers (e.g. `Authorization`). Omitted from emitted YAML when empty/undefined. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/**
+ * MCP launch descriptor — discriminated union of stdio (`command`) and HTTP
+ * (`url`) shapes.
+ */
+export type McpLaunchCommand = McpStdioLaunchCommand | McpHttpLaunchCommand;
+/**
+ * Build the structured `mcp:` frontmatter object for the default invocation target.
+ *
+ * The returned object is a plain JavaScript object — NOT a YAML string. The host
+ * renderer (in `@skillit/core`) merges it into the SKILL.md frontmatter via
+ * `SkillRenderOptions.additionalFrontmatter` and serializes through the `yaml`
+ * package, which handles quoting and indentation.
+ *
+ * Field order:
+ *
+ * Stdio shape — `{ command, args?, env? }`:
+ * 1. `command` (always present)
+ * 2. `args` (omitted when undefined or empty)
+ * 3. `env` (omitted when undefined or empty)
+ *
+ * HTTP shape — `{ url, headers? }`:
+ * 1. `url` (always present)
+ * 2. `headers` (omitted when undefined or empty)
+ *
+ * @param skillName - kebab-case skill identifier; becomes the inner mapping key.
+ * @param launchCommand - command+args+env (stdio) or url+headers (http) to embed.
+ * @returns `{ mcp: { [skillName]: <inner> } }` ready for yaml serialization.
+ */
+export declare function emitMcpFrontmatter(skillName: string, launchCommand: McpLaunchCommand): Record<string, unknown>;
+//# sourceMappingURL=frontmatter.d.ts.map

package/dist/frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACjD;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,uCAAuC;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,+FAA+F;IAC/F,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAED;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,qBAAqB,GAAG,oBAAoB,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,gBAAgB,GAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoBzB"}

package/dist/frontmatter.js

@@ -0,0 +1,80 @@
+/**
+ * Frontmatter composition for the `mcp-protocol` invocation target.
+ *
+ * @remarks
+ * MCP-native agent harnesses (OpenCode, Codex, Cursor) discover MCP server
+ * launch parameters from a `mcp:` frontmatter block in `SKILL.md`. This module
+ * builds the structured object that the core renderer's `additionalFrontmatter`
+ * mechanism serializes via the `yaml` package.
+ *
+ * Per research.md §7, the shape is one of:
+ *
+ * Stdio (command-based):
+ *
+ * ```yaml
+ * mcp:
+ *   <skillName>:
+ *     command: npx
+ *     args:
+ *       - -y
+ *       - "@modelcontextprotocol/server-filesystem"
+ *     env:
+ *       FOO: bar
+ * ```
+ *
+ * HTTP (url-based):
+ *
+ * ```yaml
+ * mcp:
+ *   <skillName>:
+ *     url: https://example.com/mcp
+ *     headers:
+ *       Authorization: Bearer test
+ * ```
+ *
+ * @module frontmatter
+ */
+/**
+ * Build the structured `mcp:` frontmatter object for the default invocation target.
+ *
+ * The returned object is a plain JavaScript object — NOT a YAML string. The host
+ * renderer (in `@skillit/core`) merges it into the SKILL.md frontmatter via
+ * `SkillRenderOptions.additionalFrontmatter` and serializes through the `yaml`
+ * package, which handles quoting and indentation.
+ *
+ * Field order:
+ *
+ * Stdio shape — `{ command, args?, env? }`:
+ * 1. `command` (always present)
+ * 2. `args` (omitted when undefined or empty)
+ * 3. `env` (omitted when undefined or empty)
+ *
+ * HTTP shape — `{ url, headers? }`:
+ * 1. `url` (always present)
+ * 2. `headers` (omitted when undefined or empty)
+ *
+ * @param skillName - kebab-case skill identifier; becomes the inner mapping key.
+ * @param launchCommand - command+args+env (stdio) or url+headers (http) to embed.
+ * @returns `{ mcp: { [skillName]: <inner> } }` ready for yaml serialization.
+ */
+export function emitMcpFrontmatter(skillName, launchCommand) {
+    const inner = {};
+    if ('url' in launchCommand) {
+        inner['url'] = launchCommand.url;
+        if (launchCommand.headers && Object.keys(launchCommand.headers).length > 0) {
+            inner['headers'] = { ...launchCommand.headers };
+        }
+    }
+    else {
+        inner['command'] = launchCommand.command;
+        if (launchCommand.args && launchCommand.args.length > 0) {
+            // Copy to a mutable plain array so YAML lib treats it as a sequence.
+            inner['args'] = [...launchCommand.args];
+        }
+        if (launchCommand.env && Object.keys(launchCommand.env).length > 0) {
+            inner['env'] = { ...launchCommand.env };
+        }
+    }
+    return { mcp: { [skillName]: inner } };
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAiCH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,kBAAkB,CAChC,SAAiB,EACjB,aAA+B;IAE/B,MAAM,KAAK,GAA4B,EAAE,CAAC;IAE1C,IAAI,KAAK,IAAI,aAAa,EAAE,CAAC;QAC3B,KAAK,CAAC,KAAK,CAAC,GAAG,aAAa,CAAC,GAAG,CAAC;QACjC,IAAI,aAAa,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3E,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,aAAa,CAAC,OAAO,EAAE,CAAC;QAClD,CAAC;IACH,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,SAAS,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC;QACzC,IAAI,aAAa,CAAC,IAAI,IAAI,aAAa,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxD,qEAAqE;YACrE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QAC1C,CAAC;QACD,IAAI,aAAa,CAAC,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACnE,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,aAAa,CAAC,GAAG,EAAE,CAAC;QAC1C,CAAC;IACH,CAAC;IAED,OAAO,EAAE,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;AACzC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `@skillit/target-mcp-protocol` — default invocation-target adapter.
+ *
+ * Resolved by `@skillit/mcp`'s adapter loader when the `mcp-protocol` target
+ * is requested. Emits SKILL.md with `mcp:` frontmatter that MCP-native agent
+ * harnesses (OpenCode, Codex, Cursor) parse to launch the server over stdio.
+ *
+ * @packageDocumentation
+ */
+export { McpProtocolAdapter } from './render.js';
+export { emitMcpFrontmatter } from './frontmatter.js';
+export type { McpLaunchCommand, McpStdioLaunchCommand, McpHttpLaunchCommand } from './frontmatter.js';
+export { PACKAGE_VERSION } from './version.js';
+import { McpProtocolAdapter } from './render.js';
+declare const adapter: McpProtocolAdapter;
+/**
+ * Default export — singleton adapter instance resolved by the adapter loader.
+ *
+ * @example
+ * ```ts
+ * import adapter from '@skillit/target-mcp-protocol';
+ * await adapter.render(skill, ctx);
+ * ```
+ */
+export default adapter;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EACV,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,QAAA,MAAM,OAAO,oBAA2B,CAAC;AAEzC;;;;;;;;GAQG;AACH,eAAe,OAAO,CAAC"}

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * `@skillit/target-mcp-protocol` — default invocation-target adapter.
+ *
+ * Resolved by `@skillit/mcp`'s adapter loader when the `mcp-protocol` target
+ * is requested. Emits SKILL.md with `mcp:` frontmatter that MCP-native agent
+ * harnesses (OpenCode, Codex, Cursor) parse to launch the server over stdio.
+ *
+ * @packageDocumentation
+ */
+export { McpProtocolAdapter } from './render.js';
+export { emitMcpFrontmatter } from './frontmatter.js';
+export { PACKAGE_VERSION } from './version.js';
+import { McpProtocolAdapter } from './render.js';
+const adapter = new McpProtocolAdapter();
+/**
+ * Default export — singleton adapter instance resolved by the adapter loader.
+ *
+ * @example
+ * ```ts
+ * import adapter from '@skillit/target-mcp-protocol';
+ * await adapter.render(skill, ctx);
+ * ```
+ */
+export default adapter;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAMtD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,OAAO,GAAG,IAAI,kBAAkB,EAAE,CAAC;AAEzC;;;;;;;;GAQG;AACH,eAAe,OAAO,CAAC"}

package/dist/render.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `McpProtocolAdapter` — default invocation adapter for MCP-native harnesses.
+ *
+ * Delegates body rendering to `@skillit/core`'s default path and injects the
+ * `mcp:` frontmatter that tells OpenCode/Codex/Cursor how to launch the server.
+ * Inherits resources/prompts reference emission from core's shared helpers.
+ *
+ * @module render
+ */
+import type { AdapterFingerprint, AdapterRenderContext, ExtractedSkill, RenderedSkill } from '@skillit/core';
+import type { InvocationAdapter } from '@skillit/mcp';
+/**
+ * Default invocation adapter: emits SKILL.md with `mcp:` frontmatter that
+ * MCP-native agent harnesses parse to launch the server over stdio or
+ * connect to it over HTTP.
+ *
+ * Launch-shape resolution narrows on `ctx.mode` (per data-model.md §1):
+ *
+ * 1. **`mode: 'bundle'`** — the host bundle command flagged this skill as
+ *    self-referential. Emits `command: npx` + `args: [-y, <packageName>]`
+ *    (or the multi-bin `--package=<pkg> <bin>` form per FR-034).
+ * 2. **`mode: 'http'`** — emits a `{ url, headers? }` shape (no shell launch).
+ * 3. **`mode: 'stdio'`** — `ctx.launchCommand` is used verbatim.
+ *
+ * The renderer's invocation-adapter dispatch in `@skillit/core` guarantees
+ * `mode` is always one of these three arms, so the previous runtime
+ * `MISSING_LAUNCH_COMMAND` throw is no longer needed at the adapter level.
+ * An exhaustive `default` branch is kept for compile-time exhaustiveness.
+ *
+ * @remarks
+ * The adapter does NOT render its own body content — it calls `renderSkill`
+ * with `invocation: undefined` to dispatch through core's default synchronous
+ * path, then injects the structured frontmatter object via
+ * `additionalFrontmatter`. This guarantees parity with non-MCP skills and means
+ * future renderer features (Quick Reference enhancements, new sections) work
+ * out of the box for MCP skills too.
+ */
+export declare class McpProtocolAdapter implements InvocationAdapter {
+    readonly target: "mcp-protocol";
+    readonly fingerprint: AdapterFingerprint;
+    constructor();
+    /**
+     * Render an `ExtractedSkill` into a `RenderedSkill` carrying `mcp:` frontmatter.
+     *
+     * Narrows on `ctx.mode` to pick the launch shape — see the class-level
+     * docstring for the per-arm dialect.
+     */
+    render(skill: ExtractedSkill, ctx: AdapterRenderContext): Promise<RenderedSkill>;
+}
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,EACd,aAAa,EACd,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAItD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,kBAAmB,YAAW,iBAAiB;IAC1D,QAAQ,CAAC,MAAM,EAAG,cAAc,CAAU;IAC1C,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC;;IASzC;;;;;OAKG;IACG,MAAM,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC;CA4CvF"}

package/dist/render.js

@@ -0,0 +1,96 @@
+/**
+ * `McpProtocolAdapter` — default invocation adapter for MCP-native harnesses.
+ *
+ * Delegates body rendering to `@skillit/core`'s default path and injects the
+ * `mcp:` frontmatter that tells OpenCode/Codex/Cursor how to launch the server.
+ * Inherits resources/prompts reference emission from core's shared helpers.
+ *
+ * @module render
+ */
+import { renderSkill } from '@skillit/core';
+import { emitMcpFrontmatter } from './frontmatter.js';
+import { PACKAGE_VERSION } from './version.js';
+/**
+ * Default invocation adapter: emits SKILL.md with `mcp:` frontmatter that
+ * MCP-native agent harnesses parse to launch the server over stdio or
+ * connect to it over HTTP.
+ *
+ * Launch-shape resolution narrows on `ctx.mode` (per data-model.md §1):
+ *
+ * 1. **`mode: 'bundle'`** — the host bundle command flagged this skill as
+ *    self-referential. Emits `command: npx` + `args: [-y, <packageName>]`
+ *    (or the multi-bin `--package=<pkg> <bin>` form per FR-034).
+ * 2. **`mode: 'http'`** — emits a `{ url, headers? }` shape (no shell launch).
+ * 3. **`mode: 'stdio'`** — `ctx.launchCommand` is used verbatim.
+ *
+ * The renderer's invocation-adapter dispatch in `@skillit/core` guarantees
+ * `mode` is always one of these three arms, so the previous runtime
+ * `MISSING_LAUNCH_COMMAND` throw is no longer needed at the adapter level.
+ * An exhaustive `default` branch is kept for compile-time exhaustiveness.
+ *
+ * @remarks
+ * The adapter does NOT render its own body content — it calls `renderSkill`
+ * with `invocation: undefined` to dispatch through core's default synchronous
+ * path, then injects the structured frontmatter object via
+ * `additionalFrontmatter`. This guarantees parity with non-MCP skills and means
+ * future renderer features (Quick Reference enhancements, new sections) work
+ * out of the box for MCP skills too.
+ */
+export class McpProtocolAdapter {
+    target = 'mcp-protocol';
+    fingerprint;
+    constructor() {
+        this.fingerprint = {
+            adapter: '@skillit/target-mcp-protocol',
+            version: PACKAGE_VERSION
+        };
+    }
+    /**
+     * Render an `ExtractedSkill` into a `RenderedSkill` carrying `mcp:` frontmatter.
+     *
+     * Narrows on `ctx.mode` to pick the launch shape — see the class-level
+     * docstring for the per-arm dialect.
+     */
+    async render(skill, ctx) {
+        let launchCommand;
+        switch (ctx.mode) {
+            case 'bundle':
+                // Bundle mode: emit npx-by-name self-reference. When the host also
+                // passes binName (multi-bin packages, FR-034), use the explicit
+                // `--package=` form so npx invokes the right bin rather than the
+                // package's "directories.bin" or single-bin default.
+                launchCommand = ctx.binName
+                    ? { command: 'npx', args: ['-y', `--package=${ctx.packageName}`, ctx.binName] }
+                    : { command: 'npx', args: ['-y', ctx.packageName] };
+                break;
+            case 'http':
+                // HTTP-extract mode: emit {url, headers} shape. No shell launch.
+                launchCommand = ctx.httpEndpoint.headers
+                    ? { url: ctx.httpEndpoint.url, headers: ctx.httpEndpoint.headers }
+                    : { url: ctx.httpEndpoint.url };
+                break;
+            case 'stdio':
+                launchCommand = ctx.launchCommand;
+                break;
+            default: {
+                // Exhaustiveness: if a new arm is added to AdapterRenderContext
+                // without updating this switch, TypeScript flags `_exhaustive`'s
+                // type as non-`never` here.
+                const _exhaustive = ctx;
+                throw new Error(`McpProtocolAdapter.render: unknown ctx.mode (${String(_exhaustive)})`);
+            }
+        }
+        const additionalFrontmatter = emitMcpFrontmatter(ctx.skillName, launchCommand);
+        // Delegate body rendering + references emission to core's default path.
+        // `invocation: undefined` dispatches the synchronous overload; `namePrefix`
+        // ensures core's toSkillName() yields the same skillName the host computed.
+        const baseRendered = renderSkill(skill, {
+            maxTokens: ctx.maxTokens,
+            additionalFrontmatter,
+            invocation: undefined,
+            namePrefix: ctx.skillName
+        });
+        return baseRendered;
+    }
+}
+//# sourceMappingURL=render.js.map

package/dist/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,kBAAkB,EAAyB,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,OAAO,kBAAkB;IACpB,MAAM,GAAG,cAAuB,CAAC;IACjC,WAAW,CAAqB;IAEzC;QACE,IAAI,CAAC,WAAW,GAAG;YACjB,OAAO,EAAE,8BAA8B;YACvC,OAAO,EAAE,eAAe;SACzB,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,MAAM,CAAC,KAAqB,EAAE,GAAyB;QAC3D,IAAI,aAA+B,CAAC;QACpC,QAAQ,GAAG,CAAC,IAAI,EAAE,CAAC;YACjB,KAAK,QAAQ;gBACX,mEAAmE;gBACnE,gEAAgE;gBAChE,iEAAiE;gBACjE,qDAAqD;gBACrD,aAAa,GAAG,GAAG,CAAC,OAAO;oBACzB,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,aAAa,GAAG,CAAC,WAAW,EAAE,EAAE,GAAG,CAAC,OAAO,CAAC,EAAE;oBAC/E,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;gBACtD,MAAM;YACR,KAAK,MAAM;gBACT,iEAAiE;gBACjE,aAAa,GAAG,GAAG,CAAC,YAAY,CAAC,OAAO;oBACtC,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,YAAY,CAAC,OAAO,EAAE;oBAClE,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC;gBAClC,MAAM;YACR,KAAK,OAAO;gBACV,aAAa,GAAG,GAAG,CAAC,aAAa,CAAC;gBAClC,MAAM;YACR,OAAO,CAAC,CAAC,CAAC;gBACR,gEAAgE;gBAChE,iEAAiE;gBACjE,4BAA4B;gBAC5B,MAAM,WAAW,GAAU,GAAG,CAAC;gBAC/B,MAAM,IAAI,KAAK,CAAC,gDAAgD,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;YAC1F,CAAC;QACH,CAAC;QAED,MAAM,qBAAqB,GAAG,kBAAkB,CAAC,GAAG,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;QAE/E,wEAAwE;QACxE,4EAA4E;QAC5E,4EAA4E;QAC5E,MAAM,YAAY,GAAG,WAAW,CAAC,KAAK,EAAE;YACtC,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,qBAAqB;YACrB,UAAU,EAAE,SAAS;YACrB,UAAU,EAAE,GAAG,CAAC,SAAS;SAC1B,CAAC,CAAC;QAEH,OAAO,YAAY,CAAC;IACtB,CAAC;CACF"}

package/dist/version.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Adapter package version — embedded into the `AdapterFingerprint`.
+ *
+ * @remarks
+ * Kept in a separate module so `render.ts` doesn't need to import the
+ * default export of `index.ts` (which would create a small circular import).
+ * Bump this string whenever the adapter's output shape changes.
+ */
+export declare const PACKAGE_VERSION = "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,10 @@
+/**
+ * Adapter package version — embedded into the `AdapterFingerprint`.
+ *
+ * @remarks
+ * Kept in a separate module so `render.ts` doesn't need to import the
+ * default export of `index.ts` (which would create a small circular import).
+ * Bump this string whenever the adapter's output shape changes.
+ */
+export const PACKAGE_VERSION = '0.1.0';
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,OAAO,CAAC"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@skillit/target-mcp-protocol",
+  "version": "2.0.0",
+  "description": "Default invocation-target adapter for @skillit/mcp — emits mcp: frontmatter for MCP-native agent harnesses (OpenCode, Codex, Cursor)",
+  "keywords": [
+    "agent-skills",
+    "ai",
+    "mcp",
+    "model-context-protocol",
+    "skillit"
+  ],
+  "license": "MIT",
+  "author": "Pradeep Mouli",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pradeepmouli/skillit.git",
+    "directory": "packages/target-mcp-protocol"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/pradeepmouli"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "yaml": "^2.9.0",
+    "@skillit/core": "1.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "vitest": "^4.1.7",
+    "@skillit/mcp": "0.3.0"
+  },
+  "peerDependencies": {
+    "@skillit/mcp": "0.3.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}