@cmdforge/gen-apic-mp 0.0.1 → 0.0.3

package/.editorconfig

@@ -0,0 +1,11 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

package/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish Package
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  id-token: write  # Required for OIDC
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
+          package-manager-cache: false  # never use caching in release builds
+      - run: npm ci
+      - run: npm run build --if-present
+      - run: npm test
+      - run: npm publish  # Or: npm stage publish

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cmdforge
+
+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

@@ -1,45 +1,136 @@
-# @cmdforge/gen-apic-mp
+# gen-apic-mp
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+Generate marketplace repository contents from an Azure API Center workspace.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+This tool reads plugin and MCP assets from API Center, translates legacy `v0/servers/{name}` data into MCP server entries, and emits the repository structure expected by marketplace-style plugin catalogs.
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+## What it generates
 
-## Purpose
+For a workspace, `gen-apic-mp` produces:
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@cmdforge/gen-apic-mp`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+```text
+.github/plugin/marketplace.json
+.claude-plugin/marketplace.json
+plugins/{pluginName}/plugin.json
+plugins/{pluginName}/.mcp.json
+```
 
-## What is OIDC Trusted Publishing?
+The generated `.mcp.json` only contains normal MCP server launch configuration:
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+- stdio servers: `transport`, `command`, `args`, `env`, `cwd`
+- remote servers: `transport`, `url`, `headers`
 
-## Setup Instructions
+## Install
 
-To properly configure OIDC trusted publishing for this package:
+```bash
+npm install
+npm run build
+```
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+To use the CLI directly from the repo during development:
 
-## DO NOT USE THIS PACKAGE
+```bash
+node dist/server/cli.js --help
+```
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+## CLI
 
-## More Information
+```bash
+gen-apic-mp <serviceName> <region> <workspaceName> [--unpack [directory]] [--mcp-meta <key>]
+```
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+Arguments:
 
----
+- `serviceName`: region-unique Azure API Center service name
+- `region`: Azure region, like `eastus`
+- `workspaceName`: API Center workspace to export
 
-**Maintained for OIDC setup purposes only**
+Option:
+
+- `--unpack [directory]`: write the generated marketplace tree directly into a directory instead of creating a zip
+- `--mcp-meta <key>`: include a specific `_meta` key from `v0/servers/{name}` in generated `.mcp.json` server entries
+
+If `--unpack` is provided without a value, it defaults to the current working directory, but only if that directory contains a `package.json`.
+
+## Examples
+
+Create a zip in the current directory:
+
+```bash
+gen-apic-mp my-api-center eastus marketplace
+```
+
+Unpack directly into the current repo:
+
+```bash
+gen-apic-mp my-api-center eastus marketplace --unpack
+```
+
+Unpack into a specific directory:
+
+```bash
+gen-apic-mp my-api-center eastus marketplace --unpack /path/to/marketplace-repo
+```
+
+Include OAuth-related `_meta` in generated `.mcp.json`:
+
+```bash
+gen-apic-mp my-api-center eastus marketplace --mcp-meta oauth-client-provider
+```
+
+Include multiple `_meta` keys:
+
+```bash
+gen-apic-mp my-api-center eastus marketplace --mcp-meta oauth-client-provider --mcp-meta x-ms-id
+```
+
+## Output behavior
+
+Without `--unpack`, the CLI writes:
+
+```text
+{workspaceName}-marketplace.zip
+```
+
+With `--unpack`, the CLI does not create a zip. It syncs the generated tree directly into the target directory.
+
+## How MCP translation works
+
+For each plugin resource with `kind: "mcp"`, the tool:
+
+1. Fetches the MCP asset using the plugin resource `resourceId`
+2. Fetches the legacy server entry from `workspaces/{workspaceName}/v0/servers/{mcp.name}`
+3. Uses the `server.name` from that payload as the key in `.mcp.json`
+4. Translates the server entry into a `types.McpServer`
+
+The translator supports:
+
+- direct stdio-style entries with `command`, `args`, and `env`
+- direct remote-style entries with `url` and remote transport
+- nested `server.remotes`
+- nested `server.packages` as fallback when `remotes` is empty
+
+If `--mcp-meta` is used, only the requested `_meta` keys are copied into each generated MCP server entry.
+
+## Current limitations
+
+- Skill directories are not generated yet, so `plugin.json` only includes `skills` when that support is added
+- The tool expects the target API Center workspace to expose:
+  - portal config at `config.json`
+  - plugin assets in the workspace API listing
+  - MCP assets reachable from plugin resource IDs
+  - legacy server entries at `v0/servers/{name}`
+
+## Development
+
+Build:
+
+```bash
+npm run build
+```
+
+Test:
+
+```bash
+npm test
+```

package/dist/server/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/server/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/server/cli.ts"],"names":[],"mappings":""}

package/dist/server/cli.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { Command, Option } from "commander";
+import { generateMarketplaceGit, resolveUnpackDirectory } from "./marketplace.js";
+const program = new Command();
+const unpackPreset = "__CURRENT_WORKING_PACKAGE__";
+const unpackOption = new Option("--unpack [directory]", "Also unpack the generated marketplace into a directory; defaults to the current directory").preset(unpackPreset);
+const mcpMetaOption = new Option("--mcp-meta <key>", "Include the specified _meta key in generated .mcp.json server entries").argParser((value, previous = []) => [...previous, value]);
+program.configureHelp({
+    optionDescription(option) {
+        const description = option.description ?? "";
+        if (option.attributeName() === "unpack" && option.presetArg === unpackPreset)
+            return description;
+        return option.description;
+    },
+});
+program
+    .argument("<serviceName>", "Region-unique API Center service name")
+    .argument("<region>", "Region name")
+    .argument("<workspaceName>", "Workspace to convert into marketplace zip")
+    .addOption(unpackOption)
+    .addOption(mcpMetaOption)
+    .action(async (serviceName, region, workspaceName, options) => {
+    const unpack = await resolveUnpackDirectory(options.unpack);
+    const mcpMetaKeys = options.mcpMeta;
+    const result = await generateMarketplaceGit({ serviceName, region, workspaceName }, { unpack, mcpMetaKeys });
+    if (result.unpackPath) {
+        console.log(`Unpacked marketplace into ${result.unpackPath}`);
+        return;
+    }
+    console.log(`Wrote ${result.pluginCount} plugins to ${result.zipPath}`);
+});
+program.parse();
+//# sourceMappingURL=cli.js.map

package/dist/server/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/server/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAElF,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAC9B,MAAM,YAAY,GAAG,6BAA6B,CAAC;AACnD,MAAM,YAAY,GAAG,IAAI,MAAM,CAC7B,sBAAsB,EACtB,2FAA2F,CAC5F,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;AACvB,MAAM,aAAa,GAAG,IAAI,MAAM,CAC9B,kBAAkB,EAClB,uEAAuE,CACxE,CAAC,SAAS,CAAC,CAAC,KAAa,EAAE,WAAqB,EAAE,EAAE,EAAE,CAAC,CAAC,GAAG,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;AAE9E,OAAO,CAAC,aAAa,CAAC;IACpB,iBAAiB,CAAC,MAAM;QACtB,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC;QAC7C,IAAI,MAAM,CAAC,aAAa,EAAE,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,KAAK,YAAY;YAC1E,OAAO,WAAW,CAAC;QACrB,OAAO,MAAM,CAAC,WAAW,CAAC;IAC5B,CAAC;CACF,CAAC,CAAC;AAEH,OAAO;KACJ,QAAQ,CAAC,eAAe,EAAE,uCAAuC,CAAC;KAClE,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;KACnC,QAAQ,CAAC,iBAAiB,EAAE,2CAA2C,CAAC;KACxE,SAAS,CAAC,YAAY,CAAC;KACvB,SAAS,CAAC,aAAa,CAAC;KACxB,MAAM,CAAC,KAAK,EACX,WAAmB,EACnB,MAAc,EACd,aAAqB,EACrB,OAAgD,EAChD,EAAE;IACF,MAAM,MAAM,GAAG,MAAM,sBAAsB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5D,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IAEpC,MAAM,MAAM,GAAG,MAAM,sBAAsB,CACzC,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,EACtC,EAAE,MAAM,EAAE,WAAW,EAAE,CACxB,CAAC;IACF,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACtB,OAAO,CAAC,GAAG,CAAC,6BAA6B,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;QAC9D,OAAO;IACT,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,SAAS,MAAM,CAAC,WAAW,eAAe,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;AAC1E,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,KAAK,EAAE,CAAC"}

package/dist/server/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./marketplace.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}

package/dist/server/index.js

@@ -0,0 +1,2 @@
+export * from "./marketplace.js";
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}

package/dist/server/marketplace.d.ts

@@ -0,0 +1,36 @@
+import { types } from "../shared/index.js";
+export declare class ApiCenterClient {
+    readonly info: types.WorkspaceInfo;
+    get serviceName(): string;
+    get region(): string;
+    get workspaceName(): string;
+    constructor(info: types.WorkspaceInfo);
+    plane(plane: types.PlaneType): string;
+    path(plane: types.PlaneType, path: string): string;
+    url(plane: types.PlaneType, path: string, params?: Record<string, unknown>): string;
+    workspace(path: string, params?: Record<string, unknown>): string;
+    get<T>(url: string): Promise<T>;
+    paged<T>(url: string): AsyncGenerator<T[], void, unknown>;
+    config(): Promise<types.PortalConfig>;
+    apis($top?: number, $skip?: number): AsyncGenerator<types.ApiAssetItem[], void, unknown>;
+    plugin(name: string): Promise<types.PluginAsset>;
+    mcp(resourceId: string): Promise<types.McpAsset>;
+    v0Server(name: string): Promise<types.V0ServerJsonEntry>;
+}
+export declare function mcpServerNameFromV0Entry(entry: types.V0ServerJsonEntry): string;
+export declare function mcpServerFromV0Entry(entry: types.V0ServerJsonEntry, options?: types.GenerateMcpServerOptions): types.McpServer;
+export declare function mcpServersFromServerJson(serverJson: types.ServerJson): {
+    [k: string]: types.McpServer;
+};
+export type GenerateMarketplaceGitOptions = {
+    unpack?: string;
+    mcpMetaKeys?: string[];
+};
+export declare function generateMarketplaceGit(info: types.WorkspaceInfo, options?: GenerateMarketplaceGitOptions): Promise<{
+    zipPath: string | undefined;
+    unpackPath: string | undefined;
+    pluginCount: number;
+    marketplaceJson: types.MarketplaceJson;
+}>;
+export declare function resolveUnpackDirectory(value: string | undefined): Promise<string | undefined>;
+//# sourceMappingURL=marketplace.d.ts.map

package/dist/server/marketplace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"marketplace.d.ts","sourceRoot":"","sources":["../../src/server/marketplace.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAI3C,qBAAa,eAAe;aAKE,IAAI,EAAE,KAAK,CAAC,aAAa;IAJrD,IAAI,WAAW,WAAoC;IACnD,IAAI,MAAM,WAA+B;IACzC,IAAI,aAAa,WAAsC;gBAE3B,IAAI,EAAE,KAAK,CAAC,aAAa;IAErD,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,SAAS;IAI5B,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,MAAM;IAIzC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;IAO9E,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;IAItD,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM;IAWjB,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM;IAUrB,MAAM;IAIZ,IAAI,CAAC,IAAI,SAAK,EAAE,KAAK,CAAC,EAAE,MAAM;IAIxB,MAAM,CAAC,IAAI,EAAE,MAAM;IAInB,GAAG,CAAC,UAAU,EAAE,MAAM;IAItB,QAAQ,CAAC,IAAI,EAAE,MAAM;CAG5B;AAgPD,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,KAAK,CAAC,iBAAiB,UAStE;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,KAAK,CAAC,iBAAiB,EAC9B,OAAO,GAAE,KAAK,CAAC,wBAA6B,GAC3C,KAAK,CAAC,SAAS,CAwCjB;AAED,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,KAAK,CAAC,UAAU;;EAKpE;AAoED,MAAM,MAAM,6BAA6B,GAAG;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;AAEF,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,KAAK,CAAC,aAAa,EACzB,OAAO,GAAE,6BAAkC;;;;qBA4DY,KAAK,CAAC,eAAe;GAK7E;AAID,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,+BAerE"}