Skip to content

Commit 18656a3

Browse files
feat(mcp): agents can write and read pull request review guides (pingdotgg#18143)
Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 1f6df6b commit 18656a3

13 files changed

Lines changed: 555 additions & 7 deletions

File tree

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ import {
2727
} from "effect/http";
2828

2929
import * as ProjectService from "../project/ProjectService.ts";
30+
import * as PullRequestReviewGuideService from "../pullRequest/PullRequestReviewGuideService.ts";
3031
import * as ServerConfig from "../config.ts";
3132
import * as McpHttpServer from "./McpHttpServer.ts";
3233
import * as McpToolAccess from "./McpToolAccess.ts";
@@ -77,6 +78,7 @@ const layerPullRequestsTest = McpHttpServer.layerPullRequestsToolkit.pipe(
7778
Layer.provide(
7879
Layer.mergeAll(
7980
Layer.mock(ProjectService.ProjectService)({}),
81+
Layer.mock(PullRequestReviewGuideService.PullRequestReviewGuideService)({}),
8082
Layer.mock(Orchestrator.OrchestratorV2)({}),
8183
Layer.mock(ProjectionStore.ProjectionStoreV2)({}),
8284
NodeServices.layer,

‎apps/server/src/mcp/McpToolAccess.test.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,7 @@ const ProbeToolkit = Toolkit.make(
8787
Tool.make("reads_as_caller", probe),
8888
Tool.make("acts_as_caller", probe),
8989
Tool.make("writes", probe),
90+
Tool.make("writes_with_capability", probe),
9091
Tool.make("writes_threads", {
9192
...probe,
9293
parameters: Schema.Struct({ threadId: Schema.optional(ThreadId) }),
@@ -106,6 +107,7 @@ const probeHandlers: McpToolAccess.Handlers<typeof ProbeToolkit.tools> = {
106107
reads_as_caller: McpToolAccess.readsAsCaller(() => ran),
107108
acts_as_caller: McpToolAccess.actsAsCaller(() => ran),
108109
writes: McpToolAccess.writes(() => ran),
110+
writes_with_capability: McpToolAccess.writesWithCapability(() => ran),
109111
writes_threads: McpToolAccess.writesThreads(
110112
(input) => [input.threadId],
111113
() => ran,
@@ -152,6 +154,7 @@ export const refusedAtCompileTime = () => {
152154
reads_as_caller: unchecked,
153155
acts_as_caller: unchecked,
154156
writes: unchecked,
157+
writes_with_capability: unchecked,
155158
writes_threads: unchecked,
156159
starts_threads: unchecked,
157160
writes_environment: unchecked,
@@ -224,6 +227,11 @@ it.effect.each([
224227
["writes", previewOnly, {}, "capability_denied"],
225228
["writes_environment", previewOnly, {}, "capability_denied"],
226229

230+
// A tool's own capability stands in for thread control; the rest of a change still applies.
231+
["writes_with_capability", previewOnly, {}, "ran"],
232+
["writes_with_capability", readOnlyClient, {}, "capability_denied"],
233+
["writes_with_capability", ended, {}, "parent_not_active"],
234+
227235
// Changing a thread: only one that runs within the caller's modes.
228236
["writes_threads", supervised, {}, "ran"],
229237
["writes_threads", supervised, { threadId: planThreadId }, "ran"],

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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -157,6 +157,14 @@ export const actsAsCaller = <P, A, E, R>(handle: (params: P) => Effect.Effect<A,
157157
export const writes = <P, A, E, R>(handle: (params: P) => Effect.Effect<A, E, R>) =>
158158
declare((params: P) => orchestratingCaller.pipe(Effect.flatMap(() => handle(params))));
159159

160+
/**
161+
* Changes something that belongs to no thread under a capability of the tool's own, such as
162+
* writing a pull request's review guide. Unlike `writes` it does not need thread control; the
163+
* handler checks its capability, as the capability toolkits do.
164+
*/
165+
export const writesWithCapability = <P, A, E, R>(handle: (params: P) => Effect.Effect<A, E, R>) =>
166+
declare((params: P) => writingCaller.pipe(Effect.flatMap(() => handle(params))));
167+
160168
/**
161169
* Changes the threads `threads` names. An omitted id is the caller's own
162170
* thread; any other thread must run within the caller's modes, checked here

‎apps/server/src/mcp/toolkits/pullRequests/handlers.test.ts‎

Lines changed: 189 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,10 @@ import {
44
ProviderInstanceId,
55
ThreadId,
66
type OrchestrationV2ServerCommand as OrchestrationCommand,
7+
PullRequestOperationError,
78
type OrchestrationProjectShell,
9+
type PullRequestRef,
10+
type PullRequestReviewGuideResult,
811
type ThreadPullRequestLink,
912
} from "@t3tools/contracts";
1013
import { describe, expect, it } from "@effect/vitest";
@@ -22,6 +25,7 @@ import {
2225
v2PullRequestThread,
2326
} from "../../../orchestration-v2/testkit/pullRequestFixtures.ts";
2427
import * as ProjectService from "../../../project/ProjectService.ts";
28+
import * as PullRequestReviewGuideService from "../../../pullRequest/PullRequestReviewGuideService.ts";
2529
import * as McpInvocationContext from "../../McpInvocationContext.ts";
2630
import * as McpToolAccess from "../../McpToolAccess.ts";
2731
import * as McpToolAccessTestkit from "../../McpToolAccess.testkit.ts";
@@ -135,12 +139,24 @@ interface HarnessOptions {
135139
readonly project?: OrchestrationProjectShell | null;
136140
/** A rejection the orchestrator reports as the dispatch error's cause. */
137141
readonly reject?: (command: OrchestrationCommand) => string | null;
142+
/** Every project in the environment; defaults to the thread's own. */
143+
readonly projects?: ReadonlyArray<OrchestrationProjectShell>;
144+
/** What the guide service answers for a pull request it is asked to write. */
145+
readonly generate?: (
146+
input: PullRequestRef,
147+
) => Effect.Effect<
148+
PullRequestReviewGuideResult & { started: boolean },
149+
PullRequestOperationError
150+
>;
138151
}
139152

153+
const NO_GUIDE: PullRequestReviewGuideResult = { guide: null, run: null, currentHeadSha: "head-1" };
154+
140155
const makeHarness = Effect.fn("makePullRequestsToolkitHarness")(function* (
141156
options: HarnessOptions = {},
142157
) {
143158
const commands = yield* Ref.make<ReadonlyArray<OrchestrationCommand>>([]);
159+
const guideRequests = yield* Ref.make<ReadonlyArray<PullRequestRef>>([]);
144160
const thread = options.thread === undefined ? makeThread([]) : options.thread;
145161
const project = options.project === undefined ? makeProject() : options.project;
146162
const dispatch: Orchestrator.OrchestratorV2Shape["dispatch"] = (command) =>
@@ -158,6 +174,25 @@ const makeHarness = Effect.fn("makePullRequestsToolkitHarness")(function* (
158174
const layerDependencies = Layer.mergeAll(
159175
Layer.mock(ProjectService.ProjectService)({
160176
getShell: () => Effect.succeed(Option.fromNullishOr(project)),
177+
listShells: () => Effect.succeed(options.projects ?? (project ? [project] : [])),
178+
}),
179+
Layer.mock(PullRequestReviewGuideService.PullRequestReviewGuideService)({
180+
get: () => Effect.succeed(NO_GUIDE),
181+
generate: (input) =>
182+
Ref.update(guideRequests, (recorded) => [...recorded, input]).pipe(
183+
Effect.andThen(
184+
options.generate?.(input) ??
185+
Effect.succeed({
186+
...NO_GUIDE,
187+
run: {
188+
_tag: "Running" as const,
189+
headSha: "head-1",
190+
startedAt: "2026-10-11T00:00:00.000Z",
191+
},
192+
started: true,
193+
}),
194+
),
195+
),
161196
}),
162197
Layer.mock(Orchestrator.OrchestratorV2)({
163198
getThreadShell: (id) =>
@@ -189,7 +224,7 @@ const makeHarness = Effect.fn("makePullRequestsToolkitHarness")(function* (
189224
Effect.provideService(McpInvocationContext.McpInvocationContext, invocation(capabilities)),
190225
Effect.provide(layerDependencies),
191226
);
192-
return { commands, call };
227+
return { commands, guideRequests, call };
193228
});
194229

195230
describe("pull request toolkit handlers", () => {
@@ -546,6 +581,159 @@ describe("listThreadPullRequests", () => {
546581
});
547582
});
548583

584+
describe("pull request guide tools", () => {
585+
it.effect(
586+
"writes guides through the project whose checkout is each pull request's repository",
587+
() =>
588+
Effect.gen(function* () {
589+
const other = {
590+
...makeProject({
591+
canonicalKey: "github.com/acme/web",
592+
locator: {
593+
source: "git-remote",
594+
remoteName: "origin",
595+
remoteUrl: "[email protected]:acme/web.git",
596+
},
597+
provider: "github",
598+
displayName: "acme/web",
599+
owner: "acme",
600+
name: "web",
601+
}),
602+
id: ProjectId.make("project-web"),
603+
};
604+
const harness = yield* makeHarness({ projects: [makeProject(), other] });
605+
const result = yield* harness.call("write_pull_request_guides", {
606+
pullRequests: [
607+
{ url: "https://github.com/acme/web/pull/7" },
608+
{ repository: "t3tools/t3code", number: 12 },
609+
{ url: "https://github.com/someone/else/pull/1" },
610+
],
611+
});
612+
expect(
613+
result.guides.map((guide) => [guide.repository, guide.number, guide.outcome]),
614+
).toEqual([
615+
["acme/web", 7, "started"],
616+
["t3tools/t3code", 12, "started"],
617+
["someone/else", 1, "failed"],
618+
]);
619+
expect(result.guides[2]?.detail).toContain("No project in this environment");
620+
expect(
621+
(yield* Ref.get(harness.guideRequests)).map((ref) => [ref.projectId, ref.number]),
622+
).toEqual([
623+
["project-web", 7],
624+
[PROJECT_ID, 12],
625+
]);
626+
}),
627+
);
628+
629+
it.effect("reports a refused run on its own pull request without failing the rest", () =>
630+
Effect.gen(function* () {
631+
const harness = yield* makeHarness({
632+
generate: (input) =>
633+
input.number === 1
634+
? Effect.fail(
635+
new PullRequestOperationError({
636+
operation: "generateReviewGuide",
637+
detail: "Review guides are off. Turn them on in Settings → Source Control.",
638+
}),
639+
)
640+
: Effect.succeed({
641+
...NO_GUIDE,
642+
run: {
643+
_tag: "Running" as const,
644+
headSha: "head-1",
645+
startedAt: "2026-10-11T00:00:00.000Z",
646+
},
647+
started: true,
648+
}),
649+
});
650+
const result = yield* harness.call("write_pull_request_guides", {
651+
pullRequests: [
652+
{ repository: "t3tools/t3code", number: 1 },
653+
{ repository: "t3tools/t3code", number: 2 },
654+
],
655+
});
656+
expect(result.guides.map((guide) => [guide.number, guide.outcome, guide.detail])).toEqual([
657+
[1, "failed", "Review guides are off. Turn them on in Settings → Source Control."],
658+
[2, "started", null],
659+
]);
660+
}),
661+
);
662+
663+
it.effect("reports an unreadable entry on its own and still writes the rest of the batch", () =>
664+
Effect.gen(function* () {
665+
const harness = yield* makeHarness();
666+
const result = yield* harness.call("write_pull_request_guides", {
667+
pullRequests: [
668+
{ url: "https://example.com/not-a-pull-request" },
669+
{ repository: "t3tools/t3code" },
670+
{ repository: "t3tools/t3code", number: 5 },
671+
],
672+
});
673+
expect(result.guides.map((guide) => guide.outcome)).toEqual(["failed", "failed", "started"]);
674+
expect(result.guides[0]?.detail).toContain("not a recognised pull request URL");
675+
expect(result.guides[1]?.detail).toContain("Pass either url");
676+
expect((yield* Ref.get(harness.guideRequests)).map((ref) => ref.number)).toEqual([5]);
677+
}),
678+
);
679+
680+
it.effect("reports a run the service joined as running, not as a new one", () =>
681+
Effect.gen(function* () {
682+
const harness = yield* makeHarness({
683+
generate: () =>
684+
Effect.succeed({
685+
...NO_GUIDE,
686+
run: { _tag: "Running", headSha: "head-1", startedAt: "2026-10-11T00:00:00.000Z" },
687+
started: false,
688+
}),
689+
});
690+
const result = yield* harness.call("write_pull_request_guides", {
691+
pullRequests: [{ repository: "t3tools/t3code", number: 4 }],
692+
});
693+
expect(result.guides.map((guide) => guide.outcome)).toEqual(["running"]);
694+
}),
695+
);
696+
697+
it.effect("finds an Azure DevOps checkout for a pull request named by its full path", () =>
698+
Effect.gen(function* () {
699+
const azure = {
700+
...makeProject({
701+
canonicalKey: "dev.azure.com/org/project/_git/web",
702+
locator: {
703+
source: "git-remote",
704+
remoteName: "origin",
705+
remoteUrl: "https://dev.azure.com/org/project/_git/web",
706+
},
707+
provider: "azure-devops",
708+
displayName: "org/project/_git/web",
709+
owner: "org",
710+
name: "web",
711+
}),
712+
id: ProjectId.make("project-azure"),
713+
};
714+
const harness = yield* makeHarness({ projects: [makeProject(), azure] });
715+
const result = yield* harness.call("write_pull_request_guides", {
716+
pullRequests: [{ host: "dev.azure.com", repository: "org/project/_git/web", number: 9 }],
717+
});
718+
expect(result.guides.map((guide) => guide.outcome)).toEqual(["started"]);
719+
expect((yield* Ref.get(harness.guideRequests)).map((ref) => ref.projectId)).toEqual([
720+
"project-azure",
721+
]);
722+
}),
723+
);
724+
725+
it.effect("reads a stored guide and says when a push left it behind", () =>
726+
Effect.gen(function* () {
727+
const harness = yield* makeHarness();
728+
const result = yield* harness.call("read_pull_request_guide", {
729+
repository: "t3tools/t3code",
730+
number: 3,
731+
});
732+
expect(result).toMatchObject({ number: 3, guide: null, run: null, stale: false });
733+
}),
734+
);
735+
});
736+
549737
it("keeps failure diagnostics as the cause rather than exposing them in the tool message", () => {
550738
const cause = new Error("database internals");
551739
const failure = new PullRequestLinkFailedError({ cause });

0 commit comments

Comments
 (0)