Semanticus
Documentation

Getting started

Semanticus is a VS Code extension with a headless engine built in. Install it, open a model, connect your AI Assistant, and within a few minutes you and the agent are driving the same live session.

Install the extension

Semanticus runs anywhere VS Code does: Windows, macOS and Linux. The extension bundles a self-contained engine, so there is no separate .NET prerequisite to install and nothing else to configure. Install the Semanticus extension for VS Code, reload the window, and you are ready to open a model.

The engine is the single writer

The extension talks to a headless engine that owns your model. Both the Studio UI and your AI Assistant attach to that one engine, so every edit lands on the same live session (see The two doors).

Open a model

Semanticus opens a model from wherever it lives. The React Studio dashboard opens beside your editor as soon as one is loaded.

Edit offline, validate live

A common pattern is to edit a local TMDL or PBIP project while a read-only connection to the deployed endpoint lets you run queries and grade scale against real cardinality. You choose when a change leaves your machine.

Connect your AI Assistant

Run the Semanticus: Connect AI Assistant command from the palette. It writes (and merges) an mcpServers.semanticus entry into your workspace .mcp.json, which is where the supported AI Assistant reads MCP servers. Any other servers already in the file are preserved.

{
  "mcpServers": {
    "semanticus": {
      "command": "<bundled engine>",
      "args": ["mcp", "--workspace", "<project root>"]
    }
  }
}

The server is attach-or-own: it is one MCP server, not a second copy of the engine. If the engine is already running for the Studio UI, your AI Assistant attaches to that same live session. If not, it starts its own. Either way there is a single writer and a single undo timeline.

Why there is no API key

The engine runs no inference and holds no model credentials. Your own AI Assistant calls the local MCP tools, so Semanticus does not add a separate model bill or send model metadata to an inference service. More in Architecture & principles.

Your first ten minutes

With a model open, these three moves orient you and prove the round trip. Each is a Studio tab you can click and an MCP tool your AI Assistant can call.

1. Orient with get_model_summary

This is the session-start primer: one token-budgeted round trip (roughly two thousand tokens) that returns the whole map. Connection state, entitlement tier, model overview and counts, the AI-readiness grade and category scores, the structural graph, any in-flight work, and suggested next actions. Each section names the drill-down op to call for more detail, so it is the natural first call for a fresh agent session.

2. Scan with ai_readiness_scan

Grade the model A–F for how well it answers Copilot, Q&A and Fabric data agents. You get an overall score, per-category scores, coverage figures, any gating reasons, and a prioritized list of findings. Each finding is tagged SafeFix (deterministic), AiContent (your AI Assistant authors it) or Proposal (human review). The same view is the AI-Readiness tab in the Studio.

The AI-Readiness tab showing an A to F scorecard by category, coverage figures, and a prioritized findings list with one-click safe fixes.

3. Run a query in DAX Lab

With a live connection (connect_xmla, connect_local, open_local or open_live), run a DAX query with run_dax and read the columns and rows back. The DAX Lab tab adds front-end and storage-engine (FE/SE) timings, a filter-context lab, and the optimise-and-prove-equivalent loop.

The DAX Lab tab: authoring and running a DAX query with front-end and storage-engine timings shown per query.

Activating Pro

Free includes the workbench, analysis and individual edits. Pro adds reviewed bulk actions, Verified Mode, enforced workflows, advanced evidence and Data Agent writes. When you buy a license you receive a signed offline token by email. To activate it, run Semanticus: Activate License from the palette and paste the token: the extension saves it to the semanticus.licenseToken setting and restarts the engine with your entitlement. Verification is fully offline, with no account and no phone-home.

Check your current tier any time with get_entitlement. See Pro for what is gated and for pricing.

Where next