Beamtrace for Cursor

Cursor plugin that connects to Beamtrace's remote MCP for read-only AI visibility insights.

Also includes server.json for the MCP Registry (remote-only) and a stdio introspection shim for catalog Docker builds.

What's included

MCP: https://beamtrace.com/api/mcp (OAuth; organization's website is resolved automatically)
Rule: how to interpret metrics and phrase human reports

Tools

Tool	Purpose
`get_visibility`	Overall visibility score and insight
`list_topics`	Topic rollups
`list_prompts`	Prompt-level metrics and coverage gaps
`list_competitors`	Visibility leaderboard
`list_improvements`	Prioritized content improvements

Stdio catalog image

The product MCP is remote (https://beamtrace.com/api/mcp). This repo also ships a stdio shim that lists the same five tools so a Docker image can start and answer introspection (initialize / tools/list). The shim does not call Beamtrace APIs.

Terminal

docker build -t beamtrace-mcp .
docker run -i --rm beamtrace-mcp

Validate

bash

pnpm validate

Pre-commit runs the same check via Lefthook (pnpm exec lefthook install after clone).

Local install (dev)

bash

ln -sf "$(pwd)" ~/.cursor/plugins/local/beamtrace

Reload Cursor → Customize → confirm Beamtrace loads → authenticate MCP.

Release

Pushing a v* tag (for example v1.0.1) runs .github/workflows/publish-mcp.yml. It logs in with HTTP domain auth, then:

bash

node scripts/publish.mjs --target all --version "$GITHUB_REF_NAME" --yes

That sets .cursor-plugin/plugin.json and server.json to the tag version (v prefix is stripped), publishes to the MCP Registry, then commits those files to the default branch if they changed. The tag itself stays on the original commit.

Add repository secret MCP_PRIVATE_KEY: the 64-character hex private key used with mcp-publisher login http (not the PEM file).

bash

git tag v1.0.1
git push origin v1.0.1

Local / interactive (install mcp-publisher first):

bash

pnpm release

Pick cursor / mcp registry / all, then patch / minor / major, or pass --version. Cursor only bumps .cursor-plugin/plugin.json. MCP also runs mcp-publisher publish.

bash

pnpm release -- --target cursor --bump patch --yes
pnpm release -- --target mcp --bump minor --yes
pnpm release -- --target all --bump patch --yes
pnpm release -- --target all --version 1.0.1 --yes

Namespace com.beamtrace/mcp needs domain auth for beamtrace.com (docs). Local login: pnpm registry:login:http. Use pnpm registry:login:github only for GitHub-owned namespaces.

Keep server.json version aligned with the live MCP serverInfo.version when you publish.

Auth

After install, complete Beamtrace sign-in when Cursor prompts. You need a Beamtrace account with a website at beamtrace.com/setup.

Publisher: Elfsight.