This commit is contained in:
mika kuns
2026-04-24 18:26:11 +02:00
commit ec42e8e4bd
28 changed files with 1205 additions and 0 deletions

View File

@@ -0,0 +1,22 @@
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net8.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
<AssemblyName>claude-mailbox</AssemblyName>
<RootNamespace>ClaudeMailbox</RootNamespace>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="8.0.11" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="8.0.11">
<PrivateAssets>all</PrivateAssets>
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
</PackageReference>
<PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.1" />
<PackageReference Include="ModelContextProtocol" Version="1.2.0" />
<PackageReference Include="ModelContextProtocol.AspNetCore" Version="1.2.0" />
</ItemGroup>
</Project>

View File

@@ -0,0 +1,104 @@
using System.Net.Http.Json;
using System.Text.Json;
namespace ClaudeMailbox.Cli;
public static class ClientCommands
{
private const string DefaultUrl = "http://127.0.0.1:47822";
public static async Task<int> RunAsync(string[] args)
{
var command = args[0];
var url = GetOption(args, "--url") ?? DefaultUrl;
using var client = new HttpClient { BaseAddress = new Uri(url) };
try
{
return command switch
{
"send" => await Send(args, client),
"peek" => await Peek(args, client),
"check" => await Check(args, client),
"list" => await List(client),
_ => PrintError($"Unknown command: {command}"),
};
}
catch (HttpRequestException ex)
{
Console.Error.WriteLine($"Could not reach daemon at {url}: {ex.Message}");
Console.Error.WriteLine("Is 'claude-mailbox serve' running?");
return 2;
}
}
private static async Task<int> Send(string[] args, HttpClient client)
{
var to = Required(args, "--to");
var from = Required(args, "--from");
var body = Required(args, "--body");
var req = new HttpRequestMessage(HttpMethod.Post, "/v1/send")
{
Content = JsonContent.Create(new { to, body }),
};
req.Headers.Add("X-Mailbox", from);
var res = await client.SendAsync(req);
res.EnsureSuccessStatusCode();
Console.WriteLine(await res.Content.ReadAsStringAsync());
return 0;
}
private static async Task<int> Peek(string[] args, HttpClient client)
{
var name = Required(args, "--name");
var res = await client.GetAsync($"/v1/peek?name={Uri.EscapeDataString(name)}");
res.EnsureSuccessStatusCode();
Console.WriteLine(await res.Content.ReadAsStringAsync());
return 0;
}
private static async Task<int> Check(string[] args, HttpClient client)
{
var name = Required(args, "--name");
var req = new HttpRequestMessage(HttpMethod.Post, $"/v1/check-inbox?name={Uri.EscapeDataString(name)}");
req.Headers.Add("X-Mailbox", name);
var res = await client.SendAsync(req);
res.EnsureSuccessStatusCode();
Console.WriteLine(await res.Content.ReadAsStringAsync());
return 0;
}
private static async Task<int> List(HttpClient client)
{
var res = await client.GetAsync("/v1/list");
res.EnsureSuccessStatusCode();
Console.WriteLine(await res.Content.ReadAsStringAsync());
return 0;
}
public static string? GetOption(string[] args, string name)
{
for (var i = 0; i < args.Length - 1; i++)
if (args[i] == name) return args[i + 1];
return null;
}
private static string Required(string[] args, string name)
{
var v = GetOption(args, name);
if (string.IsNullOrWhiteSpace(v))
throw new ArgumentException($"Missing required option {name}");
return v;
}
private static int PrintError(string msg)
{
Console.Error.WriteLine(msg);
return 1;
}
}

View File

@@ -0,0 +1,13 @@
namespace ClaudeMailbox.Config;
public sealed class DaemonConfig
{
public const int DefaultPort = 47822;
public const string DefaultBindAddress = "127.0.0.1";
public int Port { get; init; } = DefaultPort;
public string BindAddress { get; init; } = DefaultBindAddress;
public string DbPath { get; init; } = Paths.DefaultDbPath();
public string BaseUrl => $"http://{BindAddress}:{Port}";
}

View File

@@ -0,0 +1,23 @@
namespace ClaudeMailbox.Config;
public static class Paths
{
public static string Expand(string path)
{
if (string.IsNullOrWhiteSpace(path)) return path;
var expanded = Environment.ExpandEnvironmentVariables(path);
if (expanded.StartsWith("~"))
{
var home = Environment.GetFolderPath(Environment.SpecialFolder.UserProfile);
expanded = home + expanded[1..];
}
return Path.GetFullPath(expanded);
}
public static string DefaultDbPath()
{
var home = Environment.GetFolderPath(Environment.SpecialFolder.UserProfile);
return Path.Combine(home, ".claude-mailbox", "mailbox.db");
}
}

View File

@@ -0,0 +1,18 @@
using ClaudeMailbox.Data.Models;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Metadata.Builders;
namespace ClaudeMailbox.Data.Configuration;
public sealed class MailboxConfiguration : IEntityTypeConfiguration<Mailbox>
{
public void Configure(EntityTypeBuilder<Mailbox> builder)
{
builder.ToTable("mailboxes");
builder.HasKey(m => m.Name);
builder.Property(m => m.Name).HasColumnName("name").IsRequired();
builder.Property(m => m.CreatedAt).HasColumnName("created_at").IsRequired();
builder.Property(m => m.LastSeenAt).HasColumnName("last_seen_at").IsRequired();
}
}

View File

@@ -0,0 +1,34 @@
using ClaudeMailbox.Data.Models;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Metadata.Builders;
namespace ClaudeMailbox.Data.Configuration;
public sealed class MessageConfiguration : IEntityTypeConfiguration<Message>
{
public void Configure(EntityTypeBuilder<Message> builder)
{
builder.ToTable("messages");
builder.HasKey(m => m.Id);
builder.Property(m => m.Id).HasColumnName("id").ValueGeneratedOnAdd();
builder.Property(m => m.ToMailbox).HasColumnName("to_mailbox").IsRequired();
builder.Property(m => m.FromMailbox).HasColumnName("from_mailbox").IsRequired();
builder.Property(m => m.Body).HasColumnName("body").IsRequired();
builder.Property(m => m.CreatedAt).HasColumnName("created_at").IsRequired();
builder.Property(m => m.DeliveredAt).HasColumnName("delivered_at");
builder.HasOne<Mailbox>()
.WithMany()
.HasForeignKey(m => m.ToMailbox)
.OnDelete(DeleteBehavior.Restrict);
builder.HasOne<Mailbox>()
.WithMany()
.HasForeignKey(m => m.FromMailbox)
.OnDelete(DeleteBehavior.Restrict);
builder.HasIndex(m => new { m.ToMailbox, m.DeliveredAt })
.HasDatabaseName("ix_messages_to_delivered");
}
}

View File

@@ -0,0 +1,34 @@
using ClaudeMailbox.Data.Models;
using Microsoft.EntityFrameworkCore;
namespace ClaudeMailbox.Data;
public class MailboxDbContext : DbContext
{
public MailboxDbContext(DbContextOptions<MailboxDbContext> options) : base(options) { }
public DbSet<Mailbox> Mailboxes => Set<Mailbox>();
public DbSet<Message> Messages => Set<Message>();
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
modelBuilder.ApplyConfigurationsFromAssembly(typeof(MailboxDbContext).Assembly);
}
public static void EnsureReady(MailboxDbContext db)
{
var dir = Path.GetDirectoryName(db.Database.GetDbConnection().DataSource);
if (!string.IsNullOrEmpty(dir))
Directory.CreateDirectory(dir);
var conn = db.Database.GetDbConnection();
conn.Open();
using (var cmd = conn.CreateCommand())
{
cmd.CommandText = "PRAGMA journal_mode=WAL;";
cmd.ExecuteNonQuery();
}
db.Database.EnsureCreated();
}
}

View File

@@ -0,0 +1,8 @@
namespace ClaudeMailbox.Data.Models;
public sealed class Mailbox
{
public required string Name { get; set; }
public DateTime CreatedAt { get; set; }
public DateTime LastSeenAt { get; set; }
}

View File

@@ -0,0 +1,11 @@
namespace ClaudeMailbox.Data.Models;
public sealed class Message
{
public long Id { get; set; }
public required string ToMailbox { get; set; }
public required string FromMailbox { get; set; }
public required string Body { get; set; }
public DateTime CreatedAt { get; set; }
public DateTime? DeliveredAt { get; set; }
}

View File

@@ -0,0 +1,33 @@
using ClaudeMailbox.Data.Models;
using Microsoft.EntityFrameworkCore;
namespace ClaudeMailbox.Data.Repositories;
public sealed class MailboxRepository
{
private readonly MailboxDbContext _db;
public MailboxRepository(MailboxDbContext db) => _db = db;
public async Task<Mailbox> UpsertAsync(string name, CancellationToken ct = default)
{
var now = DateTime.UtcNow;
var row = await _db.Mailboxes.FirstOrDefaultAsync(m => m.Name == name, ct);
if (row is null)
{
row = new Mailbox { Name = name, CreatedAt = now, LastSeenAt = now };
_db.Mailboxes.Add(row);
}
else
{
row.LastSeenAt = now;
}
await _db.SaveChangesAsync(ct);
return row;
}
public async Task<IReadOnlyList<Mailbox>> ListAsync(CancellationToken ct = default)
{
return await _db.Mailboxes.AsNoTracking().OrderBy(m => m.Name).ToListAsync(ct);
}
}

View File

@@ -0,0 +1,77 @@
using ClaudeMailbox.Data.Models;
using Microsoft.EntityFrameworkCore;
namespace ClaudeMailbox.Data.Repositories;
public sealed class MessageRepository
{
private readonly MailboxDbContext _db;
private readonly MailboxRepository _mailboxes;
public MessageRepository(MailboxDbContext db, MailboxRepository mailboxes)
{
_db = db;
_mailboxes = mailboxes;
}
public async Task<Message> SendAsync(string from, string to, string body, CancellationToken ct = default)
{
await _mailboxes.UpsertAsync(from, ct);
await _mailboxes.UpsertAsync(to, ct);
var message = new Message
{
FromMailbox = from,
ToMailbox = to,
Body = body,
CreatedAt = DateTime.UtcNow,
DeliveredAt = null,
};
_db.Messages.Add(message);
await _db.SaveChangesAsync(ct);
return message;
}
public async Task<InboxStatus> PeekAsync(string name, CancellationToken ct = default)
{
var pending = await _db.Messages.AsNoTracking()
.Where(m => m.ToMailbox == name && m.DeliveredAt == null)
.OrderBy(m => m.Id)
.Select(m => m.CreatedAt)
.ToListAsync(ct);
return new InboxStatus(pending.Count, pending.FirstOrDefault() == default ? null : pending.First());
}
public async Task<IReadOnlyList<Message>> CheckInboxAsync(string name, CancellationToken ct = default)
{
// Atomic pull-and-mark: a transaction guarantees that two concurrent calls
// don't deliver the same message twice.
await using var tx = await _db.Database.BeginTransactionAsync(ct);
var pending = await _db.Messages
.Where(m => m.ToMailbox == name && m.DeliveredAt == null)
.OrderBy(m => m.Id)
.ToListAsync(ct);
var now = DateTime.UtcNow;
foreach (var m in pending)
m.DeliveredAt = now;
await _db.SaveChangesAsync(ct);
await tx.CommitAsync(ct);
return pending;
}
public async Task<int> PendingCountForAsync(string recipient, string sender, CancellationToken ct = default)
{
return await _db.Messages.AsNoTracking()
.CountAsync(m =>
m.ToMailbox == recipient &&
m.FromMailbox == sender &&
m.DeliveredAt == null, ct);
}
}
public sealed record InboxStatus(int Pending, DateTime? OldestAt);

View File

@@ -0,0 +1,22 @@
using Microsoft.AspNetCore.Http;
namespace ClaudeMailbox.Http;
public sealed class MailboxContextAccessor
{
private readonly IHttpContextAccessor _http;
public MailboxContextAccessor(IHttpContextAccessor http) => _http = http;
public string Current
{
get
{
var name = _http.HttpContext?.Items[MailboxHeaderMiddleware.ItemsKey] as string;
if (string.IsNullOrWhiteSpace(name))
throw new InvalidOperationException(
"No mailbox name on request. Set the X-Mailbox header in your .mcp.json.");
return name;
}
}
}

View File

@@ -0,0 +1,48 @@
using ClaudeMailbox.Data.Repositories;
using Microsoft.AspNetCore.Http;
namespace ClaudeMailbox.Http;
public sealed class MailboxHeaderMiddleware
{
public const string HeaderName = "X-Mailbox";
public const string ItemsKey = "Mailbox";
private readonly RequestDelegate _next;
public MailboxHeaderMiddleware(RequestDelegate next) => _next = next;
public async Task InvokeAsync(HttpContext ctx, MailboxRepository mailboxes)
{
// Health is always anonymous.
if (ctx.Request.Path.StartsWithSegments("/health"))
{
await _next(ctx);
return;
}
var name = ctx.Request.Headers[HeaderName].ToString().Trim();
// These endpoints work without identity (discovery / read-only status).
var path = ctx.Request.Path;
var isAnonymous =
path.Equals("/v1/list", StringComparison.OrdinalIgnoreCase) ||
path.Equals("/v1/peek", StringComparison.OrdinalIgnoreCase);
if (string.IsNullOrWhiteSpace(name))
{
if (isAnonymous)
{
await _next(ctx);
return;
}
ctx.Response.StatusCode = 400;
await ctx.Response.WriteAsync($"Missing {HeaderName} header.");
return;
}
ctx.Items[ItemsKey] = name;
await mailboxes.UpsertAsync(name, ctx.RequestAborted);
await _next(ctx);
}
}

View File

@@ -0,0 +1,78 @@
using System.Reflection;
using ClaudeMailbox.Config;
using ClaudeMailbox.Data.Repositories;
namespace ClaudeMailbox.Http;
public static class RestEndpoints
{
public static void MapMailboxEndpoints(this WebApplication app)
{
app.MapGet("/health", (DaemonConfig cfg) => Results.Ok(new
{
status = "ok",
version = Assembly.GetEntryAssembly()?.GetName().Version?.ToString() ?? "unknown",
dbPath = cfg.DbPath,
}));
var group = app.MapGroup("/v1");
group.MapPost("/send", async (
SendRequest body,
MailboxContextAccessor accessor,
MessageRepository messages,
CancellationToken ct) =>
{
if (string.IsNullOrWhiteSpace(body.To) || string.IsNullOrWhiteSpace(body.Body))
return Results.BadRequest(new { error = "to and body are required" });
var from = accessor.Current;
var msg = await messages.SendAsync(from, body.To, body.Body, ct);
return Results.Ok(new { id = msg.Id, queuedAt = msg.CreatedAt });
});
group.MapGet("/peek", async (
string name,
MessageRepository messages,
CancellationToken ct) =>
{
var status = await messages.PeekAsync(name, ct);
return Results.Ok(new { pending = status.Pending, oldestAt = status.OldestAt });
});
group.MapPost("/check-inbox", async (
string name,
MailboxContextAccessor accessor,
MessageRepository messages,
CancellationToken ct) =>
{
// Require the caller to be consuming their own inbox.
if (!string.Equals(name, accessor.Current, StringComparison.Ordinal))
return Results.StatusCode(403);
var pulled = await messages.CheckInboxAsync(name, ct);
return Results.Ok(pulled.Select(m => new
{
id = m.Id,
from = m.FromMailbox,
body = m.Body,
sentAt = m.CreatedAt,
}));
});
group.MapGet("/list", async (
MailboxRepository mailboxes,
CancellationToken ct) =>
{
var all = await mailboxes.ListAsync(ct);
return Results.Ok(all.Select(m => new
{
name = m.Name,
createdAt = m.CreatedAt,
lastSeenAt = m.LastSeenAt,
}));
});
}
public sealed record SendRequest(string To, string Body);
}

View File

@@ -0,0 +1,70 @@
using System.ComponentModel;
using ClaudeMailbox.Data.Repositories;
using ClaudeMailbox.Http;
using ModelContextProtocol.Server;
namespace ClaudeMailbox.Mcp;
public sealed record SendResult(long Id, DateTime QueuedAt);
public sealed record InboxMessage(long Id, string From, string Body, DateTime SentAt);
public sealed record InboxStatusDto(int Pending, DateTime? OldestAt);
public sealed record MailboxInfo(string Name, DateTime LastSeenAt, int PendingForYou);
[McpServerToolType]
public sealed class MailboxTools
{
private readonly MailboxContextAccessor _accessor;
private readonly MailboxRepository _mailboxes;
private readonly MessageRepository _messages;
public MailboxTools(
MailboxContextAccessor accessor,
MailboxRepository mailboxes,
MessageRepository messages)
{
_accessor = accessor;
_mailboxes = mailboxes;
_messages = messages;
}
[McpServerTool, Description("Send a message to another mailbox. The sender is the current session's X-Mailbox name.")]
public async Task<SendResult> Send(
[Description("Name of the recipient mailbox.")] string to,
[Description("Message body (plain text or markdown).")] string body,
CancellationToken ct)
{
var from = _accessor.Current;
var msg = await _messages.SendAsync(from, to, body, ct);
return new SendResult(msg.Id, msg.CreatedAt);
}
[McpServerTool, Description("Pull all undelivered messages for the current mailbox and mark them delivered. Returns an empty array when the inbox is empty.")]
public async Task<IReadOnlyList<InboxMessage>> CheckInbox(CancellationToken ct)
{
var name = _accessor.Current;
var pulled = await _messages.CheckInboxAsync(name, ct);
return pulled.Select(m => new InboxMessage(m.Id, m.FromMailbox, m.Body, m.CreatedAt)).ToList();
}
[McpServerTool, Description("Check whether the current mailbox has undelivered messages, without consuming them. Cheap; safe to call often.")]
public async Task<InboxStatusDto> PeekInbox(CancellationToken ct)
{
var name = _accessor.Current;
var status = await _messages.PeekAsync(name, ct);
return new InboxStatusDto(status.Pending, status.OldestAt);
}
[McpServerTool, Description("List all known mailboxes with their last-seen timestamp and how many messages each has queued for the current mailbox.")]
public async Task<IReadOnlyList<MailboxInfo>> ListMailboxes(CancellationToken ct)
{
var me = _accessor.Current;
var all = await _mailboxes.ListAsync(ct);
var result = new List<MailboxInfo>(all.Count);
foreach (var m in all)
{
var pending = await _messages.PendingCountForAsync(me, m.Name, ct);
result.Add(new MailboxInfo(m.Name, m.LastSeenAt, pending));
}
return result;
}
}

View File

@@ -0,0 +1,47 @@
using ClaudeMailbox;
using ClaudeMailbox.Cli;
using ClaudeMailbox.Config;
if (args.Length > 0 && args[0] is "send" or "peek" or "check" or "list")
{
return await ClientCommands.RunAsync(args);
}
// Strip the optional leading "serve" verb so WebApplication.CreateBuilder
// doesn't try to treat it as an unknown flag.
var serveArgs = (args.Length > 0 && args[0] == "serve") ? args[1..] : args;
var cfg = new DaemonConfig
{
Port = ParseInt(serveArgs, "--port", DaemonConfig.DefaultPort),
BindAddress = ClientCommands.GetOption(serveArgs, "--bind") ?? DaemonConfig.DefaultBindAddress,
DbPath = Paths.Expand(ClientCommands.GetOption(serveArgs, "--db-path") ?? Paths.DefaultDbPath()),
};
var builder = ServerHost.CreateBuilder(cfg, serveArgs);
builder.WebHost.UseUrls(cfg.BaseUrl);
var app = builder.Build();
ServerHost.ConfigurePipeline(app);
app.Logger.LogInformation("ClaudeMailbox listening on {Url} (db: {Db})", cfg.BaseUrl, cfg.DbPath);
try
{
await app.RunAsync();
return 0;
}
catch (IOException ex) when (ex.Message.Contains("address already in use", StringComparison.OrdinalIgnoreCase)
|| ex.Message.Contains("Only one usage", StringComparison.OrdinalIgnoreCase))
{
Console.Error.WriteLine($"Port {cfg.Port} is already in use. Another claude-mailbox instance may be running.");
return 3;
}
static int ParseInt(string[] args, string name, int fallback)
{
var raw = ClientCommands.GetOption(args, name);
return int.TryParse(raw, out var v) ? v : fallback;
}
public partial class Program { }

View File

@@ -0,0 +1,46 @@
using ClaudeMailbox.Config;
using ClaudeMailbox.Data;
using ClaudeMailbox.Data.Repositories;
using ClaudeMailbox.Http;
using ClaudeMailbox.Mcp;
using Microsoft.EntityFrameworkCore;
namespace ClaudeMailbox;
public static class ServerHost
{
public static WebApplicationBuilder CreateBuilder(DaemonConfig cfg, string[]? args = null)
{
var builder = WebApplication.CreateBuilder(args ?? Array.Empty<string>());
builder.Services.AddSingleton(cfg);
builder.Services.AddHttpContextAccessor();
builder.Services.AddDbContext<MailboxDbContext>(opt =>
opt.UseSqlite($"Data Source={cfg.DbPath}"));
builder.Services.AddScoped<MailboxRepository>();
builder.Services.AddScoped<MessageRepository>();
builder.Services.AddScoped<MailboxContextAccessor>();
builder.Services.AddScoped<MailboxTools>();
builder.Services.AddMcpServer()
.WithHttpTransport()
.WithTools<MailboxTools>();
return builder;
}
public static void ConfigurePipeline(WebApplication app)
{
using (var scope = app.Services.CreateScope())
{
MailboxDbContext.EnsureReady(
scope.ServiceProvider.GetRequiredService<MailboxDbContext>());
}
app.UseMiddleware<MailboxHeaderMiddleware>();
app.MapMailboxEndpoints();
app.MapMcp("/mcp");
}
}