The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import { |
| 2 | IssueCapabilities, |
| 3 | IssueListState, |
| 4 | IssueOperationError, |
| 5 | IssueState, |
| 6 | IssueTrackerKind, |
| 7 | IssueUnavailableError, |
| 8 | McpCapabilityUnavailableError, |
| 9 | OrchestratorMcpFailure, |
| 10 | ProjectId, |
| 11 | ThreadId, |
| 12 | ThreadIssueLinkSource, |
| 13 | TrimmedNonEmptyString, |
| 14 | } from "@t3tools/contracts"; |
| 15 | import * as Schema from "effect/Schema"; |
| 16 | import * as Tool from "effect/ai/Tool"; |
| 17 | import * as Toolkit from "effect/ai/Toolkit"; |
| 18 | |
| 19 | import * as IssueService from "../../../issue/IssueService.ts"; |
| 20 | import * as Orchestrator from "../../../orchestration-v2/Orchestrator.ts"; |
| 21 | import * as ThreadIssueService from "../../../orchestration-v2/ThreadIssueService.ts"; |
| 22 | import * as ThreadManagementService from "../../../orchestration-v2/ThreadManagementService.ts"; |
| 23 | import * as ProjectService from "../../../project/ProjectService.ts"; |
| 24 | import * as McpInvocationContext from "../../McpInvocationContext.ts"; |
| 25 | |
| 26 | const dependencies = [ |
| 27 | McpInvocationContext.McpInvocationContext, |
| 28 | ThreadManagementService.ThreadManagementService, |
| 29 | Orchestrator.OrchestratorV2, |
| 30 | ProjectService.ProjectService, |
| 31 | IssueService.IssueService, |
| 32 | ThreadIssueService.ThreadIssueService, |
| 33 | ]; |
| 34 | |
| 35 | /** |
| 36 | * Either the issue's URL, or its key within a project's tracker. A key alone is read through the |
| 37 | * project named, or the caller's own thread's project; a URL is read through whichever project |
| 38 | * here is a checkout of that repository, read-only when none is. |
| 39 | */ |
| 40 | export const IssueTargetInput = Schema.Struct({ |
| 41 | url: Schema.optional( |
| 42 | TrimmedNonEmptyString.annotate({ |
| 43 | description: "The issue's web URL. Preferred when you have it.", |
| 44 | }), |
| 45 | ), |
| 46 | key: Schema.optional( |
| 47 | TrimmedNonEmptyString.annotate({ |
| 48 | description: "The issue's key in the project's tracker, such as its number.", |
| 49 | }), |
| 50 | ), |
| 51 | projectId: Schema.optional( |
| 52 | ProjectId.annotate({ |
| 53 | description: "Project whose tracker holds key. Defaults to this thread's project.", |
| 54 | }), |
| 55 | ), |
| 56 | }); |
| 57 | export type IssueTargetInput = typeof IssueTargetInput.Type; |
| 58 | |
| 59 | const ThreadTargetInput = Schema.Struct({ |
| 60 | threadId: Schema.optional( |
| 61 | ThreadId.annotate({ description: "Thread to act on. Omit for this thread." }), |
| 62 | ), |
| 63 | }); |
| 64 | |
| 65 | export class IssueTargetIncompleteError extends Schema.TaggedError<IssueTargetIncompleteError>()( |
| 66 | "IssueTargetIncompleteError", |
| 67 | {}, |
| 68 | ) { |
| 69 | override get message(): string { |
| 70 | return "Pass either url, or key (with projectId when not running inside a T3 thread)."; |
| 71 | } |
| 72 | } |
| 73 | |
| 74 | export class IssueProjectRequiredError extends Schema.TaggedError<IssueProjectRequiredError>()( |
| 75 | "IssueProjectRequiredError", |
| 76 | {}, |
| 77 | ) { |
| 78 | override get message(): string { |
| 79 | return "Pass projectId: this MCP client is not running inside a T3 thread."; |
| 80 | } |
| 81 | } |
| 82 | |
| 83 | export class IssueThreadRequiredError extends Schema.TaggedError<IssueThreadRequiredError>()( |
| 84 | "IssueThreadRequiredError", |
| 85 | {}, |
| 86 | ) { |
| 87 | override get message(): string { |
| 88 | return "Pass threadId: this MCP client is not running inside a T3 thread."; |
| 89 | } |
| 90 | } |
| 91 | |
| 92 | export class IssueThreadNotFoundError extends Schema.TaggedError<IssueThreadNotFoundError>()( |
| 93 | "IssueThreadNotFoundError", |
| 94 | { threadId: Schema.String }, |
| 95 | ) { |
| 96 | override get message(): string { |
| 97 | return `Thread ${this.threadId} was not found.`; |
| 98 | } |
| 99 | } |
| 100 | |
| 101 | export class IssueProjectNotFoundError extends Schema.TaggedError<IssueProjectNotFoundError>()( |
| 102 | "IssueProjectNotFoundError", |
| 103 | { projectId: Schema.String }, |
| 104 | ) { |
| 105 | override get message(): string { |
| 106 | return `Project ${this.projectId} was not found or has no issue tracker.`; |
| 107 | } |
| 108 | } |
| 109 | |
| 110 | export class IssueLinkFailedError extends Schema.TaggedError<IssueLinkFailedError>()( |
| 111 | "IssueLinkFailedError", |
| 112 | { cause: Schema.Defect() }, |
| 113 | ) { |
| 114 | override get message(): string { |
| 115 | return "Could not change the issue link."; |
| 116 | } |
| 117 | } |
| 118 | |
| 119 | export const IssueToolError = Schema.Union([ |
| 120 | OrchestratorMcpFailure, |
| 121 | McpCapabilityUnavailableError, |
| 122 | IssueUnavailableError, |
| 123 | IssueOperationError, |
| 124 | IssueTargetIncompleteError, |
| 125 | IssueProjectRequiredError, |
| 126 | IssueThreadRequiredError, |
| 127 | IssueThreadNotFoundError, |
| 128 | IssueProjectNotFoundError, |
| 129 | IssueLinkFailedError, |
| 130 | ]); |
| 131 | export type IssueToolError = typeof IssueToolError.Type; |
| 132 | |
| 133 | /** How a tool names an issue back: enough to pass to any other issue tool. */ |
| 134 | const IssueKeyIdentity = { |
| 135 | projectId: ProjectId, |
| 136 | tracker: IssueTrackerKind, |
| 137 | host: Schema.String, |
| 138 | scope: Schema.String, |
| 139 | key: Schema.String, |
| 140 | }; |
| 141 | const IssueIdentity = { ...IssueKeyIdentity, url: Schema.String }; |
| 142 | /** A write named by key alone never read the issue, so it has no URL to hand back. */ |
| 143 | const IssueIdentityAfterWrite = { ...IssueKeyIdentity, url: Schema.optional(Schema.String) }; |
| 144 | |
| 145 | export const IssueEntry = Schema.Struct({ |
| 146 | ...IssueIdentity, |
| 147 | displayKey: Schema.String, |
| 148 | title: Schema.String, |
| 149 | state: IssueState, |
| 150 | author: Schema.NullOr(Schema.String), |
| 151 | assignees: Schema.Array(Schema.String), |
| 152 | labels: Schema.Array(Schema.String), |
| 153 | updatedAt: Schema.String, |
| 154 | commentCount: Schema.Int, |
| 155 | }); |
| 156 | export type IssueEntry = typeof IssueEntry.Type; |
| 157 | |
| 158 | export const ListIssuesResult = Schema.Struct({ |
| 159 | issues: Schema.Array(IssueEntry), |
| 160 | /** Pass back as `cursors` to read the next slice of each scope that has one. */ |
| 161 | nextCursors: Schema.Record(Schema.String, Schema.String), |
| 162 | errors: Schema.Array(Schema.Struct({ projectId: ProjectId, message: Schema.String })), |
| 163 | }); |
| 164 | export type ListIssuesResult = typeof ListIssuesResult.Type; |
| 165 | |
| 166 | export const ReadIssueResult = Schema.Struct({ |
| 167 | ...IssueIdentity, |
| 168 | displayKey: Schema.String, |
| 169 | title: Schema.String, |
| 170 | state: IssueState, |
| 171 | /** False for an issue outside every project's own scope: it can be read, not changed. */ |
| 172 | writable: Schema.Boolean, |
| 173 | capabilities: IssueCapabilities, |
| 174 | states: Schema.Array(IssueState), |
| 175 | author: Schema.NullOr(Schema.String), |
| 176 | assignees: Schema.Array(Schema.String), |
| 177 | labels: Schema.Array(Schema.String), |
| 178 | createdAt: Schema.String, |
| 179 | updatedAt: Schema.String, |
| 180 | closedAt: Schema.NullOr(Schema.String), |
| 181 | body: Schema.String, |
| 182 | comments: Schema.Array( |
| 183 | Schema.Struct({ |
| 184 | id: Schema.String, |
| 185 | author: Schema.NullOr(Schema.String), |
| 186 | body: Schema.String, |
| 187 | createdAt: Schema.String, |
| 188 | }), |
| 189 | ), |
| 190 | /** Older comments exist beyond the page returned. */ |
| 191 | commentsTruncated: Schema.Boolean, |
| 192 | linkedPullRequests: Schema.Array( |
| 193 | Schema.Struct({ |
| 194 | url: Schema.String, |
| 195 | title: Schema.String, |
| 196 | state: Schema.String, |
| 197 | closesIssue: Schema.Boolean, |
| 198 | }), |
| 199 | ), |
| 200 | }); |
| 201 | export type ReadIssueResult = typeof ReadIssueResult.Type; |
| 202 | |
| 203 | export const CreateIssueResult = Schema.Struct({ |
| 204 | ...IssueIdentity, |
| 205 | displayKey: Schema.String, |
| 206 | }); |
| 207 | export type CreateIssueResult = typeof CreateIssueResult.Type; |
| 208 | |
| 209 | export const IssueWriteResult = Schema.Struct({ ...IssueIdentityAfterWrite }); |
| 210 | |
| 211 | export const ThreadIssueEntry = Schema.Struct({ |
| 212 | ...IssueIdentity, |
| 213 | source: ThreadIssueLinkSource, |
| 214 | /** As the tracker named the issue when it was linked; `read_issue` has its current state. */ |
| 215 | displayKey: Schema.String, |
| 216 | title: Schema.String, |
| 217 | }); |
| 218 | export type ThreadIssueEntry = typeof ThreadIssueEntry.Type; |
| 219 | |
| 220 | export const LinkIssueResult = Schema.Struct({ |
| 221 | ...IssueIdentity, |
| 222 | alreadyLinked: Schema.Boolean.annotate({ |
| 223 | description: "True when the issue was linked to this thread before the call.", |
| 224 | }), |
| 225 | }); |
| 226 | export type LinkIssueResult = typeof LinkIssueResult.Type; |
| 227 | |
| 228 | export const UnlinkIssueResult = Schema.Struct({ |
| 229 | ...IssueIdentityAfterWrite, |
| 230 | wasLinked: Schema.Boolean.annotate({ |
| 231 | description: "False when the issue was not linked to this thread to begin with.", |
| 232 | }), |
| 233 | }); |
| 234 | export type UnlinkIssueResult = typeof UnlinkIssueResult.Type; |
| 235 | |
| 236 | export const ListThreadIssuesResult = Schema.Struct({ |
| 237 | issues: Schema.Array(ThreadIssueEntry), |
| 238 | }); |
| 239 | export type ListThreadIssuesResult = typeof ListThreadIssuesResult.Type; |
| 240 | |
| 241 | const ListIssuesTool = Tool.make("list_issues", { |
| 242 | description: |
| 243 | "List issues in a project's tracker, newest updated first. Pass the returned nextCursors as cursors for the next page.", |
| 244 | parameters: Schema.Struct({ |
| 245 | projectId: Schema.optional( |
| 246 | ProjectId.annotate({ description: "Defaults to this thread's project." }), |
| 247 | ), |
| 248 | state: Schema.optional(IssueListState.annotate({ description: "Defaults to open." })), |
| 249 | query: Schema.optional( |
| 250 | TrimmedNonEmptyString.check(Schema.isMaxLength(200)).annotate({ |
| 251 | description: "Free text the tracker matches itself.", |
| 252 | }), |
| 253 | ), |
| 254 | limit: Schema.optional(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 100 }))), |
| 255 | cursors: Schema.optional(Schema.Record(Schema.String, Schema.String)), |
| 256 | }), |
| 257 | success: ListIssuesResult, |
| 258 | failure: IssueToolError, |
| 259 | dependencies, |
| 260 | }) |
| 261 | .annotate(Tool.Title, "List issues") |
| 262 | .annotate(Tool.Readonly, true) |
| 263 | .annotate(Tool.Destructive, false) |
| 264 | .annotate(Tool.Idempotent, true) |
| 265 | .annotate(Tool.OpenWorld, true); |
| 266 | |
| 267 | const ReadIssueTool = Tool.make("read_issue", { |
| 268 | description: |
| 269 | "Read an issue: body, state, labels, assignees, recent comments and linked pull requests. Pass its url, or its key.", |
| 270 | parameters: IssueTargetInput, |
| 271 | success: ReadIssueResult, |
| 272 | failure: IssueToolError, |
| 273 | dependencies, |
| 274 | }) |
| 275 | .annotate(Tool.Title, "Read issue") |
| 276 | .annotate(Tool.Readonly, true) |
| 277 | .annotate(Tool.Destructive, false) |
| 278 | .annotate(Tool.Idempotent, true) |
| 279 | .annotate(Tool.OpenWorld, true); |
| 280 | |
| 281 | const CreateIssueTool = Tool.make("create_issue", { |
| 282 | description: "File an issue in a project's tracker.", |
| 283 | parameters: Schema.Struct({ |
| 284 | projectId: Schema.optional( |
| 285 | ProjectId.annotate({ description: "Defaults to this thread's project." }), |
| 286 | ), |
| 287 | title: TrimmedNonEmptyString.check(Schema.isMaxLength(1024)), |
| 288 | body: Schema.optional(Schema.String.check(Schema.isMaxLength(65_536))), |
| 289 | labels: Schema.optional(Schema.Array(TrimmedNonEmptyString).check(Schema.isMaxLength(50))), |
| 290 | assignees: Schema.optional(Schema.Array(TrimmedNonEmptyString).check(Schema.isMaxLength(25))), |
| 291 | }), |
| 292 | success: CreateIssueResult, |
| 293 | failure: IssueToolError, |
| 294 | dependencies, |
| 295 | }) |
| 296 | .annotate(Tool.Title, "Create issue") |
| 297 | .annotate(Tool.Readonly, false) |
| 298 | .annotate(Tool.Destructive, false) |
| 299 | .annotate(Tool.Idempotent, false) |
| 300 | .annotate(Tool.OpenWorld, true); |
| 301 | |
| 302 | const CommentOnIssueTool = Tool.make("comment_on_issue", { |
| 303 | description: "Post a comment on an issue.", |
| 304 | parameters: Schema.Struct({ |
| 305 | ...IssueTargetInput.fields, |
| 306 | body: Schema.String.check(Schema.isNonEmpty()).check(Schema.isMaxLength(65_536)), |
| 307 | }), |
| 308 | success: IssueWriteResult, |
| 309 | failure: IssueToolError, |
| 310 | dependencies, |
| 311 | }) |
| 312 | .annotate(Tool.Title, "Comment on issue") |
| 313 | .annotate(Tool.Readonly, false) |
| 314 | .annotate(Tool.Destructive, false) |
| 315 | .annotate(Tool.Idempotent, false) |
| 316 | .annotate(Tool.OpenWorld, true); |
| 317 | |
| 318 | const SetIssueStateTool = Tool.make("set_issue_state", { |
| 319 | description: "Move an issue to one of its states. read_issue lists them under states.", |
| 320 | parameters: Schema.Struct({ |
| 321 | ...IssueTargetInput.fields, |
| 322 | state: TrimmedNonEmptyString.annotate({ |
| 323 | description: "A state name from read_issue's states.", |
| 324 | }), |
| 325 | }), |
| 326 | success: IssueWriteResult, |
| 327 | failure: IssueToolError, |
| 328 | dependencies, |
| 329 | }) |
| 330 | .annotate(Tool.Title, "Set issue state") |
| 331 | .annotate(Tool.Readonly, false) |
| 332 | .annotate(Tool.Destructive, false) |
| 333 | .annotate(Tool.Idempotent, true) |
| 334 | .annotate(Tool.OpenWorld, true); |
| 335 | |
| 336 | const LinkIssueTool = Tool.make("link_issue", { |
| 337 | description: |
| 338 | "Link an issue to a thread so T3 Code shows it beside the thread. Link every issue you work on or file.", |
| 339 | parameters: Schema.Struct({ ...IssueTargetInput.fields, ...ThreadTargetInput.fields }), |
| 340 | success: LinkIssueResult, |
| 341 | failure: IssueToolError, |
| 342 | dependencies, |
| 343 | }) |
| 344 | .annotate(Tool.Title, "Link issue to thread") |
| 345 | .annotate(Tool.Readonly, false) |
| 346 | .annotate(Tool.Destructive, false) |
| 347 | .annotate(Tool.Idempotent, true) |
| 348 | .annotate(Tool.OpenWorld, false); |
| 349 | |
| 350 | const UnlinkIssueTool = Tool.make("unlink_issue", { |
| 351 | description: "Remove an issue link from a thread. The issue itself is not changed.", |
| 352 | parameters: Schema.Struct({ ...IssueTargetInput.fields, ...ThreadTargetInput.fields }), |
| 353 | success: UnlinkIssueResult, |
| 354 | failure: IssueToolError, |
| 355 | dependencies, |
| 356 | }) |
| 357 | .annotate(Tool.Title, "Unlink issue from thread") |
| 358 | .annotate(Tool.Readonly, false) |
| 359 | .annotate(Tool.Destructive, true) |
| 360 | .annotate(Tool.Idempotent, true) |
| 361 | .annotate(Tool.OpenWorld, false); |
| 362 | |
| 363 | const ListThreadIssuesTool = Tool.make("list_thread_issues", { |
| 364 | description: "List the issues linked to a thread.", |
| 365 | parameters: ThreadTargetInput, |
| 366 | success: ListThreadIssuesResult, |
| 367 | failure: IssueToolError, |
| 368 | dependencies, |
| 369 | }) |
| 370 | .annotate(Tool.Title, "List thread issues") |
| 371 | .annotate(Tool.Readonly, true) |
| 372 | .annotate(Tool.Destructive, false) |
| 373 | .annotate(Tool.Idempotent, true) |
| 374 | .annotate(Tool.OpenWorld, false); |
| 375 | |
| 376 | export const IssuesToolkit = Toolkit.make( |
| 377 | ListIssuesTool, |
| 378 | ReadIssueTool, |
| 379 | CreateIssueTool, |
| 380 | CommentOnIssueTool, |
| 381 | SetIssueStateTool, |
| 382 | LinkIssueTool, |
| 383 | UnlinkIssueTool, |
| 384 | ListThreadIssuesTool, |
| 385 | ); |