PayrollEngine.Mcp.Core 0.10.0-beta.4

Payroll Engine MCP Core

Part of the Payroll Engine open-source payroll automation framework. Full documentation at payrollengine.org.

Core infrastructure for building Payroll Engine MCP servers. Provides the base classes, isolation model, and permission system shared across all MCP server implementations — both read-only and write-enabled.

NuGet Package

Available as a private GitHub Package:

dotnet add package PayrollEngine.Mcp.Core

Overview

PayrollEngine.Mcp.Core is the foundation for any MCP server that exposes Payroll Engine data to AI agents. It defines:

• Isolation model — tenant, division, and employee scoping enforced at the infrastructure level
• Permission system — role-based tool visibility controlled at startup
• ToolBase — abstract base class for all MCP tool classes; provides typed service factories, identifier resolvers, isolation-aware query helpers, and uniform error handling
• ToolRegistrar — filters tool classes by role permission and isolation level compatibility at registration time

Isolation Level

Controls which records are returned at runtime. Enforcement is server-side and cannot be bypassed by the AI agent.

Roles and Permissions

Controls which tools are registered at startup. Each tool class is tagged with a [ToolRole] attribute declaring its role and minimum permission. A tool whose role is not granted is never registered — invisible to the AI agent.

Role × Isolation Level Compatibility

✓ = role applicable ✗ = not applicable at this isolation level

Architecture

IsolationContext

Singleton populated at startup from appsettings.json or environment variables. Holds the active IsolationLevel, tenant/division/employee identifiers, and McpPermissions. Injected into every tool class via the constructor.

ToolBase

Abstract base class for all MCP tool classes. Constructor injection: PayrollHttpClient + IsolationContext.

Key capabilities:

ToolRegistrar

Scans an assembly for classes decorated with [McpServerToolType] and filters them by:

1. [ToolRole] attribute — role and minimum permission check
2. Role × IsolationLevel compatibility matrix

Classes without [ToolRole] are always registered (e.g. ServerInfoTools).

ToolRoleAttribute

Applied to MCP tool classes to declare their role and minimum required permission:

[McpServerToolType]
[ToolRole(McpRole.HR, McpPermission.Read)]
public sealed class EmployeeQueryTools(PayrollHttpClient http, IsolationContext iso)
    : ToolBase(http, iso) { ... }

Extending: Building a Custom MCP Server

Any MCP server — read-only or write-enabled — inherits the full infrastructure by referencing this package:

<PackageReference Include="PayrollEngine.Mcp.Core" Version="0.10.0-beta.3" />

A write tool follows the same pattern as a read tool:

[McpServerToolType]
[ToolRole(McpRole.Payroll, McpPermission.Read)]
public sealed class CaseChangeTools(PayrollHttpClient http, IsolationContext iso)
    : ToolBase(http, iso)
{
    [McpServerTool(Name = "create_case_change")]
    public async Task<string> CreateCaseChangeAsync(...)
    {
        try
        {
            var (context, employee) = await ResolveEmployeeAsync(...);
            // write logic
        }
        catch (Exception ex) { return Error(ex); }
    }
}

All isolation enforcement, resolver logic, and error handling are inherited automatically.

Related Repositories

License

MIT License — free for personal and commercial use.