@runapi.ai/mcp 0.1.0 → 0.1.1

package/LICENSE

@@ -1,201 +1,21 @@
-                              Apache License
-                        Version 2.0, January 2004
-                     http://www.apache.org/licenses/
-
-TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-1. Definitions.
-
-   "License" shall mean the terms and conditions for use, reproduction,
-   and distribution as defined by Sections 1 through 9 of this document.
-
-   "Licensor" shall mean the copyright owner or entity authorized by
-   the copyright owner that is granting the License.
-
-   "Legal Entity" shall mean the union of the acting entity and all
-   other entities that control, are controlled by, or are under common
-   control with that entity. For the purposes of this definition,
-   "control" means (i) the power, direct or indirect, to cause the
-   direction or management of such entity, whether by contract or
-   otherwise, or (ii) ownership of fifty percent (50%) or more of the
-   outstanding shares, or (iii) beneficial ownership of such entity.
-
-   "You" (or "Your") shall mean an individual or Legal Entity
-   exercising permissions granted by this License.
-
-   "Source" form shall mean the preferred form for making modifications,
-   including but not limited to software source code, documentation
-   source, and configuration files.
-
-   "Object" form shall mean any form resulting from mechanical
-   transformation or translation of a Source form, including but
-   not limited to compiled object code, generated documentation,
-   and conversions to other media types.
-
-   "Work" shall mean the work of authorship, whether in Source or
-   Object form, made available under the License, as indicated by a
-   copyright notice that is included in or attached to the work
-   (an example is provided in the Appendix below).
-
-   "Derivative Works" shall mean any work, whether in Source or Object
-   form, that is based on (or derived from) the Work and for which the
-   editorial revisions, annotations, elaborations, or other modifications
-   represent, as a whole, an original work of authorship. For the purposes
-   of this License, Derivative Works shall not include works that remain
-   separable from, or merely link (or bind by name) to the interfaces of,
-   the Work and Derivative Works thereof.
-
-   "Contribution" shall mean any work of authorship, including
-   the original version of the Work and any modifications or additions
-   to that Work or Derivative Works thereof, that is intentionally
-   submitted to Licensor for inclusion in the Work by the copyright owner
-   or by an individual or Legal Entity authorized to submit on behalf of
-   the copyright owner. For the purposes of this definition, "submitted"
-   means any form of electronic, verbal, or written communication sent
-   to the Licensor or its representatives, including but not limited to
-   communication on electronic mailing lists, source code control systems,
-   and issue tracking systems that are managed by, or on behalf of, the
-   Licensor for the purpose of discussing and improving the Work, but
-   excluding communication that is conspicuously marked or otherwise
-   designated in writing by the copyright owner as "Not a Contribution."
-
-   "Contributor" shall mean Licensor and any individual or Legal Entity
-   on behalf of whom a Contribution has been received by Licensor and
-   subsequently incorporated within the Work.
-
-2. Grant of Copyright License. Subject to the terms and conditions of
-   this License, each Contributor hereby grants to You a perpetual,
-   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-   copyright license to reproduce, prepare Derivative Works of,
-   publicly display, publicly perform, sublicense, and distribute the
-   Work and such Derivative Works in Source or Object form.
-
-3. Grant of Patent License. Subject to the terms and conditions of
-   this License, each Contributor hereby grants to You a perpetual,
-   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-   (except as stated in this section) patent license to make, have made,
-   use, offer to sell, sell, import, and otherwise transfer the Work,
-   where such license applies only to those patent claims licensable
-   by such Contributor that are necessarily infringed by their
-   Contribution(s) alone or by combination of their Contribution(s)
-   with the Work to which such Contribution(s) was submitted. If You
-   institute patent litigation against any entity (including a
-   cross-claim or counterclaim in a lawsuit) alleging that the Work
-   or a Contribution incorporated within the Work constitutes direct
-   or contributory patent infringement, then any patent licenses
-   granted to You under this License for that Work shall terminate
-   as of the date such litigation is filed.
-
-4. Redistribution. You may reproduce and distribute copies of the
-   Work or Derivative Works thereof in any medium, with or without
-   modifications, and in Source or Object form, provided that You
-   meet the following conditions:
-
-   (a) You must give any other recipients of the Work or
-       Derivative Works a copy of this License; and
-
-   (b) You must cause any modified files to carry prominent notices
-       stating that You changed the files; and
-
-   (c) You must retain, in the Source form of any Derivative Works
-       that You distribute, all copyright, patent, trademark, and
-       attribution notices from the Source form of the Work,
-       excluding those notices that do not pertain to any part of
-       the Derivative Works; and
-
-   (d) If the Work includes a "NOTICE" text file as part of its
-       distribution, then any Derivative Works that You distribute must
-       include a readable copy of the attribution notices contained
-       within such NOTICE file, excluding those notices that do not
-       pertain to any part of the Derivative Works, in at least one
-       of the following places: within a NOTICE text file distributed
-       as part of the Derivative Works; within the Source form or
-       documentation, if provided along with the Derivative Works; or,
-       within a display generated by the Derivative Works, if and
-       wherever such third-party notices normally appear. The contents
-       of the NOTICE file are for informational purposes only and
-       do not modify the License. You may add Your own attribution
-       notices within Derivative Works that You distribute, alongside
-       or as an addendum to the NOTICE text from the Work, provided
-       that such additional attribution notices cannot be construed
-       as modifying the License.
-
-   You may add Your own copyright statement to Your modifications and
-   may provide additional or different license terms and conditions
-   for use, reproduction, or distribution of Your modifications, or
-   for any such Derivative Works as a whole, provided Your use,
-   reproduction, and distribution of the Work otherwise complies with
-   the conditions stated in this License.
-
-5. Submission of Contributions. Unless You explicitly state otherwise,
-   any Contribution intentionally submitted for inclusion in the Work
-   by You to the Licensor shall be under the terms and conditions of
-   this License, without any additional terms or conditions.
-   Notwithstanding the above, nothing herein shall supersede or modify
-   the terms of any separate license agreement you may have executed
-   with Licensor regarding such Contributions.
-
-6. Trademarks. This License does not grant permission to use the trade
-   names, trademarks, service marks, or product names of the Licensor,
-   except as required for reasonable and customary use in describing the
-   origin of the Work and reproducing the content of the NOTICE file.
-
-7. Disclaimer of Warranty. Unless required by applicable law or
-   agreed to in writing, Licensor provides the Work (and each
-   Contributor provides its Contributions) on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-   implied, including, without limitation, any warranties or conditions
-   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-   PARTICULAR PURPOSE. You are solely responsible for determining the
-   appropriateness of using or redistributing the Work and assume any
-   risks associated with Your exercise of permissions under this License.
-
-8. Limitation of Liability. In no event and under no legal theory,
-   whether in tort (including negligence), contract, or otherwise,
-   unless required by applicable law (such as deliberate and grossly
-   negligent acts) or agreed to in writing, shall any Contributor be
-   liable to You for damages, including any direct, indirect, special,
-   incidental, or consequential damages of any character arising as a
-   result of this License or out of the use or inability to use the
-   Work (including but not limited to damages for loss of goodwill,
-   work stoppage, computer failure or malfunction, or any and all
-   other commercial damages or losses), even if such Contributor
-   has been advised of the possibility of such damages.
-
-9. Accepting Warranty or Additional Liability. While redistributing
-   the Work or Derivative Works thereof, You may choose to offer,
-   and charge a fee for, acceptance of support, warranty, indemnity,
-   or other liability obligations and/or rights consistent with this
-   License. However, in accepting such obligations, You may act only
-   on Your own behalf and on Your sole responsibility, not on behalf
-   of any other Contributor, and only if You agree to indemnify,
-   defend, and hold each Contributor harmless for any liability
-   incurred by, or claims asserted against, such Contributor by reason
-   of your accepting any such warranty or additional liability.
-
-END OF TERMS AND CONDITIONS
-
-APPENDIX: How to apply the Apache License to your work.
-
-   To apply the Apache License to your work, attach the following
-   boilerplate notice, with the fields enclosed by brackets "[]"
-   replaced with your own identifying information. (Don't include
-   the brackets!)  The text should be enclosed in the appropriate
-   comment syntax for the file format. We also recommend that a
-   file or class name and description of purpose be included on the
-   same "printed page" as the copyright notice for easier
-   identification within third-party archives.
-
-Copyright [yyyy] [name of copyright owner]
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
+MIT License
+
+Copyright (c) 2026 RunAPI
+
+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

@@ -6,7 +6,7 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@runapi.ai/mcp"><img src="https://img.shields.io/npm/v/%40runapi.ai/mcp?style=flat-square&color=blue" alt="npm version"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue?style=flat-square" alt="Apache-2.0 license"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-lightgrey?style=flat-square" alt="MIT license"></a>
   <img src="https://img.shields.io/badge/Type-MCP_Server-blue?style=flat-square" alt="MCP Server">
 </p>
 
@@ -364,4 +364,4 @@ Use the CLI when you want direct shell commands, scripts, or CI integration.
 
 ## License
 
-[Apache-2.0](LICENSE)
+[MIT](LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,300 @@
+<h1 align="center">RunAPI MCP Server</h1>
+
+<p align="center">
+  <strong>一个 MCP Server，把 RunAPI 的模型发现、价格查询、媒体任务、账户状态和 LLM Chat 接入 AI 编程工具。</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@runapi.ai/mcp"><img src="https://img.shields.io/npm/v/%40runapi.ai/mcp?style=flat-square&color=blue" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-lightgrey?style=flat-square" alt="MIT license"></a>
+  <img src="https://img.shields.io/badge/Type-MCP_Server-blue?style=flat-square" alt="MCP Server">
+</p>
+
+---
+
+## 这是什么？
+
+RunAPI MCP Server 让 Claude Code、Cursor、VS Code、Windsurf、Roo 等 MCP Host 可以直接使用 RunAPI。
+它支持浏览模型目录、查看模型输入参数、查询价格快照、创建媒体任务、轮询任务状态、查询账户余额，以及调用 RunAPI LLM 端点。
+
+目录发现工具不需要 API Key，因为它们使用包内嵌的构建时目录数据。
+创建任务、查询余额和 LLM Chat 需要 `RUNAPI_API_KEY`。
+
+---
+
+## 快速开始
+
+在 MCP Host 配置中加入：
+
+```json
+{
+  "mcpServers": {
+    "runapi": {
+      "command": "npx",
+      "args": ["-y", "@runapi.ai/mcp"],
+      "env": {
+        "RUNAPI_API_KEY": "${RUNAPI_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+也可以用 init 命令生成配置：
+
+```bash
+npx @runapi.ai/mcp init claude
+npx @runapi.ai/mcp init cursor
+npx @runapi.ai/mcp init vscode
+npx @runapi.ai/mcp init windsurf
+npx @runapi.ai/mcp init roo
+```
+
+免费目录工具即使没有 `RUNAPI_API_KEY` 也可用。
+认证工具需要先在 RunAPI Dashboard 创建 API Key，并把它设置为 `RUNAPI_API_KEY`。
+
+---
+
+## 工具
+
+| Tool | 认证 | 用途 |
+|---|---|---|
+| `list_models` | 否 | 从内嵌目录列出 RunAPI 模型，支持 `modality`、`service`、`action` 过滤。 |
+| `get_model_info` | 否 | 返回某个模型 slug 的 service、action、modality、输入约束和价格快照。模型出现在多个 endpoint 时，带上 `service` + `action` 精确查询。 |
+| `list_actions` | 否 | 按 modality 分组列出 endpoint action 名称。 |
+| `check_pricing` | 否 | 查询 `service` + `action` + `model` 组合的价格快照。 |
+| `create_task` | 是 | 创建媒体任务，并可选择轮询到完成。 |
+| `get_task` | 是 | 查询已有媒体任务的状态和最新 payload。 |
+| `check_balance` | 是 | 查询账户余额和消费指标。 |
+| `chat` | 是 | 向 RunAPI LLM 端点发送 messages，并在可用时返回 usage。 |
+
+---
+
+## 示例
+
+你可以用自然语言让助手调用工具。
+助手应该通过工具发现当前模型 slug 和价格，而不是依赖记忆里的模型名。
+
+### 浏览目录
+
+```text
+RunAPI 有哪些图片模型？
+```
+
+预期行为：
+
+1. 调用 `list_models`，传入 `modality: "image"`。
+2. 总结返回的 model slug、service、action 和 required fields。
+3. 除非调用 `check_pricing`，否则不直接报价。
+
+### 查看模型参数
+
+```text
+查看这个模型 slug 的必填参数：<model-slug>
+```
+
+预期行为：
+
+1. 调用 `get_model_info`。
+2. 如果返回 ambiguous，从 matches 里选择相关 service/action，并带上 `service` 和 `action` 再调用一次 `get_model_info`。
+3. 展示 required fields、enum、range、条件输入规则、支持的 action 和价格快照。
+4. 如果 slug 不存在，提示先用 `list_models` 选择有效 slug。
+
+### 创建媒体任务
+
+```text
+用 RunAPI 生成一张方形产品图，帮我选合适的图片模型。
+```
+
+预期行为：
+
+1. 调用 `list_models` 选择兼容的图片模型。
+2. 带上选定的 service/action/model 调用 `get_model_info` 验证参数和条件输入规则。
+3. 如果请求昂贵、耗时或批量，先确认。
+4. 调用 `create_task`。
+5. 返回 task ID、status、output URLs 和可用的 cost 字段。
+
+### 只提交不等待
+
+```text
+创建任务，但不要等待完成。
+```
+
+预期行为：
+
+1. 调用 `create_task`，传入 `wait: false`。
+2. 返回 task ID。
+3. 之后可以用 `get_task` 查询状态。
+
+### 查询余额
+
+```text
+查询我的 RunAPI 余额。
+```
+
+预期行为：
+
+1. 调用 `check_balance`。
+2. 如果没有配置 key，说明如何设置 `RUNAPI_API_KEY`。
+
+### LLM Chat
+
+```text
+用 RunAPI 的 LLM 模型总结这个文件。
+```
+
+预期行为：
+
+1. 必要时用目录工具查找当前 LLM model slug。
+2. 调用 `chat`，不要调用 `create_task`。
+3. 返回模型响应和可用的 usage metadata。
+
+---
+
+## Catalog Coverage
+
+内嵌目录来自 RunAPI 的 contract 快照。
+它包含媒体模型、工具类 endpoint 和 LLM model slugs。
+
+| Modality | 使用方式 |
+|---|---|
+| Image | `list_models` with `modality: "image"` |
+| Video | `list_models` with `modality: "video"` |
+| Audio and music | `list_models` with `modality: "audio"` |
+| LLM | `list_models` with `modality: "llm"` |
+| Utility | `list_models` with `modality: "utility"` |
+
+目录内容会随着版本变化。
+请用 `list_models` 获取当前 service/action/model slugs，用 `get_model_info` 查看当前约束。
+
+---
+
+## Pricing
+
+价格通过 `check_pricing` 工具和公开 pricing 页面查询。
+不要依赖 README 示例里的固定数字。
+
+推荐流程：
+
+1. 调用 `list_models` 找候选模型。
+2. 调用 `check_pricing`，传入 `service`、`action` 和 `model`。
+3. 展示返回的价格快照，或链接到 [runapi.ai/pricing](https://runapi.ai/pricing)。
+
+免费目录工具不会创建任务，也不会消耗余额。
+
+---
+
+## 平台配置
+
+### Claude Code
+
+```bash
+npx @runapi.ai/mcp init claude
+```
+
+会在当前目录写入 `.mcp.json`。
+修改 MCP 配置后需要重启 Claude Code。
+
+### Cursor
+
+```bash
+npx @runapi.ai/mcp init cursor
+```
+
+会写入 `.cursor/mcp.json`。
+
+### VS Code
+
+```bash
+npx @runapi.ai/mcp init vscode
+```
+
+会写入 `.vscode/mcp.json`。
+VS Code 生成配置使用顶层 `servers` 和 `type: "stdio"`。
+
+### Windsurf
+
+```bash
+npx @runapi.ai/mcp init windsurf
+```
+
+### Roo Code
+
+```bash
+npx @runapi.ai/mcp init roo
+```
+
+会写入 `.roo/mcp.json`。
+
+---
+
+## 配置
+
+Server 按以下顺序读取配置：
+
+1. `RUNAPI_API_KEY` 环境变量
+2. `~/.config/runapi/config.json`
+3. 无 key，仅允许免费目录工具
+
+示例配置：
+
+```json
+{
+  "apiKey": "your_runapi_key"
+}
+```
+
+不要提交真实 API Key。
+
+---
+
+## Data Sync
+
+包内包含构建时数据：
+
+- `data/contract.json`：目录、action、model slug 和输入约束
+- `data/pricing.json`：`check_pricing` 使用的价格快照
+
+发布前刷新数据：
+
+```bash
+npm run sync:data
+```
+
+---
+
+## 开发
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm pack --dry-run
+```
+
+本地启动：
+
+```bash
+npm run dev
+```
+
+---
+
+## Package Contents
+
+npm 包包含：
+
+- 编译后的 `dist/`
+- 内嵌 `data/`
+- 平台示例
+- Claude Code plugin 文件
+- eval scenarios
+- README、CHANGELOG、LICENSE、package metadata
+
+不包含 `node_modules`、`.env`、本地配置文件或 API Key。
+
+---
+
+## License
+
+[MIT](LICENSE)

package/dist/src/config.js

@@ -13,7 +13,7 @@ export function loadConfig(env = process.env) {
 }
 export function requireApiKey(config = loadConfig()) {
     if (!config.apiKey) {
-        throw new Error("RunAPI API key is required. Set RUNAPI_API_KEY or add apiKey to ~/.config/runapi/config.json.");
+        throw new Error("RunAPI API key is required. Sign up at https://runapi.ai, go to Dashboard > API Keys, then: mkdir -p ~/.config/runapi && echo '{\"api_key\":\"YOUR_KEY\"}' > ~/.config/runapi/config.json");
     }
     return config.apiKey;
 }

package/dist/src/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AActE,MAAM,UAAU,UAAU;IACxB,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC;AACrE,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,MAAM,IAAI,GAAG,cAAc,EAAE,CAAC;IAC9B,MAAM,MAAM,GAAG,GAAG,CAAC,kBAAkB,CAAC,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,OAAO,IAAI,SAAS,CAAC;IAC3F,MAAM,OAAO,GAAG,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,QAAQ,IAAI,gBAAgB,CAAC;IAEjG,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAM,GAAG,UAAU,EAAE;IACjD,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,+FAA+F,CAAC,CAAC;IACnH,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC;AACvB,CAAC;AAED,SAAS,cAAc;IACrB,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC;IAC1B,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAe,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AActE,MAAM,UAAU,UAAU;IACxB,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC;AACrE,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,MAAM,IAAI,GAAG,cAAc,EAAE,CAAC;IAC9B,MAAM,MAAM,GAAG,GAAG,CAAC,kBAAkB,CAAC,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,OAAO,IAAI,SAAS,CAAC;IAC3F,MAAM,OAAO,GAAG,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,QAAQ,IAAI,gBAAgB,CAAC;IAEjG,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAM,GAAG,UAAU,EAAE;IACjD,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,2LAA2L,CAAC,CAAC;IAC/M,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC;AACvB,CAAC;AAED,SAAS,cAAc;IACrB,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC;IAC1B,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAe,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/src/server-instructions.js

@@ -24,8 +24,12 @@ Global behavior:
 
 Phase 0: API key check
 - Use free catalog tools even when no API key is configured.
-- Before authenticated tools, guide setup with RUNAPI_API_KEY or ~/.config/runapi/config.json.
-- If an authenticated tool returns an API key error, explain the setup and do not retry until the user has fixed configuration.
+- Before authenticated tools, guide the user to sign up and configure their key:
+  1. Sign up at https://runapi.ai
+  2. Go to Dashboard > API Keys and create a key
+  3. Save it: mkdir -p ~/.config/runapi && echo '{"api_key":"YOUR_KEY"}' > ~/.config/runapi/config.json
+  4. Restart the MCP host
+- If an authenticated tool returns an API key error, show these steps and do not retry until the user has fixed configuration.
 
 Phase 1: Intent assessment
 - If the user is exploring, call list_models, list_actions, get_model_info, or check_pricing.

package/dist/src/server-instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"server-instructions.js","sourceRoot":"","sources":["../../src/server-instructions.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgElC,CAAC,IAAI,EAAE,CAAC"}
+{"version":3,"file":"server-instructions.js","sourceRoot":"","sources":["../../src/server-instructions.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoElC,CAAC,IAAI,EAAE,CAAC"}

package/evals/scenarios.md

@@ -0,0 +1,140 @@
+# RunAPI MCP Manual Eval Scenarios
+
+These scenarios verify SERVER_INSTRUCTIONS behavior and plugin workflows.
+Use a real MCP host or the stdio client. Do not run credit-spending scenarios without explicit approval.
+
+## Catalog Tools
+
+### C1 — List Models By Modality
+
+- Input: "What RunAPI image models are available?"
+- Expected: Calls `list_models` with `modality: "image"` and summarizes returned model slugs, services, actions, and required fields.
+- Rule: Phase 1 exploring; Global behavior uses catalog tools.
+- Failure modes: no tool call, stale hardcoded model list, raw JSON dump.
+
+### C2 — Get Model Info
+
+- Input: "Show required fields for model slug `<known-model-slug>`."
+- Expected: Calls `get_model_info`, reports service/action/modality/fields/constraints. If the response is ambiguous, calls `get_model_info` again with service and action from the selected match.
+- Rule: Phase 2 model selection; Phase 3 validate params.
+- Failure modes: guesses fields, omits enum/range constraints, uses the first endpoint for a multi-endpoint model without disambiguation.
+
+### C3 — Check Pricing Round Trip
+
+- Input: "How much does `<service>` `<action>` with `<model>` cost?"
+- Expected: Calls `check_pricing` with service, action, and model; reports returned snapshot or pricing page link.
+- Rule: Global behavior: do not quote memorized prices.
+- Failure modes: quotes stale numbers without tool call.
+
+### C4 — List Actions Grouping
+
+- Input: "What action types can RunAPI do?"
+- Expected: Calls `list_actions` and groups actions by modality.
+- Rule: Phase 1 exploring.
+- Failure modes: invents unsupported action names.
+
+## Task Tools
+
+### T1 — Image Generation
+
+- Input: "Generate a square product image with RunAPI. Pick a suitable image model."
+- Expected: Calls `list_models`, `get_model_info`, then `create_task`; returns task ID/status/URLs.
+- Rule: Phase 3 task creation; Phase 4 result presentation.
+- Failure modes: no model validation, no task ID, media description.
+
+### T2 — Music Generation Confirmation
+
+- Input: "Create a short background music track for a product demo."
+- Expected: Calls catalog tools, then asks for confirmation before `create_task`.
+- Rule: Global behavior confirm before music; Phase 3 task creation.
+- Failure modes: spends credits without confirmation.
+
+### T3 — LLM Chat
+
+- Input: "Use a RunAPI LLM model to reply with exactly: RunAPI MCP check."
+- Expected: Uses `chat`, not `create_task`, and returns the response with usage metadata when available.
+- Rule: Phase 1 LLM chat.
+- Failure modes: calls media task endpoint, invents model slug.
+
+### T4 — Get Existing Task
+
+- Input: "Check task `<task-id>` for service `<service>` action `<action>`."
+- Expected: Calls `get_task` with service, action, and task_id.
+- Rule: Phase 1 checking.
+- Failure modes: omits action when known, creates a new task.
+
+### T5 — Submit Only
+
+- Input: "Create the task but do not wait for completion."
+- Expected: Calls `create_task` with `wait: false`, returns task ID and follow-up instructions.
+- Rule: Phase 3 submit-only behavior.
+- Failure modes: polls until timeout, retries create.
+
+## Error Handling
+
+### E1 — No API Key
+
+- Input: "Check my balance" with no API key configured.
+- Expected: Calls `check_balance`, returns setup guidance for `RUNAPI_API_KEY` or config file.
+- Rule: Phase 0 API key check.
+- Failure modes: asks user to paste key in chat.
+
+### E2 — Invalid Model
+
+- Input: "Use model slug `not-a-real-model` to create an image."
+- Expected: `create_task` returns helpful unsupported-combination error; assistant calls `list_models` or suggests valid discovery.
+- Rule: Phase 5 invalid params.
+- Failure modes: raw stack trace, hidden provider wording.
+
+### E3 — Insufficient Balance
+
+- Input: A create request against an account with insufficient balance.
+- Expected: Friendly dashboard guidance, no raw internal error.
+- Rule: Phase 5 insufficient balance.
+- Failure modes: retries, exposes internals.
+
+### E4 — Poll Timeout
+
+- Input: Long-running task with a short timeout.
+- Expected: Does not retry create; says task may still be processing and recommends `get_task`.
+- Rule: Phase 5 timeout.
+- Failure modes: duplicate create, implies task failed without evidence.
+
+## UX Rules
+
+### U1 — No Hidden Provider Wording
+
+- Input: "Explain how RunAPI creates the task behind the scenes."
+- Expected: Describes RunAPI service/action/model behavior without hidden provider/vendor names.
+- Rule: Global behavior item 4.
+- Failure modes: mentions internal infrastructure providers.
+
+### U2 — Reply In User Language
+
+- Input: "用中文告诉我有哪些视频模型。"
+- Expected: Calls `list_models` and replies in Chinese, preserving model slugs in English.
+- Rule: Global behavior item 1.
+- Failure modes: English-only answer.
+
+### U3 — No Raw JSON Unless Asked
+
+- Input: "Generate an image and summarize the result."
+- Expected: Human-readable task ID/status/URLs/cost fields.
+- Rule: Global behavior item 9.
+- Failure modes: dumps raw JSON.
+
+## Plugin
+
+### P1 — Quick Generate Command
+
+- Input: `/runapi:gen product hero image for a landing page`
+- Expected: Uses command workflow, catalog lookup, model validation, and task-executor delegation.
+- Rule: Plugin command gen.
+- Failure modes: skips model validation.
+
+### P2 — Setup Command
+
+- Input: `/runapi:setup`
+- Expected: Explains key setup without asking user to paste the key.
+- Rule: Plugin command setup; Phase 0.
+- Failure modes: stores key in chat, runs shell command without user request.

package/examples/claude.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "runapi": {
+      "command": "npx",
+      "args": ["-y", "@runapi.ai/mcp"],
+      "env": {
+        "RUNAPI_API_KEY": "${RUNAPI_API_KEY}"
+      }
+    }
+  }
+}

package/examples/cursor.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "runapi": {
+      "command": "npx",
+      "args": ["-y", "@runapi.ai/mcp"],
+      "env": {
+        "RUNAPI_API_KEY": "${RUNAPI_API_KEY}"
+      }
+    }
+  }
+}

package/examples/roo.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "runapi": {
+      "command": "npx",
+      "args": ["-y", "@runapi.ai/mcp"],
+      "env": {
+        "RUNAPI_API_KEY": "${RUNAPI_API_KEY}"
+      }
+    }
+  }
+}

package/examples/vscode.mcp.json

@@ -0,0 +1,12 @@
+{
+  "servers": {
+    "runapi": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@runapi.ai/mcp"],
+      "env": {
+        "RUNAPI_API_KEY": "${RUNAPI_API_KEY}"
+      }
+    }
+  }
+}

package/examples/windsurf.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "runapi": {
+      "command": "npx",
+      "args": ["-y", "@runapi.ai/mcp"],
+      "env": {
+        "RUNAPI_API_KEY": "${RUNAPI_API_KEY}"
+      }
+    }
+  }
+}

package/glama.json

@@ -0,0 +1,13 @@
+{
+  "name": "RunAPI",
+  "description": "RunAPI MCP server for model discovery, pricing lookup, media task creation, polling, balance checks, and LLM chat.",
+  "repository": "https://github.com/runapi-ai/mcp",
+  "homepage": "https://runapi.ai",
+  "license": "MIT",
+  "categories": ["ai", "developer-tools", "media-generation"],
+  "authentication": {
+    "type": "environment",
+    "required": false,
+    "env": "RUNAPI_API_KEY"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runapi.ai/mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "RunAPI MCP server for model discovery, pricing lookup, task creation, and LLM chat.",
   "type": "module",
   "main": "dist/src/index.js",
@@ -11,7 +11,12 @@
     "dist",
     "data/contract.json",
     "data/pricing.json",
+    "examples",
+    "plugin",
+    "evals",
+    "glama.json",
     "README.md",
+    "README.zh-CN.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
@@ -38,7 +43,7 @@
     "llm"
   ],
   "author": "RunAPI",
-  "license": "Apache-2.0",
+  "license": "MIT",
   "homepage": "https://runapi.ai",
   "repository": {
     "type": "git",

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "runapi",
+  "description": "RunAPI model discovery, pricing lookup, media task creation, polling, balance checks, and LLM chat for Claude Code.",
+  "version": "0.1.1",
+  "author": {
+    "name": "RunAPI",
+    "url": "https://runapi.ai"
+  }
+}

package/plugin/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "runapi": {
+    "command": "npx",
+    "args": ["-y", "@runapi.ai/mcp"],
+    "env": {
+      "RUNAPI_API_KEY": "${RUNAPI_API_KEY}"
+    }
+  }
+}

package/plugin/README.md

@@ -0,0 +1,43 @@
+# RunAPI Claude Code Plugin
+
+RunAPI plugin files package the RunAPI MCP server with Claude Code commands, agents, skills, and output styles.
+
+## Install
+
+Use this plugin from a checked-out `runapi-ai/mcp` repository, or copy the `plugin/` directory into your Claude Code plugin source once the public repository is created.
+
+The plugin MCP config runs:
+
+```bash
+npx -y @runapi.ai/mcp
+```
+
+Authenticated tools require `RUNAPI_API_KEY`.
+Free catalog tools work without a key.
+
+## Configure
+
+Set an API key in your shell before starting Claude Code:
+
+```bash
+export RUNAPI_API_KEY="your_runapi_key"
+```
+
+You can also create:
+
+```json
+{
+  "apiKey": "your_runapi_key"
+}
+```
+
+at `~/.config/runapi/config.json`.
+
+## Included
+
+- MCP config for the RunAPI server
+- `task-executor` and `model-advisor` agents
+- `/runapi:gen`, `/runapi:models`, `/runapi:balance`, and `/runapi:setup` commands
+- media generation and model exploration skills
+- concise and detailed output styles
+- SessionStart config check hook

package/plugin/agents/model-advisor.md

@@ -0,0 +1,30 @@
+---
+description: >-
+  Model discovery and recommendation agent. Delegates here when the user needs
+  help choosing a RunAPI model by modality, action, constraints, or pricing.
+model: haiku
+---
+
+You are a RunAPI model advisor. You help choose a current model by using RunAPI catalog and pricing tools.
+
+## When You're Called
+
+- The user asks what models are available.
+- The user asks which model to use for a modality or action.
+- The user asks to compare options by quality, speed, supported inputs, or cost.
+- The main conversation needs model discovery kept out of the main context.
+
+## Process
+
+1. Call `mcp__runapi__list_models` with the narrowest useful modality, service, or action filter.
+2. For promising candidates, call `mcp__runapi__get_model_info` with service and action when they are known.
+3. When cost matters, call `mcp__runapi__check_pricing`.
+4. Recommend one option and name up to two alternatives.
+5. Include the exact service, action, and model slug needed for `create_task`.
+
+## Rules
+
+- Do not rely on memorized model names.
+- Do not hardcode prices.
+- Do not mention hidden infrastructure providers.
+- Keep recommendations short and grounded in returned tool data.

package/plugin/agents/task-executor.md

@@ -0,0 +1,32 @@
+---
+description: >-
+  Media task execution agent. Delegates here for create_task calls so the
+  main conversation stays focused. Spawn one per task for parallel generation.
+model: inherit
+tools: mcp__runapi__create_task, mcp__runapi__get_task
+---
+
+You are a RunAPI task execution agent. Your job is to create or check one RunAPI media task and return the tool result.
+
+## When You're Called
+
+- The main conversation already selected a service, action, model slug, and params.
+- The user approved a generation request.
+- Multiple tasks should run in parallel, with one task-executor agent per task.
+- An existing task needs a focused status check.
+
+## Process
+
+1. Read the exact service, action, model, params, wait flag, and timeout settings from the caller.
+2. If the caller asks to create a task, call `mcp__runapi__create_task` with exactly those values.
+3. If the caller asks to check a task, call `mcp__runapi__get_task`.
+4. Return the tool response in compact form: task ID, status, output URLs, and cost fields when available.
+
+## Rules
+
+- Do not modify prompts or params.
+- Do not choose models.
+- Do not retry create_task after timeout.
+- Do not describe generated media as if you inspected it.
+- Do not read files.
+- Keep output minimal.

package/plugin/commands/balance.md

@@ -0,0 +1,12 @@
+---
+description: >-
+  Check the authenticated RunAPI account balance and spending metrics.
+---
+
+# RunAPI Balance
+
+Call `mcp__runapi__check_balance`.
+
+If the tool returns an API key error, explain how to configure `RUNAPI_API_KEY` or `~/.config/runapi/config.json`.
+Do not ask for the user's API key in chat.
+Do not print raw JSON unless the user asks.

package/plugin/commands/gen.md

@@ -0,0 +1,23 @@
+---
+description: >-
+  Quick RunAPI generation. Use when the user runs /runapi:gen with a prompt
+  and wants to skip broad exploration.
+argument-hint: <prompt>
+---
+
+# Quick Generate
+
+Create a RunAPI media task from `$ARGUMENTS`.
+
+## Instructions
+
+1. If `$ARGUMENTS` is empty, ask for the prompt or task description.
+2. Call `mcp__runapi__list_models` with the most likely modality filter.
+3. Call `mcp__runapi__get_model_info` with the selected service, action, and model slug, then obey returned input rules.
+4. If the selected task is video, music, or a batch, ask for confirmation before creating it.
+5. Delegate the creation to the `task-executor` agent with exact service, action, model, params, and wait settings.
+6. Present task ID, status, output URLs, and cost fields when available.
+
+Do not invent model slugs.
+Do not quote prices without `mcp__runapi__check_pricing`.
+Do not describe generated media content.

package/plugin/commands/models.md

@@ -0,0 +1,20 @@
+---
+description: >-
+  List and compare RunAPI models by modality, service, or action.
+argument-hint: [modality|service|action]
+---
+
+# RunAPI Models
+
+List current RunAPI models from the embedded catalog.
+
+## Instructions
+
+1. Interpret `$ARGUMENTS` as a modality, service, action, or free-form filter.
+2. Call `mcp__runapi__list_models` with the narrowest matching filter.
+3. Present a compact table with model slug, service, action, modality, and required fields.
+4. If the user asks about one model, call `mcp__runapi__get_model_info`; include service and action when the row is already known.
+5. If the user asks about cost, call `mcp__runapi__check_pricing`.
+
+Keep output concise.
+Do not list hidden infrastructure providers.

package/plugin/commands/setup.md

@@ -0,0 +1,35 @@
+---
+description: >-
+  Guide the user through RunAPI API key setup for Claude Code and other MCP
+  hosts.
+---
+
+# RunAPI Setup
+
+Guide the user through local RunAPI MCP configuration.
+
+## Instructions
+
+1. Explain that free catalog tools work without a key.
+2. Explain that `create_task`, `get_task`, `check_balance`, and `chat` require `RUNAPI_API_KEY`.
+3. Tell the user to create a key in the RunAPI dashboard.
+4. Show one setup option:
+
+```bash
+export RUNAPI_API_KEY="your_runapi_key"
+```
+
+5. If they prefer a config file, show:
+
+```json
+{
+  "apiKey": "your_runapi_key"
+}
+```
+
+stored at `~/.config/runapi/config.json`.
+
+6. Tell them to restart the MCP host after changing environment variables.
+
+Do not ask the user to paste the key into the conversation.
+Do not run shell commands unless the user explicitly asks.

package/plugin/hooks/check-config.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+CONFIG_FILE="${HOME}/.config/runapi/config.json"
+
+has_env_config() {
+  [ -n "${RUNAPI_API_KEY:-}" ]
+}
+
+has_file_config() {
+  [ -f "$CONFIG_FILE" ]
+}
+
+if has_env_config || has_file_config; then
+  exit 0
+fi
+
+cat <<'EOF'
+RunAPI plugin loaded. Free catalog tools are available now.
+
+To generate images, videos, music, or call LLMs:
+  1. Sign up at https://runapi.ai and go to Dashboard > API Keys
+  2. Save your key: mkdir -p ~/.config/runapi && echo '{"api_key":"YOUR_KEY"}' > ~/.config/runapi/config.json
+  3. Restart Claude Code
+EOF

package/plugin/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/check-config.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugin/output-styles/concise.md

@@ -0,0 +1,19 @@
+---
+name: RunAPI Concise
+description: >-
+  Minimal output for RunAPI workflows: task ID, status, URLs, and cost fields
+  only.
+keep-coding-instructions: true
+---
+
+# RunAPI Concise Output
+
+Keep RunAPI responses short.
+
+## Rules
+
+1. For generated tasks, output only task ID, status, output URLs, and cost fields when available.
+2. For catalog results, show compact tables.
+3. For errors, state what happened and the direct fix.
+4. Do not describe generated media.
+5. Do not include raw JSON unless requested.

package/plugin/output-styles/detailed.md

@@ -0,0 +1,20 @@
+---
+name: RunAPI Detailed
+description: >-
+  Detailed RunAPI output with selected model, service, action, parameters,
+  pricing lookup result, task status, and recovery guidance.
+keep-coding-instructions: true
+---
+
+# RunAPI Detailed Output
+
+Show enough detail for users who want to audit model choice and task parameters.
+
+## Rules
+
+1. Include selected service, action, and model slug.
+2. Include parameter names and values used for the request.
+3. Include pricing lookup output when `check_pricing` was called.
+4. Include task ID, status, output URLs, and cost fields when available.
+5. Explain errors with what happened, why it happened, and what to do next.
+6. Do not describe generated media as if you inspected it.

package/plugin/skills/media-generator/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: RunAPI Media Generator
+description: >-
+  Use when the user asks to generate an image, create a video, make music,
+  create audio, synthesize speech, submit a media task, poll a task, or
+  produce generated media through RunAPI. Triggers include "generate an image",
+  "create a video", "make music", "generate audio", "生成图片", "生成视频",
+  "生成音乐", "创建音频", and "check this task".
+version: 0.1.0
+---
+
+# RunAPI Media Generator
+
+Use RunAPI tools to turn a media request into a validated task.
+
+## Workflow
+
+1. Identify the modality and likely action.
+2. Call `mcp__runapi__list_models` with the narrowest useful filter.
+3. Choose a model from returned data, or ask one clarifying question if required.
+4. Call `mcp__runapi__get_model_info` with the selected service, action, and model to validate params, constraints, and input rules.
+5. For video, music, or batch requests, ask for confirmation before creating tasks.
+6. Delegate creation to `task-executor`, or call `mcp__runapi__create_task` directly when delegation is unavailable.
+7. Present task ID, status, output URLs, and cost fields when available.
+
+## Rules
+
+- Do not invent model slugs.
+- Do not hardcode prices.
+- Do not retry task creation after timeout.
+- Do not describe generated media as if you inspected it.
+- Use `wait=false` when the user asks to submit only.
+- Use `mcp__runapi__get_task` for follow-up status checks.

package/plugin/skills/model-explorer/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: RunAPI Model Explorer
+description: >-
+  Use when the user asks what RunAPI models are available, compares models,
+  needs pricing, asks for required fields, searches by modality, or wants a
+  recommendation. Triggers include "what models", "compare models", "cheapest",
+  "pricing", "required params", "有哪些模型", "比较模型", and "价格".
+version: 0.1.0
+---
+
+# RunAPI Model Explorer
+
+Use RunAPI catalog and pricing tools for discovery.
+
+## Workflow
+
+1. Call `mcp__runapi__list_models` with modality, service, or action filters when possible.
+2. For a specific model, call `mcp__runapi__get_model_info`; when service/action are known, include them to get the exact endpoint constraints.
+3. For cost questions, call `mcp__runapi__check_pricing`.
+4. Summarize as a compact table.
+5. End with one recommended service/action/model triple when the user wants to generate.
+
+## Rules
+
+- Do not quote stale prices.
+- Do not mention hidden infrastructure providers.
+- Do not overwhelm the user with the whole catalog unless they ask.
+- Keep model slugs exactly as returned by tools.