DataverseMCPToolBox.Extensibility
0.2.260204-beta
dotnet add package DataverseMCPToolBox.Extensibility --version 0.2.260204-beta
NuGet\Install-Package DataverseMCPToolBox.Extensibility -Version 0.2.260204-beta
<PackageReference Include="DataverseMCPToolBox.Extensibility" Version="0.2.260204-beta" />
<PackageVersion Include="DataverseMCPToolBox.Extensibility" Version="0.2.260204-beta" />
<PackageReference Include="DataverseMCPToolBox.Extensibility" />
paket add DataverseMCPToolBox.Extensibility --version 0.2.260204-beta
#r "nuget: DataverseMCPToolBox.Extensibility, 0.2.260204-beta"
#:package DataverseMCPToolBox.Extensibility@0.2.260204-beta
#addin nuget:?package=DataverseMCPToolBox.Extensibility&version=0.2.260204-beta&prerelease
#tool nuget:?package=DataverseMCPToolBox.Extensibility&version=0.2.260204-beta&prerelease
DataverseMCPToolBox.Extensibility
Extensibility SDK for building MCP (Model Context Protocol) plugins that extend the DataverseMCPToolBox with custom Dataverse operations.
Overview
The DataverseMCPToolBox.Extensibility package provides a comprehensive framework for developing plugins that expose MCP-compliant tools for Dataverse operations. Plugins are:
- Distributed as NuGet packages for easy installation and versioning
- Dynamically loaded by the Core Server at runtime
- Isolated with proper lifecycle management
- Type-safe with automatic JSON schema generation
- MCP-compliant with standardized tool interfaces
Key Features
- Plugin Architecture: Implement
IPlugininterface for complete lifecycle management (initialization and disposal) - Automatic Tool Discovery: Two approaches:
- Attribute-based: Decorate methods with
[McpTool]for automatic registration - Manual registration: Override
GetTools()for explicit tool registration
- Attribute-based: Decorate methods with
- Strongly-Typed Tools: Use
McpToolBase<TInput, TOutput>for type-safe implementations with:- Automatic parameter deserialization (camelCase JSON → PascalCase C#)
- Input validation against JSON Schema
- Exception handling and error formatting
- JSON Schema Generation: Automatic schema generation from C# types using NJsonSchema
- Dataverse Integration: Direct access to:
- Authenticated
IOrganizationServiceAsync2service client - Connection metadata (URL, connection ID)
- Cancellation tokens for async operations
- Authenticated
- MCP Compliance:
- Kebab-case naming enforcement (e.g.,
create-record,list-entities) - Standardized error codes and messages
- Structured error details
- Kebab-case naming enforcement (e.g.,
- Development Experience:
- IntelliSense support with XML documentation
- Helper utilities (SchemaGenerator)
- Comprehensive examples and samples
Quick Start
1. Create a Plugin Class
using DataverseMCPToolBox.Extensibility;
using DataverseMCPToolBox.Extensibility.Abstractions;
using DataverseMCPToolBox.Extensibility.Attributes;
[McpPlugin("my-dataverse-plugin", "1.0.0",
Author = "Your Name",
Description = "Custom Dataverse operations plugin")]
public class MyDataversePlugin : PluginBase
{
[McpTool("Lists all user accounts in the Dataverse organization")]
public async Task<object> ListUsers(IDataverseContext context, CancellationToken cancellationToken)
{
var query = new QueryExpression("systemuser")
{
ColumnSet = new ColumnSet("fullname", "internalemailaddress")
};
var results = await context.ServiceClient.RetrieveMultipleAsync(query, cancellationToken);
return results.Entities.Select(e => new
{
Name = e.GetAttributeValue<string>("fullname"),
Email = e.GetAttributeValue<string>("internalemailaddress")
}).ToList();
}
}
2. Using Strongly-Typed Tools
public class CreateAccountInput
{
public string Name { get; set; }
public string? Email { get; set; }
}
public class CreateAccountOutput
{
public Guid AccountId { get; set; }
public string Name { get; set; }
}
[McpPlugin("account-plugin", "1.0.0")]
public class AccountPlugin : PluginBase
{
public class CreateAccountTool : McpToolBase<CreateAccountInput, CreateAccountOutput>
{
public CreateAccountTool()
: base("create-account", "Creates a new account record in Dataverse")
{
}
protected override async Task<CreateAccountOutput> ExecuteAsync(
CreateAccountInput parameters,
IDataverseContext context,
CancellationToken cancellationToken)
{
var account = new Entity("account");
account["name"] = parameters.Name;
if (!string.IsNullOrEmpty(parameters.Email))
account["emailaddress1"] = parameters.Email;
var accountId = await context.ServiceClient.CreateAsync(account, cancellationToken);
return new CreateAccountOutput
{
AccountId = accountId,
Name = parameters.Name
};
}
}
public override IEnumerable<IMcpTool> GetTools()
{
yield return new CreateAccountTool();
}
}
Key Interfaces
IPlugin
Defines plugin lifecycle: InitializeAsync(IServiceProvider) and Dispose()
IToolProvider
Exposes tools via GetTools() method
IDataverseContext
Provides:
IOrganizationServiceAsync2 ServiceClient- Authenticated Dataverse clientstring ConnectionId- Connection identifierstring OrganizationUrl- Organization URLCancellationToken CancellationToken- Cancellation support
IMcpTool
Defines MCP tool contract:
string Name- Kebab-case tool name (e.g., "list-entities")string Description- Human-readable descriptionJsonSchema InputSchema- Parameter validation schemaTask<ToolExecutionResult> ExecuteAsync(...)- Execution method
Attributes
[McpPlugin]
Marks a class as a plugin with metadata:
[McpPlugin("plugin-name", "1.0.0",
Author = "Author Name",
Description = "Plugin description")]
[McpTool]
Marks a method in PluginBase as a tool:
[McpTool("Description of what the tool does")]
public async Task<object> ToolMethod(IDataverseContext context) { ... }
Base Classes
PluginBase
Abstract base class with automatic tool discovery from [McpTool] decorated methods.
McpToolBase<TInput, TOutput>
Generic base class for strongly-typed tools with automatic:
- Parameter deserialization (camelCase JSON)
- Schema generation from
TInputtype - Schema validation
- Error handling
- Kebab-case name enforcement
Naming Conventions
Tool Names
- MUST be in kebab-case format:
list-entities,create-record,whoami - Enforced at construction time in
McpToolBase - Invalid names throw
ArgumentException
Parameter Serialization
- C# properties use
PascalCase - JSON parameters use
camelCase(auto-converted) - Example:
public string UserName { get; set; }→"userName"in JSON
Error Handling
ToolExecutionException
Throw this exception to return structured errors:
throw new ToolExecutionException(
"ENTITY_NOT_FOUND",
"The specified entity does not exist",
new { entityId = id });
Error Codes
Standard error codes:
VALIDATION_ERROR- Invalid input parametersEXECUTION_ERROR- General execution failureDATAVERSE_ERROR- Dataverse SDK errorAUTHORIZATION_ERROR- Permission deniedOPERATION_CANCELLED- Cancelled by user/timeout
Plugin Discovery
Plugins are discovered via assembly scanning:
var assemblies = LoadPluginAssemblies();
var manifests = PluginManifest.DiscoverPlugins(assemblies);
Installation
Via NuGet Package Manager
dotnet add package DataverseMCPToolBox.Extensibility
Via .NET CLI
dotnet nuget install DataverseMCPToolBox.Extensibility
Package Manager Console (Visual Studio)
Install-Package DataverseMCPToolBox.Extensibility
Requirements
- .NET 8.0 or later
- C# 12 or later (for latest language features)
- NuGet Package Manager
Dependencies
This SDK automatically includes:
- Microsoft.PowerPlatform.Dataverse.Client (v1.1.32) - Official Dataverse SDK
- NJsonSchema (v11.0.2) - JSON Schema generation and validation
- Newtonsoft.Json (v13.0.3) - JSON serialization with camelCase support
Plugin Distribution
Building and Packaging
Create your plugin project targeting
net8.0:dotnet new classlib -n MyDataversePlugin -f net8.0 cd MyDataversePlugin dotnet add package DataverseMCPToolBox.ExtensibilityImplement your plugin (see Quick Start examples below)
Build in Release mode:
dotnet build --configuration ReleasePackage as NuGet:
dotnet pack --configuration ReleasePublish your plugin:
- Public: Publish to NuGet.org
- Private: Use Azure Artifacts, GitHub Packages, or private NuGet feed
- Local: Place
.nupkgfile in plugin directory
Plugin Installation (End Users)
Users install your plugin via the VS Code Extension:
- Open Dataverse MCP Toolbox panel
- Navigate to Plugins section
- Click "Install Plugin"
- Enter package ID:
YourPluginName - Plugin is automatically downloaded, extracted, and loaded
Example Plugin Structure
MyDataversePlugin/
├── MyDataversePlugin.csproj # Project file with package metadata
├── README.md # Plugin documentation (included in NuGet)
├── MyPlugin.cs # Main plugin class (PluginBase implementation)
├── Tools/
│ ├── ListEntitiesTool.cs # Individual tool implementations
│ ├── CreateRecordTool.cs
│ └── QueryDataTool.cs
├── Models/
│ ├── ListEntitiesInput.cs # Input DTOs (PascalCase properties)
│ ├── ListEntitiesOutput.cs # Output DTOs
│ ├── CreateRecordInput.cs
│ └── CreateRecordOutput.cs
└── Helpers/ # Optional utility classes
└── DataverseHelper.cs
Best Practices
- ✅ Use kebab-case for all tool names (enforced by
McpToolBase) - ✅ PascalCase for C# properties, auto-converted to camelCase in JSON
- ✅ Implement IDisposable properly if managing resources
- ✅ Use CancellationToken for all async operations
- ✅ Throw ToolExecutionException for structured errors
- ✅ Log to stderr only, never to stdout
- ✅ Include README.md in your NuGet package
- ✅ Version your plugin semantically (e.g., 1.0.0, 1.1.0, 2.0.0)
- ✅ Document parameters with XML comments for IntelliSense
Troubleshooting
Common Issues
"Tool name must be in kebab-case format"
- Ensure tool names use hyphens:
list-entities, notListEntitiesorlist_entities
"Cannot load plugin assembly"
- Verify your plugin targets
net8.0 - Check all dependencies are compatible
"JSON Schema validation failed"
- Ensure input models have public getters/setters
- Check property types are JSON-serializable
"Dataverse operation failed"
- Verify connection is active before executing operations
- Check entity logical names and attribute names
- Review Dataverse SDK error messages
Version History
0.1.0-alpha (Current)
- Initial release of Extensibility SDK
- Core interfaces:
IPlugin,IMcpTool,IDataverseContext - Base classes:
PluginBase,McpToolBase<TInput, TOutput> - Attributes:
[McpPlugin],[McpTool] - JSON Schema generation with NJsonSchema
- Automatic camelCase/PascalCase conversion
- Standard error handling with
ToolExecutionException
License
MIT License - See LICENSE file for details.
Documentation
Comprehensive guides available:
Repository
GitHub: https://github.com/tchinnin/dataverse-mcp-toolbox
Support
For questions, issues, or feature requests:
- Issues: GitHub Issues
- Discussions: GitHub Discussions
Contributing
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Submit a pull request with clear description
See CONTRIBUTING.md for guidelines.
Related Packages
- DataverseMCPToolBox.Runtime - Core Server and MCP Bridge binaries
- DataverseMCPToolBox.WhoAmI - Sample plugin implementation
Author
Théophile CHIN-NIN
- GitHub: @tchinnin
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net8.0
- Microsoft.PowerPlatform.Dataverse.Client (>= 1.1.32)
- Newtonsoft.Json (>= 13.0.3)
- NJsonSchema (>= 11.0.2)
NuGet packages (2)
Showing the top 2 NuGet packages that depend on DataverseMCPToolBox.Extensibility:
| Package | Downloads |
|---|---|
|
DataverseMCPToolBox.Runtime
Runtime package for Dataverse MCP Toolbox. Contains Core Server and Bridge binaries for all supported platforms (macOS, Windows, Linux). |
|
|
DataverseMCPToolBox.WhoAmI
WhoAmI plugin for DataverseMCPToolBox - retrieves current Dataverse user information |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.2.260204-beta | 116 | 2/4/2026 |
| 0.1.0-alpha | 99 | 1/23/2026 |