SeeAny Sun MCP

This directory provides a local stdio MCP Server that can be called by MCP clients such as Codex, Claude Desktop, and Cursor.

It supports two modes:

• demo: no API key required; uses product images in the repository for offline simulation and does not call paid APIs.

• live: after setting SEEANY_API_KEY, calls the main site https://api.seeany.com; supports image upload, AI creation, task polling, download, and AI refinement.

Authentication environment variables

Use uniformly:

SEEANY_API_KEY=sk-sa-xxxxxxxx

Do not write the real Key into Git, browser code, or chat messages. Copy .env.example to your local environment and fill it in. If there is no Key, the service automatically enters Demo mode; you can also use SEEANY_MCP_MODE=demo to force offline mode.

Related MCP server: metalevel/snapix-mcp-server

Local installation and testing

cd mcp-server
npm install
npm run build
npm run smoke

The Smoke test forces Demo mode and will not incur real charges.

If you need to perform a real end-to-end acceptance test (which will incur charges on the main account), after confirming that the new Key has been set, run:

npm run live-smoke

Connecting Codex

codex mcp add seeany-sun-mcp -- npx --yes seeany-sun-mcp

Install as a Codex plugin (MCP + Skill)

The repository also provides a Codex plugin manifest: after installation, you will get both the SeeAny MCP tools and the seeany-product-visuals product visual workflow Skill.

codex plugin marketplace add juin20260102-oss/seeany-sun-mcp --sparse .agents/plugins
codex plugin add seeany-sun-mcp@seeany

After installation, start a new Codex conversation; for real image generation, you still need to set SEEANY_API_KEY in your local environment. If you only need the MCP tools, use the codex mcp add command above.

If you use the real API, set SEEANY_API_KEY in the same environment where you start the MCP. After connecting, it is recommended to call seeany_get_capabilities first, then call in the following order:

1. seeany_upload_asset (when there is a reference image)

2. seeany_refine_prompt (optional)

3. seeany_generate_product_image

4. seeany_wait_generation

5. seeany_download_assets

MCP Inspector

npm run inspect

Current real API mapping

Tasks default to asynchronous mode. The main site API's image/video tasks are billed according to account configuration; seeany_quote_generation only returns an estimate and does not pre-deduct charges.

SeeAny Skill

The repository includes skills/seeany-product-visuals, used to guide the Agent through the complete flow of “upload reference image → prompt refinement → quote → generate → poll → download” when calling the MCP. The npm package also includes this Skill directory.

npm package name

The current package name is set to seeany-sun-mcp, suitable for first publishing a public unscoped package. Before the official release, you need to confirm the name is available on npm; if SeeAny has established an npm scope, you can also migrate to @seeany/sun-mcp.

The simplest invocation after publishing:

npx --yes seeany-sun-mcp

Check the package contents before publishing:

npm run pack:check

Automated testing and publishing

GitHub Actions will run on Push and Pull Request to the main branch using Node.js 20, 22, and 24 to perform plugin validation, MCP Smoke Test, and npm packaging checks.

When publishing a new version, first update the versions in package.json, package-lock.json, and .codex-plugin/plugin.json in sync, then create a Git Tag with the same version:

git tag v0.5.0
git push origin v0.5.0

release.yml verifies that the Tag matches the package version, then publishes via npm Trusted Publishing and creates a GitHub Release. Before first use, you need to add the GitHub Actions Trusted Publisher in the npm package settings:

• GitHub user: juin20260102-oss

• Repository: seeany-sun-mcp

• Workflow: release.yml

• Allowed action: npm publish