elfsight/beamtrace-mcp

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.

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

Validate

pnpm validate

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

Local install (dev)

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:

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).

git tag v1.0.1
git push origin v1.0.1

Local / interactive (install mcp-publisher first):

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.

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.