@mcp-com-ai/plugin-sdk 1.0.1-beta.260912 → 1.0.2-beta.260914

package/README.md

@@ -1,48 +1,48 @@
-# @hapi/plugin-sdk
-
-The contract every HAPI CLI plugin implements.
-
-This package is intentionally tiny and stable. It exports:
-
-- `HapiCliPlugin` — the plugin shape the core CLI loads
-- `CliCommand` / `CliContext` / `CliInvocation` — the runtime types
-- `defineCommand` / `definePlugin` — identity helpers for IntelliSense + validation
-- `parseArgs` — a small, dependency-free flag parser
-- `renderCommandHelp` — consistent help output
-- `HAPI_CLI_API_VERSION` — the current plugin-contract version
-
-## Writing a plugin
-
-```ts
-import { definePlugin, defineCommand, HAPI_CLI_API_VERSION } from '@mcp-com-ai/plugin-sdk';
-
-const connect = defineCommand({
-  name: 'connect',
-  description: 'Connect to an MCP server',
-  arguments: [{ name: 'server-url', description: 'Target MCP server URL', required: true }],
-  async run({ positionals }, ctx) {
-    const [url] = positionals;
-    ctx.stdout.write(`Connecting to ${url}\n`);
-  },
-});
-
-export default definePlugin({
-  name: '@mcp-com-ai/client',
-  version: '0.1.0',
-  compatibility: { cliApiVersion: HAPI_CLI_API_VERSION },
-  commands: [
-    {
-      name: 'client',
-      description: 'MCP client operations',
-      subcommands: [connect],
-    },
-  ],
-});
+<!--
+MCP.com.ai — Server Registry
+Deploying & Registering MCP Servers
+-->
+
+<p align="center">
+  <img src="https://img.shields.io/badge/MCP-Model%20Context%20Protocol-1193b0?style=for-the-badge" />
+  <img src="https://img.shields.io/badge/Server%20Registry-Deploy%20%26%20Discover-da7756?style=for-the-badge" />
+</p>
+
+<h1 align="center">MCP Server Registry Integration</h1>
+
+<p align="center">
+  <b>Build Once. Deploy Everywhere. Discover Globally.</b><br/>
+  Self-host, deploy, and register MCP servers with confidence using HAPI CLI, Docker, or Cloudflare Workers.
+</p>
+
+<p align="center">
+  <a href="https://mcp.com.ai"><b>Website</b></a>
+  ·
+  <a href="https://docs.mcp.com.ai"><b>Docs</b></a>
+  ·
+  <a href="https://registry.modelcontextprotocol.io/?q=ai.com.mcp"><b>MCP Registry</b></a>
+  ·
+  <a href="https://run.mcp.com.ai"><b>Run MCP</b></a>
+  ·
+  <a href="https://hapi.mcp.com.ai"><b>HAPI CLI</b></a>
+</p>
+
+---
+
+# HAPI plugin SDK  ![NPM Version](https://img.shields.io/npm/v/%40mcp-com-ai%2fhapi)
+
+`@mcp-com-ai/plugin-sdk` is the contract that lets HAPI plugins work with the
+`hapi` command. It is for plugin authors, not for people simply serving an API
+or workflow as MCP.
+
+To run an OpenAPI API or Arazzo workflow, install the CLI and the appropriate
+document plugin instead:
+
+```sh
+bun add -g @mcp-com-ai/hapi @mcp-com-ai/plugin-openapi
+hapi serve --specs ./openapi.yaml --mcp
 ```
 
-## Stability policy
-
-The SDK follows a simple rule: **additive changes keep the same
-`HAPI_CLI_API_VERSION`. Any breaking change bumps the major.** The CLI
-refuses to load plugins whose `compatibility.cliApiVersion` does not
-match the CLI's advertised version.
+The CLI and first-party plugins install this package automatically. Keep it on
+the same version as the HAPI packages that depend on it. Plugin-development
+material is intentionally kept out of this end-user package guide.

package/dist/index.js

@@ -1,16 +1,16 @@
 // @bun
-var M="1.0.1-beta.260912";var T=Number(M.split(".")[0]);function P(e){return e}function F(e){if(!e.name)throw Error("HAPI plugin missing required `name`");if(!e.version)throw Error(`HAPI plugin '${e.name}' missing required \`version\``);if(!e.compatibility?.cliApiVersion)throw Error(`HAPI plugin '${e.name}' must declare compatibility.cliApiVersion (current: '${T}')`);if(!Array.isArray(e.commands))throw Error(`HAPI plugin '${e.name}' must declare a commands[] array`);let r=new Set;for(let s of e.serveProviders??[]){if(!s.id||!s.kind||!s.rootField||!s.description)throw Error(`HAPI plugin '${e.name}' has an invalid serve provider declaration`);if(typeof s.serve!=="function")throw Error(`HAPI plugin '${e.name}' serve provider '${s.id}' must declare serve()`);if(r.has(s.id))throw Error(`HAPI plugin '${e.name}' declares duplicate serve provider '${s.id}'`);r.add(s.id)}return e}function H(e,r=[],s={}){let c=s.allowUnknown??!0,n=[],t=[],f={};for(let i of r)if(i.env&&process.env[i.env]!==void 0)f[i.name]=E(process.env[i.env],i);else if(i.default!==void 0)f[i.name]=i.default;let u=new Map,j=new Map;for(let i of r)if(u.set(i.name,i),i.alias)j.set(i.alias,i);let h=0;while(h<e.length){let i=e[h];if(i==="--"){t.push(...e.slice(h+1));break}if(i.startsWith("--")){let d=i.slice(2),R=d.indexOf("="),x=R>=0?d.slice(0,R):d,S=R>=0?d.slice(R+1):void 0,U=x.startsWith("no-"),V=U?x.slice(3):x,L=u.get(V)??u.get(Z(V));if(!L){if(!c)throw Error(`Unknown option: --${x}`);if(S!==void 0)f[D(x)]=S,h++;else if(U)f[D(V)]=!1,h++;else{let A=e[h+1];if(A!==void 0&&!String(A).startsWith("-"))f[D(x)]=A,h+=2;else f[D(x)]=!0,h++}continue}if(L.type==="boolean"){f[L.name]=U?!1:S?O(S):!0,h++;continue}let m=S;if(m===void 0)m=e[h+1],h+=m!==void 0&&!String(m).startsWith("-")?2:1;else h++;if(L.type==="array"){let A=f[L.name]??[];f[L.name]=[...A,...String(m??"").split(",").map((_)=>_.trim()).filter(Boolean)]}else f[L.name]=E(m,L);continue}if(i.startsWith("-")&&i.length>1){let d=i.slice(1),R=d.indexOf("="),x=R>=0?d.slice(0,R):d,S=R>=0?d.slice(R+1):void 0,U=j.get(x);if(!U){if(!c)throw Error(`Unknown option: -${x}`);n.push(i),h++;continue}if(U.type==="boolean"){f[U.name]=S?O(S):!0,h++;continue}let V=S;if(V===void 0)V=e[h+1],h+=V!==void 0&&!String(V).startsWith("-")?2:1;else h++;f[U.name]=E(V,U);continue}n.push(i),h++}return{positionals:n,options:f,rest:t}}function E(e,r){if(e===void 0)return e;switch(r.type){case"number":{let s=Number(e);return Number.isFinite(s)?s:e}case"boolean":return O(e);case"array":return String(e).split(",").map((s)=>s.trim()).filter(Boolean);default:return String(e)}}function O(e){if(typeof e==="boolean")return e;let r=String(e).toLowerCase();return r==="1"||r==="true"||r==="yes"||r==="on"}function Z(e){return e.replace(/-([a-z0-9])/g,(r,s)=>s.toUpperCase())}function D(e){return Z(e)}function W(e,r,s=[]){let c=s.length?`${s.join(" ")} `:"",n=(t)=>r.stdout.write(t);if(n(`
-${c}${e.name} \u2014 ${e.description}
-`),e.arguments?.length){n(`
+var k="1.0.2-beta.260914";var P=Number(k.split(".")[0]);function V(e){return e}function N(e){if(!e.name)throw Error("HAPI plugin missing required `name`");if(!e.version)throw Error(`HAPI plugin '${e.name}' missing required \`version\``);if(!e.compatibility?.cliApiVersion)throw Error(`HAPI plugin '${e.name}' must declare compatibility.cliApiVersion (current: '${P}')`);if(!Array.isArray(e.commands))throw Error(`HAPI plugin '${e.name}' must declare a commands[] array`);let n=new Set;for(let t of e.serveProviders??[]){if(!t.id||!t.kind||!t.rootField||!t.description)throw Error(`HAPI plugin '${e.name}' has an invalid serve provider declaration`);if(typeof t.serve!=="function")throw Error(`HAPI plugin '${e.name}' serve provider '${t.id}' must declare serve()`);if(n.has(t.id))throw Error(`HAPI plugin '${e.name}' declares duplicate serve provider '${t.id}'`);n.add(t.id)}return e}function L(e,n=[],t={}){let a=t.allowUnknown??!0,i=[],r=[],o={},l=[];for(let s of n)if(s.env&&process.env[s.env]!==void 0)o[s.name]=w(process.env[s.env],s);else if(s.default!==void 0)o[s.name]=s.default;let u=new Map,I=new Map;for(let s of n)if(u.set(s.name,s),s.alias)I.set(s.alias,s);let c=0;while(c<e.length){let s=e[c];if(s==="--"){r.push(...e.slice(c+1));break}if(s.startsWith("--")){let p=s.slice(2),m=p.indexOf("="),d=m>=0?p.slice(0,m):p,f=m>=0?p.slice(m+1):void 0,g=d.startsWith("no-"),h=g?d.slice(3):d,C=u.get(h)??u.get(R(h));if(!C){if(!a)throw Error(`Unknown option: --${d}`);if(l.push(d),f!==void 0)o[v(d)]=f,c++;else if(g)o[v(h)]=!1,c++;else{let x=e[c+1];if(x!==void 0&&!String(x).startsWith("-"))o[v(d)]=x,c+=2;else o[v(d)]=!0,c++}continue}if(C.type==="boolean"){o[C.name]=g?!1:f?A(f):!0,c++;continue}let b=f;if(b===void 0)b=e[c+1],c+=b!==void 0&&!String(b).startsWith("-")?2:1;else c++;if(C.type==="array"){let x=o[C.name]??[];o[C.name]=[...x,...String(b??"").split(",").map((H)=>H.trim()).filter(Boolean)]}else o[C.name]=w(b,C);continue}if(s.startsWith("-")&&s.length>1){let p=s.slice(1),m=p.indexOf("="),d=m>=0?p.slice(0,m):p,f=m>=0?p.slice(m+1):void 0,g=I.get(d);if(!g){if(!a)throw Error(`Unknown option: -${d}`);i.push(s),c++;continue}if(g.type==="boolean"){o[g.name]=f?A(f):!0,c++;continue}let h=f;if(h===void 0)h=e[c+1],c+=h!==void 0&&!String(h).startsWith("-")?2:1;else c++;o[g.name]=w(h,g);continue}i.push(s),c++}return{positionals:i,options:o,rest:r,unknownOptions:l}}function w(e,n){if(e===void 0)return e;switch(n.type){case"number":{let t=Number(e);return Number.isFinite(t)?t:e}case"boolean":return A(e);case"array":return String(e).split(",").map((t)=>t.trim()).filter(Boolean);default:return String(e)}}function A(e){if(typeof e==="boolean")return e;let n=String(e).toLowerCase();return n==="1"||n==="true"||n==="yes"||n==="on"}function R(e){return e.replace(/-([a-z0-9])/g,(n,t)=>t.toUpperCase())}function v(e){return R(e)}function _(e,n,t=[]){let a=t.length?`${t.join(" ")} `:"",i=(r)=>n.stdout.write(r);if(i(`
+${a}${e.name} \u2014 ${e.description}
+`),e.arguments?.length){i(`
 Arguments:
-`);for(let t of e.arguments){let f=t.variadic?`${t.name}...`:t.name,u=t.required?`<${f}>`:`[${f}]`;n(`  ${u.padEnd(24)} ${t.description}
-`)}}if(e.options?.length){n(`
+`);for(let r of e.arguments){let o=r.variadic?`${r.name}...`:r.name,l=r.required?`<${o}>`:`[${o}]`;i(`  ${l.padEnd(24)} ${r.description}
+`)}}if(e.options?.length){i(`
 Options:
-`);for(let t of e.options){let f=t.alias?`-${t.alias}, --${t.name}`:`    --${t.name}`,u=t.default!==void 0?`${t.description} (default: ${JSON.stringify(t.default)})`:t.description;n(`  ${f.padEnd(28)} ${u}
-`)}}if(e.subcommands?.length){n(`
+`);for(let r of e.options){let o=r.alias?`-${r.alias}, --${r.name}`:`    --${r.name}`,l=r.default!==void 0?`${r.description} (default: ${JSON.stringify(r.default)})`:r.description;i(`  ${o.padEnd(28)} ${l}
+`)}}if(e.subcommands?.length){i(`
 Subcommands:
-`);for(let t of e.subcommands){if(t.hidden)continue;n(`  ${t.name.padEnd(14)} ${t.description}
-`)}}if(e.longHelp)n(`
+`);for(let r of e.subcommands){if(r.hidden)continue;i(`  ${r.name.padEnd(14)} ${r.description}
+`)}}if(e.longHelp)i(`
 ${e.longHelp}
-`);n(`
-`)}var Y=Object.freeze({maxBytes:5242880,timeoutMs:1e4,maxRedirects:5});function B(e){if(e.protocol!=="http:"&&e.protocol!=="https:")throw Error(`Remote documents cannot resolve ${e.protocol} sources`)}function b(e){try{let r=e instanceof URL?new URL(e.href):new URL(e);if(r.username="",r.password="",r.search)r.search="?redacted";return r.href}catch{return String(e)}}var G=/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z.-]+)?$/,$=/^(<=|>=|<|>|=)?(\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z.-]+)?)$/;function J(e,r){let s=C(e);if(!s||!y(r))return!1;if(r.startsWith("^")){let n=C(r.slice(1));return n!==void 0&&z(s,n)>=0&&z(s,K(n))<0}let c=r.trim().split(/\s+/).filter(Boolean);return c.length>0&&c.every((n)=>{let t=n.match($);if(!t)return!1;let f=t[2];if(!f)return!1;let u=C(f);if(!u)return!1;let j=z(s,u);switch(t[1]??"="){case"=":return j===0;case">":return j>0;case">=":return j>=0;case"<":return j<0;case"<=":return j<=0;default:return!1}})}function y(e){if(e.startsWith("^"))return C(e.slice(1))!==void 0;let r=e.trim().split(/\s+/).filter(Boolean);return r.length>0&&r.every((s)=>{let n=s.match($)?.[2];return n!==void 0&&C(n)!==void 0})}function C(e){let r=e.match(G);if(!r)return;return{major:Number(r[1]),minor:Number(r[2]),patch:Number(r[3]),prerelease:r[4]?.split(".")??[]}}function K(e){if(e.major>0)return{major:e.major+1,minor:0,patch:0,prerelease:["0"]};if(e.minor>0)return{major:0,minor:e.minor+1,patch:0,prerelease:["0"]};return{major:0,minor:0,patch:e.patch+1,prerelease:["0"]}}function z(e,r){for(let c of["major","minor","patch"])if(e[c]!==r[c])return e[c]<r[c]?-1:1;if(e.prerelease.length===0||r.prerelease.length===0){if(e.prerelease.length===r.prerelease.length)return 0;return e.prerelease.length===0?1:-1}let s=Math.max(e.prerelease.length,r.prerelease.length);for(let c=0;c<s;c++){let n=e.prerelease[c],t=r.prerelease[c];if(n===void 0)return-1;if(t===void 0)return 1;if(n===t)continue;let f=/^\d+$/.test(n),u=/^\d+$/.test(t);if(f&&u)return Number(n)<Number(t)?-1:1;if(f!==u)return f?-1:1;return n<t?-1:1}return 0}export{J as satisfiesVersionRange,W as renderCommandHelp,b as redactDocumentUrl,H as parseArgs,y as isSupportedVersionRange,F as definePlugin,P as defineCommand,B as assertRemoteDocumentUrl,T as HAPI_CLI_API_VERSION,Y as DEFAULT_DOCUMENT_SOURCE_POLICY};
+`);i(`
+`)}var j=Object.freeze({maxBytes:5242880,timeoutMs:1e4,maxRedirects:5});function D(e){if(e.protocol!=="http:"&&e.protocol!=="https:")throw Error(`Remote documents cannot resolve ${e.protocol} sources`)}function W(e){try{let n=e instanceof URL?new URL(e.href):new URL(e);if(n.username="",n.password="",n.search)n.search="?redacted";return n.href}catch{return String(e)}}var q=/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z.-]+)?$/,E=/^(<=|>=|<|>|=)?(\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z.-]+)?)$/;function M(e,n){let t=y(e);if(!t||!O(n))return!1;if(n.startsWith("^")){let i=y(n.slice(1));return i!==void 0&&S(t,i)>=0&&S(t,T(i))<0}let a=n.trim().split(/\s+/).filter(Boolean);return a.length>0&&a.every((i)=>{let r=i.match(E);if(!r)return!1;let o=r[2];if(!o)return!1;let l=y(o);if(!l)return!1;let u=S(t,l);switch(r[1]??"="){case"=":return u===0;case">":return u>0;case">=":return u>=0;case"<":return u<0;case"<=":return u<=0;default:return!1}})}function O(e){if(e.startsWith("^"))return y(e.slice(1))!==void 0;let n=e.trim().split(/\s+/).filter(Boolean);return n.length>0&&n.every((t)=>{let i=t.match(E)?.[2];return i!==void 0&&y(i)!==void 0})}function y(e){let n=e.match(q);if(!n)return;return{major:Number(n[1]),minor:Number(n[2]),patch:Number(n[3]),prerelease:n[4]?.split(".")??[]}}function T(e){if(e.major>0)return{major:e.major+1,minor:0,patch:0,prerelease:["0"]};if(e.minor>0)return{major:0,minor:e.minor+1,patch:0,prerelease:["0"]};return{major:0,minor:0,patch:e.patch+1,prerelease:["0"]}}function S(e,n){for(let a of["major","minor","patch"])if(e[a]!==n[a])return e[a]<n[a]?-1:1;if(e.prerelease.length===0||n.prerelease.length===0){if(e.prerelease.length===n.prerelease.length)return 0;return e.prerelease.length===0?1:-1}let t=Math.max(e.prerelease.length,n.prerelease.length);for(let a=0;a<t;a++){let i=e.prerelease[a],r=n.prerelease[a];if(i===void 0)return-1;if(r===void 0)return 1;if(i===r)continue;let o=/^\d+$/.test(i),l=/^\d+$/.test(r);if(o&&l)return Number(i)<Number(r)?-1:1;if(o!==l)return o?-1:1;return i<r?-1:1}return 0}export{j as DEFAULT_DOCUMENT_SOURCE_POLICY,P as HAPI_CLI_API_VERSION,D as assertRemoteDocumentUrl,V as defineCommand,N as definePlugin,O as isSupportedVersionRange,L as parseArgs,W as redactDocumentUrl,_ as renderCommandHelp,M as satisfiesVersionRange};

package/dist/types.d.ts

@@ -90,6 +90,15 @@ export interface CliInvocation {
     positionals: string[];
     options: Record<string, unknown>;
     rest: string[];
+    /**
+     * Flags on argv that didn't match any declared CliOption (by name or its
+     * kebab/camel variant), e.g. from a typo like --project-name instead of
+     * --project. Still parsed into `options` under a best-guess key (so
+     * intentional passthrough, like wrangler --var forwarding, keeps working),
+     * but callers should warn on these — a silently-ignored typo'd flag is
+     * much harder to notice than a merely-unused one.
+     */
+    unknownOptions?: string[];
 }
 /** A parsed source passed from the CLI to a document-specific serve provider. */
 export interface DocumentSourceEnvelope {
@@ -120,6 +129,8 @@ export interface ServeProvider {
     rootField: string;
     description: string;
     options?: readonly CliOption[];
+    /** Optional long-form help appended below the generic `hapi serve --help` block. */
+    longHelp?: string;
     /** Permit legacy identifiers that do not resolve to a document, e.g. an OpenAPI project name. */
     legacyFallback?: boolean;
     serve: (request: ServeProviderRequest, context: CliContext) => Promise<number | void> | number | void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-com-ai/plugin-sdk",
-  "version": "1.0.1-beta.260912",
+  "version": "1.0.2-beta.260914",
   "description": "The shared plugin contract for the HAPI CLI. Consumed by the core CLI, first-party plugins, and third-party extensions.",
   "license": "LRL-CL",
   "type": "module",
@@ -24,10 +24,10 @@
     "typescript": "^5"
   },
   "engines": {
-  "bun": ">=1.3.0"
-},
-"publishConfig": {
-"access": "public"
-},
-"keywords": ["hapi", "hapi-plugin", "mcp", "cli"]
+    "bun": ">=1.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": ["hapi", "hapi-plugin", "mcp", "cli"]
 }