UserManagementMcpServer

A sample .NET 8 MCP server for managing users with SQLite and demonstrating agent runtime hooks.

Features

• MCP server over stdio using ModelContextProtocol
• Interactive console harness for local testing
• SQLite persistence with Entity Framework Core
• User operations:
  • CreateUser
  • GetUser
  • GetAllUsers
• Hook pipeline for:
  • session start
  • prompt auditing
  • pre-tool validation
  • post-tool metrics
  • final response formatting

Requirements

• .NET 8 SDK
• Windows, macOS, or Linux with a terminal

Project Structure

UserManagementMcpServer/
├── UserManagementMcpServer.csproj
├── Program.cs                          ← hosting + transport wiring
├── Models/
│   └── User.cs
├── Context/
│   └── UserDbContext.cs                ← EF Core DbContext
├── Services/
│   └── UserService.cs
├── Tools/
│   └── UserManagementToolsWithHooks.cs ← MCP tool definitions
├── Hooks/
│   ├── IAgentHook.cs                   ← hook interfaces
│   ├── HookContexts.cs                 ← per-hook context types
│   ├── HookService.cs                  ← built-in hook implementations
│   └── AgentHookManager.cs             ← orchestrates hook pipeline
└── Parsing/
    └── IntentParser.cs                 ← console harness only

Run the Console Harness

From the repository root:

dotnet run --project .\UserManagementMcpServer\UserManagementMcpServer.csproj

Available commands:

• create user <Name> <Email>
• get user <Name>
• show all users
• exit

Run as an MCP Server

dotnet run --project .\UserManagementMcpServer\UserManagementMcpServer.csproj -- --mcp

When running in MCP mode:

• stdout is reserved for JSON-RPC messages
• logs are routed to stderr
• the SQLite database is created automatically if it does not exist

Database

The app uses a local SQLite database file:

• users.db

The database is initialized automatically on startup.

Hook Behavior

The sample hook implementations demonstrate:

• session initialization
• tool audit logging
• blocking suspicious usernames such as admin or root
• basic email validation
• execution metrics logging
• final response timestamp formatting

Hook Registration

Register hooks in Program.cs by adding them to the DI container against the appropriate hook interface. AgentHookManager accepts all five lifecycle hook types via constructor injection.

// Register the hook manager itself
builder.Services.AddSingleton<AgentHookManager>();

// SessionStart — fires once when the first tool call arrives
builder.Services.AddSingleton<ISessionStartHook, SessionInitializationHook>();

// UserPromptSubmit — fires for every tool invocation before any validation
builder.Services.AddSingleton<IUserPromptSubmitHook, AuditLoggingHook>();

// PreToolUse — fires immediately before the tool executes; set Cancel = true to block
builder.Services.AddSingleton<IPreToolUseHook, SecurityValidationHook>();

// PostToolUse — fires after the tool completes; result and duration are available
builder.Services.AddSingleton<IPostToolUseHook, MetricsLoggingHook>();

// Stop — fires before the final response is returned to the MCP client
builder.Services.AddSingleton<IStopHook, ResponseFormattingHook>();

Multiple implementations of the same interface can be registered; they execute in Priority order (lower numbers run first).

Build

dotnet build .\UserManagementMcpServer\UserManagementMcpServer.csproj