Introduction

Agrafe is the Dolfin web app for writing, compiling and deploying ontologies in your browser. This book documents Agrafe itself: its features, screens and integrations.

The Dolfin language (syntax, types, units, the Turtle correspondence) has its own documentation at www.dolfin.fr/docs. Nothing here repeats it.

What is covered

Using Agrafe: from an empty account to a live API.

• Projects: create, organise in folders, share and publish projects.
• The project workspace: the screen you work in, and how its parts fit together.
  • Files: the file tree, its right-click menus, zip import and export.
  • The Dolfin editor: completion, hover, quick fixes and the right-click menu.
  • Problems, hints and quick fixes: what the checker reports and how to fix it in one click.
• The output panel: Parse, Turtle and SVG, the interactive Graph and its right-click menus, the SPARQL console, Deployments and their API, and History.
• Collaboration: roles, editing together, public projects.
• Account settings and Keyboard and mouse.

Turtle projects: start from an existing OWL/Turtle file and keep both worlds connected.

• Importing a Turtle file creates a Dolfin project and keeps the original .ttl in it.
• The Turtle editor edits that file with syntax checking.
• Reveal jumps from a Dolfin declaration to the Turtle it corresponds to, and back.
• Sync writes your Dolfin edits into the Turtle automatically.
• Re-translate regenerates the Dolfin files after you changed the Turtle by hand.

Integrations: query your deployed ontologies from Claude and other MCP clients.

First steps

1. On the Projects page, press + and choose New project.
2. Open it and pick an example, or paste your own Dolfin. See An empty project.
3. Edit. The Problems panel and the Graph follow as you type.
4. Press Deploy and copy your token. See Deployments.

A short guided tour runs the first time you open the Projects page and a project. The ? button in the output panel walks you through its tabs at any time.

Conventions

• Dolfin file or dlf: a .dlf source file of the project.
• Origin: the .ttl a project was imported from (see Importing).
• Menu and button names are written exactly as they appear in the app.
• On a Mac, read ⌘ wherever this book says Ctrl.

Projects

The Projects page is where you land after signing in. It lists your projects and folders, and the projects other people shared with you.

Creating a project

The round + button (bottom right) opens three choices:

When you have no project yet, the page shows the same two starting points as cards: Start from scratch and Import from Turtle.

The number of projects you can own depends on your plan. When you reach it, a message says so; Settings → License lists the plans that raise it.

Finding a project

• Search filters by project name and comment.
• Sort orders the list: Manual (the order you dragged things into), Recently opened or Recently modified.

Folders

Folders group projects. They are yours only: they are not shared with anyone.

• A folder shows as a title bar with a horizontal preview of what it contains. Click it to open it; the breadcrumb above the list (Home › …) takes you back up.
• An open folder has its own address, such as /home/Clients/Acme%20Corp: bookmark it or reopen it in another tab, and the browser’s Back and Forward buttons move between folders. If two folders in the same place share a name, the address uses the folder’s id instead of its name.
• Drag a project onto a folder to move it there. Hold a dragged project over a folder title for a moment and the folder springs open, so you can drop it deeper.
• In Manual sort, dragging also reorders projects and folders. The other cards move aside as you drag, so the list already shows the order you get when you let go. Drag a card over a folder’s preview to place it inside that folder at that exact spot. On a folder title, the middle moves the item into the folder; the top and bottom edges place it before or after the folder. Press Escape to cancel.
• Rename a folder with its pencil button; press Enter to confirm or Escape to cancel.
• Delete a folder by pressing and holding its trash button for two seconds. Only an empty folder can be deleted.

Project card

Each project card shows its name, its creation date and, for a shared project, who shared it. The card actions are for the owner:

Projects shared with you appear under Shared with you.

Hold-to-delete buttons

Every destructive button in Agrafe (projects, folders, files, deployments, restoring a version) is a hold button: press and keep holding until the fill completes. Releasing early cancels. A quick click only shows a reminder, so you cannot delete anything by accident.

The project workspace

Opening a project shows the workspace. It is made for a wide screen; on a narrow one Agrafe asks for a wider window.

┌───────────┬──────────────────────────────┬───────────────────────────────┐
│ Sidebar   │ File tabs                    │ Output tabs                   │
│           ├──────────────────────────────┤ Parse · Turtle · SVG · Graph  │
│ Search    │                              │ SPARQL · Deployments · History│
│ Public    │  Editor                      │                               │
│ Deploy    │                              │  Output panel                 │
│ Files     │                              │                               │
│           │                              │                               │
│ ⚙ Package ├──────────────────────────────┴───────────────────────────────┤
│           │ Problems                                                     │
└───────────┴──────────────────────────────────────────────────────────────┘

Sidebar

From top to bottom:

Searching the project

Type at least two characters in Search…. Results come from every file and are labelled by kind: concept, property, rule, fact or comment, with the file and line. Click a result to open the file at that line. Escape clears the search.

File tabs

Each file you open gets a tab above the editor. Click a tab to switch, click its ✕ to close it. The ‹ at the left of the tab bar hides the editor so the output panel takes the full width; the thin › rail brings it back, and so does opening a file. Your choice is remembered. When you view an old version from History, a purple Diff: file @ version tab appears; closing it returns to the live file.

In a project imported from Turtle, a sync status chip sits at the right of the tab bar. See Keeping Turtle and Dolfin in sync.

Saving

There is no save button. Every edit is saved automatically a moment after you stop typing. The editor header shows Saving…, then Saved (or Save error).

Compiled output (Turtle, diagram, graph, problems) follows the saved source.

Resizing

• The strip between the editor and the output panel resizes both. Drag it, or focus it and use ← / →. Double-click it (or press Home) to reset the split.
• The top edge of the Problems panel resizes it; click its header to fold it.

Both sizes are remembered in your browser.

An empty project

A project with no file of its own offers two ways to start:

• Start from an example: Library (books, members and loans: concepts, enums, facts, a rule and a query) or People (one concept, one enum, a few facts). The example becomes an ordinary file you can edit.
• Paste or import existing Dolfin: Paste Dolfin… opens a box where you name the file and paste its source, then Create file.

Nothing is deployed until you press Deploy.

Package settings

⚙ Package replaces the editor with a form over the project’s package.dlf, a file that is hidden from the tree:

The form tells you whether there are unsaved changes. Save package settings writes them to package.dlf. Closing the form with unsaved changes asks whether to Discard them or Keep editing.

Files

The Dolfin files tree in the sidebar lists the project’s files. package.dlf is not in it: edit it through ⚙ Package.

A file opens in the editor that matches its extension:

Toolbar

The number of files per project depends on the owner’s plan.

Folders

Folders come from file names: a file named models/person.dlf sits in a models folder. A folder disappears when its last file goes.

Hover a folder for two buttons: + (new file in that folder) and a hold-to-delete trash that removes the folder and every file in it.

Right-click menus

Right-click a file:

Right-click a folder:

The same file actions also exist on hover: a pencil (Rename, also F2) and a hold-to-delete trash.

Renaming a Dolfin file changes its namespace, so the IRIs of everything declared in it change too.

Badges

• A file with problems shows its error and warning counts next to its name. The Problems panel lists them.
• In a project imported from Turtle, the original file carries an origin badge and stays at the top. Deleting it asks for confirmation, because Reveal and sync depend on it. See Importing a Turtle file.

Keyboard

The tree is a single stop in the tab order. Once it has focus:

The Dolfin editor

.dlf files open in the Dolfin editor. It checks your source as you type, completes names, explains symbols and fixes common mistakes for you.

As you type

Quick fixes

When a problem has a mechanical fix, the editor offers it in two places:

• A line reading 💡 fix — click to insert above the affected block. Click it to apply the fix.
• The tooltip of the underlined text, which lists the same fix as a button.

The fix is also a button on the problem’s row in the Problems panel. A fix may edit another file, or create one: Declare concept Person in people.dlf adds the declaration to people.dlf.

Right-click menu

Right-click in the editor. What the menu shows depends on where you click.

The Go to definition, Peek info, Find all references and Rename symbol items appear once the language service has started, a second or two after the page loads.

The Turtle editor has a shorter menu.

Keyboard

The usual editing keys work: undo and redo, search and replace, bracket matching. See Keyboard shortcuts for the full list.

Editing together

When someone else has the same file open, you see their cursor and selection in their colour, labelled with their name, and their edits appear as they type. Undo only undoes your own edits. See Collaboration.

Who can edit

On a project shared with you as Viewer, the editor is read-only: you can select, copy, hover, search, reveal and go to definition, but Cut, Paste, Rename symbol and quick fixes are not offered. The same goes for an Editor whose plan does not include editing shared projects. See Collaboration.

Problems, hints and quick fixes

The Problems panel runs along the bottom of the workspace. It lists what is wrong, or could be better, in every file of the project, not only the open one.

Reading the panel

The header sums up the project: ❌ 3 errors, ⚠ 2 warnings, or ✓ No problems. Click the header to fold or unfold the panel; drag its top edge to resize it.

Below, problems are grouped by file. Click a file name to fold its group. Each row shows:

❌ 14:12  unknown property `titel` in fact `hobbit`   [Replace with `title`]
          did you mean `title`?

While your latest edit is being checked, the list is dimmed with ⟳ updating… and cannot be clicked, so you never apply a fix to a problem that is already gone.

Severities and filters

Untick a filter to hide that severity. The counts in the header always include everything.

The file tree also shows error and warning counts next to each file.

Quick fixes

A problem with a mechanical fix has a button on its row, labelled with what it will do. Click it to apply the edit. The same fix is offered in the editor, as a 💡 … — click to insert line above the block and in the tooltip of the underlined text (see The Dolfin editor).

A fix can change another file than the one with the problem. It is saved like any edit, and the problem disappears once the project is checked again.

What is checked

Besides syntax errors, which come with a hint when the parser can guess what you meant, the checker reports the following. For what the language allows, see the Dolfin language documentation.

Errors

Warnings

Hints

When the project does not compile

The outputs keep the last version that compiled, dimmed, with a note such as Showing the last valid graph; the current source doesn’t parse yet. See Problems below. The Turtle download is disabled until the errors are fixed. See Compiled output.

Compiled output: Parse, Turtle, SVG

The output panel on the right of the workspace has seven tabs. This page covers the first three, which show what the compiler makes of your source. The others are Graph, SPARQL, Deployments and History.

The ? at the end of the tab bar starts a short guided tour of the tabs.

Output follows the saved source

Every tab updates a moment after your edit is saved. When the source stops compiling (you are half-way through typing a concept, say), the tabs do not go blank: they keep the last output that compiled, dimmed, under a note such as:

Showing the last valid Turtle; the current source doesn’t compile yet, so the download is disabled. See Problems below.

The reason is in the Problems panel. When nothing has ever compiled, the tab says so instead.

Parse

The parse tree of the open file: the syntax exactly as the compiler reads it. Useful to check how an indented block or an annotation was understood.

If the file has syntax errors, the tab lists them instead, each with its Ln, Col position (click it to jump there) and a hint when there is one.

Turtle

The whole project compiled to RDF Turtle, with syntax colouring: exactly what a deployment serves and what the triple store holds for your schema. Named queries of the project appear as # Query: … blocks.

• ⬇ Download .ttl saves it as <package name>-<package version>.ttl (both come from the package settings). The button is disabled while the output is out of date.
• Reveal in turtle export, in the editor’s right-click menu, switches to this tab and highlights the block generated for a declaration. See Reveal.

SVG

A diagram of the open file: its concepts, their fields and the relations between them.

⬇ Download .svg saves the diagram as <file name>.svg.

When other people have the project open, their visible area can be shown as a labelled frame. Right-click the SVG tab to Show others’ viewports or Hide others’ viewports. See Collaboration.

For an interactive view of the whole project, use the Graph tab.

Graph

The Graph tab draws the whole project as an interactive graph. You can rearrange it, navigate from it to your source, and act on concepts and files through right-click menus.

What you see

Nodes that do not belong to the open file are faded, so the file you are working on stands out. Hover a node to read its description. Hover a property (an arrow, a field row inside a box, or a property node) to read its # comment. A field or arrow without its own comment shows the comment of the top-level property of the same name, marked [inherited]. With neither, you see its signature, Domain -> Range, with cardinalities.

Moving around

The layout, zoom included, is saved with the project: you find it as you left it, and so do the people you share the project with.

Going to the source

Hover a node: a ⌖ target appears at the right of its header. Click it to open the file at the declaration.

From the editor, right-click a name and choose Reveal in graph: the Graph tab opens, centres on the node and highlights it.

Right-click a node

Right-click a property arrow

A has line draws an arrow from the concept to the property’s type. Right-click the arrow or its label for the same menu, acting on that has line: Go to… opens it, Copy id gives animals:owner, Edit… shows the line with its axioms, Rename puts a text box on the label and renames the property everywhere it is used, New sub-property… proposes the arrow’s concept and type as domain and range, Delete… removes the line, and Center in view centres on the arrow.

Right-click a file frame

The round + button at the top left of the graph opens a menu with Concept and Property, which do the same in the open file.

Every change is written to the .dlf source, then the graph redraws. People with the file open see the change in their editor right away, and it appears in the file’s history like any other save.

The editing items and buttons are not offered on a public project.

Right-click the Graph tab

When other people have the project open, right-click the Graph tab title to choose what you see of them:

Nodes someone else drags move on your screen too. See Collaboration.

When the graph is empty or dimmed

• Graph renders here after save: nothing has been saved yet.
• No concepts to draw yet. Write a concept and save.: the project compiles but declares no concept.
• The graph needs source that parses.: nothing has compiled yet; the Problems panel says why.
• A dimmed graph under Showing the last valid graph… is the last version that compiled.

SPARQL

The SPARQL tab runs read-only SPARQL 1.1 SELECT and ASK queries, either against your current work or against a deployment, without leaving the editor.

Choosing what to query

The first drop-down picks the data:

In both cases the project’s rules are applied, so inferred triples are part of the answer.

Writing and running a query

• The @prefix declarations of the Turtle tab are added to your query for you, so you can write ex:Book without a PREFIX line. For a deployment, they use the IRIs that deployment was published with.
• Run the query with the button or Ctrl+Enter (⌘+Enter on a Mac).
• A SELECT shows a table. IRIs are shortened to prefix:name and quantities shown as value unit; hover a cell for its full value. An ASK shows ASK → true or false.

Saved queries

The second drop-down, Saved queries…, has two groups:

Pick a query to load it in the editor box.

To query deployments from your own code, see the deployment’s API section in Deployments. To query them from an AI assistant, see Connecting AI assistants (MCP).

Deployments

Deploying compiles the project and publishes it behind a live write API: programs holding a token can then add triples that follow your schema, and query them with SPARQL.

Deploying

Press Deploy in the sidebar.

The first time for a project, Agrafe asks Publish this project? and shows what will go out: the package name and version, the number of files, and the endpoint POST /api/data/<deployment-id>/triples. Deploying uses the files as they are saved right now. Later deploys go straight through.

Then a dialog shows:

Full API reference → opens the API section of the new deployment.

Each Deploy creates a new deployment with its own id and tokens. To publish changes under the same id, use Update instead. The number of active deployments depends on your plan.

The Deployments tab

Only people who can edit the project see Tokens and Update, and only the owner sees the trash button (see Collaboration). Each deployment is listed with its date, its status (active or not), its version and its size, for example v2 · 184 triples (58 schema · 11 fact · 115 data).

The API

The API section of a deployment lists its endpoints:

Every call needs the header Authorization: Bearer <token>. SPARQL answers are application/sparql-results+json and only see this deployment.

It also shows each concept with its properties, their type and whether they are required, an example request, and a Try it form: paste a token, fill in a subject, a predicate and a value, and Send writes that triple.

To explore the deployed data interactively, use the SPARQL tab.

History

Agrafe keeps versions of your files as you save them; small edits saved within about 15 seconds of each other are merged into one version. The History tab lists them, lets you compare any version with the current file and bring an old one back.

The timeline

Versions of all files are listed newest first, each with its file, its date and, for a grouped version, its group name. File: narrows the list to one file; All files shows them all again.

The newest version of each file is marked HEAD: it is the file as it is now. Older versions may show as (pruned): they fell outside what your plan keeps.

Versions in a group are always kept.

With one file selected, Graph view draws its history as a branch graph; List view goes back to the list.

Comparing and restoring

Click a version to open it next to the current file: a purple Diff: file @ version tab replaces the editor, with the differences highlighted. Close the tab (or click HEAD) to return to the editor.

On the selected version, press and hold Restore. Its content is saved as a new version on top of the current one: nothing in the history is lost, and you can restore the newer version again.

Grouping versions

Tick the boxes of several versions to act on them together:

Groups are listed at the top of the timeline. Rename one with its pencil or delete it with its trash; deleting a group keeps its versions.

Collaboration

Sharing a project

On the Projects page, the owner opens Share on a project card, types an email address, picks a role and presses Send invite. The person receives an email; once they accept, the project appears under Shared with you on their Projects page. The same dialog lists People with access; the ✕ next to a name removes that person.

Roles

“With a Pro plan” refers to the editor’s own plan. Without it, an Editor works as a Viewer. A badge at the top of the sidebar reminds you of your role on a shared project.

When you cannot edit a project, the controls that would change it are hidden: Deploy, New file and Import, the file tree’s rename and delete actions and right-click menus, the graph’s file menu, quick fixes, token management and Update on deployments. Save package settings stays visible but disabled.

The owner’s plan still sets the project’s limits (number of files, of deployments).

To leave a project shared with you, use Settings → Shared.

Working at the same time

Several people can have the same project open. Everything is live:

• Who is here: the avatars of the other people who have the project open appear in the top bar. Hover one for the name.
• Editing: when two people open the same file, each sees the other’s cursor and selection, labelled with a name and a colour, and the text changes as they type. Ctrl+Z undoes only your own edits.
• Graph: nodes someone drags move on your screen too.
• Where the others look: right-click the Graph or SVG tab title to show or hide the others’ visible area (Show others’ viewports) and, on the graph, their pointer (Show others’ mouse).

Public projects

The owner can make a project public with the Public switch, on the project card or in the sidebar. Anyone, signed in or not, can then open it read-only at /public/<project id>, and it is listed on the Public projects page (/public).

A visitor sees the file tree, the source, the outputs, the graph, the SPARQL console, the deployments and their API documentation. They cannot edit, deploy, share, open the package settings or the history, and their graph moves are not saved.

The number of public projects you can have depends on your plan.

Account settings

Click your avatar in the top bar to open Settings. The sections are listed on the left.

The theme switch in the top bar (System, Light, Dark) is not a setting of your account: it is remembered by your browser, and shared with the other Dolfin apps.

Keyboard and mouse

On a Mac, read ⌘ for Ctrl.

Dolfin and Turtle editors

Workspace

Graph and SVG

Hold buttons

Delete and restore buttons must be held until their fill completes. A quick click only shows a reminder.

Importing a Turtle file

Agrafe can create a project from an existing Turtle (.ttl) ontology, so you do not have to retype it in Dolfin.

How to import

1. Open the project list and choose Import from Turtle.
2. Pick a .ttl or .turtle file. It must be UTF-8 text.
3. A new project appears with the placeholder name New project. Rename it inline, exactly as after New project.

If the file cannot be read, you get an error (Could not read turtle: …) and no project is created: the Turtle is translated before anything is stored.

Imported projects always start private and count against your private-project limit. The import is refused if your licence has expired, if you are at your project limit, or if the generated Dolfin files would exceed your per-project file limit.

What you get

• Dolfin files. The Turtle is translated to .dlf files. Each entity goes into the file named by its rdfs:isDefinedBy triple; Turtle without that information is split by IRI structure. See Turtle & OWL Correspondence for the exact rules.
• package.dlf. Built from the Turtle’s owl:Ontology metadata. If the Turtle has none, a default manifest is generated.
• The original Turtle. It is stored in the project as a normal file named <file name>.ttl and recorded as the project’s origin. Everything that follows (the editor, Reveal, sync and Re-translate) works on this file.

The base IRI of the project is the subject of the Turtle’s owl:Ontology. It is recorded once at import, and later features reuse it so that translation and sync always agree.

The origin file in the file tree

The origin file is pinned at the top of the tree with an origin badge. Otherwise it behaves like any file:

• It is editable, collaborative, versioned and included in project ZIP exports.
• You can rename it. The project remembers it by identity, not by name.
• It does not count against the per-project file limit.
• It is ignored by everything Dolfin: compilation, linting, the wire format and deployments only look at .dlf files.

Deleting the origin file

Deleting the origin asks for confirmation:

This is the project’s original Turtle file. Deleting it breaks “Reveal in turtle source” and syncing Dolfin edits back to Turtle. Delete anyway?

If you confirm, the project stops being a turtle-origin project: the origin, the sync baseline and the sync state are removed. Reveal falls back to Reveal in turtle export, and there is no automatic sync or Re-translate any more.

Projects imported before this feature

Older imported projects have no origin: the original Turtle was discarded at import and cannot be recovered. They keep working normally, and Reveal in turtle export is available, but they have no sync and no Re-translate. To get the full feature, import the Turtle again as a new project.

Other .ttl files

You can add other .ttl files to a project. They open in the Turtle editor and are otherwise ignored, but they are not an origin: no sync, no Re-translate, no Reveal in dolfin.

The Turtle editor

Any .ttl or .turtle file in a project opens in a Turtle editor instead of the Dolfin one. It never runs Dolfin diagnostics on the file.

What it does

Completion does not yet offer the namespaces of your Dolfin files; a Turtle imported into Agrafe already declares them in its own @prefix lines.

Context menu

Right-click in the Turtle editor for Cut, Copy, Select word and Paste. In the origin file there is also Reveal in dolfin, described in Reveal.

Editing the origin file

Editing the origin Turtle by hand is supported. Two things follow:

• The Dolfin files do not change on their own. Use Re-translate to Dolfin to bring your edits over.
• While the Turtle has a syntax error, sync is blocked (nothing is written to it) until you fix the error.

Reveal

Reveal jumps between a Dolfin declaration and its Turtle. Right-click a word in the editor to use it.

From Dolfin to Turtle

In a Dolfin file, right-click a name. The menu has Reveal in graph and one of two Turtle items, depending on the project:

What you can reveal

• concepts and properties;
• the name of a has field;
• an enum value inside one of:;
• the id of a fact.

Any other word (for example the type at the end of has owner: Person) is looked up as a concept or property name.

Which statement

A declaration corresponds to all Turtle statements whose subject is its IRI; Reveal shows the first one in the file. If there are several, a message says Showing the first of N statements. In the export, a concept with a one of: list has two blocks; the first (the class declaration) is shown.

A has field corresponds to its property, so a property shared by two concepts (has name on both) reveals the same statement from either. An enum value corresponds to its individual. A concept with an @iri_name override is found by that exact IRI.

When nothing is found

• No turtle counterpart: the declaration is new or renamed and the Turtle has not caught up yet (see sync), or the word is not a declaration.
• An error message if the origin Turtle does not parse.

From Turtle to Dolfin

In the origin Turtle editor, right-click a prefixed name or an <IRI> and choose Reveal in dolfin. The matching Dolfin file opens with the declaration selected. The item exists only in the origin file, not in other .ttl files.

• On a predicate, a keyword or anything that is not a declaration, Reveal uses the subject of the statement you clicked in. Right-clicking rdfs:domain inside ex:Dog … reveals Dog.
• When one IRI maps to several declarations, the order of preference is concept, property, fact, enum value, field.
• The Dolfin source is read as it is now, not as it was at import, so it keeps working after you edit either side.

Messages:

• No dolfin counterpart (not in dolfin yet? use Re-translate): you added the class to the Turtle by hand. See Re-translate.
• No dolfin counterpart found: N dolfin file(s) have syntax errors: Reveal skips Dolfin files that do not parse.

A concept that carries a concept-level @iri_name cannot be revealed from the Turtle yet; it gives the miss message.

Keeping Turtle and Dolfin in sync

In a turtle-origin project, every change you save in a Dolfin file is written back into the original Turtle automatically. You never have to export by hand.

When it runs

• Three seconds after you save a .dlf file. Further saves within those three seconds are merged into one run.
• When you delete or rename a .dlf file.

It runs once at a time per project and never for edits to package.dlf or to the Turtle itself.

What is changed in the Turtle

Sync compares what Dolfin produced at the last sync with what it produces now, subject by subject, and touches only the subjects that differ.

• A changed declaration has its statement rewritten in place, using the Turtle’s own prefixes (missing prefixes are added after the last directive).
• A new declaration is appended after its concept’s last statement, or at the end of the file.
• A deleted declaration has its statements removed.
• Everything else is left byte for byte: untouched statements, comments and blank lines between statements, and Turtle that Dolfin does not model (“foreign” statements, for example your own annotations) even on a subject that is rewritten.

Limits

• Comments inside a rewritten statement are lost. Comments between statements are kept.
• A rewritten statement uses the serializer’s layout, not yours, and blank nodes come back with generated labels (_:ts…).
• A restriction or list whose blank nodes no longer match is replaced as a whole (it is listed as Degraded in the report).
• Changes to package.dlf (version, author, description) are not copied to the Turtle.
• Renaming a .dlf file changes its namespace and therefore the IRI of everything in it. Sync treats it as removing the old subjects and adding the new ones.

The status chip

The project toolbar shows a chip for turtle-origin projects. Click it for details.

While blocked, no edit is lost: sync keeps its reference point and applies the whole difference once it can run.

Details

The popover shows the last report:

• Updated, Added, Removed: the subjects sync touched;
• Degraded: blank-node structures replaced as a whole;
• Missing: subjects sync wanted to remove or change but could not find, because you already edited them in the Turtle (skipped);
• the number of non-Dolfin statements kept.

Undo last sync

Undo last sync restores the Turtle as it was before the last sync, and survives a restart. It is refused if you edited the Turtle by hand since, or if it was already used.

Undo changes only the Turtle: the Dolfin edits that were synced stay. Turtle and Dolfin then differ until you change those declarations again or use Re-translate. Later edits sync normally.

If the Turtle is open while sync writes

If someone has the Turtle open, sync edits it as normal text operations, so other people’s cursors and selections are not disturbed. If the text changed under it, sync retries once and then reports error: concurrent edit.

Re-translate to Dolfin

Re-translate to Dolfin regenerates the Dolfin files from the current Turtle. Use it after you edited the origin Turtle by hand, or after adding a class there that has no Dolfin declaration yet.

It overwrites Dolfin files, so it always shows a preview first and never touches a file you did not tick.

Start it from the Re-translate to Dolfin… button in the origin Turtle’s toolbar, or from ⟳ Re-translate to Dolfin… in the origin file’s context menu in the file tree.

The dialog

The Turtle is translated exactly as at import, then compared with your current Dolfin files. Each file gets a status:

package.dlf is never ticked by default: your version, author and description are only overwritten if you tick it.

Click a file name to see a side-by-side diff: current Dolfin on the left, after re-translate on the right.

The footer says how many files will be replaced. Confirm with Replace N file(s).

If the Turtle has a syntax error, the dialog shows it with its line and column and does nothing.

Safety

• Previous contents stay restorable from each file’s version history.
• Afterwards the project’s sync reference is set to the new Dolfin files, so the automatic sync that follows finds nothing to do and does not write anything back.
• Edits you saved in the last three seconds in files you did not tick are treated as already synced.
• If something fails halfway, the chip shows error: partial re-translate — run Re-translate again and automatic sync is switched off. Run Re-translate again: files already written show as unchanged, and it finishes the rest.
• The file limit still applies to added files (the origin Turtle and package.dlf are not counted).

Connecting AI assistants (MCP)

Agrafe is a remote Model Context Protocol server. An MCP client such as Claude can read your deployed ontologies, run SPARQL queries against them and read your project glossaries, with your own permissions.

What it exposes

You can access your own projects and projects shared with you (accepted invitations), with their deployments. A deployment or project that does not exist and one you cannot access give the same error.

run_sparql_query returns at most 1000 rows. When more rows match, a second message says the result was truncated; page with LIMIT and OFFSET. A query still running after 10 seconds is cancelled.

Scopes

A client that asks for no scope gets every scope it is allowed. A tool called without its scope answers access denied: missing <scope> scope. Connectors registered before glossary:read was offered to MCP clients must be reconnected to get it.

Connecting

Claude (claude.ai)

Add a custom connector with the URL https://agrafe.dolfin.fr/mcp. Claude registers itself as a public OAuth client (no secret, PKCE), sends you to Agrafe to log in and authorize, and connects. No configuration file is needed.

Claude Desktop and other stdio clients

Settings → MCP in Agrafe shows a ready-to-copy configuration that bridges through mcp-remote:

{
  "mcpServers": {
    "agrafe": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://agrafe.dolfin.fr/mcp/sse"]
    }
  }
}

Use Copy config and paste it into claude_desktop_config.json.

Endpoints

For integrators. Both transports are supported:

initialize answers with the protocol version the client asked for when it is one of 2025-06-18, 2025-03-26 or 2024-11-05. Otherwise it answers with the newest, 2025-06-18, or with 2024-11-05 if the client sent no version.

On the streamable transport, POST /mcp takes one JSON-RPC request and returns one JSON response; batches are not supported. The response to initialize carries an Mcp-Session-Id header. Send it on every later request:

GET /mcp with the session header opens a Server-Sent Events stream for messages from the server. Opening a new one replaces the previous stream. DELETE /mcp ends the session. A session with no open stream expires one hour after its last request.

Supported methods: initialize, ping, resources/list, resources/read, tools/list, tools/call, prompts/list, prompts/get. Any notifications/* message is acknowledged and ignored.

The server advertises resources.listChanged. When a project gets a new deployment, every open stream of every user who can access that project (owner or accepted share) receives notifications/resources/list_changed: the GET /mcp stream on the streamable transport, the /mcp/sse stream on the SSE transport. A streamable session with no GET /mcp stream open gets no notification. resources/subscribe is not supported: a deployment never changes once created.

Authorization is OAuth 2.1 with PKCE (S256):

Rate limits

POST /mcp, DELETE /mcp and POST /mcp/message are rate-limited per access token: 100 requests per minute by default (RATE_LIMIT_RPM on the server), counted separately from the data API. Over the limit, a request gets 429 Too Many Requests; wait and retry. Opening a stream (GET /mcp or GET /mcp/sse) is not limited. There is no per-plan query quota.

An unauthenticated request gets 401 with WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource", which is how a client discovers where to log in.

Behind a proxy

The SSE stream needs unbuffered responses. Agrafe sends X-Accel-Buffering: no, so nginx does not stall the handshake; other proxies must not buffer /mcp/sse either. HOST=https://… splash-graph/check-mcp.sh checks discovery, OAuth registration, both transports and the buffering.