Content
# Competitor Promo Agent Kit
An open, self-hosted toolkit for current competitor-promotion audits:
- an [Agent Skills](https://openagentskills.dev/) workflow;
- an [MCP](https://modelcontextprotocol.io/) server for local and remote agents;
- a CLI for agents that only have shell access;
- Playwright evidence capture;
- Excel reports with each brand's screenshots embedded in its row.
[中文说明](README.zh-CN.md)
This repository is the lowest-upfront-cost deployment: open source and self-hosted. It does not include accounts, billing, cloud storage, or a managed service.
## How it stays agent-neutral
| Agent capability | Integration |
|---|---|
| Agent Skills + MCP | Install the skill and connect the MCP server |
| MCP only | Call the three MCP tools directly |
| Shell access only | Run `promo-audit capture` and `promo-audit report` |
| Neither Skills nor MCP | Use the reusable prompt and invoke the CLI through the agent's execution tool |
There is no universal one-click installer shared by every agent product. Agent Skills provide the workflow, MCP provides interoperable tools, and the CLI is the fallback.
Tested integration targets:
- Codex personal Skills plus local or remote MCP;
- Claude custom Skill upload plus remote OAuth MCP;
- Claude Code personal/project Skills plus local or remote MCP;
- OpenClaw managed Skills plus local or Streamable HTTP MCP;
- generic Agent Skills and MCP clients.
## What the server does
The server deliberately separates evidence collection from interpretation:
1. `capture_promotion_pages` captures official-site screenshots, visible text, final URLs, timestamps, and promotion-link candidates.
2. The connected agent determines which explicit claims are supported by that evidence.
3. `build_promotion_report` creates the comparison workbook and embeds one to three screenshots in each brand row.
4. `read_promotion_artifact` returns a generated artifact as an embedded MCP resource for remote clients.
It does not force a Prime Day or holiday association. The report uses the promotion actually visible on the latest captured official page.
## One-command install
For Codex, Claude Code, or OpenClaw running on macOS or Linux, paste the matching
command into a terminal or ask the agent to run it:
```bash
# Codex
curl -fsSL https://raw.githubusercontent.com/ljh1097912305-wq/competitor-promo-agent-kit/main/install.sh | bash -s -- codex
# Claude Code
curl -fsSL https://raw.githubusercontent.com/ljh1097912305-wq/competitor-promo-agent-kit/main/install.sh | bash -s -- claude-code
# OpenClaw
curl -fsSL https://raw.githubusercontent.com/ljh1097912305-wq/competitor-promo-agent-kit/main/install.sh | bash -s -- openclaw
```
Run only the line for the target agent. The installer:
1. installs a private Node.js 22 runtime when the machine does not have one;
2. downloads and verifies the `v0.3.0` runtime package;
3. installs production dependencies and Playwright Chromium;
4. installs the Agent Skill in the target's personal Skills directory;
5. registers and probes the local stdio MCP server.
Restart the agent or open a new session after the command finishes. Re-running
the same command updates the installation in place.
This path requires an agent with terminal execution. Claude web, Cowork, and
other no-shell cloud clients still require a Skill upload plus a reachable
remote MCP deployment.
## Manual local install
Requirements: Node.js 22+ and pnpm.
```bash
corepack enable
pnpm install
pnpm exec playwright install chromium
node ./src/cli.mjs --help
```
Capture the six example e-bike brands:
```bash
node ./src/cli.mjs capture \
--input ./examples/inputs/capture-six-ebike-brands.json \
--output ./data/current-audit
```
The connected agent reads `data/current-audit/capture-manifest.json`, creates a verified report input, and then runs:
```bash
node ./src/cli.mjs report \
--input ./report.json \
--output ./data/competitor-promotion-comparison.xlsx
```
## Local MCP over stdio
Install dependencies, then adapt [the stdio example](examples/mcp-configs/stdio.json) to the MCP configuration format used by your agent. The underlying process is:
```bash
node /absolute/path/to/src/cli.mjs mcp \
--data-dir /absolute/path/to/promo-data
```
The server writes all screenshots, manifests, and workbooks under `--data-dir`.
## Remote MCP for cloud agents
Start an OAuth-protected Streamable HTTP endpoint:
```bash
OAUTH_ENABLED=1 \
OAUTH_ADMIN_PASSWORD='replace-with-a-long-random-password' \
HOST=0.0.0.0 \
PORT=3000 \
PUBLIC_BASE_URL='https://promo-mcp.example.com' \
node ./src/cli.mjs serve
```
Connect the cloud agent to:
```text
https://promo-mcp.example.com/mcp
```
The client discovers OAuth metadata, dynamically registers, and opens a consent page. Enter `OAUTH_ADMIN_PASSWORD` to authorize it. Access and refresh tokens persist under `DATA_DIR/.oauth/` with owner-only file permissions.
Use TLS through a reverse proxy and follow [the security guidance](SECURITY.md). Generated files are available through `read_promotion_artifact`; authenticated HTTP downloads are also available below `/files/`.
## Docker
The included Compose configuration is local-only by default:
```bash
docker compose up --build -d
curl http://127.0.0.1:3000/health
```
Outputs appear in `./data`. To make the service reachable by a cloud agent, change the published port, enable OAuth, set the public HTTPS URL, and place it behind a TLS reverse proxy.
Build without Compose:
```bash
docker build -t competitor-promo-agent-kit .
docker run --rm \
-p 127.0.0.1:3000:3000 \
-e ALLOW_INSECURE_REMOTE=1 \
-v "$PWD/data:/data" \
competitor-promo-agent-kit
```
For a public HTTPS deployment, point the domain's DNS to the server and run:
```bash
DOMAIN=promo-mcp.example.com \
OAUTH_ADMIN_PASSWORD='replace-with-a-long-random-password' \
docker compose -f compose.remote.yaml up --build -d
```
The remote Compose file adds Caddy for automatic TLS and keeps the MCP container private behind the reverse proxy.
## Claude
Claude web, Cowork, and Claude Desktop:
1. Upload the release file `capture-competitor-promotions-claude-skill-v0.3.0.zip` in **Customize → Skills**.
2. Add `https://promo-mcp.example.com/mcp` as a custom connector.
3. Complete the OAuth consent page using the deployment password.
Claude Code:
```bash
curl -fsSL https://raw.githubusercontent.com/ljh1097912305-wq/competitor-promo-agent-kit/main/install.sh | bash -s -- claude-code
```
This installs both the personal Skill and a local MCP server. For a project-local
Skill or a remote OAuth MCP deployment, use the manual setup above.
## Codex
```bash
curl -fsSL https://raw.githubusercontent.com/ljh1097912305-wq/competitor-promo-agent-kit/main/install.sh | bash -s -- codex
```
This installs the Skill in `~/.codex/skills/` and registers the local MCP server
in Codex. The Skill-only release file is
`capture-competitor-promotions-codex-skill-v0.3.0.zip`.
## OpenClaw
```bash
curl -fsSL https://raw.githubusercontent.com/ljh1097912305-wq/competitor-promo-agent-kit/main/install.sh | bash -s -- openclaw
```
This installs the managed Skill, registers the local MCP server, and probes it
before completion. For remote OAuth, use
[the remote configuration example](examples/mcp-configs/openclaw-oauth.json).
## Other Agent Skills clients
```bash
node ./src/cli.mjs install-skill --path /custom/agent/skills
```
Connect the same remote MCP endpoint. If the agent supports neither Skills nor MCP, use [the reusable prompt](prompts/competitor-promotion-audit.md) with the CLI.
## MCP tool summary
| Tool | Purpose |
|---|---|
| `capture_promotion_pages` | Capture one to three official-site evidence pages per brand |
| `build_promotion_report` | Create the comparison workbook with screenshots embedded in brand rows |
| `read_promotion_artifact` | Transfer a generated artifact through MCP |
Input and output examples are documented in the [skill reference](skills/capture-competitor-promotions/references/manifest-schema.md).
## Safety defaults
- normal screenshots rather than unbounded full-page captures;
- three-screenshot hard limit per brand;
- official URLs supplied explicitly;
- localhost and private-network browser targets blocked by default;
- output path confinement under `DATA_DIR`;
- localhost-only HTTP bind by default;
- OAuth 2.1 with PKCE, dynamic client registration, refresh-token rotation, and protected-resource discovery;
- bearer or OAuth authentication required for non-loopback binds unless explicitly overridden.
## Development
```bash
pnpm run check
pnpm test
```
The test suite covers browser evidence capture, screenshot-embedded Excel generation, Skill installation, stdio and Streamable HTTP MCP discovery, and the full OAuth discovery/registration/PKCE/token/refresh flow.
## License
MIT
