MCP tools

Specra currently exposes seven MCP tools.

If your agent supports skills, the preferred setup is to install the Specra skill first:

bunx skills add lanc33llis/specra-skill

The ui-from-references skill gives the agent the right trigger conditions, project discovery rules, and default tool loop for UI work that should match a Specra project.

Project ID convention

When working in a local repo, keep a .specra.json file at the repo root:

{
  "projectId": "7a4b8e9b-5f49-4b4d-a612-e870c2d529e6"
}

Specra tool descriptions tell the agent to read projectId from that file and pass it as project_id by default.

`specra_evaluate_screenshot`

User-facing title: Evaluate UI

Use this when a screenshot has already been captured on the user machine and MCP should only evaluate it.

This is the preferred localhost-preview path.

When you are iterating, pass iteration_context so the tool can return a deterministic iteration_plan instead of vague loop guidance.

`specra_get_artifact`

User-facing title: Get Artifact

Use this when you need the exact current text of one public handoff artifact from the latest revision.

Examples:

inspect the project’s theme.css
read design-foundations.md
fetch patterns.md
inspect features.md directly

`specra_load_project_context`

User-facing title: Load Project Context

Use this as the prerequisite setup call before implementation.

It returns the latest:

theme.css
design-foundations.md
patterns.md
features.md
revision metadata
static runtime system.md

`specra_evaluate_micro_polish`

User-facing title: Micro Polish

Use this when the UI is broadly correct but still has small human-noticeable issues such as:

icon centering
optical alignment
padding imbalance
small proportional drift

When you are already in a screenshot loop, pass iteration_context here too so Specra can decide whether to stop, revert to the best prior candidate, or allow one more tiny fix pass.

`specra_map_ui_to_code`

Use this when a visible region needs to be mapped back to source, preferably through data-specra-id.

It is the deterministic bridge from screenshot or DOM selection back to files and snippets.

`specra_validate_generated_ui`

Use this after changing UI files.

It checks generated files for drift against the current Specra project and can flag:

incorrect radius buckets
overly heavy shadows
missing semantic theme usage
implementation choices that do not match the extracted handoff

`specra_suggest_ui_fix`

Use this after validation if drift is found.

It returns a minimal suggested correction for a file instead of a full rewrite.

This is best for:

reducing spacing drift
correcting rounded and shadow utilities
tightening generated code back toward the extracted system

Recommended agent loop

If the skill is installed, prefer its workflow instead of manually re-deciding this sequence on every prompt.

load the linked project from .specra.json
specra_load_project_context
if needed, inspect one artifact directly with specra_get_artifact
generate or edit the UI in code
specra_validate_generated_ui
capture a screenshot locally
specra_evaluate_screenshot with iteration_context
follow iteration_plan.nextStep
switch to specra_evaluate_micro_polish only when the plan says to
specra_suggest_ui_fix if needed

Good default trigger

Your agent should use Specra for any request that means:

match this reference
stay on-brand
build a dashboard like this
use the same structure
keep the same feel

With the skill installed, these are the cases where the agent should automatically ground the work in Specra instead of guessing from the prompt alone.