xpp-mcp
# xpp-mcp
An MCP server for Dynamics 365 Finance and Operations X++ development. It reads and edits X++ artifacts, keeps
`.rnrproj`/`.sln` files in step with them, and drives the Visual Studio that is already open on your solution for
builds, live cross-references and database synchronization.
**It needs two packages, and it does not work without both:**
| Package | What it is | Where it lives |
| --- | --- | --- |
| `@artman41/xpp-mcp-vs` | The MCP server (Node.js, stdio). Its executable is `xpp-mcp`. | GitHub Packages (npm) |
| `XppMcp.VsBridge.vsix` | The Visual Studio extension. It lets the server talk to your open IDE over a per-user named pipe. | Attached to the `v0.16.0` GitHub release |
The server answers references, project membership, builds and sync from the running Visual Studio, so Visual Studio
must be open with your X++ solution loaded.
## Requirements
- Windows, with PowerShell
- Node.js 22 or later
- Visual Studio 2022 (17.x; Community, Professional or Enterprise) with the Dynamics 365 Finance and Operations tools
- .NET Framework 4.8
## Setup
### 1. Install the Visual Studio extension
Download the vsix (or take it from the release page) and install it:
```powershell
Invoke-WebRequest https://github.com/artman41/xpp-mcp/releases/download/v0.16.0/XppMcp.VsBridge.vsix -OutFile XppMcp.VsBridge.vsix
```
Close Visual Studio, double-click the file and follow the installer, then reopen Visual Studio and your solution.
The extension starts with Visual Studio and listens on a named pipe restricted to your Windows user.
### 2. Install the MCP server
The server is published to GitHub Packages, which needs a token even for public packages. Create a GitHub personal
access token with the `read:packages` scope, then point the `@artman41` scope at the registry and authenticate once:
```powershell
npm config set "@artman41:registry" https://npm.pkg.github.com
npm config set "//npm.pkg.github.com/:_authToken" <your-token>
npm install -g "@artman41/xpp-mcp-vs"
```
The server and the extension must come from the same release; install the vsix matching the version you installed here.
### 3. Write a config file (optional)
Without a config file everything is read-only. Copy `config.example.json` (shipped in the package) somewhere and edit
it:
```json
{
"dataDirectory": ".xpp-mcp/data",
"policies": {
"allowWrites": false,
"allowBuilds": false,
"allowDatabaseSynchronization": false,
"allowEndpointMutations": false
},
"databaseSync": {
"target": { "server": "localhost", "database": "AxDB" }
}
}
```
| Key | Meaning |
| --- | --- |
| `policies.allowWrites` | Allow source, project, solution and artifact changes to be written. Off: every mutating tool can only dry-run. |
| `policies.allowBuilds` | Allow `build_project`, `build_solution` and `build_model` to run. |
| `policies.allowDatabaseSynchronization` | Allow `db_sync`. |
| `policies.allowEndpointMutations` | Allow OData/DMF/custom-service mutations. |
| `databaseSync.target` | The only database a local sync may touch (`server` and `database` must match what Visual Studio reports). |
| `databaseSync.allowCloudRuntime` / `finOpsUri` | Opt-in for syncs against CloudRuntime / online environments. |
| `timeouts`, `referenceIndex`, `build.maxOutputBytes` | Bounds on processes, HTTP calls, result sizes and build output. |
| `environment.connectCommand` | Visual Studio command used to start the Dataverse connection wizard. |
Paths in the config are resolved relative to the config file.
### 4. Register it with your MCP client
Any stdio MCP client works. For example, in a `.mcp.json`:
```json
{
"mcpServers": {
"xpp": {
"command": "xpp-mcp",
"env": { "XPP_MCP_CONFIG": "C:\\path\\to\\config.json" }
}
}
}
```
Leave `XPP_MCP_CONFIG` out for the read-only defaults. Logs go to stderr; stdout carries only protocol messages.
With Visual Studio open on your solution, call `server_status` to confirm the server is running, then `ide_solution_projects`
to confirm it can see the IDE.
## What it provides
Every change defaults to a dry-run that returns a diff. Writes are validated first, use atomic replacement, and keep
the file's encoding and newline style. A failed multi-file change leaves nothing half-applied.
**Server**
- `server_status`: version, safety policies and configured resource counts.
- `resolve_path`: resolve a file or directory visible to the solution loaded in Visual Studio.
**Live Visual Studio queries**
- `ide_solution_projects`, `ide_project_items`: the projects, models and elements as the IDE sees them.
- `ide_references`: find references from the IDE's live cross-reference store.
- `ide_definition`: every model that defines an element, with layer and the element file.
- `ide_search`: search artifact names of one AOT element type (Class, Table, Form, security roles and so on).
- `ide_type_relations`: bases, derived classes, interface implementers and attribute users.
**Reference graph**
- `reference_tree`, `reference_resolve`, `reference_references`: browse by package, model, type, artifact and member, and read typed incoming/outgoing edges.
- `reference_impact`: bounded dependents or dependencies at artifact level.
- `reference_graph`: class dependency graph with members and module boundaries.
- `reference_extensions`: extension elements, chain-of-command classes, event handlers and delegate subscribers that hook into an artifact.
- `reference_labels`: label ids (`@File:Id`) to text.
- `reference_reindex`: rebuild a model's cross-reference data when queries come back empty.
- `reference_status`, `reference_refresh`: freshness and provenance of the data; drop cached project membership.
**Source files**
- `source_read`, `source_parse`, `source_validate`, `source_write`: read, parse and validate Dynamics XML and X++ (lexical and structural checks, not compiler-level semantics), and replace a file safely with an expected-hash conflict check.
**Artifacts** (68 fixture-backed types, for example Class, Table, Edt, Enum, Form, labels and resources)
- `artifact_registry`: supported types and the ones that are unavailable.
- `artifact_design`, `artifact_build`: generate XML and create the artifact, with optional `.rnrproj` membership.
- `artifact_validate`, `artifact_update`: validate, update and rename, reconciling project memberships.
- `artifact_remove`: remove after an impact report; needs `confirm=true`.
`artifact_build` creates the metadata files. It does not compile X++.
**Projects and solutions**
- `project_inspect`, `project_update`: parse and validate `.rnrproj` files; create or update them with reconciled artifacts.
- `solution_inspect`, `solution_update`: enumerate, add, remove and reorder X++ projects in a `.sln`, keeping dependencies and configuration rows in step.
**Builds and database** (run in the open Visual Studio; need `allowBuilds` / `allowDatabaseSynchronization`)
- `build_project`, `build_solution`, `build_model`: compile with bounded diagnostics and logs. Builds are serialized.
- `db_sync`: full database synchronization with preflight checks. A local sync only runs against `databaseSync.target`, and `confirmDatabase` must equal its name.
**Environment**
- `environment_info`: the Dataverse / online F&O environment Visual Studio is connected to.
- `environment_connect`: starts Visual Studio's own connection wizard and waits for you to finish signing in.
## Troubleshooting
- **Tools report that Visual Studio is not available:** Visual Studio is not running, the extension is not installed, or no solution is open. Reopen Visual Studio and check the extension is enabled under Extensions > Manage Extensions.
- **A write or build is refused:** the matching policy in your config is still `false`.
- **Several Visual Studio instances:** the server picks the one whose solution matches the target; open only the solution you are working on if it picks the wrong one.
## Development
```powershell
npm install
npm run build
npm run typecheck
npm run lint
npm test
```
CI (`.github/workflows/ci.yml`) runs lint and tests on every push and pull request, and publishes
`@artman41/xpp-mcp-vs` to GitHub Packages on a push to `master` whose version is not published yet.
The extension source is in `vs-extension/`. It is **not** built in CI: it compiles against the Dynamics 365 Finance
and Operations tools and Power Platform Tools assemblies from your local Visual Studio installation, which cannot be
redistributed to a hosted runner. Build it on a machine that has them and attach the vsix to the GitHub release:
```powershell
# override DynamicsToolsDir / PowerPlatformToolsDir if your Visual Studio edition is not Professional
msbuild vs-extension\XppMcp.VsBridge.csproj /restore /p:Configuration=Release
```
## License
MIT. See `LICENSE`.
TDQS
Scored across 38 tools
Prefix grouping helps, but several tools target nearly the same question through different backends: reference_references vs ide_references (both find references), reference_impact vs reference_graph vs ide_type_relations (all dependency traversal), and solution_inspect vs ide_solution_projects vs project_inspect vs ide_project_items (project/solution enumeration). The descriptions do explain the distinction (cached xref store vs live IDE, artifact vs class granularity), so an attentive agent can pick, but the boundaries require careful reading.
Clear domain prefixes (reference_, source_, project_, solution_, artifact_, build_, ide_, environment_, db_) followed by verb or noun, mostly verb_noun (source_parse, artifact_validate, build_model). A few noun-only outliers (reference_tree, artifact_registry, environment_info) and the mix of project_/solution_/ide_ prefixes for overlapping concepts are minor deviations rather than a breakdown.
38 tools is well past the 25-tool threshold and a handful are near-redundant or thin utility calls (reference_refresh, reference_status, server_status, resolve_path, artifact_registry) that inflate the surface. The domain is genuinely broad (xref, IDE, source, project, artifact, build, environment, DB), but the set could be consolidated meaningfully.
Coverage is strong: read/parse/validate/write for sources, design/build/update/remove for artifacts, inspect/update for projects and solutions, three build scopes, cross-reference querying and reindexing, plus environment and DB sync. Minor gaps remain — no delete/rename for projects or solutions, no test execution or rollback, and no explicit 'list artifacts in project' beyond ide_project_items.