dataverse-modelling-mcp
CLAUDE.md8 starsChanged 41 days agoMITView on GitHub
Everything in this repository is written in English: commit messages, PR titles and bodies, branch names, code, comments, tool descriptions, error messages, docs and skills — also when the conversation with the user is in another language. Two deliberate exceptions: - Search keywords in skill descriptions — German terms such as "Geschäftsprozessfluss" stay in a skill's description, so that the skill is also picked for a German request. - Test data that reproduces real content — e.g. the German e-mail…
- Commits and pushes
In this repository7 other files it gives its agents.
- business-process-flowsSkill
- classic-workflowsSkill
- cloud-flowsSkill
- command-bar-buttonsSkill
- form-authoringSkill
- modeling-patternsSkill
- solution-pipelinesSkill
The file
We split this CLAUDE.md into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 20
Everything in this repository is written in English: commit messages, PR titles and bodies, branch names, code, comments, tool …
- Very specific: line 122
Do not commit local dev artefacts (ws-log.json, screenshots) — they are gitignored.
- Distinctive: line 128
Create a feature branch and open a PR (against master)
- Very specific: line 143
No session restart needed: .mcp.json does not start the binary directly but the launcher scripts/run-server.ps1, which on every server …
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
dataverse-modelling-mcp
Build
dotnet build
Test
dotnet test
Run (local MCP server)
dotnet run --project src/Dataverse.Server
Setup (first time or after update)
dotnet run --project src/Dataverse.Setup
Pack (dotnet tool)
dotnet pack src/Dataverse.Setup -c Release
Language
Everything in this repository is written in English: commit messages, PR titles and bodies, branch names, code, comments, tool descriptions, error messages, docs and skills — also when the conversation with the user is in another language.
Two deliberate exceptions:
- Search keywords in skill descriptions — German terms such as "Geschäftsprozessfluss" stay in a
skill's
description, so that the skill is also picked for a German request. - Test data that reproduces real content — e.g. the German e-mail texts in the workflow fixtures, or strings that test umlaut handling.
LanguageTests fails the build when German text shows up anywhere else; its allowlist names the
exceptions. Older commit messages are partly German; they stay, because rewriting the history would
detach the release tags the launcher downloads from.
Two repositories
The project lives in two repositories, and both trees are meant to be identical:
hydr/dataverse-modelling-mcp(public) — the publication. Releases, with the binary and NuGet asset, are built here.crossvertise/dataverse-modelling-mcp(private) — the internal working repository. It carries the unsanitised commit history and the PR discussions with internal references; that is why it stays private.
Releases are built in the public repository only. scripts/BINARY_VERSION and the default of
the release_repo option point to the public repository in both repositories, so the launcher
always downloads the binary from there. A tag in the private repository would create a second,
unused release of the same version — so do not tag there.
No company internals in the public repository
The public repository is deliberately anonymised (#26, #35). No identifier from a real
environment may go into it — not in docs, code comments or tool descriptions, nor in tests,
commit messages or PR texts. This has happened before (v1.19.0 carried 77 xv_* and 46
Crossvertise* occurrences, cleaned up in 1.20.0), and a release cannot be taken back afterwards.
| Instead of | Use |
A real org's publisher prefix, e.g. xv_ | sample_ |
| Real solution names | Contoso… (e.g. ContosoForms, ContosoOrders) |
| Real tables and columns | sample_widget, sample_score, … |
| Real namespaces of code components | Contoso.DocumentViewer |
| GUIDs from an environment | recognisably synthetic ones (11111111-1111-1111-1111-111111110001) |
Real versionnumber values, dependency counts, solution landscapes | synthetic values or no number at all |
Standard Dataverse tables (account, contact, invoice, salesorder, product) are harmless
and stay. So does the publisher identity of the repository in LICENSE, SECURITY.md,
README.md, .claude-plugin/plugin.json, .claude-plugin/marketplace.json and Dataverse.Setup.csproj — that one is intended.
Check before committing:
git grep -I -i -E "xv_|crossvertise|xvdev|xvstaging" -- docs src tests skills README.mdHits outside the identity files named above are an error. The same goes for git log -p on your own
commits, because commit messages can no longer be corrected once a tag has been set.
For live tests against a real environment this means: anonymise results before they go into a
file. The test environment itself may of course be real — only its identifiers do not belong in
the repository. One exception is the pre-existing integration test SolutionIntegrationTests.cs,
which needs a real MetadataId as its fixture.
Skills
Skills belong in skills/ — this directory ships with the plugin and is therefore active in
every repository the plugin is installed in. Not in .claude/skills/: that restricts them to this
repository, i.e. to precisely the one environment where Dataverse knowledge is needed least.
Skills are plain Markdown files with no tie to the binary — changing them needs no new binary. For clients to pick them up, though, the plugin version has to go up, and it is coupled to binary and tool (see Release process). So: bump all three version files, merge, tag. The release then rebuilds a functionally identical binary — the price of keeping the version number unambiguous.
Docs travel with the fix
A finding that only exists in the code does not exist for the next agent. So with every change, also update:
| What changes | Where |
| New validation code | Code table in skills/classic-workflows/SKILL.md |
| New field in the definition model | SKILL.md |
| New tool | Tool map in SKILL.md and docs/tools/<area>.md |
| Finding about the XAML format | docs/classic-workflows-reference.md |
| BPF: new code, new model field, new tool | skills/business-process-flows/SKILL.md (tools also docs/tools/business-process-flows.md) |
| BPF: finding about the XAML format | docs/business-process-flows-reference.md |
DocumentationCoverageTests checks the first three (and the BPF row) automatically and fails when
something is missing — only the fourth point relies on discipline.
Git conventions
- Feature branches, never directly on
master. Naming:feature/<topic>for features,chore/<topic>for housekeeping,fix/<topic>for bug fixes. - Changes land via pull requests against
master. One logical step per commit, one topic per branch/PR. - Commit and push regularly — small commits while working instead of one big drop at the end.
- Check the current branch before starting (
git branch --show-current) and decide whether to continue there or open a new branch. - Do not commit local dev artefacts (
ws-log.json, screenshots) — they are gitignored.
Release process (for every change)
For changes to the MCP server always — steps 1 to 3 in both repositories, step 4 only in the public one (see Two repositories):
- Create a feature branch and open a PR (against
master) Raise the version (minor for new features, patch for bug fixes) — in all three files to exactly the same value, which is also the release tag:
src/Dataverse.Setup/Dataverse.Setup.csproj→<Version>scripts/BINARY_VERSION(hook and launcher download the binary fromreleases/download/v<BINARY_VERSION>/…).claude-plugin/plugin.json→version
The release workflow compares all three with the tag and aborts on any mismatch. Keep
<Version>insrc/Dataverse.Server/Dataverse.Server.csprojin step too: the feedback event reports it asserverVersion.- Merge the PR
- Set a git tag in the public repository (
git tag v<Version> && git push origin v<Version>) → triggers the release workflow (NuGet publish + GitHub release including the server binary asset)
Using a new version in a running session
No session restart needed: .mcp.json does not start the binary directly but the launcher
scripts/run-server.ps1, which on every server start brings the binary to the version pinned in
scripts/BINARY_VERSION and then starts it (stdio passed through unchanged).
So after a release: update the plugin (so that BINARY_VERSION is right), then reconnect the
server dataverse-modelling in the /mcp menu — done.
Details on binary delivery: see docs/GH-RELEASE-SETUP.md.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

