Skip to content

Commit c03cefc

Browse files
feat(mcp): expose existing thread organization commands
1 parent 4cfe358 commit c03cefc

8 files changed

Lines changed: 308 additions & 3 deletions

File tree

‎apps/server/src/mcp/McpHttpServer.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstab
1212
import packageJson from "../../package.json" with { type: "json" };
1313
import * as McpInvocationContext from "./McpInvocationContext.ts";
1414
import * as OrchestratorMcpService from "./OrchestratorMcpService.ts";
15+
import { ThreadToolkit } from "./toolkits/thread/tools.ts";
16+
import { ThreadToolkitHandlersLive } from "./toolkits/thread/handlers.ts";
1517
import * as ThreadMetadataMcpService from "./ThreadMetadataMcpService.ts";
1618
import * as McpSessionRegistry from "./McpSessionRegistry.ts";
1719
import * as PreviewAutomationBroker from "./PreviewAutomationBroker.ts";
@@ -228,6 +230,10 @@ export const OrchestratorToolkitRegistrationLive = McpServer.toolkit(Orchestrato
228230
Layer.provide(ThreadMetadataMcpService.layer),
229231
);
230232

233+
export const ThreadToolkitRegistrationLive = McpServer.toolkit(ThreadToolkit).pipe(
234+
Layer.provide(ThreadToolkitHandlersLive),
235+
);
236+
231237
export const WorktreeToolkitRegistrationLive = McpServer.toolkit(WorktreeToolkit).pipe(
232238
Layer.provide(WorktreeToolkitHandlersLive),
233239
Layer.provide(WorktreeMcpService.layer),
@@ -243,5 +249,6 @@ const McpTransportLive = McpServer.layerHttp({
243249
export const layer = Layer.mergeAll(
244250
PreviewToolkitRegistrationLive,
245251
OrchestratorToolkitRegistrationLive,
252+
ThreadToolkitRegistrationLive,
246253
WorktreeToolkitRegistrationLive,
247254
).pipe(Layer.provideMerge(McpTransportLive));

‎apps/server/src/mcp/OrchestratorMcpService.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -420,7 +420,7 @@ function interactionModeRank(mode: ProviderInteractionMode): number {
420420
return mode === "plan" ? 0 : 1;
421421
}
422422

423-
function resolveRuntimeMode(
423+
export function resolveRuntimeMode(
424424
parentMode: RuntimeMode,
425425
requested: OrchestratorMcpRuntimeMode | undefined,
426426
): Effect.Effect<RuntimeMode, OrchestratorMcpFailure> {
@@ -435,7 +435,7 @@ function resolveRuntimeMode(
435435
: Effect.succeed(resolved);
436436
}
437437

438-
function resolveInteractionMode(
438+
export function resolveInteractionMode(
439439
parentMode: ProviderInteractionMode,
440440
requested: OrchestratorMcpInteractionMode | undefined,
441441
): Effect.Effect<ProviderInteractionMode, OrchestratorMcpFailure> {

‎apps/server/src/mcp/OrchestratorMcpToolkit.integration.test.ts‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -613,7 +613,10 @@ describe("orchestrator MCP toolkit", () => {
613613
runNow: () => Effect.die("ScheduledTaskService.runNow is unused in this test"),
614614
}),
615615
);
616-
const testLayer = McpHttpServer.OrchestratorToolkitRegistrationLive.pipe(
616+
const testLayer = Layer.merge(
617+
McpHttpServer.OrchestratorToolkitRegistrationLive,
618+
McpHttpServer.ThreadToolkitRegistrationLive,
619+
).pipe(
617620
Layer.provideMerge(McpServer.McpServer.layer),
618621
Layer.provideMerge(orchestrationLayer),
619622
Layer.provide(providerRegistryLayer),
@@ -683,6 +686,12 @@ describe("orchestrator MCP toolkit", () => {
683686
const invoke = (name: string, args: Record<string, unknown>) =>
684687
invokeAs(invocation, name, args);
685688

689+
const pinned = yield* invoke("t3_thread_organize", { action: "pin" });
690+
expect(pinned.structuredContent).toHaveProperty("sequence");
691+
expect((yield* orchestrator.getThreadShell(parentThreadId))?.pinnedAt).not.toBeNull();
692+
yield* invoke("t3_thread_organize", { action: "unpin" });
693+
expect((yield* orchestrator.getThreadShell(parentThreadId))?.pinnedAt).toBeNull();
694+
686695
if (parentRun === undefined || parentRun.rootNodeId === null) {
687696
return yield* Effect.die(new Error("Parent run missing."));
688697
}
@@ -2126,6 +2135,15 @@ describe("orchestrator MCP toolkit", () => {
21262135
branch: null,
21272136
worktreePath: cwd,
21282137
});
2138+
const foreignOrganizeCall = yield* invoke("t3_thread_organize", {
2139+
threadId: foreignThreadId,
2140+
action: "pin",
2141+
});
2142+
expect(foreignOrganizeCall.structuredContent).toMatchObject({
2143+
code: "thread_not_found",
2144+
});
2145+
expect((yield* orchestrator.getThreadShell(foreignThreadId))?.pinnedAt).toBeNull();
2146+
21292147
const foreignReadCall = yield* invoke("t3_thread_read", {
21302148
threadId: foreignThreadId,
21312149
});
Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
import {
2+
CommandId,
3+
OrchestratorMcpFailure,
4+
type ThreadId,
5+
type OrchestrationV2ThreadShell,
6+
} from "@t3tools/contracts";
7+
import * as Crypto from "effect/Crypto";
8+
import * as Effect from "effect/Effect";
9+
10+
import * as ThreadManagement from "../orchestration-v2/ThreadManagementService.ts";
11+
import * as OrchestrationMcp from "./OrchestratorMcpService.ts";
12+
import { type McpInvocationScope, McpInvocationContext } from "./McpInvocationContext.ts";
13+
14+
export const unavailable = () =>
15+
new OrchestratorMcpFailure({
16+
code: "orchestration_error",
17+
message: "The operation could not be completed.",
18+
});
19+
20+
export const readCaller = Effect.fn("mcp.readCaller")(function* () {
21+
const scope = yield* McpInvocationContext;
22+
if (!scope.capabilities.has("orchestration")) {
23+
return yield* new OrchestratorMcpFailure({
24+
code: "capability_denied",
25+
message: "This credential cannot control threads.",
26+
});
27+
}
28+
const threads = yield* ThreadManagement.ThreadManagementService;
29+
const caller = yield* threads.getThreadShell(scope.threadId).pipe(Effect.mapError(unavailable));
30+
if (caller === null || caller.deletedAt !== null) {
31+
return yield* new OrchestratorMcpFailure({
32+
code: "thread_not_found",
33+
message: "The calling thread was not found.",
34+
});
35+
}
36+
return { scope, threads, caller };
37+
});
38+
39+
function assertLiveCaller({
40+
caller,
41+
scope,
42+
}: {
43+
caller: OrchestrationV2ThreadShell;
44+
scope: McpInvocationScope;
45+
}) {
46+
return caller.archivedAt !== null ||
47+
caller.activeRunId === null ||
48+
caller.providerInstanceId !== scope.providerInstanceId
49+
? Effect.fail(
50+
new OrchestratorMcpFailure({
51+
code: "parent_not_active",
52+
message: "The calling provider no longer owns an active thread run.",
53+
}),
54+
)
55+
: Effect.void;
56+
}
57+
export const readMutationCaller = Effect.fn("mcp.readMutationCaller")(function* () {
58+
const context = yield* readCaller();
59+
yield* assertLiveCaller(context);
60+
return context;
61+
});
62+
63+
/** Resolve the credential's project before looking up a caller-supplied thread. */
64+
export const readThread = Effect.fn("mcp.readThread")(function* (threadId?: ThreadId) {
65+
const { scope, threads, caller } = yield* readCaller();
66+
const projection = yield* threads
67+
.getProjectThread({ projectId: caller.projectId, threadId: threadId ?? caller.id })
68+
.pipe(
69+
Effect.mapError((error) =>
70+
error._tag === "ThreadManagementThreadNotFoundError"
71+
? new OrchestratorMcpFailure({
72+
code: "thread_not_found",
73+
message: "The thread was not found in the calling project.",
74+
})
75+
: unavailable(),
76+
),
77+
);
78+
return { scope, threads, caller, projection };
79+
});
80+
81+
export const readWritableThread = Effect.fn("mcp.readWritableThread")(function* (
82+
threadId?: ThreadId,
83+
) {
84+
const context = yield* readThread(threadId);
85+
yield* assertLiveCaller(context);
86+
yield* OrchestrationMcp.resolveRuntimeMode(
87+
context.caller.runtimeMode,
88+
context.projection.thread.runtimeMode,
89+
);
90+
yield* OrchestrationMcp.resolveInteractionMode(
91+
context.caller.interactionMode,
92+
context.projection.thread.interactionMode,
93+
);
94+
return context;
95+
});
96+
97+
export const newCommandId = Effect.fn("mcp.newCommandId")(function* () {
98+
const crypto = yield* Crypto.Crypto;
99+
return CommandId.make(`mcp:${yield* crypto.randomUUIDv4.pipe(Effect.orDie)}`);
100+
});
Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
import * as NodeCrypto from "@effect/platform-node/NodeCrypto";
2+
import { expect, it } from "@effect/vitest";
3+
import { EnvironmentId, ProviderInstanceId, ThreadId } from "@t3tools/contracts";
4+
import * as Effect from "effect/Effect";
5+
import * as Layer from "effect/Layer";
6+
import { McpSchema, McpServer, Tool } from "effect/unstable/ai";
7+
8+
import { OrchestratorProjectionError } from "../../orchestration-v2/Orchestrator.ts";
9+
import * as ThreadManagement from "../../orchestration-v2/ThreadManagementService.ts";
10+
import * as McpHttpServer from "../McpHttpServer.ts";
11+
import { McpInvocationContext, type McpInvocationScope } from "../McpInvocationContext.ts";
12+
import { OrchestratorToolkit } from "./orchestrator/tools.ts";
13+
import { PreviewToolkit } from "./preview/tools.ts";
14+
import { ThreadToolkit } from "./thread/tools.ts";
15+
import { WorktreeToolkit } from "./worktree/tools.ts";
16+
17+
it("publishes unique tool names with object-root inputs", () => {
18+
const names = new Set<string>();
19+
for (const toolkit of [OrchestratorToolkit, PreviewToolkit, WorktreeToolkit, ThreadToolkit]) {
20+
for (const tool of Object.values(toolkit.tools)) {
21+
expect(names.has(tool.name)).toBe(false);
22+
names.add(tool.name);
23+
expect(Tool.getJsonSchema(tool)).toMatchObject({ type: "object" });
24+
}
25+
}
26+
});
27+
28+
const threadId = ThreadId.make("mcp-core-thread");
29+
const scope: McpInvocationScope = {
30+
environmentId: EnvironmentId.make("mcp-core-environment"),
31+
threadId,
32+
providerSessionId: "mcp-core-session",
33+
providerInstanceId: ProviderInstanceId.make("codex"),
34+
issuedAt: 0,
35+
capabilities: new Set(["orchestration"]),
36+
};
37+
const client = McpSchema.McpServerClient.of({
38+
clientId: 1,
39+
protocolVersion: "2025-06-18",
40+
initializePayload: {
41+
protocolVersion: "2025-06-18",
42+
capabilities: {},
43+
clientInfo: { name: "mcp-core", version: "1" },
44+
},
45+
getClient: Effect.die("unused"),
46+
});
47+
48+
it.effect("checks capability before accessing services through the production registration", () =>
49+
Effect.gen(function* () {
50+
const server = yield* McpServer.McpServer;
51+
expect(server.tools.some(({ tool }) => tool.name === "t3_thread_organize")).toBe(true);
52+
const result = yield* server
53+
.callTool({ name: "t3_thread_organize", arguments: { action: "pin" } })
54+
.pipe(
55+
Effect.provideService(McpInvocationContext, { ...scope, capabilities: new Set<never>() }),
56+
Effect.provideService(McpSchema.McpServerClient, client),
57+
);
58+
expect(result.structuredContent).toMatchObject({ code: "capability_denied" });
59+
}).pipe(
60+
Effect.provide(
61+
McpHttpServer.ThreadToolkitRegistrationLive.pipe(
62+
Layer.provideMerge(McpServer.McpServer.layer),
63+
Layer.provide(NodeCrypto.layer),
64+
Layer.provide(Layer.mock(ThreadManagement.ThreadManagementService)({})),
65+
),
66+
),
67+
),
68+
);
69+
70+
it.effect("returns a bounded public failure without serializing storage causes", () =>
71+
Effect.gen(function* () {
72+
const server = yield* McpServer.McpServer;
73+
const result = yield* server
74+
.callTool({ name: "t3_thread_organize", arguments: { action: "pin" } })
75+
.pipe(
76+
Effect.provideService(McpInvocationContext, scope),
77+
Effect.provideService(McpSchema.McpServerClient, client),
78+
);
79+
expect(result.structuredContent).toEqual({
80+
_tag: "OrchestratorMcpFailure",
81+
code: "orchestration_error",
82+
message: "The operation could not be completed.",
83+
});
84+
}).pipe(
85+
Effect.provide(
86+
McpHttpServer.ThreadToolkitRegistrationLive.pipe(
87+
Layer.provideMerge(McpServer.McpServer.layer),
88+
Layer.provide(NodeCrypto.layer),
89+
Layer.provide(
90+
Layer.mock(ThreadManagement.ThreadManagementService)({
91+
getThreadShell: () =>
92+
Effect.fail(
93+
new OrchestratorProjectionError({
94+
threadId,
95+
cause: new Error("private-storage-path"),
96+
}),
97+
),
98+
}),
99+
),
100+
),
101+
),
102+
),
103+
);
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
import { OrchestratorMcpFailure, type OrchestrationV2Command } from "@t3tools/contracts";
2+
import * as Effect from "effect/Effect";
3+
4+
import { newCommandId, readWritableThread, unavailable } from "../../threadAccess.ts";
5+
import { ThreadToolkit } from "./tools.ts";
6+
7+
export const ThreadToolkitHandlersLive = ThreadToolkit.toLayer({
8+
t3_thread_organize: (input) =>
9+
Effect.gen(function* () {
10+
const { threads, projection } = yield* readWritableThread(input.threadId);
11+
const common = { commandId: yield* newCommandId(), threadId: projection.thread.id };
12+
let command: OrchestrationV2Command;
13+
switch (input.action) {
14+
case "snooze":
15+
if (input.snoozedUntil === undefined) {
16+
return yield* new OrchestratorMcpFailure({
17+
code: "invalid_request",
18+
message: "snooze requires snoozedUntil.",
19+
});
20+
}
21+
command = { ...common, type: "thread.snooze", snoozedUntil: input.snoozedUntil };
22+
break;
23+
case "unsnooze":
24+
case "unsettle":
25+
command = { ...common, type: `thread.${input.action}`, reason: "user" };
26+
break;
27+
case "mark_unread":
28+
command = { ...common, type: "thread.mark-unread" };
29+
break;
30+
default:
31+
command = { ...common, type: `thread.${input.action}` };
32+
}
33+
const result = yield* threads.dispatch(command).pipe(Effect.mapError(unavailable));
34+
return { sequence: result.sequence };
35+
}),
36+
});
Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
import {
2+
IsoDateTime,
3+
OrchestratorMcpFailure,
4+
OrchestrationV2DispatchCommandResult,
5+
ThreadId,
6+
} from "@t3tools/contracts";
7+
import * as Crypto from "effect/Crypto";
8+
import * as Schema from "effect/Schema";
9+
import { Tool, Toolkit } from "effect/unstable/ai";
10+
11+
import { ThreadManagementService } from "../../../orchestration-v2/ThreadManagementService.ts";
12+
import { McpInvocationContext } from "../../McpInvocationContext.ts";
13+
14+
export const ThreadOrganizeTool = Tool.make("t3_thread_organize", {
15+
description:
16+
"Pin, snooze, settle, archive, or mark a thread unread in the calling project. Omit threadId for this thread. snooze requires snoozedUntil. Existing thread lifecycle rules apply; this does not schedule a future action.",
17+
parameters: Schema.Struct({
18+
threadId: Schema.optional(ThreadId),
19+
action: Schema.Literals([
20+
"pin",
21+
"unpin",
22+
"snooze",
23+
"unsnooze",
24+
"settle",
25+
"unsettle",
26+
"archive",
27+
"unarchive",
28+
"mark_unread",
29+
]),
30+
snoozedUntil: Schema.optional(IsoDateTime),
31+
}),
32+
success: OrchestrationV2DispatchCommandResult,
33+
failure: OrchestratorMcpFailure,
34+
failureMode: "return",
35+
dependencies: [McpInvocationContext, ThreadManagementService, Crypto.Crypto],
36+
})
37+
.annotate(Tool.Title, "Organize a thread")
38+
.annotate(Tool.Destructive, true);
39+
40+
export const ThreadToolkit = Toolkit.make(ThreadOrganizeTool);

‎packages/shared/src/t3McpToolPresentation.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ const T3_MCP_TOOLS: Record<
4848
t3_thread_start: { displayName: "Start a T3 thread", summaryAction: "thread-create" },
4949
t3_thread_list: { displayName: "List T3 threads", summaryAction: "thread-list" },
5050
t3_thread_read: { displayName: "Read a T3 thread", summaryAction: "thread-read" },
51+
t3_thread_organize: { displayName: "Organize a thread" },
5152
t3_thread_update: { displayName: "Update T3 thread metadata" },
5253
t3_thread_send: { displayName: "Send to a T3 thread", summaryAction: "thread-send" },
5354
t3_thread_wait: { displayName: "Wait for a T3 thread", summaryAction: "thread-wait" },

0 commit comments

Comments
 (0)