diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..bb76967 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,18 @@ +{ + "name": "hydracept", + "description": "Official Hydracept plugin marketplace for Claude Code.", + "owner": { + "name": "Zencode Consulting Inc.", + "email": "support@hydracept.com", + "url": "https://hydracept.com" + }, + "plugins": [ + { + "name": "hydracept", + "source": "./", + "description": "Image, audio, video, 3D, and text generation for coding agents through one remote MCP server (https://api.hydracept.com/mcp).", + "category": "integrations", + "tags": ["mcp", "image-generation", "audio", "video", "3d", "game-assets"] + } + ] +} diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..fbf845e --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,46 @@ +{ + "name": "hydracept", + "displayName": "Hydracept", + "version": "0.1.9", + "description": "Image, audio, video, 3D, and text generation for coding agents through one remote MCP server, with durable jobs, budgets, receipts, and BYOK.", + "author": { + "name": "Zencode Consulting Inc.", + "email": "support@hydracept.com", + "url": "https://hydracept.com" + }, + "homepage": "https://hydracept.com/plugin", + "repository": "https://github.com/zencodeinc/hydracept-plugin", + "license": "MIT", + "keywords": [ + "hydracept", + "mcp", + "image-generation", + "audio-generation", + "video-generation", + "3d-generation", + "text-generation", + "game-assets", + "sprite-sheet", + "durable-jobs", + "receipts", + "byok" + ], + "userConfig": { + "api_key": { + "type": "string", + "title": "Hydracept API key", + "description": "Workspace API key from https://hydracept.com/start. Stored in your OS credential store, never in settings.json.", + "required": true, + "sensitive": true + } + }, + "mcpServers": { + "hydracept": { + "type": "http", + "url": "https://api.hydracept.com/mcp", + "headers": { + "Authorization": "Bearer ${user_config.api_key}" + } + } + } +} diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json index 94404ba..0ec2666 100644 --- a/.cursor-plugin/marketplace.json +++ b/.cursor-plugin/marketplace.json @@ -5,13 +5,13 @@ "email": "support@hydracept.com" }, "metadata": { - "description": "Official Hydracept Cursor plugin (skills, rules, commands, stdio MCP wiring)." + "description": "Official Hydracept Cursor plugin (skills, rules, commands, stdio MCP)." }, "plugins": [ { "name": "hydracept", "source": ".", - "description": "One execution surface for text/reasoning, media, domains, DNS, and other external capabilities, with durable jobs, budgets, receipts, and BYOK." + "description": "Give coding agents image, audio, video, 3D, and text generation (plus domains/DNS and other external capabilities) through one Hydracept MCP interface, with durable jobs, budgets, receipts, and BYOK." } ] } diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index c8a3d76..d3a10d5 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,8 +1,8 @@ { "name": "hydracept", "displayName": "Hydracept", - "version": "0.1.8", - "description": "One execution surface for text/reasoning, media, domains, DNS, and other external capabilities, with durable jobs, budgets, receipts, and BYOK.", + "version": "0.1.9", + "description": "Give coding agents image, audio, video, 3D, and text generation (plus domains/DNS and other external capabilities) through one Hydracept MCP interface, with durable jobs, budgets, receipts, and BYOK.", "author": { "name": "Zencode Consulting Inc.", "email": "support@hydracept.com" @@ -13,25 +13,21 @@ "keywords": [ "hydracept", "mcp", - "execution-control-plane", "agent-tools", + "image-generation", + "audio-generation", + "video-generation", + "3d-generation", + "text-generation", + "transparent-png", + "sprite-sheet", "durable-jobs", "receipts", - "multi-provider", + "budgets", "byok", - "text-generation", - "image-generation", + "multi-provider", "domains", - "dns", - "game-assets", - "cursor", - "claude-code", - "unity", - "gamedev", - "sprite-sheet", - "transparent-png", - "reference-image", - "game-ai" + "dns" ], "logo": "assets/logo.png", "publisher": "Zencode Consulting Inc.", @@ -39,25 +35,21 @@ "tags": [ "hydracept", "mcp", - "execution-control-plane", "agent-tools", + "image-generation", + "audio-generation", + "video-generation", + "3d-generation", + "text-generation", + "transparent-png", + "sprite-sheet", "durable-jobs", "receipts", - "multi-provider", + "budgets", "byok", - "text-generation", - "image-generation", + "multi-provider", "domains", - "dns", - "game-assets", - "cursor", - "claude-code", - "unity", - "gamedev", - "sprite-sheet", - "transparent-png", - "reference-image", - "game-ai" + "dns" ], "mcpServers": "./mcp.json" } diff --git a/.github/workflows/validate-manifests.yml b/.github/workflows/validate-manifests.yml new file mode 100644 index 0000000..fbc0efa --- /dev/null +++ b/.github/workflows/validate-manifests.yml @@ -0,0 +1,49 @@ +name: Validate manifests + +on: + pull_request: + push: + branches: + - main + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-node@v4 + with: + node-version: "22" + + - name: Install validators + run: | + npm install -g @anthropic-ai/claude-code @google/gemini-cli + + - name: Parse JSON manifests + run: | + python3 - <<'PY' + import json + from pathlib import Path + + paths = [ + ".cursor-plugin/plugin.json", + ".cursor-plugin/marketplace.json", + ".claude-plugin/plugin.json", + ".claude-plugin/marketplace.json", + "gemini-extension.json", + "mcp.json", + "mcp-registry/server.json", + ] + for p in paths: + json.loads(Path(p).read_text()) + print(f"OK {p}") + PY + + - name: Claude Code plugin validate + run: | + claude plugin validate --strict . + claude plugin validate --strict .claude-plugin/plugin.json + + - name: Gemini CLI extension validate + run: gemini extensions validate . diff --git a/CHANGELOG.md b/CHANGELOG.md index 8c0ee50..f97dcf6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,12 +2,21 @@ ## Unreleased -- Add `mcp-registry/server.json` for the official MCP Registry (`com.hydracept/hydracept`, PyPI stdio + hosted remote) -- Add `.cursor-plugin/marketplace.json`; point `plugin.json` repository at this repo -- README: canonical repo note, install/auth, and registry publishing guidance +## 0.1.9 + +- Claude Code plugin (`.claude-plugin/`) with hosted MCP `https://api.hydracept.com/mcp` and API key via plugin configure +- Gemini CLI extension (`gemini-extension.json`) +- README install sections for Claude Code, Claude Desktop, Google Antigravity, and Gemini CLI +- CI: validate Claude Code and Gemini CLI manifests on pull requests ## 0.1.8 +- Marketplace listing polish: clearer description and keywords (image/audio/video/3D/text), drop game-only tags +- README: what's included, install, auth, example prompts, pricing, support +- `hydracept-image` skill: general-purpose image wording +- Add `mcp-registry/server.json` for the official MCP Registry (`com.hydracept/hydracept`, PyPI stdio + hosted remote) +- Add `.cursor-plugin/marketplace.json`; point `plugin.json` repository at this repo +- README: canonical repo note, install/auth, and registry publishing guidance - Stdio MCP (`python -m hydracept mcp serve`) using CLI workspace secrets; no secrets in git - Skills, commands, and a rule that never solicits API keys in chat - Cursor Marketplace schema: plugin.json + `.cursor-plugin/marketplace.json` diff --git a/README.md b/README.md index adb7ede..6a05655 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,157 @@ # Hydracept for Cursor -One execution surface for text/reasoning, media, domains, DNS, and other external capabilities, with durable jobs, budgets, receipts, and BYOK. +Give Cursor's agent image, audio, video, 3D, and text generation, plus domains/DNS and other external capabilities, through one [Hydracept](https://hydracept.com) MCP interface. Every run is a durable job with budgets, typed artifacts, and an immutable receipt. Bring your own provider keys (BYOK) or use managed execution. -**Canonical repository:** [`zencodeinc/hydracept-plugin`](https://github.com/zencodeinc/hydracept-plugin) (Cursor plugin **0.1.8**). The older [`zencodeinc/hydracept-agent-plugins`](https://github.com/zencodeinc/hydracept-agent-plugins) catalog is retired. - -Plugin homepage: https://hydracept.com/plugin +- Website: https://hydracept.com +- Plugin page: https://hydracept.com/plugin +- Python package / MCP server: [`hydracept` on PyPI](https://pypi.org/project/hydracept/) +- MCP Registry: `com.hydracept/hydracept` A Zencode product · © Zencode Consulting Inc. +## What's included + +| Component | Name | Purpose | +| --- | --- | --- | +| MCP server | `hydracept` (`mcp.json`) | Stdio MCP: `python -m hydracept mcp serve`. No secrets in the repo. | +| Skills | `hydracept`, `hydracept-setup`, `hydracept-image`, `hydracept-sheet`, `hydracept-smoke` | When and how to use Hydracept capabilities; setup; image generation; sprite/icon sheets; opt-in paid smoke test | +| Commands | `/hydracept-init`, `/hydracept-doctor` | Bootstrap a project; check connection and MCP binding | +| Rule | `hydracept.mdc` | Never ask for API keys in chat; use canonical init and stdio MCP | + ## Install -- **Cursor Marketplace:** search for **Hydracept** or submit this repo at [cursor.com/marketplace/publish](https://cursor.com/marketplace/publish) after review. -- **From Git:** clone `https://github.com/zencodeinc/hydracept-plugin` and add the repo as a Cursor plugin (root contains `.cursor-plugin/plugin.json`). +1. Install **Hydracept** from the Cursor Marketplace (Customize → search "Hydracept"), or test locally by copying this repo into `~/.cursor/plugins/local/hydracept` and reloading the window. +2. Install the Python package the MCP server runs on: + + ```bash + pip install -U hydracept + ``` + +3. **Claude Code:** add marketplace `zencodeinc/hydracept-plugin` and install `hydracept@hydracept` — see [Install in Claude Code](#install-in-claude-code). -Requires the [`hydracept`](https://pypi.org/project/hydracept/) Python package on your machine for stdio MCP (`python -m hydracept …`). +## Install in Claude Code -## Authentication (project checkout) +Hydracept ships a Claude Code plugin marketplace in this repository (`.claude-plugin/marketplace.json`). -Do **not** paste `HYDRACEPT_API_KEY` into chat or into **Plugins → Configure** for workspace-bound stdio. +```text +/plugin marketplace add zencodeinc/hydracept-plugin +/plugin install hydracept@hydracept +``` -In a project checkout run: +Or from your shell: + +```bash +claude plugin marketplace add zencodeinc/hydracept-plugin +claude plugin install hydracept@hydracept +``` + +When the plugin is enabled, Claude Code asks for your **Hydracept API key** (get one at https://hydracept.com/start). The key is stored in your OS credential store, not in `settings.json`, and is sent as `Authorization: Bearer ` to the hosted MCP server `https://api.hydracept.com/mcp`. To change it later, run `/plugin configure hydracept@hydracept`. + +The plugin adds the Hydracept MCP server plus the Hydracept skills (`/hydracept:hydracept`, `/hydracept:hydracept-image`, and others). To update, run `claude plugin update hydracept@hydracept`. + +**MCP server only (no plugin):** with `HYDRACEPT_API_KEY` exported in your shell: + +```bash +claude mcp add --transport http hydracept https://api.hydracept.com/mcp \ + --header "Authorization: Bearer $HYDRACEPT_API_KEY" +``` + +## Install in Claude Desktop + +Claude Desktop's `claude_desktop_config.json` starts local (stdio) servers. Use the `hydracept` PyPI package via [`uv`](https://docs.astral.sh/uv/). Open **Settings → Developer → Edit Config** and add: + +```json +{ + "mcpServers": { + "hydracept": { + "command": "uvx", + "args": ["hydracept@0.4.4", "mcp", "serve"], + "env": { + "HYDRACEPT_API_KEY": "" + } + } + } +} +``` + +Restart Claude Desktop. Keep this file private because it holds your key. + +**Custom connector (remote):** Hydracept authenticates with an API key, not OAuth. You can add `https://api.hydracept.com/mcp` under **Settings → Connectors → Add custom connector** only if your organization has the beta **Request headers** option. Choose **No sign-in** and add the `authorization` header with the value `Bearer `. Without that option, use the config above. + +## Install in Google Antigravity + +Antigravity 2.0, the Antigravity IDE, and the Antigravity CLI (`agy`) all read one MCP config file: `~/.gemini/config/mcp_config.json`. For a single project, use `.agents/mcp_config.json` in the workspace. In the IDE, open **… → MCP Servers → Manage MCP Servers → View raw config** and add: + +```json +{ + "mcpServers": { + "hydracept": { + "serverUrl": "https://api.hydracept.com/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } +} +``` + +Antigravity requires `serverUrl`; the keys `url` and `httpUrl` don't work there. After saving, refresh **Settings → Customizations → Installed MCP Servers**. If you use a workspace `.agents/mcp_config.json`, add it to `.gitignore` so the key is never committed. + +## Install in Gemini CLI + +This repository is also a Gemini CLI extension (`gemini-extension.json`): + +```bash +gemini extensions install https://github.com/zencodeinc/hydracept-plugin +``` + +The installer asks for your **Hydracept API key** and stores it as a sensitive setting (`HYDRACEPT_API_KEY`). To change it, run `gemini extensions config hydracept`. + +## Authentication + +Get an account and key at https://hydracept.com/start. Do **not** paste `HYDRACEPT_API_KEY` into chat, and do not put it in **Plugins → Configure** for project checkouts. + +In a project checkout, run (or ask the agent to run `/hydracept-init`): ```bash python -m hydracept init --apply --yes --json ``` -That writes workspace secrets under `.hydracept/` and binds project MCP to stdio (`python -m hydracept mcp serve`). Reload MCP once when init says it is required. +Init writes workspace secrets under `.hydracept/` (gitignored) and binds project MCP to stdio. If it returns `status: interaction_required`, open the activation URL from the JSON output, then run the suggested `afterCompletion.command`. Reload MCP once if init says it is required. Run `/hydracept-doctor` to verify. + +Other clients: + +- **Key-only stdio:** `uvx hydracept mcp serve` with `HYDRACEPT_API_KEY` set in the environment. +- **Hosted MCP (no checkout, e.g. ChatGPT):** `https://api.hydracept.com/mcp` with `Authorization: Bearer `. + +## Example prompts + +- "Generate a transparent 512×512 PNG app icon of a paper plane in a flat style and save it to `assets/icon.png`." +- "Make a cohesive set of 8 UI glyphs (home, search, settings, …) as a sprite sheet and slice it into separate PNGs." +- "Create a 10-second upbeat background music loop for the landing page." +- "Generate a short product teaser video from this screenshot." +- "Produce a low-poly 3D model of a coffee cup as a GLB for the three.js scene." +- "Translate `locales/en.json` into French and German as a durable job and show me the receipt." +- "What would it cost to generate 20 hero images? Quote it before running anything." -If init returns `status: interaction_required`, follow the Hydracept activation URL from the JSON output, then run the suggested `afterCompletion.command` (usually the same init with `--wait`). +Available capabilities depend on the live Hydracept catalog; the agent discovers them with `hydracept_capabilities` / `python -m hydracept capabilities find`. -**Hosted MCP (no checkout):** `https://api.hydracept.com/mcp` with `Authorization: Bearer `. Get a key at https://hydracept.com/start . +## Pricing -**Quick key-only stdio:** `uvx hydracept@0.4.4 mcp serve` with `HYDRACEPT_API_KEY` set (see [MCP Registry manifest](./mcp-registry/server.json)). +The plugin is free and open source. Hydracept execution is billed by Hydracept: BYOK carries a 0% Hydracept service fee; managed execution is provider price plus 6%. See https://hydracept.com. -Commands: `/hydracept-init`, `/hydracept-doctor`. +## Security -Local CLI fallback (optional): `python -m hydracept agents install --auto`. +This repository contains no API keys or tokens. Keys stay in `.hydracept/secrets.json` (gitignored) or your environment. Report security issues to support@hydracept.com. ## MCP Registry -Official registry manifest: [`mcp-registry/server.json`](./mcp-registry/server.json). +Registry manifest: [`mcp-registry/server.json`](./mcp-registry/server.json) (`com.hydracept/hydracept`, version tracks the PyPI package, not this plugin's semver). -- **Registry name (domain namespace):** `com.hydracept/hydracept` — aligned with the PyPI README `mcp-name` line in the `zencodeinc/hydracept` monorepo (owner verifies **hydracept.com** for the `com.hydracept` namespace). -- **Manifest version `0.4.4`** tracks the published PyPI MCP server, not the Cursor plugin semver (`0.1.8`). +## Support -Publishing is manual: validate with `mcp-publisher validate mcp-registry/server.json`, then `cd mcp-registry && mcp-publisher publish` after domain verification and PyPI README ownership are complete. Do not publish the hosted remote until redirect/TLS issues on `https://api.hydracept.com/mcp` are fixed. +- Email: support@hydracept.com +- Issues: https://github.com/zencodeinc/hydracept-plugin/issues ## License diff --git a/gemini-extension.json b/gemini-extension.json new file mode 100644 index 0000000..f46b912 --- /dev/null +++ b/gemini-extension.json @@ -0,0 +1,21 @@ +{ + "name": "hydracept", + "version": "0.1.9", + "description": "Image, audio, video, 3D, and text generation for coding agents through one remote MCP server, with durable jobs, budgets, and receipts.", + "settings": [ + { + "name": "Hydracept API key", + "description": "Workspace API key from https://hydracept.com/start.", + "envVar": "HYDRACEPT_API_KEY", + "sensitive": true + } + ], + "mcpServers": { + "hydracept": { + "httpUrl": "https://api.hydracept.com/mcp", + "headers": { + "Authorization": "Bearer ${HYDRACEPT_API_KEY}" + } + } + } +} diff --git a/skills/hydracept-image/SKILL.md b/skills/hydracept-image/SKILL.md index 4be6684..3f2efaa 100644 --- a/skills/hydracept-image/SKILL.md +++ b/skills/hydracept-image/SKILL.md @@ -1,13 +1,13 @@ --- name: hydracept-image description: > - Generate production game images through Hydracept image.generate.v1 — transparent - sprites, icons, variants, and receipted jobs. + Generate production images through Hydracept image.generate.v1 — transparent + PNGs, icons, sprites, variants, and receipted jobs. --- # Hydracept Image -Production image generation judgment for game assets. +Production image generation judgment for app, web, and game art (icons, sprites, illustrations, transparent PNGs). ## Capability @@ -55,7 +55,7 @@ Keep prompts short, product-neutral, and lighting-first. Do not name a provider. ## Workflow -1. Describe the asset need in game terms, not provider terms +1. Describe the asset need in product terms (use, size, style), not provider terms 2. Read `pricingFactors` on `image.generate.v1`. Optional: `hydracept_quote_capability` (`POST /quote`) for a 0.3 `pricing.quote` preview. Do **not** attach a stale `execution.quoteId`. 3. Submit a job with project context from the workspace. **Omit `execution.quoteId`.** The API seals pricing at admission. 4. Poll until `succeeded`