Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.
feat(server): add MCP health controls (#86)
Leo92e573a93c43
diff --git a/apps/server/src/provider/AkeruCatalogToolHandlers.test.ts b/apps/server/src/provider/AkeruCatalogToolHandlers.test.tsindex b0d75a1ce..432675a21 100644--- a/apps/server/src/provider/AkeruCatalogToolHandlers.test.ts+++ b/apps/server/src/provider/AkeruCatalogToolHandlers.test.ts@@ -1,5 +1,5 @@-import type { McpManager } from "@mastra/code-sdk/mcp/index";-import type { OrchestrationCommand } from "@t3tools/contracts";+import type { McpManager, McpServerStatus } from "@mastra/code-sdk/mcp/index";+import { BotId, type OrchestrationCommand } from "@t3tools/contracts";import { describe, expect, it, vi } from "vite-plus/test";import {@@ -7,6 +7,28 @@ import {createAkeruPluginRuntime,} from "./AkeruCatalogToolHandlers.ts";+const connectedStatus: McpServerStatus = {+ name: "search",+ connected: true,+ toolCount: 1,+ toolNames: ["search_web"],+ transport: "http",+};++function healthOptions(overrides = {}) {+ return {+ getRequestHealth: () => undefined,+ recordSuccess: vi.fn(),+ recordFailure: vi.fn(),+ getDependencies: async () => ({+ dependentBots: [{ id: BotId.make("bot-akeru"), name: "Akeru" }],+ dependentRoutines: [],+ }),+ now: () => "2026-09-01T02:00:00.000Z",+ ...overrides,+ };+}+const now = "2026-01-01T00:00:00.000Z";function snapshot(mcpServers: readonly Record<string, unknown>[] = [],@@ -224,6 +246,80 @@ describe("Akeru catalog MCP tool handlers", () => {expect(dispatch).toHaveBeenCalledOnce();});+ it("reports real request evidence instead of treating a connection as healthy", async () => {+ const manager = { getServerStatuses: () => [connectedStatus] } as unknown as McpManager;+ const handler = createAkeruCatalogToolHandlers(+ manager,+ undefined,+ healthOptions({+ getRequestHealth: () => ({+ health: "failed" as const,+ lastSuccessfulRequestAt: "2026-09-01T01:00:00.000Z",+ lastFailedRequest: { at: "2026-09-01T01:30:00.000Z", message: "OAuth expired." },+ }),+ }),+ ).GetMcpServerStatus!;++ await expect(+ handler({ input: { serverId: "search" }, emitProgress: vi.fn() }),+ ).resolves.toEqual(+ expect.objectContaining({+ connectionState: "connected",+ healthTest: "failed",+ authenticationExpiresAt: null,+ lastFailure: { at: "2026-09-01T01:30:00.000Z", message: "OAuth expired." },+ dependentBots: [{ id: "bot-akeru", name: "Akeru" }],+ dependentRoutines: [],+ }),+ );+ });++ it.each(["TestMcpServer", "ReconnectMcpServer"] as const)(+ "%s records the real reconnect result",+ async (toolId) => {+ const reconnectServer = vi.fn(async () => connectedStatus);+ const manager = {+ getServerStatuses: () => [connectedStatus],+ reconnectServer,+ } as unknown as McpManager;+ const recordSuccess = vi.fn();+ const onRecovery = vi.fn();+ const handler = createAkeruCatalogToolHandlers(+ manager,+ undefined,+ healthOptions({ recordSuccess, onRecovery }),+ )[toolId]!;++ await expect(+ handler({ input: { serverId: "search" }, emitProgress: vi.fn() }),+ ).resolves.toEqual(expect.objectContaining({ connected: true }));+ expect(reconnectServer).toHaveBeenCalledWith("search");+ expect(recordSuccess).toHaveBeenCalledWith("search", "2026-09-01T02:00:00.000Z");+ expect(onRecovery).toHaveBeenCalledOnce();+ },+ );++ it("records and escalates a failed health test", async () => {+ const failed = { ...connectedStatus, connected: false, error: "OAuth expired." };+ const manager = {+ getServerStatuses: () => [connectedStatus],+ reconnectServer: async () => failed,+ } as unknown as McpManager;+ const recordFailure = vi.fn();+ const onFailure = vi.fn();+ const handler = createAkeruCatalogToolHandlers(+ manager,+ undefined,+ healthOptions({ recordFailure, onFailure }),+ ).TestMcpServer!;++ await expect(handler({ input: { serverId: "search" }, emitProgress: vi.fn() })).rejects.toThrow(+ "OAuth expired",+ );+ expect(recordFailure).toHaveBeenCalledOnce();+ expect(onFailure).toHaveBeenCalledOnce();+ });+it("removes installed plugins with the pre-change dependent view", async () => {const dispatch = vi.fn<(command: OrchestrationCommand) => Promise<void>>(async () => undefined);const runtime = createAkeruPluginRuntime({diff --git a/apps/server/src/provider/AkeruCatalogToolHandlers.ts b/apps/server/src/provider/AkeruCatalogToolHandlers.tsindex 45589a7ab..1b5896d23 100644--- a/apps/server/src/provider/AkeruCatalogToolHandlers.ts+++ b/apps/server/src/provider/AkeruCatalogToolHandlers.ts@@ -2,8 +2,9 @@import * as NodeCrypto from "node:crypto";import * as NodeFS from "node:fs";-import type { McpManager } from "@mastra/code-sdk/mcp/index";+import type { McpManager, McpServerStatus } from "@mastra/code-sdk/mcp/index";import {+ type BotId,CommandId,McpServerId,type AkeruToolId,@@ -12,6 +13,7 @@ import {type OrchestrationCommand,type OrchestrationReadModel,} from "@t3tools/contracts";+import * as DateTime from "effect/DateTime";import {isInstallableManifest,@@ -49,6 +51,8 @@ const catalogManifestModules =}): loadNodeCatalogModules();+import type { RequestHealthStatus } from "../subscription-auth/service.ts";+export interface AkeruCatalogToolHandlerInput {readonly input: unknown;readonly emitProgress: (summary: string) => void | Promise<void>;@@ -56,6 +60,29 @@ export interface AkeruCatalogToolHandlerInput {export type AkeruCatalogToolHandler = (input: AkeruCatalogToolHandlerInput) => Promise<unknown>;+export interface AkeruMcpDependencies {+ readonly dependentBots: ReadonlyArray<{ readonly id: BotId; readonly name: string }>;+ readonly dependentRoutines: ReadonlyArray<string>;+}++export interface AkeruMcpHealthHandlerOptions {+ readonly getRequestHealth: (serverId: string) => RequestHealthStatus | undefined;+ readonly recordSuccess: (serverId: string, at: string) => void;+ readonly recordFailure: (serverId: string, message: string, at: string) => void;+ readonly getDependencies: (serverId: string) => Promise<AkeruMcpDependencies>;+ readonly onFailure?: (+ serverId: string,+ message: string,+ dependencies: AkeruMcpDependencies,+ ) => void | Promise<void>;+ readonly onRecovery?: (+ serverId: string,+ dependencies: AkeruMcpDependencies,+ ) => void | Promise<void>;+ readonly authenticationExpiresAt?: (serverId: string) => string | undefined;+ readonly now?: () => string;+}+type McpRuntimeStatus = ReturnType<McpManager["getServerStatuses"]>[number];export interface AkeruPluginRuntimeOptions {@@ -307,9 +334,83 @@ function requiredString(value: unknown, key: string): string {return candidate;}+function requireServerStatus(mcpManager: McpManager, serverId: string): McpServerStatus {+ const status = mcpManager.getServerStatuses().find((candidate) => candidate.name === serverId);+ if (!status) throw new Error(`MCP server '${serverId}' is not configured for this bot.`);+ return status;+}++async function mcpHealthStatus(+ mcpManager: McpManager,+ options: AkeruMcpHealthHandlerOptions,+ serverId: string,+ status = requireServerStatus(mcpManager, serverId),+) {+ const health = options.getRequestHealth(serverId);+ const dependencies = await options.getDependencies(serverId);+ const healthTest =+ health?.health === "healthy" || health?.health === "recovered"+ ? "passed"+ : health?.health === "failed" || health?.health === "failed-first-request" || status.error+ ? "failed"+ : "not-run";+ const connectionState = status.disabled+ ? "disabled"+ : status.authenticating+ ? "authenticating"+ : status.connecting+ ? "connecting"+ : status.connected+ ? "connected"+ : status.needsAuth+ ? "authentication-required"+ : "failed";+ return {+ serverId,+ connectionState,+ healthTest,+ connected: status.connected,+ transport: status.transport,+ toolCount: status.toolCount,+ toolNames: status.toolNames,+ needsAuthentication: status.needsAuth ?? false,+ authenticationExpiresAt: options.authenticationExpiresAt?.(serverId) ?? null,+ lastSuccessfulRequestAt: health?.lastSuccessfulRequestAt ?? null,+ lastFailure:+ health?.lastFailedRequest ?? (status.error ? { at: null, message: status.error } : null),+ nextRetryAt: health?.nextRetryAt ?? null,+ dependentBots: dependencies.dependentBots,+ dependentRoutines: dependencies.dependentRoutines,+ };+}++async function checkMcpConnection(+ mcpManager: McpManager,+ options: AkeruMcpHealthHandlerOptions,+ serverId: string,+ emitProgress: AkeruCatalogToolHandlerInput["emitProgress"],+ action: "Testing" | "Reconnecting",+) {+ requireServerStatus(mcpManager, serverId);+ await emitProgress(`${action} MCP server '${serverId}'.`);+ const status = await mcpManager.reconnectServer(serverId);+ const at = options.now?.() ?? DateTime.formatIso(DateTime.nowUnsafe());+ const dependencies = await options.getDependencies(serverId);+ if (!status.connected) {+ const message = status.error ?? `MCP server '${serverId}' did not connect.`;+ options.recordFailure(serverId, message, at);+ await options.onFailure?.(serverId, message, dependencies);+ throw new Error(message);+ }+ options.recordSuccess(serverId, at);+ await options.onRecovery?.(serverId, dependencies);+ return mcpHealthStatus(mcpManager, options, serverId, status);+}+export function createAkeruCatalogToolHandlers(mcpManager?: McpManager,pluginRuntime?: ReturnType<typeof createAkeruPluginRuntime>,+ health?: AkeruMcpHealthHandlerOptions,): Partial<Record<AkeruToolId, AkeruCatalogToolHandler>> {const statuses = () => mcpManager?.getServerStatuses() ?? [];return {@@ -336,6 +437,28 @@ export function createAkeruCatalogToolHandlers(: {}),...(mcpManager? {+ ...(health+ ? {+ GetMcpServerStatus: async ({ input }) =>+ mcpHealthStatus(mcpManager, health, requiredString(input, "serverId")),+ TestMcpServer: async ({ input, emitProgress }) =>+ checkMcpConnection(+ mcpManager,+ health,+ requiredString(input, "serverId"),+ emitProgress,+ "Testing",+ ),+ ReconnectMcpServer: async ({ input, emitProgress }) =>+ checkMcpConnection(+ mcpManager,+ health,+ requiredString(input, "serverId"),+ emitProgress,+ "Reconnecting",+ ),+ }+ : {}),AuthenticateMcpServer: async ({ input, emitProgress }) => {const serverId = requiredString(input, "serverId");let authorizationUrl: string | undefined;diff --git a/apps/server/src/provider/AkeruToolRuntime.test.ts b/apps/server/src/provider/AkeruToolRuntime.test.tsindex b43c063eb..b6627fc79 100644--- a/apps/server/src/provider/AkeruToolRuntime.test.ts+++ b/apps/server/src/provider/AkeruToolRuntime.test.ts@@ -439,6 +439,30 @@ describe("AkeruToolRuntime", () => {});});+ it("requires a production grant before an MCP connection test can reconnect", async () => {+ const testConnection = vi.fn(async () => ({ connected: true }));+ const runtime = createAkeruToolRuntime();+ runtime.registerSession("thread-mcp-test", {+ runtimeMode: "full-access",+ workspaceType: "none",+ catalogHandlers: { TestMcpServer: testConnection },+ });+ const execution = {+ threadId: "thread-mcp-test",+ toolId: "TestMcpServer" as const,+ toolCallId: "tool-test-mcp",+ input: { serverId: "search" },+ approvalMode: "require-grant" as const,+ };++ await expect(runtime.execute(execution)).rejects.toThrow("requires approval");+ expect(testConnection).not.toHaveBeenCalled();++ runtime.grantApproval(execution);+ await expect(runtime.execute(execution)).resolves.toEqual({ connected: true });+ expect(testConnection).toHaveBeenCalledOnce();+ });+it("rejects shell working directories outside both workspace boundaries", async () => {const runtime = createAkeruToolRuntime();const bot = workspace("cwd-bot");diff --git a/apps/server/src/provider/AkeruToolRuntime.ts b/apps/server/src/provider/AkeruToolRuntime.tsindex 4f3a6edbf..8b7bc6377 100644--- a/apps/server/src/provider/AkeruToolRuntime.ts+++ b/apps/server/src/provider/AkeruToolRuntime.ts@@ -143,6 +143,9 @@ const BACKEND_NAMES: Record<| "GetPlugin"| "InstallPlugin"| "UninstallPlugin"+ | "GetMcpServerStatus"+ | "TestMcpServer"+ | "ReconnectMcpServer"| "AuthenticateMcpServer"| "RestartMcpServers">,diff --git a/apps/server/src/provider/Layers/AgentController.ts b/apps/server/src/provider/Layers/AgentController.tsindex 26ee6fb77..2a5c20a18 100644--- a/apps/server/src/provider/Layers/AgentController.ts+++ b/apps/server/src/provider/Layers/AgentController.ts@@ -429,6 +429,7 @@ const make = (options?: AgentControllerLiveOptions) =>>();let channelRuntime: AkeruChannelRuntime | undefined;let pluginRuntime: ReturnType<typeof createAkeruPluginRuntime> | undefined;+ let pluginRuntimeOptions: AkeruPluginRuntimeOptions | undefined;let botStateRuntime: AkeruBotStateRuntime | undefined;const childWaiters = new Map<string,@@ -1427,6 +1428,11 @@ const make = (options?: AgentControllerLiveOptions) =>access.memoryScopes.length > 0? memoryHandlers(input.memoryAccess, access.memoryScopes): undefined;+ const mcpManager = sessionResources.getMcpManager(key);+ const mcpDependencies =+ input.botId && input.botName+ ? { dependentBots: [{ id: input.botId, name: input.botName }], dependentRoutines: [] }+ : { dependentBots: [], dependentRoutines: [] };const toolSession: AkeruToolSession = {...(botId ? { botId } : {}),...(input.botName ? { botName: input.botName } : {}),@@ -1437,8 +1443,50 @@ const make = (options?: AgentControllerLiveOptions) =>...(registeredMemoryHandlers ? { memoryHandlers: registeredMemoryHandlers } : {}),...(input.botId && botStateRuntime ? { botState: botStateRuntime } : {}),catalogHandlers: createAkeruCatalogToolHandlers(- sessionResources.getMcpManager(key),+ mcpManager,pluginRuntime,+ mcpManager+ ? {+ getRequestHealth: (serverId) => subscriptionAuth.mcpRequestHealth(serverId),+ recordSuccess: (serverId, at) =>+ subscriptionAuth.recordMcpRequestSuccess(serverId, at),+ recordFailure: (serverId, message, at) =>+ subscriptionAuth.recordMcpRequestFailure(serverId, message, at),+ getDependencies: async (serverId) => {+ const snapshot = await pluginRuntimeOptions?.readSnapshot();+ return snapshot+ ? {+ dependentBots: snapshot.bots+ .filter(+ (bot) =>+ bot.archivedAt === null &&+ !bot.disabledMcpServerIds.some((id) => String(id) === serverId),+ )+ .map((bot) => ({ id: bot.id, name: bot.name })),+ dependentRoutines: [],+ }+ : mcpDependencies;+ },+ onFailure: (serverId, message, dependencies) => {+ for (const bot of dependencies.dependentBots) {+ botInbox.ensureOpen({+ incidentKey: `access:mcp-${serverId}:${bot.id}`,+ kind: "connector-failure",+ botId: bot.id,+ botName: bot.name,+ taskOrRoutine: `${serverId} access`,+ lastFailure: message,+ nextAction: `Reconnect ${serverId}, then retry its failed request.`,+ });+ }+ },+ onRecovery: (serverId, dependencies) => {+ for (const bot of dependencies.dependentBots) {+ botInbox.resolve(`access:mcp-${serverId}:${bot.id}`);+ }+ },+ }+ : undefined,),...(delegatedAccess && botId ? { billedBotId: botId } : {}),...(delegationRuntime && botId@@ -1913,6 +1961,7 @@ const make = (options?: AgentControllerLiveOptions) =>return AgentController.of({configurePluginRuntime: (input: AkeruPluginRuntimeOptions) =>Effect.sync(() => {+ pluginRuntimeOptions = input;pluginRuntime = createAkeruPluginRuntime(input);}),configureDelegation: (input) =>diff --git a/docs/internals/plugin-lifecycle-verification.md b/docs/internals/plugin-lifecycle-verification.mdindex e80d280bf..74cdab97d 100644--- a/docs/internals/plugin-lifecycle-verification.md+++ b/docs/internals/plugin-lifecycle-verification.md@@ -14,6 +14,10 @@ The lifecycle matrix does not copy runtime tests. These focused tests own the ru- `apps/server/src/subscription-auth/snapshot.test.ts` keeps a built-in MCP detected until a real request passes, reports healthy and disabled state, and lists dependent bots.- `apps/server/src/bot-inbox/connectorIncidents.test.ts` covers provider and MCP first-request failure, recovery, and stale dependent cleanup.+Bot-facing MCP controls use the same session-scoped Mastra `McpManager`. `GetMcpServerStatus` returns the manager connection plus persisted request evidence. `TestMcpServer` and `ReconnectMcpServer` use the manager's real per-server reconnect result, then update the same health and inbox records. A connected manager without a completed request or connection test reports `not-run`, not healthy.++Routine pausing remains an explicit dependency on the routine runtime in `t3code/routines-and-skills` commit `e77798657`. That branch owns durable connector dependencies and pause commands. Until it lands, MCP tool results return an empty `dependentRoutines` list and do not claim that a routine paused. Bind its repository and pause command at `AkeruMcpHealthHandlerOptions.getDependencies` and `onFailure`. Do not add a second routine store here.+Run the matrix with the catalog, schema, runtime, and validator checks. Do not call a vendor endpoint from automated tests.## Vendor statusdiff --git a/packages/contracts/src/akeruTools.test.ts b/packages/contracts/src/akeruTools.test.tsindex 0377a8221..79dcd8950 100644--- a/packages/contracts/src/akeruTools.test.ts+++ b/packages/contracts/src/akeruTools.test.ts@@ -48,6 +48,15 @@ describe("Akeru tool contracts", () => {);expect(AKERU_TOOL_CATALOG.find((tool) => tool.id === "SearchPlugins")?.approval).toBe("none");expect(AKERU_TOOL_CATALOG.find((tool) => tool.id === "GetPlugin")?.approval).toBe("none");+ expect(AKERU_TOOL_CATALOG.find((tool) => tool.id === "GetMcpServerStatus")?.approval).toBe(+ "none",+ );+ expect(AKERU_TOOL_CATALOG.find((tool) => tool.id === "TestMcpServer")?.approval).toBe(+ "production",+ );+ expect(AKERU_TOOL_CATALOG.find((tool) => tool.id === "ReconnectMcpServer")?.approval).toBe(+ "production",+ );});it("accepts catalog-owned plugin inputs and rejects model-supplied recipes", () => {diff --git a/packages/contracts/src/akeruTools.ts b/packages/contracts/src/akeruTools.tsindex 683f5345d..6da8705e3 100644--- a/packages/contracts/src/akeruTools.ts+++ b/packages/contracts/src/akeruTools.ts@@ -75,6 +75,9 @@ export const AkeruToolId = Schema.Literals(["GetPlugin","InstallPlugin","UninstallPlugin",+ "GetMcpServerStatus",+ "TestMcpServer",+ "ReconnectMcpServer","UpdateBotProfile","AuthenticateMcpServer","RestartMcpServers",@@ -148,6 +151,9 @@ export const AkeruToolInputSchemas = {GetPlugin: Schema.Struct({ pluginId: TrimmedNonEmptyString }),InstallPlugin: Schema.Struct({ pluginId: TrimmedNonEmptyString }),UninstallPlugin: Schema.Struct({ pluginId: TrimmedNonEmptyString }),+ GetMcpServerStatus: McpServerIdInput,+ TestMcpServer: McpServerIdInput,+ ReconnectMcpServer: McpServerIdInput,UpdateBotProfile: UpdateBotProfileInput,AuthenticateMcpServer: McpServerIdInput,RestartMcpServers: Schema.Struct({@@ -298,6 +304,13 @@ export const AKERU_TOOL_CATALOG = [define("UninstallPlugin", "bot-workspace", "Remove a curated plugin after inspecting it.", {approval: "delete",}),+ define("GetMcpServerStatus", "bot-workspace", "Inspect an MCP server connection."),+ define("TestMcpServer", "bot-workspace", "Run a real MCP server connection test.", {+ approval: "production",+ }),+ define("ReconnectMcpServer", "bot-workspace", "Reconnect one MCP server.", {+ approval: "production",+ }),define("UpdateBotProfile", "bot-workspace", "Update this bot's public profile."),define("AuthenticateMcpServer", "bot-workspace", "Authenticate an MCP server.", {approval: "secrets",