@agent-proxy-kit/puraroute-mcp-server 0.0.0-stage → 0.1.1

package/bundle/run-mcp.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { access } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const bundleDir = dirname(fileURLToPath(import.meta.url));
+if (process.argv[2] === "--setup" && process.argv.length === 3) {
+  await import("./setup.mjs");
+  process.exit(0);
+}
+if (process.argv.length !== 2) {
+  process.stderr.write("Unknown MCP launcher argument.\n");
+  process.exit(1);
+}
+let runtimeEntry;
+const packagedRuntime = join(bundleDir, "..", "dist", "cli.js");
+try {
+  await access(packagedRuntime);
+  runtimeEntry = packagedRuntime;
+} catch {
+  try {
+    const require = createRequire(import.meta.url);
+    runtimeEntry = join(
+      dirname(require.resolve("proxy-agent-mcp-runtime/package.json")),
+      "dist/cli.js",
+    );
+  } catch {
+    process.stderr.write(
+      "Brand MCP runtime is missing. Reinstall the reviewed package.\n",
+    );
+    process.exit(1);
+  }
+}
+
+// Resolve the reviewed bundle from this file, so users never type its path.
+process.env.PROXY_AGENT_BUNDLE_DIR = bundleDir;
+await import(pathToFileURL(runtimeEntry).href);

package/bundle/setup.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const bundleDir = dirname(fileURLToPath(import.meta.url));
+const brand = JSON.parse(await readFile(join(bundleDir, "brand.json"), "utf8"));
+const launcher = join(bundleDir, "run-mcp.mjs");
+const skill = join(bundleDir, "skill", brand.skillName);
+const codexSkillTarget = join(homedir(), ".agents", "skills", brand.skillName);
+const claudeSkillTarget = join(homedir(), ".claude", "skills", brand.skillName);
+const quotedLauncher =
+  process.platform === "win32"
+    ? `"${launcher}"`
+    : `'${launcher.replaceAll("'", "'\\''")}'`;
+
+process.stdout.write(
+  `Brand package: ${brand.npmPackageName ?? brand.displayName}\n` +
+    `MCP launcher: ${launcher}\n` +
+    `Agent Skill folder: ${skill}\n` +
+    `Codex user Skill target: ${codexSkillTarget}\n` +
+    `Claude Code user Skill target: ${claudeSkillTarget}\n` +
+    `Copy the entire Skill folder to the target for the client you use; check before replacing an existing installation.\n` +
+    `\nCodex config.toml:\n` +
+    `[mcp_servers.${brand.serverName}]\n` +
+    `command = "node"\n` +
+    `args = [${JSON.stringify(launcher)}]\n` +
+    `env_vars = ["PROXY_AGENT_API_ORIGIN", "PROXY_AGENT_API_KEY"]\n` +
+    `\nClaude Code:\n` +
+    `claude mcp add --scope user --transport stdio ${brand.serverName} -- node ${quotedLauncher}\n` +
+    `The client process must inherit PROXY_AGENT_API_ORIGIN and PROXY_AGENT_API_KEY from a trusted local source.\n` +
+    `Ask a local Agent with machine access to read this output, install the Skill, register the MCP launcher, and verify the server name and tools. Never paste the API key into chat or command arguments. If the Agent lacks local access, follow these steps manually.\n`,
+);

package/bundle/skill/puraroute-proxy/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: puraroute-proxy
+description: Manage proxy resources with PuraRoute, assemble connection settings, troubleshoot failures, and use connected MCP tools for approved purchases or renewals.
+---
+
+# PuraRoute
+
+Use this Skill for proxy tasks with PuraRoute. Discover the connected tools; the bundled public contract declares the supported operations. Select the instance and resource before using account or connection data.
+
+If the local MCP server is absent, explain concepts or format connection settings from details the user already has. Mark those details unverified. Live balance, stock, account, order, credential, purchase, and renewal work requires the connected MCP server. See [setup](references/setup.md). Never ask for an account API key or proxy password in chat just to diagnose a missing tool.
+
+## Route the request
+
+| Goal                     | First action                                                                      | Guide                                                                             |
+| ------------------------ | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| Use an existing proxy    | Read resources and status for the selected instance.                              | [Workflows](references/workflows.md), [formats](references/connection-formats.md) |
+| Select or purchase       | Gather workload, region, protocol, duration, and traffic needs; read live offers. | [Products](references/products.md), [workflows](references/workflows.md)          |
+| Renew                    | Read target resource and current quote before a write.                            | [Workflows](references/workflows.md)                                              |
+| Fix a connection         | Locate the failing stage and inspect current resource data.                       | [Troubleshooting](references/troubleshooting.md)                                  |
+| Configure an application | Confirm the user-selected application and supported format.                       | [Formats](references/connection-formats.md), [workflows](references/workflows.md) |
+
+Use only named business tools in the [contract map](references/verified-contract.md). Do not construct arbitrary HTTP calls. Never pass a target host, origin, account API key, or arbitrary URL as a tool argument. The selected instance's live results determine prices, resources, stock, status, and connection credentials.
+
+Before a purchase or renewal, show the instance, target, quantity or term, and live price; obtain authorization for that exact write. After an uncertain write, read the original order or resource state before considering any repeat. A returned connection string does not change the Agent host or operating system network exit. Configure only the user-selected application when local control and permission exist, then verify from that application. Otherwise provide a copyable configuration and say it has not been applied.
+
+Treat proxy credentials as sensitive. Show a full password only for an explicit connection configuration request; never expose the account API key. For Chinese guidance, read the [Chinese guide](references/zh-CN.md). The [fixture cases](examples/connection-cases.md) use synthetic values.

package/bundle/skill/puraroute-proxy/examples/connection-cases.md

@@ -0,0 +1,33 @@
+# Synthetic connection cases
+
+These fictional cases use reserved `.example.test` hosts and sanitized fields. They illustrate the operations in this brand's public contract, not live PuraRoute resource values.
+
+## Existing proxy
+
+**Request:** “Use my existing static proxy.”
+
+**Expected tool sequence:** Call `listStaticResources`, identify the selected item, and inspect its status, `host`, `port`, `protocol`, `account`, and `password`. If the selected item is absent or a required field is missing, report that the configuration is incomplete. Do not use the allocated `ip` as the dial host without evidence.
+
+## HTTP and SOCKS5
+
+**Fictional static result:** `protocol=HTTP`, `host=static.example.test`, `port=3128`, `account=case@user`, `password=p:a/ss`, `ip=192.0.2.10`.
+
+**Expected HTTP configuration:** `http://case%40user:p%3Aa%2Fss@static.example.test:3128`.
+
+**Fictional dynamic result:** `host=dynamic.example.test`, `socks5_port=1080`, `proxy_username=case-user`, `password=case-pass`.
+
+**Expected SOCKS5 configuration:** `socks5://case-user:case-pass@dynamic.example.test:1080`, if the selected application accepts that scheme. Call `generateDynamicProxyCredentials` only when the user needs a usable dynamic connection. A generated credential does not itself apply the configuration.
+
+## Expired resource
+
+**Request:** “Why does my static proxy fail?”
+
+**Expected tool sequence:** Use `listStaticResources` to confirm the resource status, then `quoteStaticRenewal` if renewal is available and the user wants a price. Report an observed expired status; never invent an offer or silently submit `createStaticRenewalOrder`.
+
+## Uncertain purchase
+
+**Request:** “My static purchase timed out.”
+
+**Expected tool sequence:** Preserve the original `request_no`, use `listStaticPurchaseOrders` or `getStaticPurchaseOrder` to reconcile the order, then inspect resources if needed. Do not submit `createStaticPurchaseOrder` again with a new request number. If the lookup cannot settle the state, report uncertainty.
+
+The configuration has not been applied unless the selected application was actually changed and its exit checked.

package/bundle/skill/puraroute-proxy/references/connection-formats.md

@@ -0,0 +1,40 @@
+# Connection formats
+
+Use connection details returned for the selected PuraRoute resource and instance. The bundled public contract identifies the field paths below. The example values are synthetic; they are not live endpoints or credentials.
+
+For `generateDynamicProxyCredentials`, read `data.host`, `data.proxy_username`, `data.password`, and the port for the chosen protocol: `data.http_port` or `data.socks5_port`. For `listStaticResources`, inspect an item in `data.list` and read `host`, `port`, `account`, `password`, and `protocol`. Keep `ip` separate from the dial host. If the selected item or required field is absent, report an incomplete configuration.
+
+## Field check before formatting
+
+| Field                 | Use                                                               | Check                                                                                                |
+| --------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| Protocol              | Select the application's HTTP or SOCKS5 mode.                     | The resource and application both support it. Do not infer it from a port.                           |
+| Connection host       | Hostname or address the client dials.                             | Prefer the field documented as the proxy entry point. An allocated IP may describe the exit instead. |
+| Port                  | Port paired with that host and protocol.                          | Use the current value from the selected resource; do not reuse another product's port.               |
+| Username/password     | Proxy authentication, when required.                              | Use only returned proxy credentials. The account API key is unrelated.                               |
+| Allowlisted source IP | An alternative or additional access condition only if documented. | Confirm the product's rule and the user's actual source IP before describing it as active.           |
+
+If any required field or the authentication mode is unknown, label the configuration incomplete. Do not guess a username, password, default port, domain, or browser import format.
+
+## URL-style configuration
+
+When the target application accepts a proxy URL, percent-encode **each credential component** separately. Keep the host unescaped as a hostname; bracket a literal IPv6 address. The general shape is:
+
+```text
+http://ENCODED_USER:ENCODED_PASSWORD@CONNECTION_HOST:PORT
+socks5://ENCODED_USER:ENCODED_PASSWORD@CONNECTION_HOST:PORT
+```
+
+For a fictional HTTP result with host `static.example.test`, port `3128`, username `case@user`, and password `p:a/ss`, the URL is:
+
+```text
+http://case%40user:p%3Aa%2Fss@static.example.test:3128
+```
+
+Enter unescaped credentials when the application offers separate username and password fields. Do not append region or session tokens to the username unless the reviewed product instructions explicitly define that syntax. Some clients distinguish SOCKS5 DNS modes and accept different URL schemes; check the chosen client's documentation instead of assuming `socks5://` works everywhere.
+
+## Delivery and verification
+
+For an explicit setup request, provide the complete, copyable format that the chosen application accepts. In broader reports, mask the proxy password. Never put the account API key into a proxy URL or echo it back. Avoid saving a full credential URL in a shared file, log, screenshot, or shell command history.
+
+Once applied, run a read-only IP check **from the selected application** and compare the observed exit with the resource's expected region or IP when such an expectation is documented. A retrieved connection string alone proves neither application configuration nor a changed network exit. See [workflows](workflows.md) for the setup sequence.

package/bundle/skill/puraroute-proxy/references/products.md

@@ -0,0 +1,9 @@
+# Product selection
+
+Use PuraRoute MCP results for current products, selectable regions, inventory, prices, limits, wallet balance, and account resources. The bundled contract defines fields; it does not promise a fixed gateway, port, rotation interval, or price. If a required read tool is missing, state the gap.
+
+Ask first whether the user has a resource. For a new choice, establish the target application, exit region, HTTP or SOCKS5 requirement, expected traffic and concurrency, duration, and whether a stable exit identity is needed. Compare only offers supported by live results from the selected instance.
+
+HTTP and SOCKS5 are different client protocols. Rotation and sticky sessions describe how exit identity may change; confirm actual behavior from the selected product. An allocated IP may describe the exit and may differ from the connection host. Verify IP allowlisting rules before treating them as active authentication.
+
+Show billing unit, quantity, total, stock, and wallet balance before a purchase. Preserve decimal money and traffic values as returned strings. Never invent an unavailable price or region.

package/bundle/skill/puraroute-proxy/references/setup.md

@@ -0,0 +1,19 @@
+# Local MCP setup for PuraRoute
+
+Install the reviewed PuraRoute npm package from its approved publisher. It includes this brand's contract, MCP launcher, and Agent Skill and the shared neutral runtime code.
+
+```text
+npm install --global @agent-proxy-kit/puraroute-mcp-server
+puraroute-proxy-mcp --setup
+```
+
+The setup output prints the absolute MCP launcher and Skill source folder. npm installs both files, but does not register the MCP server or activate the Skill in an Agent client. With the user's permission, an Agent that can operate this machine can complete the following steps. Without local access, provide the exact steps for the user to run and say what remains unconfigured.
+
+1. Run `puraroute-proxy-mcp --setup` and use its actual installed paths. Copy the entire Skill folder, including `SKILL.md` and `references/`, to the chosen client's user Skill directory: `~/.agents/skills/puraroute-proxy` for Codex or `~/.claude/skills/puraroute-proxy` for Claude Code. On Windows, use the corresponding directories under the user's home folder. Inspect an existing target before replacing it.
+2. Register the printed launcher as a local stdio MCP server. For Codex, use the printed `config.toml` block. For Claude Code, use the printed `claude mcp add --scope user` command. The launcher finds its bundled contract automatically; users do not set a bundle path.
+3. Have the user arrange for `PROXY_AGENT_API_ORIGIN` and `PROXY_AGENT_API_KEY` to be inherited by the Agent client from a trusted local source. The origin is an approved HTTPS **origin without a path**, query, or fragment; the origin and key must belong to the same instance. Do not ask the user to paste the API key into chat, put it in command arguments or Skill text, or log its value.
+4. Restart or refresh the client. Check that it loads the `puraroute-proxy` Skill and connects to MCP service `puraroute-proxy-mcp`; compare `tools/list` with the bundled `bundle-manifest.json`. Do not call purchase, renewal, or account-write tools merely to verify setup.
+
+The optional timeout is `PROXY_AGENT_REQUEST_TIMEOUT_MS`. Keep the key out of shell history and project files.
+
+For installation help, use https://puraroute.com. Do not substitute another brand's API origin or bundle.

package/bundle/skill/puraroute-proxy/references/troubleshooting.md

@@ -0,0 +1,17 @@
+# Troubleshooting
+
+Start with the selected instance, resource ID, live status, and the exact failing stage: MCP startup, customer API call, proxy connection, or application exit test. A failure at one stage does not prove a failure at another. Do not include an account API key, proxy password, request body, or full API URL in diagnostic summaries.
+
+| Observation                                            | Check                                                                                                               | Safe next action                                                                                                           |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| MCP tools are absent or startup fails                  | Reviewed contract path, adapter policy, HTTPS instance origin, and whether the client process received its API key. | Report the missing configuration or contract; do not invent operation names.                                               |
+| `business_error` under HTTP 200                        | Business code, safe message, trace ID, selected instance, and resource status.                                      | Use the documented meaning of that code; if unknown, report the code without guessing.                                     |
+| `http_error` 401/403                                   | Instance/key pairing and actual business permission, without exposing the key.                                      | Ask the operator to check the secure local configuration and account authorization.                                        |
+| `http_error` 5xx, `malformed_json`, or `network_error` | Service health, trace ID, and whether the operation was a read or write.                                            | Preserve diagnostics; do not convert an unknown write result into a new purchase.                                          |
+| `timeout` on a read                                    | Whether the read can be safely repeated and whether the instance is reachable.                                      | Retry only a suitable read if useful; keep the same instance.                                                              |
+| `uncertain_write_result`                               | Original operation and request number.                                                                              | Query order/resource state with an approved read tool; stop if no such tool exists. Do not repeat the write automatically. |
+| Proxy authentication or connection failure             | Current resource status, verified protocol/host/port, proxy credentials, and any documented allowlist condition.    | Correct only the field supported by evidence. Never substitute the account API key as a proxy password.                    |
+| Resource is expired or depleted                        | Live status, expiry or quota, and a verified renewal offer.                                                         | Show price and target before an authorized renewal.                                                                        |
+| Application still shows its original exit IP           | Whether that specific application accepted and applied the proxy settings; whether the test ran inside it.          | Recheck its proxy mode and perform another read-only exit test. Do not claim the whole OS changed.                         |
+
+When contacting support, include operation ID, safe business code or HTTP status, trace ID if present, and the approximate time. Keep proxy credentials and account keys out of the report. For a write timeout, preserve the original request number for reconciliation.

package/bundle/skill/puraroute-proxy/references/verified-contract.md

@@ -0,0 +1,34 @@
+# Bundled business tools
+
+The PuraRoute public bundle declares 26 operations under `/gin/open-api/v1/`. Discover the tools available in the connected MCP session and use their advertised input schemas. The local runtime sends requests only to the configured HTTPS instance origin.
+
+- `createDynamicAccount`: Create a dynamic proxy account
+- `createStaticPurchaseOrder`: Place a static proxy order
+- `createStaticRenewalOrder`: Renew a static proxy resource
+- `generateDynamicProxyCredentials`: Generate dynamic proxy credentials
+- `getDynamicAccount`: Get dynamic account details
+- `getDynamicTrafficBalance`: Get dynamic traffic balance
+- `getDynamicTrafficOrder`: Get dynamic traffic order
+- `getStaticInventory`: Check static proxy inventory
+- `getStaticPurchaseOrder`: Get static purchase order
+- `getStaticRenewalOrder`: Get static renewal order
+- `getWalletBalance`: Get wallet balance
+- `listDynamicAccounts`: List dynamic proxy accounts
+- `listDynamicDailyUsage`: List daily dynamic traffic usage
+- `listDynamicRegions`: List dynamic proxy regions
+- `listDynamicTrafficOrders`: List dynamic traffic orders
+- `listDynamicTrafficProducts`: List dynamic traffic products
+- `listEffectiveDynamicTrafficLots`: List active traffic lots
+- `listStaticPurchaseOrders`: List static purchase orders
+- `listStaticRegions`: List static proxy regions
+- `listStaticRenewalOrders`: List static renewal orders
+- `listStaticResources`: List static proxy resources
+- `purchaseDynamicTraffic`: Purchase dynamic traffic
+- `quoteStaticPurchase`: Quote static proxy purchase
+- `quoteStaticRenewal`: Quote static proxy renewal
+- `setDynamicAccountStatus`: Set dynamic account status
+- `updateDynamicAccountLimit`: Update dynamic account limit
+
+The business adapter treats HTTP 200 with `code=0` as success for this sample contract; `msg`, `data`, and `next` are response envelope fields. Do not treat transport success as a completed purchase. The bundle's adapter policy is the authority for success semantics.
+
+For `listDynamicRegions`, use `query.level=COUNTRY` without `parent_code`; for `PROVINCE` or `CITY`, provide the parent region's `region_code` as `query.parent_code`. The bundled tool constraints enforce this rule.

package/bundle/skill/puraroute-proxy/references/workflows.md

@@ -0,0 +1,33 @@
+# Operational workflows
+
+The MCP server exposes the operations in the PuraRoute public contract. Discover their names and input schemas at runtime. Keep the instance and resource identifiers from the same API origin throughout a workflow.
+
+## Use an existing resource
+
+1. Identify the requested instance and resource. If the user has no resource ID, use an approved list/search operation if the connected contract provides one.
+2. Read the resource's current status and connection details. A stale result or a different instance's data cannot establish usability.
+3. Check protocol, connection host, port, authentication mode, and required credentials. Distinguish a dial host from an allocated/exit IP. Read [connection formats](connection-formats.md) before constructing a URL.
+4. Give the requested configuration or a precise list of missing fields. Do not purchase a replacement merely because the first lookup failed.
+
+## Choose and purchase
+
+1. Gather workload and location requirements using [product selection](products.md), then read live product/price/stock and wallet results from the selected instance.
+2. Present a purchase summary: instance, exact product or SKU, region or mode if applicable, quantity, billing unit, current total, and any target resource. Mark values that the API does not provide as unknown.
+3. After the user authorizes that concrete purchase, submit the specific approved write operation once with its original request number. Do not create a generic HTTP call.
+4. On a confirmed success, use approved read tools to confirm the order/resource and then read its connection details. A 2xx HTTP response alone is not business success; inspect the business code.
+5. On `uncertain_write_result`, keep the original request number and query order/resource state with a read-only tool. If the contract lacks a lookup, report uncertainty and stop. Never submit again with a fresh request number just to resolve a timeout.
+
+## Renew
+
+Read the target resource and its current expiry/status, then read the available renewal offer and price. Show the instance, resource, extension term or quantity, and total before the write. Follow the same single-write and uncertain-result recovery rules as purchase. Do not assume that an expired resource can be renewed until the live API confirms the action.
+
+## Configure a selected application
+
+1. Confirm the user-selected application and its accepted proxy protocol and field format. Assemble the exact verified connection data.
+2. If the Agent has local control and the user asked it to configure that application, change only that application's proxy settings. Avoid changing system-wide or other applications' settings as a side effect.
+3. Make a read-only IP check from within that application. Report the observed exit IP and whether it matches a verified expectation. If the application cannot perform such a check, say verification is pending.
+4. Without local control, provide a copyable configuration and state plainly that it has not been applied.
+
+## Answer state explicitly
+
+A useful answer separates **resource found**, **connection details complete**, **configuration applied**, and **exit verified**. These are different outcomes. Give the selected instance/resource and status, any remaining missing field or read operation, and the next safe action. Include full proxy credentials only when the user asked for a complete configuration.

package/bundle/skill/puraroute-proxy/references/zh-CN.md

@@ -0,0 +1,13 @@
+# PuraRoute 代理操作指南
+
+先确认用户要使用现有代理、选购或续费、排查连接，还是配置指定应用。当前品牌的本地 MCP 工具来自随包公开契约；实时产品、库存、余额、资源状态和凭据都要查询选中的实例。缺少 MCP 时，可解释概念或整理用户已提供的连接字段，但不能声称账户和资源已核实；安装方式见[本地配置](setup.md)。不要要求用户在聊天中粘贴账户 API Key 或代理密码。
+
+npm 包已经包含 Skill 文件，但不会自动把它加载到 Agent 客户端。可让有本机操作权限的 Agent 运行 `puraroute-proxy-mcp --setup`，按输出将整个 Skill 文件夹复制到 Codex 用户目录 `~/.agents/skills/puraroute-proxy` 或 Claude Code 用户目录 `~/.claude/skills/puraroute-proxy`，再注册 MCP、从本机安全来源配置实例地址与 API Key，重启并验证工具列表。没有本机权限时，只提供具体手动步骤，不声称已完成配置。
+
+选型前确认目标应用、地区、HTTP 或 SOCKS5 协议、用量、并发、使用时长及是否需要稳定出口。轮换、粘性会话和 IP 白名单的具体行为必须以该实例的已审核资料或实时结果为准。`listDynamicRegions` 查询国家时不传 `parent_code`；查询省州或城市时须传上级 `region_code`。
+
+完整连接配置需要协议、连接入口主机、端口和适用的认证字段。动态代理凭据可查看 `generateDynamicProxyCredentials` 的 `data.host`、`data.proxy_username`、`data.password`、`data.http_port` 或 `data.socks5_port`；静态资源可查看 `listStaticResources` 的 `data.list` 条目。分配 IP 可能是出口 IP，不能自动当成连接主机。URL 格式要分别编码用户名和密码；没有字段就说明配置不完整，不猜网关或端口。
+
+购买或续费前展示实例、目标资源或产品、数量或时长、实时总价，取得对该写操作的授权。若写操作超时，保留原请求号，先查订单或资源；不要盲目重试。HTTP 成功不等于业务成功，应核对业务码。
+
+只有在用户指定应用、Agent 有本机控制权且获得相应授权时，才修改该应用的代理设置，并从应用内部检查出口 IP。否则给出可复制的配置并明确说“尚未应用”。读取连接信息本身不会改变操作系统出口。概览中隐藏代理密码，绝不展示账户 API Key。

package/bundle/tool-constraints.json

@@ -0,0 +1,28 @@
+{
+  "listDynamicRegions": {
+    "oneOf": [
+      {
+        "description": "COUNTRY lookup must not include parent_code.",
+        "properties": {
+          "query": {
+            "properties": {
+              "level": { "const": "COUNTRY" }
+            },
+            "not": { "required": ["parent_code"] }
+          }
+        }
+      },
+      {
+        "description": "PROVINCE and CITY lookups require parent_code.",
+        "properties": {
+          "query": {
+            "properties": {
+              "level": { "enum": ["PROVINCE", "CITY"] }
+            },
+            "required": ["parent_code"]
+          }
+        }
+      }
+    ]
+  }
+}

package/dist/brand.js

@@ -0,0 +1,40 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+export function validateBrandProfile(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Invalid brand.json");
+    const profile = value;
+    if (typeof profile.id !== "string" ||
+        !/^[a-z][a-z0-9-]{1,62}$/.test(profile.id) ||
+        typeof profile.displayName !== "string" ||
+        !/^[\p{L}\p{N}][\p{L}\p{N} .&'-]{1,79}$/u.test(profile.displayName) ||
+        typeof profile.serverName !== "string" ||
+        !/^[a-z][a-z0-9-]{1,62}$/.test(profile.serverName) ||
+        typeof profile.skillName !== "string" ||
+        !/^[a-z][a-z0-9-]{1,62}$/.test(profile.skillName) ||
+        typeof profile.version !== "string" ||
+        !/^\d+\.\d+\.\d+$/.test(profile.version) ||
+        typeof profile.supportUrl !== "string")
+        throw new Error("Invalid brand.json");
+    if (profile.npmPackageName !== undefined &&
+        (typeof profile.npmPackageName !== "string" ||
+            !/^@[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/.test(profile.npmPackageName)))
+        throw new Error("Invalid brand.json npm package name");
+    try {
+        const url = new URL(profile.supportUrl);
+        if (url.protocol !== "https:" || url.username || url.password)
+            throw new Error("Invalid brand.json");
+    }
+    catch {
+        throw new Error("Invalid brand.json");
+    }
+    return profile;
+}
+export async function readBrandProfile(bundleDir) {
+    try {
+        return validateBrandProfile(JSON.parse(await readFile(join(bundleDir, "brand.json"), "utf8")));
+    }
+    catch {
+        throw new Error("Missing or invalid brand.json in bundle");
+    }
+}

package/dist/catalog/input-validator.js

@@ -0,0 +1,40 @@
+import { Ajv } from "@modelcontextprotocol/server/validators/ajv";
+// OpenAPI formats used by approved inputs. The numeric formats must be checked
+// explicitly because unknown Ajv formats otherwise become warnings and no-op rules.
+export function newInputValidator() {
+    const validator = new Ajv({ strict: false, allErrors: true });
+    validator.addFormat("int32", {
+        type: "number",
+        validate: (value) => Number.isInteger(value) && value >= -2147483648 && value <= 2147483647,
+    });
+    validator.addFormat("int64", {
+        type: "number",
+        validate: (value) => Number.isSafeInteger(value),
+    });
+    validator.addFormat("date", {
+        type: "string",
+        validate: (value) => {
+            if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
+                return false;
+            const date = new Date(`${value}T00:00:00.000Z`);
+            return (!Number.isNaN(date.valueOf()) && date.toISOString().startsWith(value));
+        },
+    });
+    validator.addFormat("date-time", {
+        type: "string",
+        validate: (value) => /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(value) && !Number.isNaN(Date.parse(value)),
+    });
+    validator.addFormat("uri", {
+        type: "string",
+        validate: (value) => {
+            try {
+                return Boolean(new URL(value).protocol);
+            }
+            catch {
+                return false;
+            }
+        },
+    });
+    validator.addFormat("password", { type: "string", validate: () => true });
+    return validator;
+}

package/dist/catalog/load.js

@@ -0,0 +1,137 @@
+import { readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { dirname, join } from "node:path";
+import YAML from "yaml";
+import { dereference, validate } from "@scalar/openapi-parser";
+import { collectOperations, } from "./operations.js";
+const obj = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value
+    : {};
+function rejectExternalReferences(value, location = "contract") {
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => rejectExternalReferences(item, `${location}[${index}]`));
+    }
+    else if (value !== null && typeof value === "object") {
+        const record = value;
+        if (typeof record.$ref === "string" && !record.$ref.startsWith("#/")) {
+            throw new Error(`${location}: external $ref is unsupported`);
+        }
+        for (const [key, item] of Object.entries(record))
+            rejectExternalReferences(item, `${location}.${key}`);
+    }
+}
+function checkSecurity(document) {
+    const schemes = obj(obj(document.components).securitySchemes);
+    const goodSchemes = Object.entries(schemes)
+        .filter(([, value]) => {
+        const scheme = obj(value);
+        return (scheme.type === "apiKey" &&
+            scheme.in === "header" &&
+            scheme.name === "X-API-Key");
+    })
+        .map(([name]) => name);
+    if (goodSchemes.length !== 1 || Object.keys(schemes).length !== 1) {
+        throw new Error("Contract must declare only the X-API-Key header security scheme");
+    }
+    const required = JSON.stringify([{ [goodSchemes[0]]: [] }]);
+    if (JSON.stringify(document.security) !== required)
+        throw new Error("Contract must require X-API-Key globally");
+    for (const [path, itemValue] of Object.entries(obj(document.paths))) {
+        for (const [method, value] of Object.entries(obj(itemValue))) {
+            if (["get", "post", "put", "patch", "delete"].includes(method) &&
+                obj(value).security !== undefined) {
+                if (JSON.stringify(obj(value).security) !== required)
+                    throw new Error(`${method.toUpperCase()} ${path}: unsupported security override`);
+            }
+        }
+    }
+}
+async function applyToolConstraints(contractPath, operations) {
+    let source;
+    try {
+        source = await readFile(join(dirname(contractPath), "tool-constraints.json"), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw new Error("Cannot read tool-constraints.json");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch {
+        throw new Error("Invalid tool-constraints.json");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error("Invalid tool-constraints.json");
+    const byName = new Map(operations.map((operation) => [operation.operationId, operation]));
+    for (const [name, constraint] of Object.entries(parsed)) {
+        const operation = byName.get(name);
+        if (!operation)
+            throw new Error(`Unknown tool constraint: ${name}`);
+        if (!constraint ||
+            typeof constraint !== "object" ||
+            Array.isArray(constraint))
+            throw new Error(`Invalid tool constraint: ${name}`);
+        operation.inputConstraints = constraint;
+    }
+}
+export async function loadCatalog(contractPath) {
+    const bytes = await readFile(contractPath);
+    const source = bytes.toString("utf8");
+    let parsed;
+    try {
+        parsed = obj(YAML.parse(source));
+    }
+    catch {
+        throw new Error("Invalid OpenAPI JSON/YAML document");
+    }
+    const version = parsed.openapi;
+    if (typeof version !== "string" || !/^3\.(0|1)\.\d+$/.test(version)) {
+        throw new Error("Unsupported OpenAPI version; expected 3.0.x or 3.1.x");
+    }
+    rejectExternalReferences(parsed);
+    checkSecurity(parsed);
+    const servers = parsed.servers;
+    if (!Array.isArray(servers) || servers.length !== 1)
+        throw new Error("Contract must declare exactly one server URL");
+    const serverUrl = obj(servers[0]).url;
+    if (typeof serverUrl !== "string")
+        throw new Error("Unsupported server URL");
+    let serverPath = serverUrl;
+    if (/^https?:\/\//i.test(serverUrl)) {
+        let parsedUrl;
+        try {
+            parsedUrl = new URL(serverUrl);
+        }
+        catch {
+            throw new Error("Unsupported server URL");
+        }
+        if (parsedUrl.username ||
+            parsedUrl.password ||
+            parsedUrl.search ||
+            parsedUrl.hash)
+            throw new Error("Unsupported server URL");
+        serverPath = parsedUrl.pathname;
+    }
+    if (!/^\/[A-Za-z0-9/_-]*$/.test(serverPath) || serverPath.includes(".."))
+        throw new Error("Unsupported server URL; expected a safe base path");
+    // The contract authority is metadata only. Runtime requests use the configured HTTPS origin.
+    const basePath = serverPath.replace(/\/$/, "") || "";
+    const validation = await validate(source);
+    if (!validation.valid)
+        throw new Error(`OpenAPI validation failed: ${validation.errors.map(String).join("; ")}`);
+    const resolved = await dereference(source);
+    if (resolved.errors?.length)
+        throw new Error(`OpenAPI dereference failed: ${resolved.errors.map(String).join("; ")}`);
+    const document = obj(resolved.schema);
+    const operations = collectOperations(document, basePath, version);
+    await applyToolConstraints(contractPath, operations);
+    return {
+        contractSha256: createHash("sha256").update(bytes).digest("hex"),
+        serverBasePath: basePath,
+        operations,
+        openapiVersion: version,
+    };
+}