AI assistant

Ask questions about a file, have a view drafted, or ask for a change. Nothing is changed until you approve it in Arspec's own window.

There are two ways to let an AI assistant work on the file you have open. The built-in assistant is a chat pane inside Arspec that talks to an AI service of your choice using your own key. Alternatively, on a desktop, you can connect the AI chat you already use: Arspec makes its tools available to Claude Desktop, Claude Code, Cursor and any other app that supports the Model Context Protocol (MCP), on the account you already have, with no key to configure. Whichever way you choose, the assistant gets the same abilities and the same rule about changes.

What the assistant can do

Seven tools, whichever way the assistant reaches them. Six of them read; one proposes a change, which you approve or refuse.

Tool	What it gives the assistant
`get_document_overview`	The selected file at a glance: its name, how many statements and terms it has, its base address, its own namespace, the prefixes it declares, and what it imports. Where a conversation usually starts.
`search_terms`	Terms whose name contains a given text, ignoring case.
`describe_term`	Everything the file says about one term.
`list_definitions`	Every perspective, lens and stylesheet that applies to the file, wherever it is kept.
`get_definition`	One of those, in full, exactly as the app would save it.
`read_vocabulary`	The definition of the language perspectives are written in, so the assistant can draft one that loads.
`apply_turtle_patch`	Proposes a change to the open file, the topic, or your profile, as statements to remove and add. The proposal opens in a confirmation dialog in Arspec, shown as a difference against the file, and the tool waits for your decision. Approved, it becomes one undoable step like any edit of your own. Imported files and the built-in definitions cannot be changed this way.

So the assistant can answer questions about an ontology, find its way around it, draft a view for a task you describe, or propose an edit. The edit is previewed where you can see the data, not in the chat. Refusing costs nothing, and an approved change is one Ctrl+Z away from undone.

The built-in assistant

The chat pane opens from the app bar. It talks to the service you pick in Preferences → AI Assistant:

Service	Notes
Anthropic (Claude)	Key from the Anthropic console.
OpenAI	Key from the OpenAI platform.
xAI (Grok)	OpenAI-compatible.
Mistral	OpenAI-compatible.
Ollama (local)	No account and no key: a model running on your own machine. The easiest way to try the assistant.
Custom (OpenAI-compatible)	Any endpoint that speaks the OpenAI dialect: a proxy, a llama.cpp server, a provider not listed here.

The service and model you choose are saved with your other preferences. The key is not: preferences can be exported and shared, and a secret has no place in a shared file, so keys are stored in the operating system's keystore. The built-in assistant is the only way to use an assistant on a phone or in the browser, where an outside chat app cannot reach Arspec.

The assistant pane open beside the Functions view of a file of small programs, with one function selected. The user has asked whether it can make a view for that function alone; the assistant has looked up the views the file already has, and answers with the ways it could be done. — The assistant at work. Asked for a view about the selected function, it reads the views the file already has before it says what it would write.

Your own chat, over MCP

Desktop only: Windows, macOS, Linux. Switch the server on in Preferences → AI Assistant, and Arspec starts listening on your own computer only, on a port it picks. Set your chat app up once, as described below, and from then on it can read and edit whichever file is selected in Arspec. While none is selected, the tools say so.

The AI Assistant page of Preferences: a switch labelled Let AI chats on this computer work with Arspec, off, and the provider for the built-in assistant below it. — *Preferences → AI Assistant*. The switch starts the server; nothing listens until it is on.

Three safeguards, as the protocol asks of a local server:

Arspec listens on the local loopback address only. Nothing outside this computer can reach it.
Requests that appear to come from a web page rather than from an app on this computer are refused.
Every request must carry a token the app generated. The token is shown in Preferences, goes into the chat app's setup once, and is stored in the operating system's keystore, never in the preferences file. New token cuts off every chat app set up with the old one.

The preferences screen copies the setup for each chat app to your clipboard and shows the steps. They are repeated here. In every snippet, PORT and TOKEN stand for the values Preferences shows you.

Keep Arspec running with your file open: the tools act on the file selected there, and the chat app is told when none is.

Claude Code

One command, in a terminal in the project you use Claude Code with. Add --scope user after claude mcp add to have Arspec available in every project instead.

claude mcp add --transport http arspec http://127.0.0.1:PORT/mcp \
    --header "Authorization: Bearer TOKEN"

Paste and run the command. Claude Code confirms that the server was added.
Start Claude Code, or a new session, and type /mcp: Arspec is listed as connected, with its tools.
The first call to each tool asks for permission; always allow keeps it from asking again.

Claude Desktop

Claude Desktop starts local servers itself, so its entry runs a small bridge program, mcp-remote, that relays to Arspec. The bridge needs Node.js; this is the one setup with a prerequisite.

{
  "mcpServers": {
    "arspec": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "http://127.0.0.1:PORT/mcp",
        "--header", "Authorization:${ARSPEC_MCP_AUTH}"
      ],
      "env": { "ARSPEC_MCP_AUTH": "Bearer TOKEN" }
    }
  }
}

Install Node.js if it is not on this computer already.
In Claude Desktop, open Settings → Developer → Edit Config. It shows the file claude_desktop_config.json, in %APPDATA%\Claude on Windows or ~/Library/Application Support/Claude on macOS.
Paste the entry. If the file already has an "mcpServers" section, put the "arspec" part inside it rather than adding a second section.
Save and restart Claude Desktop: quit it fully, from the menu bar or the system tray, then open it again.
In a new chat, Arspec appears among the connectors, and its tools can be switched on from the tools menu. The first call to a tool asks for permission.

Cursor, Windsurf, VS Code and others

Most other clients take this entry under mcpServers in their config file. Cursor reads .cursor/mcp.json in the project, or ~/.cursor/mcp.json for every project; Settings → MCP → Add gets there too. VS Code takes the same "arspec" entry under "servers" instead of "mcpServers", in .vscode/mcp.json.

{
  "mcpServers": {
    "arspec": {
      "type": "http",
      "url": "http://127.0.0.1:PORT/mcp",
      "headers": { "Authorization": "Bearer TOKEN" }
    }
  }
}

Paste the entry, inside an existing "mcpServers" section if there is one.
Save. The client picks the server up on its next reload, or restart it.
Approve Arspec's tools when it asks.

What is sent where

With the built-in assistant, what you type and what the tools return go to the service you configured, on your key, and nowhere else. With your own chat app connected, nothing leaves the machine on Arspec's account: the chat app is the one talking to its provider, under its own terms, and Arspec only answers that app's requests on your own computer. In both cases the file on disk changes only through the confirmation dialog.