convez.ai
AgenteDados & AnalyticsIntermediário
semaphor-analytics

Semaphor Agent Plugin

semaphor-analytics/agent-plugin

Construa data apps React conectados a dados governados com IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Plugin que conecta Claude Code ou Codex a projetos Semaphor para construir data apps React governados. O agente pode inspecionar dados, responder perguntas de negócio, gerar código React e publicar apps diretamente no Semaphor com validação integrada.

Instalação

$npx convez-ai semaphor-analytics/agent-plugin

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
37%
Último commit
há 3 dias
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Gerar dashboards e aplicações de dados com Claude Code
  • Inspecionar e explorar dados governados via agente IA
  • Automatizar criação de visualizações e KPIs em React
  • Publicar data apps validados direto do ambiente de desenvolvimento

Veredito

Plugin maduro e bem-documentado que integra análise de dados com geração de código. Excelente para times que já usam Semaphor e querem acelerar desenvolvimento de data apps com assistência de IA, mas requer setup inicial com tokens de projeto.

README

A tradução para o português deste README ainda está na fila.

Semaphor Agent Plugin

Build data apps and answer business questions, grounded in your data.

The Semaphor Agent Plugin connects Codex or Claude Code to your Semaphor project. Your agent can inspect governed data, answer business questions, plan KPIs and charts, generate React data-app code, validate the result, and publish the finished app back to Semaphor.

Quick Start

1. Install

Add the Semaphor marketplace from GitHub, then install the plugin.

Codex:

codex plugin marketplace add semaphor-analytics/agent-plugin
codex plugin add semaphor@semaphor-analytics

Claude Code:

claude plugin marketplace add semaphor-analytics/agent-plugin
claude plugin install semaphor@semaphor-analytics

2. Open Or Create A React App

If you already have a React app, use that app. If you are starting fresh, use the Semaphor Data App Starter:

git clone https://github.com/semaphor-analytics/semaphor-data-app-starter.git my-data-app
cd my-data-app
npm install

The starter is a simple Vite + shadcn app with the basics in place so the agent can focus on your data app instead of initial project setup.

3. Connect To Semaphor

If you do not have a project token configured, log in with Semaphor.

From Codex:

codex mcp login semaphor

From Claude Code, run the /mcp slash command in your session and complete the OAuth flow for the semaphor server.

After login, ask the agent to list your projects and choose the project for this app. If the app needs to run locally, the agent can mint a scoped development runtime token for that project and write VITE_SEMAPHOR_PROJECT_TOKEN to the app's ignored .env.local. The OAuth token itself is never written into the app.

If you already know the project and want a deterministic scoped setup, create or update your app's ignored local env file:

VITE_SEMAPHOR_PROJECT_TOKEN="<project-token-from-semaphor-project-page>"

Get project tokens from your Semaphor project page:

https://semaphor.cloud/project

Do not commit real tokens.

4. Open Your App

Start your coding agent from the app directory (codex or claude) and try:

Inspect my Semaphor project and propose a data app plan.

Semaphor should inspect your project data, propose a plan, and then help build the app once you approve the direction.

What You Need

  • A Vite React app. For a new app, start with semaphor-data-app-starter. Existing Vite React apps and monorepos are fine too.
  • Semaphor login, or a Semaphor project token for deterministic scoped development.
  • Codex or Claude Code.
  • react-semaphor in your app. The agent can add it if it is missing.

Codex Commands

Install

codex plugin marketplace add semaphor-analytics/agent-plugin
codex plugin add semaphor@semaphor-analytics

Verify

codex plugin marketplace list
codex plugin list --marketplace semaphor-analytics

After installation, Semaphor MCP tools should be available to Codex as first-class callable tools. The plugin exposes:

  • semaphor: hosted OAuth MCP for login and project discovery.
  • semaphor-project: project-token MCP bridge for scoped/local development.

Upgrade

codex plugin marketplace upgrade semaphor-analytics

If Codex still shows an older plugin after upgrading the marketplace, remove and reinstall the plugin:

codex plugin remove semaphor@semaphor-analytics
codex plugin add semaphor@semaphor-analytics

Remove

Remove only the installed plugin:

codex plugin remove semaphor@semaphor-analytics

Remove the marketplace source as well:

codex plugin marketplace remove semaphor-analytics

plugin remove removes the installed plugin. marketplace remove removes the marketplace source.

Debug MCP Tool Access

Most users should not need this. Use it only when debugging from a local checkout of this repository and a host does not expose the Semaphor MCP tools as first-class callable tools:

npm run call:mcp -- --list-tools --dir /path/to/react-app
npm run call:mcp -- semaphor_get_access_context --dir /path/to/react-app

Claude Code Commands

Install

claude plugin marketplace add semaphor-analytics/agent-plugin
claude plugin install semaphor@semaphor-analytics

Or, from inside a Claude Code session:

/plugin marketplace add semaphor-analytics/agent-plugin
/plugin install semaphor@semaphor-analytics

Restart Claude Code (or run /reload-plugins) so the new plugin and its MCP servers are picked up.

Verify

claude plugin marketplace list
claude plugin list

After installation, Semaphor MCP tools should be available to Claude Code as first-class callable tools. The plugin exposes:

  • semaphor: hosted OAuth MCP for login and project discovery.
  • semaphor-project: project-token MCP bridge for scoped/local development.

If a tool call asks for OAuth on first use, complete the login through the /mcp slash command in your Claude Code session, then re-run the request.

Upgrade

claude plugin marketplace update semaphor-analytics

If Claude Code still shows an older plugin after updating the marketplace, remove and reinstall the plugin:

claude plugin uninstall semaphor@semaphor-analytics
claude plugin install semaphor@semaphor-analytics

Remove

Remove only the installed plugin:

claude plugin uninstall semaphor@semaphor-analytics

Remove the marketplace source as well:

claude plugin marketplace remove semaphor-analytics

plugin uninstall removes the installed plugin. marketplace remove removes the marketplace source.

Debug MCP Tool Access

Most users should not need this. Use it only when debugging from a local checkout of this repository and a host does not expose the Semaphor MCP tools as first-class callable tools:

npm run call:mcp -- --list-tools --dir /path/to/react-app
npm run call:mcp -- semaphor_get_access_context --dir /path/to/react-app

Connect To Semaphor

The lowest-friction first run is Semaphor login.

From Codex:

codex mcp login semaphor

From Claude Code, run the /mcp slash command in your session and complete the OAuth flow for the semaphor server.

Then ask the agent:

What Semaphor projects can I use?

For deterministic scoped app development, put a project token in .env.local:

VITE_SEMAPHOR_PROJECT_TOKEN="<project-token-from-semaphor-project-page>"

The plugin helper scripts can also read:

SEMAPHOR_PROJECT_TOKEN="<project-token-from-semaphor-project-page>"

Hosted Semaphor does not require a separate server URL. Self-hosted or custom Semaphor deployments may set:

SEMAPHOR_SERVER_URL="https://your-semaphor-host"

When SEMAPHOR_SERVER_URL is absent, the plugin uses the Semaphor host encoded in the project token and falls back to https://semaphor.cloud.

For production apps, provide runtime tokens through your backend, Semaphor embed/token flow, or Semaphor hosted Data App runtime.

When using OAuth for local development, ask the agent to mint or refresh the local runtime token instead of manually copying one:

Mint a local runtime token for this project.

The agent should use semaphor_get_data_app_runtime_token, write the returned project token only to ignored local env, and avoid printing it.

Good First Prompts

Create a data app from my project.
Add a revenue chart with period-over-period change.
What's driving the trend in my top KPI?
Publish this app to Semaphor.

Common Workflows

Answer A Business Question

Why did revenue change last month?

Plan A Data App

Plan an operations data app from my Semaphor project.

Add A View

Add a revenue trend and segment table to this page.

Add Filters

Add a region filter and make the KPI, trend, and table respond to it.

Build Matrix Or Pivot Tables

Show revenue by region and segment with row totals and a grand total.

Add Governed Calculations

Add gross margin as a derived metric.

Use SQL When Needed

Use SQL to show the latest raw inventory movement rows, then add a bounded table.

Save Or Publish

Save this as a Semaphor Data App named "Operations App".
Publish the latest revision to Semaphor.

What The Agent Should Do

For broad app-building requests, the agent should:

  1. Inspect your Semaphor project metadata.
  2. Plan the app before writing code.
  3. Explain which views are backed by governed queries and which gaps need model improvements.
  4. Generate React code using react-semaphor/data-app-sdk.
  5. Validate loading, empty, error, and data states.
  6. Save or publish the app when you approve it.

The agent should not hardcode sample data when a view should execute governed Semaphor analytics.

Generated Code Pattern

The plugin generates standard React code using the public Semaphor Data App SDK:

import {
  SemaphorDataAppProvider,
  SemaphorDevtools,
  semaphor,
  useSemaphorQuery,
} from "react-semaphor/data-app-sdk";

Generated local/dev apps should mount the SDK DevTools root once near the provider so developers and agents can inspect query traces:

const enableDevtools =
  import.meta.env.DEV ||
  (typeof window !== "undefined" && window.location.hostname === "localhost");

<SemaphorDataAppProvider
  token={runtimeToken}
  debug={enableDevtools ? { exposeWindowBridge: true } : false}
>
  <App />
  <SemaphorDevtools
    initialIsOpen={false}
    buttonPosition="bottom-right"
    panelPosition="right"
  />
</SemaphorDataAppProvider>

The window bridge is for local/dev agent inspection only. Do not enable it for production embeds or normal end-user runtime code.

Typical query pattern:

const revenueQuery = semaphor.metric({
  id: "total-revenue",
  source,
  measures: [revenue],
  primaryMeasure: revenue,
});

function RevenueKpi() {
  const result = useSemaphorQuery(revenueQuery);

  if (result.isLoading) return <span>Loading...</span>;
  if (result.error) return <span>{result.error.message}</span>;

  return <strong>{formatNumber(result.value)}</strong>;
}

The plugin supports:

  • metrics
  • records and tables
  • filters and controls
  • driver and period-change analysis
  • matrix and pivot tables
  • derived fields
  • SQL-backed views when governed builders cannot express the question
  • save and publish to Semaphor

Validate Your App

Ask the agent to validate the app before you review or publish it:

Validate this Semaphor data app and run the app's normal typecheck/build.

The agent should use your app's existing package manager and scripts, then run Semaphor-specific checks for common SDK and publish issues.

Publish To Semaphor

Ask the agent to save or publish when the app is ready:

Save this as a Semaphor Data App named "Operations App".
Publish the latest revision to Semaphor.

The first save or publish creates a Semaphor-hosted Data App and writes its identity to semaphor.data-app.json. Later saves and publishes update the same app.

Repository Layout

This GitHub repo is the marketplace root for both Codex and Claude Code:

agent-plugin/
  .agents/plugins/marketplace.json      # Codex marketplace catalog
  .claude-plugin/marketplace.json       # Claude Code marketplace catalog
  plugins/semaphor/                     # Shared installable plugin package

Codex and Claude Code use different marketplace file locations, but both marketplaces point to the same plugins/semaphor package.

More Documentation

Ver o original no GitHub

Bom para

Relacionados