@byldd/seo-tools-plugin

Byldd SEO Tools — Paperclip Plugin

A Paperclip AI plugin that connects autonomous SEO agents to the Byldd SEO Backend. It exposes keyword research, clustering, and content brief generation as agent tools — enabling a fully automated, Human-in-the-Loop SEO content pipeline.

What It Does

This plugin registers 12 agent tools that proxy requests to the Byldd SEO backend API:

Tool	Description
runKeywordResearch	Start an async keyword discovery + enrichment pipeline for a seed keyword
getKeywordSessionStatus	Poll a running keyword research job until completion
listKeywordSessions	List all past keyword research sessions
clusterKeywords	Group enriched keywords into topical hub-and-spoke clusters
getClusterStatus	Poll a running clustering job until completion
listClusterSessions	List all past clustering sessions
generateContentBrief	Generate a full content brief from a cluster or standalone keyword
getBriefStatus	Poll a running brief generation job until completion
listContentBriefs	List content briefs, optionally filtered by cluster
rerunBriefStage	Regenerate a single stage of the brief pipeline
attachProofPoints	Inject business-specific proof points (pricing, timelines, outcomes) into a brief

UI Components

Slot	Type	Description
health-widget	Dashboard Widget	Shows plugin health status
keyword-research-tab	Issue Detail Tab	Keyword research data tab on issues

Data Handlers

Key	Description
health	Plugin health check
sessions	List keyword research sessions (backs the UI tab)
enrichResult	Full keyword metrics for a session (backs the UI tab)

Prerequisites

• Paperclip AI instance running locally or deployed
• Byldd SEO Backend running and accessible
• Node.js ≥ 18

Setup

1. Install Dependencies

npm install

2. Build

npm run build

3. Install Into Paperclip

Once published to npm, you can install the plugin directly using its package name:

paperclipai plugin install @byldd/seo-tools

Note: For local development before publishing, you can still install it from the local path:

paperclipai plugin install /path/to/seo-tools

4. Configure Credentials

This plugin reads the backend URL and auth token from Paperclip's plugin instance config (not hardcoded in source). Set them after installing:

Via CLI:

npx paperclipai plugin config:set byldd.seo-tools \
  --payload-json '{"backendUrl":"https://seo-api.byldd.com","authToken":"<YOUR_JWT_TOKEN>"}'

Via Paperclip UI:

1. Open Paperclip → Settings → Plugins → Seo Tools
2. Fill in:
   • Backend URL: Your SEO backend base URL (e.g. https://seo-api.byldd.com)
   • Auth Token: A valid JWT token for the backend

Note: The auth token is a JWT with an expiry. Rotate it in the Paperclip UI when it expires — no code changes needed.

Development

npm run dev          # watch-mode rebuild (worker + manifest + UI)
npm run dev:ui       # local UI dev server with hot-reload
npm test             # run tests with vitest
npm run typecheck    # type-check without emitting

npm run dev rebuilds into dist/ on file changes. Paperclip watches the output directory and hot-reloads the plugin worker automatically for local installs.

Project Structure

seo-tools/
├── src/
│   ├── worker.ts          # Plugin worker — tool handlers + data handlers
│   ├── manifest.ts        # Plugin manifest — tools, capabilities, config schema
│   ├── types/
│   │   └── index.ts       # TypeScript interfaces for tool params + cluster shapes
│   └── ui/
│       └── index.tsx       # React UI components (dashboard widget, detail tab)
├── tests/
│   └── plugin.spec.ts     # Plugin tests
├── dist/                  # Build output (gitignored)
├── esbuild.config.mjs     # esbuild bundler config
├── rollup.config.mjs      # Rollup bundler config (alternative)
├── tsconfig.json
├── vitest.config.ts
└── package.json

Configuration Schema

The plugin declares an instanceConfigSchema in the manifest. Operators fill these fields in the Paperclip UI:

Field	Type	Required	Description
backendUrl	string		Base URL of the SEO backend API
authToken	string		JWT auth token for the backend

Capabilities

This plugin requests the following Paperclip capabilities:

Capability	Purpose
agent.tools.register	Register SEO tools for agent use
http.outbound	Make HTTP requests to the SEO backend
ui.detailTab.register	Render the Keyword Research tab on issues
ui.dashboardWidget.register	Render the health dashboard widget
events.subscribe	Listen to Paperclip domain events
plugin.state.read	Read plugin-scoped state
plugin.state.write	Write plugin-scoped state

Build Options

• npm run build — esbuild (default, faster)
• npm run build:rollup — rollup (alternative)

Both output to dist/.

License

MIT