From c00d45c31ba494bea2d4eb7987542868ba22d94b Mon Sep 17 00:00:00 2001 From: yakimoto Date: Fri, 11 Sep 2026 13:03:53 -0400 Subject: [PATCH] feat: scaffold WAVE agent/Cursor plugin (INTENT wave-agent-plugin) Remote MCP https://api.wave.online/mcp with optional WAVE_API_KEY (person path only). Lean skills: wave-media, wave-transcribe, wave-captions, wave-render, wave-clips, wave-x402-call, wave-openapi. Listing copy per Scout Keep. --- .cursor-plugin/plugin.json | 20 +++ LICENSE | 222 +++----------------------------- README.md | 56 ++++++++ mcp.json | 15 +++ plugin.json | 20 +++ skills/wave-captions/SKILL.md | 13 ++ skills/wave-clips/SKILL.md | 13 ++ skills/wave-media/SKILL.md | 23 ++++ skills/wave-openapi/SKILL.md | 13 ++ skills/wave-render/SKILL.md | 14 ++ skills/wave-transcribe/SKILL.md | 13 ++ skills/wave-x402-call/SKILL.md | 21 +++ 12 files changed, 242 insertions(+), 201 deletions(-) create mode 100644 .cursor-plugin/plugin.json create mode 100644 README.md create mode 100644 mcp.json create mode 100644 plugin.json create mode 100644 skills/wave-captions/SKILL.md create mode 100644 skills/wave-clips/SKILL.md create mode 100644 skills/wave-media/SKILL.md create mode 100644 skills/wave-openapi/SKILL.md create mode 100644 skills/wave-render/SKILL.md create mode 100644 skills/wave-transcribe/SKILL.md create mode 100644 skills/wave-x402-call/SKILL.md diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json new file mode 100644 index 0000000..d7a8214 --- /dev/null +++ b/.cursor-plugin/plugin.json @@ -0,0 +1,20 @@ +{ + "name": "wave", + "displayName": "WAVE", + "version": "0.1.0", + "description": "Media MCP for agents: captions, clips, render, live — pay with key or x402.", + "publisher": "wave-av", + "repository": "https://github.com/wave-av/wave-cursor-plugin", + "license": "MIT", + "keywords": ["mcp", "media", "x402", "captions", "render", "transcribe", "clips"], + "skills": [ + "skills/wave-media", + "skills/wave-transcribe", + "skills/wave-captions", + "skills/wave-render", + "skills/wave-clips", + "skills/wave-x402-call", + "skills/wave-openapi" + ], + "mcp": "mcp.json" +} diff --git a/LICENSE b/LICENSE index 261eeb9..208736e 100644 --- a/LICENSE +++ b/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 WAVE / wave-av + +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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..24de6a8 --- /dev/null +++ b/README.md @@ -0,0 +1,56 @@ +# WAVE Cursor / Agent Plugin + +**Media MCP for agents: captions, clips, render, live — pay with key or x402.** + +Also: *96 media tools. One remote MCP. Dual-402 (API key or Base USDC).* + +Surface: `wave-agent-plugin` (INTENT). Plugin packaging is unmetered; tool calls re-enter the WAVE gateway meters (`wave_transcription_minutes`, `wave_render_minutes`, `wave_caption_minutes`, …). + +## Connect + +Remote MCP (authority projection of the API): + +- `https://api.wave.online/mcp` +- Discovery: `https://wave.online/.well-known/mcp.json` +- OpenAPI authority: `https://api.wave.online/openapi.json` + +## Dual auth + +| Path | Who | How | +|------|-----|-----| +| **Agent / x402** | autonomous agents | Call with **no** API key → HTTP **402** challenge → settle Base USDC → retry. No WAVE account. | +| **Person / Bearer** | humans / orgs | Optional `WAVE_API_KEY` → `Authorization: Bearer …`. Cost-heavy routes may require a card (`SPEND_CAP_TIER_BLOCKED`). | + +`WAVE_API_KEY` is **optional** and must **not** be required to install or connect. Never commit keys. + +## Skills (lean matrix) + +| Skill | Tools / endpoints | Meters | +|-------|-------------------|--------| +| `wave-media` | `facilitator_status`, discovery | [] | +| `wave-transcribe` | `wave_*` transcribe / `POST /v1/transcribe` | `wave_transcription_minutes` | +| `wave-captions` | `wave_*` captions | `wave_caption_minutes` | +| `wave-render` | `wave_render_video` / poll | `wave_render_minutes` | +| `wave-clips` | `wave_*` clips | (gateway) | +| `wave-x402-call` | 402 settle/retry | per challenge | +| `wave-openapi` | points at OpenAPI JSON | n/a | + +Four-renderings law: **API is authority**; MCP/CLI/SDK are projections. Skills teach *when/how to call* — they are not a fifth semantic path. Do not invent transcripts, captions, receipts, or tools. + +## Layout + +``` +.cursor-plugin/plugin.json +plugin.json +mcp.json +skills/*/SKILL.md +README.md +``` + +## States + +`unconnected` → `connected-no-key` → (`connected-with-key` | `payment-required-402`) + +## License + +MIT diff --git a/mcp.json b/mcp.json new file mode 100644 index 0000000..5252fc3 --- /dev/null +++ b/mcp.json @@ -0,0 +1,15 @@ +{ + "mcpServers": { + "wave": { + "url": "https://api.wave.online/mcp", + "transport": "http" + } + }, + "variables": { + "WAVE_API_KEY": { + "description": "Optional person-path API key. When set, clients may send Authorization: Bearer . Not required for agent/x402 path.", + "required": false, + "secret": true + } + } +} diff --git a/plugin.json b/plugin.json new file mode 100644 index 0000000..9986007 --- /dev/null +++ b/plugin.json @@ -0,0 +1,20 @@ +{ + "name": "wave", + "displayName": "WAVE", + "version": "0.1.0", + "description": "Media MCP for agents: captions, clips, render, live — pay with key or x402.", + "publisher": "wave-av", + "repository": "https://github.com/wave-av/wave-cursor-plugin", + "license": "MIT", + "keywords": ["mcp", "media", "x402", "captions", "render", "transcribe", "clips"], + "skills": [ + "./skills/wave-media", + "./skills/wave-transcribe", + "./skills/wave-captions", + "./skills/wave-render", + "./skills/wave-clips", + "./skills/wave-x402-call", + "./skills/wave-openapi" + ], + "mcpServers": "mcp.json" +} diff --git a/skills/wave-captions/SKILL.md b/skills/wave-captions/SKILL.md new file mode 100644 index 0000000..da413f8 --- /dev/null +++ b/skills/wave-captions/SKILL.md @@ -0,0 +1,13 @@ +--- +name: wave-captions +description: use when creating or downloading WAVE captions / subtitles for media +meters: [wave_caption_minutes] +endpoints: + - /v1/captions +tools: [wave_create_caption_job, wave_get_caption_job, wave_download_captions, wave_list_captions] +--- +# wave-captions + +Caption/subtitle jobs via WAVE MCP or `/v1/captions*`. Meter: `wave_caption_minutes`. + +Return real job status / SRT|VTT downloads only — never fabricate subtitle text. diff --git a/skills/wave-clips/SKILL.md b/skills/wave-clips/SKILL.md new file mode 100644 index 0000000..cc32454 --- /dev/null +++ b/skills/wave-clips/SKILL.md @@ -0,0 +1,13 @@ +--- +name: wave-clips +description: use when creating, detecting, or managing WAVE clips / highlights +meters: [] +endpoints: + - /v1/clips +tools: [wave_create_clip, wave_get_clip, wave_list_clips, wave_detect_clips, wave_update_clip] +--- +# wave-clips + +Clips and highlight detection via `wave_*` clips tools / `/v1/clips*`. Meters re-enter gateway per PRODUCT-TRUTH. + +Auth: Bearer or x402. Never invent clip URLs or detection results. diff --git a/skills/wave-media/SKILL.md b/skills/wave-media/SKILL.md new file mode 100644 index 0000000..7aaeb35 --- /dev/null +++ b/skills/wave-media/SKILL.md @@ -0,0 +1,23 @@ +--- +name: wave-media +description: >- + use when discovering WAVE media MCP/API, checking facilitator_status, or + explaining dual-402 (key or x402) before a specific media call +meters: [] +endpoints: + - https://api.wave.online/mcp + - https://wave.online/.well-known/mcp.json + - https://api.wave.online/openapi.json +--- +# wave-media + +Discovery and health for WAVE media. Prefer this before specialized skills. + +## Do +1. Connect remote MCP `https://api.wave.online/mcp` (no API key required). +2. Call `facilitator_status` / discovery; confirm x402 rails live. +3. Route next: transcribe, captions, render, clips, or x402-call. + +## Do not +- Invent tools, meters, transcripts, or receipts. +- Require `WAVE_API_KEY` for agent path. diff --git a/skills/wave-openapi/SKILL.md b/skills/wave-openapi/SKILL.md new file mode 100644 index 0000000..8377a79 --- /dev/null +++ b/skills/wave-openapi/SKILL.md @@ -0,0 +1,13 @@ +--- +name: wave-openapi +description: >- + use when you need the WAVE HTTP API contract; OpenAPI is authority for paths + and schemas (MCP/CLI/SDK are projections) +endpoints: + - https://api.wave.online/openapi.json +--- +# wave-openapi + +OpenAPI authority: **https://api.wave.online/openapi.json** + +Four-renderings law: API is authority; MCP/CLI/SDK project it. Skills teach when/how to call — not a fifth semantic path. Prefer live OpenAPI over memorized shapes. diff --git a/skills/wave-render/SKILL.md b/skills/wave-render/SKILL.md new file mode 100644 index 0000000..d01863b --- /dev/null +++ b/skills/wave-render/SKILL.md @@ -0,0 +1,14 @@ +--- +name: wave-render +description: use when rendering programmatic video via WAVE (Brief templates, wave_render_video) +meters: [wave_render_minutes] +endpoints: + - POST /v1/render + - GET /v1/render/{jobId} +tools: [wave_render_video, wave_render_poll] +--- +# wave-render + +Programmatic render via `wave_render_video` / `wave_render_poll` (or OpenAPI `/v1/render`). Meter: `wave_render_minutes`. + +Auth: Bearer or x402. Do not invent render outputs or receipts. diff --git a/skills/wave-transcribe/SKILL.md b/skills/wave-transcribe/SKILL.md new file mode 100644 index 0000000..ade91ed --- /dev/null +++ b/skills/wave-transcribe/SKILL.md @@ -0,0 +1,13 @@ +--- +name: wave-transcribe +description: use when transcribing audio or video with WAVE (speech-to-text) +meters: [wave_transcription_minutes] +endpoints: + - POST /v1/transcribe +tools: [wave_create_transcription, wave_get_transcription, wave_list_transcriptions] +--- +# wave-transcribe + +Speech-to-text via WAVE MCP tools or `POST /v1/transcribe`. Meter: `wave_transcription_minutes` (gateway re-entry). + +Auth: optional Bearer **or** unpaid → 402 → x402 settle → retry (`wave-x402-call`). Never invent transcripts. diff --git a/skills/wave-x402-call/SKILL.md b/skills/wave-x402-call/SKILL.md new file mode 100644 index 0000000..d7a145e --- /dev/null +++ b/skills/wave-x402-call/SKILL.md @@ -0,0 +1,21 @@ +--- +name: wave-x402-call +description: >- + use when an agent must pay for a WAVE call via HTTP 402 / x402 (Base USDC) + without a WAVE API key +meters: [] +endpoints: + - https://api.wave.online/mcp + - https://wave.online/.well-known/x402 +tools: [facilitator_status, list_supported_protocols] +--- +# wave-x402-call + +Agent path (no key): + +1. Call capability (MCP or OpenAPI). +2. On **402**, treat challenge body as authoritative payment terms. +3. Settle x402 (Base USDC); retry with protocol credential header. +4. Report settle errors honestly — never invent a paid receipt. + +Do not confuse person-path `SPEND_CAP_TIER_BLOCKED` (needs card) with x402.