| 1 | //! The MCP server's tools: a few resource tools, each with an `action`. |
| 2 | //! |
| 3 | //! Every operation is one action of one tool. A call is dispatched to the |
| 4 | //! operation it names, so permissions, the audit log, billing and outcomes |
| 5 | //! are exactly those of the REST API. A token sees only the actions its |
| 6 | //! scopes allow, and a tool none of whose actions it may use is not listed. |
| 7 | //! |
| 8 | //! The listed input schema is one flat object: `action`, then every field |
| 9 | //! any of its actions takes. Which fields each action needs is in the |
| 10 | //! `action` field's description and checked on every call. Claude's API, |
| 11 | //! and so most MCP clients, refuse a tool whose input schema has `oneOf` |
| 12 | //! at its top level, so the schema keyed by action, with each action's |
| 13 | //! required fields, is [`discriminated`], published on the server's card |
| 14 | //! and in the docs. |
| 15 | |
| 16 | use g1t_contracts::credentials::NEVER; |
| 17 | use g1t_contracts::identity::AgentScope; |
| 18 | use g1t_contracts::scopes::{Level, NO_SCOPE, TokenAccess, scope_for}; |
| 19 | use serde_json::{Map, Value, json}; |
| 20 | |
| 21 | use crate::about::AboutOp; |
| 22 | use crate::artifacts::ArtifactsOp; |
| 23 | use crate::deploy_keys::DeployKeysOp; |
| 24 | use crate::deployments::DeploymentsOp; |
| 25 | use crate::packages::PackagesOp; |
| 26 | use crate::protection::ProtectionOp; |
| 27 | use crate::token_policy::TokenOp; |
| 28 | use crate::operations::Op; |
| 29 | use crate::checks::ChecksOp; |
| 30 | use crate::rules::RulesOp; |
| 31 | use crate::security::SecurityOp; |
| 32 | |
| 33 | pub struct Action { |
| 34 | pub name: &'static str, |
| 35 | pub op: Op, |
| 36 | /// One line, for the `action` field's description. |
| 37 | pub summary: &'static str, |
| 38 | } |
| 39 | |
| 40 | pub struct Tool { |
| 41 | pub name: &'static str, |
| 42 | pub title: &'static str, |
| 43 | /// What it is for, in a sentence or two. |
| 44 | pub description: &'static str, |
| 45 | pub actions: &'static [Action], |
| 46 | /// The action a call without one runs. |
| 47 | pub default_action: Option<&'static str>, |
| 48 | } |
| 49 | |
| 50 | const fn a(name: &'static str, op: Op, summary: &'static str) -> Action { |
| 51 | Action { name, op, summary } |
| 52 | } |
| 53 | |
| 54 | pub const TOOLS: &[Tool] = &[ |
| 55 | Tool { |
| 56 | name: "search", |
| 57 | title: "Search", |
| 58 | description: "Find things. `code` (the default) searches all of g1t you can see: repositories, code, issues, pull requests and people, with qualifiers like repo:owner/name, language:rust, is:issue. `context` searches one workspace's catalog, docs, issues and memory by meaning.", |
| 59 | default_action: Some("code"), |
| 60 | actions: &[ |
| 61 | a("code", Op::Search, "Search all of g1t: repositories, code, issues, pull requests, people"), |
| 62 | a("context", Op::SearchContext, "Search a workspace's context hub by meaning"), |
| 63 | a("entity", Op::GetEntity, "One catalog entry and its relations"), |
| 64 | a("ticket", Op::GetContext, "A Jira, Linear or Sentry item the work refers to, as it is now"), |
| 65 | ], |
| 66 | }, |
| 67 | Tool { |
| 68 | name: "repository", |
| 69 | title: "Repositories", |
| 70 | description: "Repositories: find, read and create them, change their settings and rulesets (what may happen to branches and tags, and what a pull request needs to merge), check their CODEOWNERS file, manage their labels and milestones, see and dismiss their security alerts (secrets and vulnerable dependencies), read what their default branch says (languages, contributors, license), star them, and publish releases. Name one as \"owner/name\". Deleting, transferring and changing visibility need `confirm`.", |
| 71 | default_action: None, |
| 72 | actions: &[ |
| 73 | a("list", Op::ListRepos, "Repositories you can see"), |
| 74 | a("get", Op::GetRepo, "One repository"), |
| 75 | a("create", Op::CreateRepo, "Create one, empty or copied from a public git URL"), |
| 76 | a("update", Op::UpdateRepo, "Change description, website, topics, default branch, protection"), |
| 77 | a("get_settings", Op::GetRepoSettings, "How pull requests merge, and the default branch's protection as its rules stack"), |
| 78 | a("update_settings", Op::UpdateRepoSettings, "Change how pull requests merge and the default branch protection ruleset"), |
| 79 | a("check_names", Op::ListCheckNames, "Check names reported lately, to require in a ruleset"), |
| 80 | a("list_rulesets", Op::Rules(RulesOp::ListRepoRulesets), "Its rulesets, and its workspace's that hold in it"), |
| 81 | a("get_ruleset", Op::Rules(RulesOp::GetRepoRuleset), "One ruleset"), |
| 82 | a("create_ruleset", Op::Rules(RulesOp::CreateRepoRuleset), "Create a ruleset for its branches or tags"), |
| 83 | a("update_ruleset", Op::Rules(RulesOp::UpdateRepoRuleset), "Change a ruleset"), |
| 84 | a("delete_ruleset", Op::Rules(RulesOp::DeleteRepoRuleset), "Delete a ruleset"), |
| 85 | a("branch_rules", Op::Rules(RulesOp::GetBranchRules), "Every rule that holds for a branch or tag, and where it comes from"), |
| 86 | a("rule_evaluations", Op::Rules(RulesOp::ListRuleEvaluations), "How its rules judged pushes and merges, with insights"), |
| 87 | a("codeowners", Op::GetCodeownersErrors, "Problems in its CODEOWNERS file, by line"), |
| 88 | a("list_labels", Op::ListLabels, "Labels, with colors and how many issues and pull requests carry each"), |
| 89 | a("create_label", Op::CreateLabel, "Create a label"), |
| 90 | a("update_label", Op::UpdateLabel, "Rename a label or change its color or description"), |
| 91 | a("delete_label", Op::DeleteLabel, "Delete a label, from everything that carries it"), |
| 92 | a("add_default_labels", Op::AddDefaultLabels, "Add the default labels it is missing"), |
| 93 | a("list_milestones", Op::ListMilestones, "Milestones, with progress and due dates"), |
| 94 | a("get_milestone", Op::GetMilestone, "One milestone with its issues and pull requests"), |
| 95 | a("create_milestone", Op::CreateMilestone, "Create a milestone"), |
| 96 | a("update_milestone", Op::UpdateMilestone, "Change a milestone's title, description, due date or state"), |
| 97 | a("delete_milestone", Op::DeleteMilestone, "Delete a milestone"), |
| 98 | a("list_events", Op::ListEvents, "Timeline: pushes, issues, pull requests, comments"), |
| 99 | a("languages", Op::About(AboutOp::GetLanguages), "Its languages by bytes, with colors and percentages"), |
| 100 | a("contributors", Op::About(AboutOp::ListContributors), "Who made it: commits per person, agent and author, by week"), |
| 101 | a("license", Op::About(AboutOp::GetLicense), "The license its LICENSE file holds"), |
| 102 | a("stargazers", Op::About(AboutOp::ListStargazers), "Who starred it"), |
| 103 | a("starred", Op::About(AboutOp::CheckStarred), "Whether you starred it, and how many have"), |
| 104 | a("star", Op::About(AboutOp::Star), "Star it"), |
| 105 | a("unstar", Op::About(AboutOp::Unstar), "Take your star back"), |
| 106 | a("list_starred", Op::About(AboutOp::ListStarred), "Repositories you starred"), |
| 107 | a("list_releases", Op::About(AboutOp::ListReleases), "Releases, newest first"), |
| 108 | a("latest_release", Op::About(AboutOp::GetLatestRelease), "The latest release"), |
| 109 | a("get_release", Op::About(AboutOp::GetRelease), "One release by id"), |
| 110 | a("get_release_by_tag", Op::About(AboutOp::GetReleaseByTag), "The release of a tag"), |
| 111 | a("create_release", Op::About(AboutOp::CreateRelease), "Publish a release of a tag, making the tag if needed"), |
| 112 | a("update_release", Op::About(AboutOp::UpdateRelease), "Change a release's title, notes, draft or prerelease"), |
| 113 | a("delete_release", Op::About(AboutOp::DeleteRelease), "Delete a release; its tag stays"), |
| 114 | a("rename_branch", Op::RenameBranch, "Rename a branch"), |
| 115 | a("rename", Op::RenameRepo, "Rename it; old addresses redirect"), |
| 116 | a("transfer", Op::TransferRepo, "Move it to another workspace you own"), |
| 117 | a("archive", Op::ArchiveRepo, "Make it read-only"), |
| 118 | a("unarchive", Op::UnarchiveRepo, "Make it writable again"), |
| 119 | a("set_visibility", Op::SetRepoVisibility, "Make it public or private"), |
| 120 | a("delete", Op::DeleteRepo, "Delete it; restorable for 30 days"), |
| 121 | a("list_deleted", Op::ListDeletedRepos, "A workspace's deleted repositories"), |
| 122 | a("restore", Op::RestoreRepo, "Restore a deleted one"), |
| 123 | a("purge", Op::PurgeRepo, "Remove a deleted one for good"), |
| 124 | a("security_alerts", Op::ListSecurityAlerts, "Secret and dependency alerts, filtered by state"), |
| 125 | a("dismiss_alert", Op::DismissSecurityAlert, "Dismiss an alert with a reason"), |
| 126 | a("reopen_alert", Op::ReopenSecurityAlert, "Reopen a dismissed alert"), |
| 127 | ], |
| 128 | }, |
| 129 | Tool { |
| 130 | name: "issue", |
| 131 | title: "Issues", |
| 132 | description: "Issues: what should change. Read one before working on it to see the pull requests already made for it. Issues and pull requests share numbers; `comment` works on either.", |
| 133 | default_action: None, |
| 134 | actions: &[ |
| 135 | a("list", Op::ListIssues, "Issues on a repository, newest first"), |
| 136 | a("get", Op::GetIssue, "One issue with comments and its pull requests"), |
| 137 | a("create", Op::CreateIssue, "Open an issue"), |
| 138 | a("update", Op::UpdateIssue, "Change title, body, labels, milestone or assignees"), |
| 139 | a("labels", Op::ListIssueLabels, "The labels an issue or pull request carries"), |
| 140 | a("add_labels", Op::AddIssueLabels, "Add labels to an issue or pull request"), |
| 141 | a("set_labels", Op::SetIssueLabels, "Replace the labels of an issue or pull request"), |
| 142 | a("remove_labels", Op::RemoveIssueLabels, "Take labels off an issue or pull request"), |
| 143 | a("close", Op::CloseIssue, "Close it without a pull request"), |
| 144 | a("reopen", Op::ReopenIssue, "Reopen it"), |
| 145 | a("comment", Op::AddComment, "Comment on an issue or pull request; path and line for one line of a change"), |
| 146 | a("edit_comment", Op::EditComment, "Change a comment's text: your own, or any with the Maintain role"), |
| 147 | a("delete_comment", Op::DeleteComment, "Delete a comment: your own, or any with the Maintain role"), |
| 148 | a("import", Op::ImportIssue, "Open an issue from a Jira, Linear or Sentry item"), |
| 149 | ], |
| 150 | }, |
| 151 | Tool { |
| 152 | name: "pull_request", |
| 153 | title: "Pull requests", |
| 154 | description: "Pull requests: start a change for an issue, record your session, mark it ready, ask people and teams to review, review and merge. Read `overlaps` and `behind` on `get` before going far, and `code_owners` for whose approval it needs.", |
| 155 | default_action: None, |
| 156 | actions: &[ |
| 157 | a("list", Op::ListPullRequests, "Pull requests on a repository, newest first"), |
| 158 | a("get", Op::GetPullRequest, "Status, checks and required checks, reviews, overlaps, whether it is behind"), |
| 159 | a("changes", Op::GetPullRequestChanges, "Files and line-by-line diff"), |
| 160 | a("create", Op::CreatePullRequest, "Start a draft with its own fork to push to, or open one from a pushed branch"), |
| 161 | a("update", Op::UpdatePullRequest, "Change its base branch, labels, milestone, assignees or reviewers"), |
| 162 | a("record_session", Op::RecordSession, "Append prompt, reasoning and tool entries to its session"), |
| 163 | a("read_session", Op::ReadSession, "Its recorded session"), |
| 164 | a("ready", Op::MarkPullRequestReady, "Mark a draft ready, with a summary"), |
| 165 | a("draft", Op::ConvertPullRequestToDraft, "Turn it back into a draft"), |
| 166 | a("request_reviewers", Op::RequestReviewers, "Ask people or teams to review it"), |
| 167 | a("remove_requested_reviewers", Op::RemoveRequestedReviewers, "Stop asking people or teams to review it"), |
| 168 | a("review", Op::ReviewPullRequest, "Approve or request changes"), |
| 169 | a("close", Op::ClosePullRequest, "Close without merging"), |
| 170 | a("reopen", Op::ReopenPullRequest, "Reopen a closed one"), |
| 171 | a("merge", Op::MergePullRequest, "Land it, or join the merge queue"), |
| 172 | a("merge_queue", Op::GetMergeQueue, "The repository's merge queue"), |
| 173 | ], |
| 174 | }, |
| 175 | Tool { |
| 176 | name: "agent", |
| 177 | title: "g1t agents", |
| 178 | description: "Put g1t's agent to work and talk to it. One agent per issue; to do more at once, use more issues. Starting an agent uses the workspace's money.", |
| 179 | default_action: None, |
| 180 | actions: &[ |
| 181 | a("delegate", Op::Delegate, "Open an issue and put an agent on it in one step"), |
| 182 | a("assign", Op::AssignIssue, "Put an agent on an existing issue"), |
| 183 | a("message", Op::MessageAgent, "Tell the agent on a pull request something, or ask another agent"), |
| 184 | a("answer", Op::AnswerMessage, "Answer a question or handoff sent to you"), |
| 185 | a("take_messages", Op::TakeMessages, "For a g1t agent: messages not seen yet"), |
| 186 | ], |
| 187 | }, |
| 188 | Tool { |
| 189 | name: "plan", |
| 190 | title: "Plans", |
| 191 | description: "Turn an outcome into issues: an agent proposes them with what done means and their dependencies; nothing opens until you apply the plan.", |
| 192 | default_action: None, |
| 193 | actions: &[ |
| 194 | a("create", Op::PlanWork, "Ask an agent for a plan; read it with get until ready"), |
| 195 | a("get", Op::GetPlan, "A plan and the issues it proposes"), |
| 196 | a("apply", Op::ApplyPlan, "Open its issues; with assign, agents start in dependency order"), |
| 197 | ], |
| 198 | }, |
| 199 | Tool { |
| 200 | name: "memory", |
| 201 | title: "Memory", |
| 202 | description: "What the project and its workspace remember for the next agent: how to build, conventions, decisions, traps. Recall before you start; remember one short fact at a time, never a secret.", |
| 203 | default_action: None, |
| 204 | actions: &[ |
| 205 | a("recall", Op::Recall, "Search memory, or list it all"), |
| 206 | a("remember", Op::Remember, "Save one fact"), |
| 207 | ], |
| 208 | }, |
| 209 | Tool { |
| 210 | name: "workflow", |
| 211 | title: "Workflows", |
| 212 | description: "GitHub Actions workflows from .g1t/workflows: their runs, jobs and logs, and running, cancelling or rerunning them. Runs' artifacts: listing, a download link, deleting, and how long they are kept. Deployments wherever they run (reported from any CI, made by jobs with an `environment:`, or built on g1t.page), their statuses and environments, and reporting your own; environments' protection rules, approving or rejecting the jobs they hold, approving a pull request's run from outside, the token's default permissions and repository dispatch. Checks on commits: statuses, check runs (a g1t Actions job is one) and check suites, to read where a commit stands or report on it from CI or an integration. Also the self-hosted runners they run on: a workspace's (`workspace`) or a repository's own (`repo`), their groups, and where agent work runs.", |
| 213 | default_action: None, |
| 214 | actions: &[ |
| 215 | a("list", Op::ListWorkflows, "Workflows on the default branch"), |
| 216 | a("list_runs", Op::ListWorkflowRuns, "Runs, newest first"), |
| 217 | a("get_run", Op::GetWorkflowRun, "One run with its jobs and steps; an earlier attempt with attempt"), |
| 218 | a("job_logs", Op::GetJobLogs, "A job's log after a sequence number"), |
| 219 | a("dispatch", Op::DispatchWorkflow, "Run a workflow_dispatch workflow"), |
| 220 | a("cancel", Op::CancelWorkflowRun, "Cancel a run, letting its jobs clean up; force stops them outright"), |
| 221 | a("rerun", Op::RerunWorkflowRun, "Run a finished run again: all, failed_only, or one job; debug for debug logging"), |
| 222 | a("update", Op::UpdateWorkflow, "Turn a workflow on or off"), |
| 223 | a("list_artifacts", Op::Artifacts(ArtifactsOp::ListArtifacts), "A repository's artifacts, newest first; or a run's with run_artifacts"), |
| 224 | a("run_artifacts", Op::Artifacts(ArtifactsOp::ListRunArtifacts), "One run's artifacts"), |
| 225 | a("get_artifact", Op::Artifacts(ArtifactsOp::GetArtifact), "One artifact: size, digest, expiry, run"), |
| 226 | a("download_artifact", Op::Artifacts(ArtifactsOp::DownloadArtifact), "A 10-minute link to an artifact's zip"), |
| 227 | a("delete_artifact", Op::Artifacts(ArtifactsOp::DeleteArtifact), "Delete an artifact before it expires"), |
| 228 | a("artifact_retention", Op::Artifacts(ArtifactsOp::GetArtifactRetention), "Days the repository keeps artifacts"), |
| 229 | a("set_artifact_retention", Op::Artifacts(ArtifactsOp::SetArtifactRetention), "Change the days the repository keeps artifacts"), |
| 230 | a("combined_status", Op::Checks(ChecksOp::GetCombinedStatus), "A commit's statuses and the state they add up to"), |
| 231 | a("list_statuses", Op::Checks(ChecksOp::ListCommitStatuses), "A commit's statuses, newest first"), |
| 232 | a("set_status", Op::Checks(ChecksOp::CreateCommitStatus), "Set a status on a commit"), |
| 233 | a("list_check_runs", Op::Checks(ChecksOp::ListCheckRunsForRef), "A commit's check runs, g1t Actions jobs included"), |
| 234 | a("get_check_run", Op::Checks(ChecksOp::GetCheckRun), "One check run with its report"), |
| 235 | a("check_run_annotations", Op::Checks(ChecksOp::ListCheckRunAnnotations), "What a check run says about lines of files"), |
| 236 | a("create_check_run", Op::Checks(ChecksOp::CreateCheckRun), "Report a check run on a commit"), |
| 237 | a("update_check_run", Op::Checks(ChecksOp::UpdateCheckRun), "Move a check run on, complete it, add annotations"), |
| 238 | a("rerequest_check_run", Op::Checks(ChecksOp::RerequestCheckRun), "Ask for a check run to run again"), |
| 239 | a("list_check_suites", Op::Checks(ChecksOp::ListCheckSuitesForRef), "A commit's check suites, one per reporter or workflow run"), |
| 240 | a("get_check_suite", Op::Checks(ChecksOp::GetCheckSuite), "One check suite"), |
| 241 | a("rerequest_check_suite", Op::Checks(ChecksOp::RerequestCheckSuite), "Ask for a check suite to run again"), |
| 242 | a("list_deployments", Op::Deployments(DeploymentsOp::ListDeployments), "Deployments wherever they run, newest first, filtered"), |
| 243 | a("get_deployment", Op::Deployments(DeploymentsOp::GetDeployment), "One deployment with every status it has had"), |
| 244 | a("create_deployment", Op::Deployments(DeploymentsOp::CreateDeployment), "Report a deployment of a ref to an environment"), |
| 245 | a("deployment_statuses", Op::Deployments(DeploymentsOp::ListDeploymentStatuses), "A deployment's statuses, newest first"), |
| 246 | a("create_deployment_status", Op::Deployments(DeploymentsOp::CreateDeploymentStatus), "Report where a deployment is: in_progress, success, failure"), |
| 247 | a("list_environments", Op::Deployments(DeploymentsOp::ListEnvironments), "Environments with their current and latest deployments"), |
| 248 | a("get_environment", Op::Deployments(DeploymentsOp::GetEnvironment), "One environment by name, with its protection rules"), |
| 249 | a("update_environment", Op::Protection(ProtectionOp::UpdateEnvironment), "Set an environment's reviewers, wait timer and branches"), |
| 250 | a("delete_environment", Op::Protection(ProtectionOp::DeleteEnvironment), "Remove an environment's protection rules"), |
| 251 | a("pending_deployments", Op::Protection(ProtectionOp::GetPendingDeployments), "The environments holding a run's jobs"), |
| 252 | a("review_deployments", Op::Protection(ProtectionOp::ReviewPendingDeployments), "Approve or reject a run's jobs for its environments"), |
| 253 | a("approve_run", Op::Protection(ProtectionOp::ApproveWorkflowRun), "Let a run of a pull request from outside start"), |
| 254 | a("get_permissions", Op::Protection(ProtectionOp::GetWorkflowPermissions), "What a job's token gets without `permissions:`"), |
| 255 | a("set_permissions", Op::Protection(ProtectionOp::SetWorkflowPermissions), "Set it: read or write"), |
| 256 | a("get_approval_policy", Op::Protection(ProtectionOp::GetForkPrApproval), "Which pull requests' runs wait for approval"), |
| 257 | a("set_approval_policy", Op::Protection(ProtectionOp::SetForkPrApproval), "Set which pull requests' runs wait for approval"), |
| 258 | a("get_access", Op::Protection(ProtectionOp::GetActionsAccess), "Which repositories may use this one's actions and workflows"), |
| 259 | a("set_access", Op::Protection(ProtectionOp::SetActionsAccess), "Let the workspace's private repositories use them, or not"), |
| 260 | a("repository_dispatch", Op::Protection(ProtectionOp::CreateRepositoryDispatch), "Start repository_dispatch workflows with an event"), |
| 261 | a("get_workspace_permissions", Op::Protection(ProtectionOp::GetWorkspaceWorkflowPermissions), "A workspace's default and maximum token permissions"), |
| 262 | a("set_workspace_permissions", Op::Protection(ProtectionOp::SetWorkspaceWorkflowPermissions), "Set them, and whether jobs may open pull requests"), |
| 263 | a("list_runners", Op::ListRunners, "Self-hosted runners, with status, labels and what each is doing"), |
| 264 | a("create_runner_token", Op::CreateRunnerRegistrationToken, "A one-hour token for g1t-runner register"), |
| 265 | a("remove_runner", Op::RemoveRunner, "Remove a self-hosted runner"), |
| 266 | a("list_runner_groups", Op::ListRunnerGroups, "A workspace's runner groups"), |
| 267 | a("create_runner_group", Op::CreateRunnerGroup, "Make a group, for some repositories"), |
| 268 | a("update_runner_group", Op::UpdateRunnerGroup, "Rename a group or change its repositories"), |
| 269 | a("delete_runner_group", Op::DeleteRunnerGroup, "Delete a group; its runners join the default"), |
| 270 | a("get_runner_settings", Op::GetRunnerSettings, "Where agent work runs; whether forks may use runners"), |
| 271 | a("update_runner_settings", Op::UpdateRunnerSettings, "Change them"), |
| 272 | ], |
| 273 | }, |
| 274 | Tool { |
| 275 | name: "package", |
| 276 | title: "Packages", |
| 277 | description: "A workspace's packages in every registry (container images, npm, Cargo, Maven, NuGet, RubyGems, Composer): their versions and downloads, deleting and restoring them within 30 days, their visibility and repository, who has a role on them, and which repositories' workflows may use them (Manage Actions access). Name one by workspace, package_type and package_name.", |
| 278 | default_action: None, |
| 279 | actions: &[ |
| 280 | a("list", Op::Packages(PackagesOp::ListPackages), "A workspace's packages; state deleted for restorable ones"), |
| 281 | a("get", Op::Packages(PackagesOp::GetPackage), "One package: address, visibility, repository, downloads"), |
| 282 | a("versions", Op::Packages(PackagesOp::ListVersions), "Its versions with tags and downloads; state deleted too"), |
| 283 | a("get_version", Op::Packages(PackagesOp::GetVersion), "One version by id, version, digest or tag"), |
| 284 | a("update", Op::Packages(PackagesOp::UpdatePackage), "Set visibility, or inherit_access for a linked one"), |
| 285 | a("link", Op::Packages(PackagesOp::LinkPackage), "Link it to a repository of its workspace"), |
| 286 | a("unlink", Op::Packages(PackagesOp::UnlinkPackage), "Unlink it: the workspace's, private"), |
| 287 | a("access", Op::Packages(PackagesOp::ListAccess), "People and teams with a role on it"), |
| 288 | a("set_access", Op::Packages(PackagesOp::SetAccess), "Give a person or team read, write or admin"), |
| 289 | a("remove_access", Op::Packages(PackagesOp::RemoveAccess), "Take a person's or team's role away"), |
| 290 | a("actions_access", Op::Packages(PackagesOp::ListActionsAccess), "Repositories whose workflows may use it"), |
| 291 | a("set_actions_access", Op::Packages(PackagesOp::SetActionsAccess), "Let a repository's workflows read or write it"), |
| 292 | a("remove_actions_access", Op::Packages(PackagesOp::RemoveActionsAccess), "Stop a repository's workflows using it"), |
| 293 | a("delete", Op::Packages(PackagesOp::DeletePackage), "Delete it; restorable for 30 days"), |
| 294 | a("restore", Op::Packages(PackagesOp::RestorePackage), "Restore a deleted package"), |
| 295 | a("delete_version", Op::Packages(PackagesOp::DeleteVersion), "Delete a version; restorable for 30 days"), |
| 296 | a("restore_version", Op::Packages(PackagesOp::RestoreVersion), "Restore a deleted version"), |
| 297 | ], |
| 298 | }, |
| 299 | Tool { |
| 300 | name: "secret", |
| 301 | title: "Secrets and variables", |
| 302 | description: "A repository's or workspace's secrets and variables, read by workflows and deployments. Secret values are never returned.", |
| 303 | default_action: None, |
| 304 | actions: &[ |
| 305 | a("list_secrets", Op::ListActionsSecrets, "Secrets, without values"), |
| 306 | a("set_secret", Op::SetActionsSecret, "Add or change a secret"), |
| 307 | a("delete_secret", Op::DeleteActionsSecret, "Remove a secret"), |
| 308 | a("list_variables", Op::ListActionsVariables, "Variables, with values"), |
| 309 | a("set_variable", Op::SetActionsVariable, "Add or change a variable"), |
| 310 | a("delete_variable", Op::DeleteActionsVariable, "Remove a variable"), |
| 311 | ], |
| 312 | }, |
| 313 | Tool { |
| 314 | name: "webhook", |
| 315 | title: "Webhooks", |
| 316 | description: "HTTPS addresses sent signed events as they happen, for a repository or a whole workspace.", |
| 317 | default_action: None, |
| 318 | actions: &[ |
| 319 | a("list", Op::ListWebhooks, "Webhooks, without secrets"), |
| 320 | a("create", Op::CreateWebhook, "Register one; a ping is sent"), |
| 321 | a("update", Op::UpdateWebhook, "Change address, events or active"), |
| 322 | a("delete", Op::DeleteWebhook, "Remove one"), |
| 323 | a("ping", Op::PingWebhook, "Send a ping"), |
| 324 | a("list_deliveries", Op::ListWebhookDeliveries, "Latest deliveries"), |
| 325 | a("redeliver", Op::RedeliverWebhook, "Send a delivery again"), |
| 326 | ], |
| 327 | }, |
| 328 | Tool { |
| 329 | name: "access", |
| 330 | title: "Who has access", |
| 331 | description: "Who has access to a repository and with which role (read, triage, write, maintain, admin), outside collaborators, a workspace's base permission, and a repository's deploy keys.", |
| 332 | default_action: None, |
| 333 | actions: &[ |
| 334 | a("list_collaborators", Op::ListCollaborators, "Everyone with a role, and pending invitations"), |
| 335 | a("get_permission", Op::GetCollaboratorPermission, "One person's role and capabilities"), |
| 336 | a("add_collaborator", Op::AddCollaborator, "Give someone a role, by username or email"), |
| 337 | a("update_collaborator", Op::UpdateCollaborator, "Change a direct role"), |
| 338 | a("remove_collaborator", Op::RemoveCollaborator, "Take away a direct role"), |
| 339 | a("list_invitations", Op::ListRepoInvitations, "Pending invitations to a repository"), |
| 340 | a("revoke_invitation", Op::RevokeRepoInvitation, "Withdraw one"), |
| 341 | a("set_base_permission", Op::SetBasePermission, "What every member gets on each repository"), |
| 342 | a("list_outside_collaborators", Op::ListOutsideCollaborators, "People with roles who are not members"), |
| 343 | a("list_deploy_keys", Op::DeployKeys(DeployKeysOp::ListDeployKeys), "SSH keys that reach this one repository"), |
| 344 | a("get_deploy_key", Op::DeployKeys(DeployKeysOp::GetDeployKey), "One deploy key, by id"), |
| 345 | a("add_deploy_key", Op::DeployKeys(DeployKeysOp::CreateDeployKey), "Add one; read-only unless read_only is false"), |
| 346 | a("remove_deploy_key", Op::DeployKeys(DeployKeysOp::DeleteDeployKey), "Delete one"), |
| 347 | ], |
| 348 | }, |
| 349 | Tool { |
| 350 | name: "team", |
| 351 | title: "Teams", |
| 352 | description: "Teams: groups of a workspace's members, given roles on repositories together, mentioned as @workspace/team and asked to review together. Name one by `workspace` and its slug (`team`). Any member may create a team; the workspace's owners and the team's maintainers manage it. A secret team is seen only by its people and the owners.", |
| 353 | default_action: None, |
| 354 | actions: &[ |
| 355 | a("list", Op::ListTeams, "A workspace's teams you can see"), |
| 356 | a("get", Op::GetTeam, "One team"), |
| 357 | a("create", Op::CreateTeam, "Create a team; you become its maintainer"), |
| 358 | a("update", Op::UpdateTeam, "Change its name, slug, description, visibility, parent or notifications"), |
| 359 | a("delete", Op::DeleteTeam, "Delete it; its child teams move up"), |
| 360 | a("list_members", Op::ListTeamMembers, "Its people and their roles, child teams' with include_child_teams"), |
| 361 | a("set_member", Op::SetTeamMember, "Add a member of the workspace, or change their role"), |
| 362 | a("remove_member", Op::RemoveTeamMember, "Take someone out of it"), |
| 363 | a("list_child_teams", Op::ListChildTeams, "The teams nested under it"), |
| 364 | a("list_repos", Op::ListTeamRepos, "The repositories it has a role on"), |
| 365 | a("set_repo", Op::SetTeamRepo, "Give it a role on a repository"), |
| 366 | a("remove_repo", Op::RemoveTeamRepo, "Take its role on a repository away"), |
| 367 | a("set_review_assignment", Op::SetTeamReviewAssignment, "Whom it picks when asked to review"), |
| 368 | a("list_user_teams", Op::ListUserTeams, "The teams someone is in"), |
| 369 | ], |
| 370 | }, |
| 371 | Tool { |
| 372 | name: "workspace", |
| 373 | title: "Workspaces", |
| 374 | description: "Workspaces own repositories (g1t.sh/{workspace}/{repo}): create, update or delete one, invite members, connect integrations and model providers, set rulesets that hold across its repositories, read and change its projects (what each is, where it runs, its links), and keep your own pinned projects at the top of its sidebar.", |
| 375 | default_action: None, |
| 376 | actions: &[ |
| 377 | a("get", Op::GetWorkspace, "A workspace's details and settings"), |
| 378 | a("create", Op::CreateWorkspace, "Create a workspace"), |
| 379 | a("delete", Op::DeleteWorkspace, "Delete a workspace and everything in it (support can restore it for 30 days)"), |
| 380 | a("update", Op::UpdateWorkspace, "Change its name, description, base permission, who may create teams, member privileges or the two-factor requirement"), |
| 381 | a("list_members", Op::ListMembers, "Its members, owners first, with their roles"), |
| 382 | a("update_member", Op::UpdateMember, "Make someone an owner or a member, billing manager or security manager"), |
| 383 | a("remove_member", Op::RemoveMember, "Remove someone from it"), |
| 384 | a("transfer_ownership", Op::TransferOwnership, "Hand it to another member: they become an owner, you a member"), |
| 385 | a("leave", Op::LeaveWorkspace, "Leave it yourself"), |
| 386 | a("list_invites", Op::ListWorkspaceInvites, "Its invites"), |
| 387 | a("invite_member", Op::InviteMember, "Invite someone by username or email address"), |
| 388 | a("revoke_invite", Op::RevokeWorkspaceInvite, "Revoke a pending invite"), |
| 389 | a("list_integrations", Op::ListIntegrations, "Model providers, alert sources, trackers"), |
| 390 | a("connect_integration", Op::ConnectIntegration, "Connect one"), |
| 391 | a("update_integration", Op::UpdateIntegration, "Change one: rotate its key, choose its AI Gateway models"), |
| 392 | a("disconnect_integration", Op::DisconnectIntegration, "Remove one"), |
| 393 | a("test_integration", Op::TestIntegration, "Check its credentials"), |
| 394 | a("get_model_routes", Op::GetModelRoutes, "Where each kind of work's model requests go"), |
| 395 | a("set_model_routes", Op::SetModelRoutes, "Replace them"), |
| 396 | a("list_projects", Op::ListProjects, "Its projects you can see: what each is, where it runs, its links"), |
| 397 | a("get_project", Op::GetProject, "One project"), |
| 398 | a("update_project", Op::UpdateProject, "Change a project's name, description, kind, where it runs or its links"), |
| 399 | a("list_pinned_projects", Op::ListPinnedProjects, "Your pinned projects in it, in your order"), |
| 400 | a("pin_project", Op::PinProject, "Pin a project, at a position or the end"), |
| 401 | a("unpin_project", Op::UnpinProject, "Unpin a project"), |
| 402 | a("reorder_pinned_projects", Op::ReorderPinnedProjects, "Put your pins in a new order"), |
| 403 | a("list_rulesets", Op::Rules(RulesOp::ListWorkspaceRulesets), "Its rulesets, which hold across its repositories"), |
| 404 | a("get_ruleset", Op::Rules(RulesOp::GetWorkspaceRuleset), "One of its rulesets"), |
| 405 | a("create_ruleset", Op::Rules(RulesOp::CreateWorkspaceRuleset), "Create a ruleset for some or all of its repositories"), |
| 406 | a("update_ruleset", Op::Rules(RulesOp::UpdateWorkspaceRuleset), "Change one of its rulesets"), |
| 407 | a("delete_ruleset", Op::Rules(RulesOp::DeleteWorkspaceRuleset), "Delete one of its rulesets"), |
| 408 | a("rule_evaluations", Op::Rules(RulesOp::ListWorkspaceRuleEvaluations), "How rules judged changes across its repositories"), |
| 409 | a("get_token_policy", Op::Tokens(TokenOp::GetTokenPolicy), "Its rules for personal access tokens"), |
| 410 | a("set_token_policy", Op::Tokens(TokenOp::SetTokenPolicy), "Change them: kinds allowed, approval, lifetime"), |
| 411 | a("list_member_tokens", Op::Tokens(TokenOp::ListMemberTokens), "Members' personal access tokens that reach it"), |
| 412 | a("list_token_requests", Op::Tokens(TokenOp::ListTokenRequests), "Fine-grained tokens waiting for approval"), |
| 413 | a("review_token_request", Op::Tokens(TokenOp::ReviewTokenRequest), "Approve or deny one"), |
| 414 | a("revoke_member_token", Op::Tokens(TokenOp::RevokeMemberToken), "Revoke a member's token in it"), |
| 415 | ], |
| 416 | }, |
| 417 | Tool { |
| 418 | name: "billing", |
| 419 | title: "Billing", |
| 420 | description: "A workspace's billing: its usage by product, project and day, its budget (the monthly spend limit, alerts and whether usage pauses at it), its AI credit, its invoices, and its AI Gateway requests. Amounts are whole millionths of a dollar (`_micros`), or cents (`_cents`) where named. Members read it; changing the budget and buying credit are for owners, as people, and never for g1t's agents.", |
| 421 | default_action: Some("usage"), |
| 422 | actions: &[ |
| 423 | a("usage", Op::GetUsage, "Usage over a range of days, by product, meter, project and day, and what paid for it"), |
| 424 | a("budget", Op::GetBudget, "The monthly spend limit, what was spent, alerts and whether usage pauses at the limit"), |
| 425 | a("set_budget", Op::SetBudget, "Change the spend limit, alerts, pausing or the alert webhook"), |
| 426 | a("ai_credit", Op::GetAiCredit, "AI credit left, its grants, auto-reload and how to buy more"), |
| 427 | a("buy_ai_credit", Op::BuyAiCredit, "A payment page to buy AI credit, for a person to open"), |
| 428 | a("invoices", Op::ListInvoices, "Every invoice, the itemised usage invoices, and the next one so far"), |
| 429 | a("billing_details", Op::GetBillingDetails, "Who invoices are made out to and the payment method on file"), |
| 430 | a("gateway_requests", Op::ListGatewayRequests, "Recent AI Gateway requests: model, tokens, cost, status and token"), |
| 431 | ], |
| 432 | }, |
| 433 | Tool { |
| 434 | name: "security", |
| 435 | title: "Security", |
| 436 | description: "A repository's security: secret scanning alerts and push protection bypasses, custom secret patterns, code scanning alerts and SARIF uploads, vulnerability alerts, the dependency graph and its SBOM, dependency review, settings, and a workspace's overview. Fix an alert with g1t. Findings are shown to those who can change the code only. Give `repo` (owner/name), or `workspace` for lists across one.", |
| 437 | default_action: Some("secret_alerts"), |
| 438 | actions: &[ |
| 439 | a("secret_alerts", Op::Security(SecurityOp::ListSecretAlerts), "Secret scanning alerts; by state, secret_type, validity, bypassed"), |
| 440 | a("secret_alert", Op::Security(SecurityOp::GetSecretAlert), "One secret alert, with where it was found and its bypass requests"), |
| 441 | a("update_secret_alert", Op::Security(SecurityOp::UpdateSecretAlert), "Dismiss a secret alert with a reason, or reopen it"), |
| 442 | a("secret_locations", Op::Security(SecurityOp::ListSecretLocations), "Every file, line and commit a secret is in"), |
| 443 | a("bypass", Op::Security(SecurityOp::BypassPushProtection), "Push past push protection with a reason, or ask to"), |
| 444 | a("check_validity", Op::Security(SecurityOp::CheckSecretValidity), "Ask a secret's issuer whether it still works"), |
| 445 | a("bypass_requests", Op::Security(SecurityOp::ListBypassRequests), "A workspace's push protection bypass requests"), |
| 446 | a("review_bypass", Op::Security(SecurityOp::ReviewBypassRequest), "Approve, deny or cancel a bypass request"), |
| 447 | a("patterns", Op::Security(SecurityOp::ListCustomPatterns), "Custom secret patterns of a repository or workspace"), |
| 448 | a("create_pattern", Op::Security(SecurityOp::CreateCustomPattern), "Create a custom secret pattern, as a draft or published"), |
| 449 | a("update_pattern", Op::Security(SecurityOp::UpdateCustomPattern), "Change, publish or unpublish a custom pattern"), |
| 450 | a("delete_pattern", Op::Security(SecurityOp::DeleteCustomPattern), "Delete a custom pattern"), |
| 451 | a("dry_run_pattern", Op::Security(SecurityOp::DryRunCustomPattern), "Run a pattern over the default branch without saving it"), |
| 452 | a("code_alerts", Op::Security(SecurityOp::ListCodeAlerts), "Code scanning alerts; by state, severity, tool, rule_id"), |
| 453 | a("code_alert", Op::Security(SecurityOp::GetCodeAlert), "One code scanning alert by number"), |
| 454 | a("update_code_alert", Op::Security(SecurityOp::UpdateCodeAlert), "Dismiss a code scanning alert with a reason, or reopen it"), |
| 455 | a("analyses", Op::Security(SecurityOp::ListAnalyses), "Code scanning analyses, newest first"), |
| 456 | a("upload_sarif", Op::Security(SecurityOp::UploadSarif), "Upload a SARIF file, gzipped and base64-encoded"), |
| 457 | a("sarif_upload", Op::Security(SecurityOp::GetSarifUpload), "Whether a SARIF upload was read, and its analyses"), |
| 458 | a("vulnerability_alerts", Op::Security(SecurityOp::ListVulnerabilityAlerts), "Vulnerable dependencies; by state, severity, ecosystem, package"), |
| 459 | a("vulnerability_alert", Op::Security(SecurityOp::GetVulnerabilityAlert), "One vulnerability alert"), |
| 460 | a("update_vulnerability_alert", Op::Security(SecurityOp::UpdateVulnerabilityAlert), "Dismiss a vulnerability alert with a reason, or reopen it"), |
| 461 | a("fix", Op::Security(SecurityOp::FixAlert), "Put g1t on an issue to fix an alert"), |
| 462 | a("dependency_graph", Op::Security(SecurityOp::GetDependencyGraph), "Every package the lockfiles resolve, direct or transitive"), |
| 463 | a("sbom", Op::Security(SecurityOp::GetSbom), "The dependency graph as an SPDX 2.3 document"), |
| 464 | a("compare_dependencies", Op::Security(SecurityOp::CompareDependencies), "What changes in dependencies between base...head"), |
| 465 | a("settings", Op::Security(SecurityOp::GetSettings), "A repository's security settings"), |
| 466 | a("update_settings", Op::Security(SecurityOp::UpdateSettings), "Change when checks fail and dependency review's policy"), |
| 467 | a("workspace_settings", Op::Security(SecurityOp::GetWorkspaceSettings), "A workspace's delegated bypass and validity checks"), |
| 468 | a("update_workspace_settings", Op::Security(SecurityOp::UpdateWorkspaceSettings), "Turn delegated bypass or validity checks on or off"), |
| 469 | a("overview", Op::Security(SecurityOp::GetOverview), "A workspace's alerts, trends and coverage"), |
| 470 | ], |
| 471 | }, |
| 472 | Tool { |
| 473 | name: "notifications", |
| 474 | title: "Notifications", |
| 475 | description: "Your inbox: what needs you, and what you follow. One thread per issue, pull request, workflow or deployment, with why you were told (`reason`): an agent waiting on you, a review asked of you, an assignment, a mention, your work's checks, or what you subscribe to and watch. Mark threads read or done once handled, and choose what you hear of with subscribe, unsubscribe and watch. Your own: a personal token.", |
| 476 | default_action: Some("list"), |
| 477 | actions: &[ |
| 478 | a("list", Op::ListNotifications, "Unread threads, latest first; all, a view, a reason, a repository"), |
| 479 | a("get", Op::GetNotificationThread, "One thread with its recent activity and your subscription"), |
| 480 | a("mark_read", Op::MarkThreadRead, "Mark a thread read, or unread"), |
| 481 | a("mark_all_read", Op::MarkNotificationsRead, "Mark everything read up to a time, or one repository's"), |
| 482 | a("done", Op::MarkThreadDone, "Mark a thread done; new activity brings it back"), |
| 483 | a("save", Op::SaveThread, "Save a thread, or unsave it"), |
| 484 | a("snooze", Op::SnoozeThread, "Snooze a thread until a time, or bring it back"), |
| 485 | a("subscription", Op::GetThreadSubscription, "Your subscription to an issue or pull request"), |
| 486 | a("subscribe", Op::SetThreadSubscription, "Subscribe to an issue or pull request, or ignore it"), |
| 487 | a("unsubscribe", Op::DeleteThreadSubscription, "Unsubscribe until you comment or are mentioned"), |
| 488 | a("watching", Op::GetRepoSubscription, "How you watch a repository"), |
| 489 | a("watch", Op::SetRepoSubscription, "Watch a repository: participating, all, ignore or custom"), |
| 490 | a("unwatch", Op::DeleteRepoSubscription, "Stop watching a repository"), |
| 491 | a("watched", Op::ListWatchedRepos, "Repositories you watch other than the default way"), |
| 492 | ], |
| 493 | }, |
| 494 | Tool { |
| 495 | name: "account", |
| 496 | title: "Your account", |
| 497 | description: "Who this token acts as and its workspaces (`whoami`), your email addresses, your invites, and invitations to workspaces and repositories waiting for you.", |
| 498 | default_action: Some("whoami"), |
| 499 | actions: &[ |
| 500 | a("whoami", Op::Whoami, "Who the token acts as, and its workspaces"), |
| 501 | a("list_emails", Op::ListEmails, "Your addresses"), |
| 502 | a("add_email", Op::AddEmail, "Add an address"), |
| 503 | a("confirm_email", Op::ConfirmEmail, "Confirm an address with the code from its email"), |
| 504 | a("remove_email", Op::RemoveEmail, "Remove an address"), |
| 505 | a("update_email_settings", Op::UpdateEmailSettings, "Primary, backup and privacy"), |
| 506 | a("list_invites", Op::ListInvites, "Your invites to g1t"), |
| 507 | a("create_invite", Op::CreateInvite, "Make an invite"), |
| 508 | a("revoke_invite", Op::RevokeInvite, "Revoke one"), |
| 509 | a("list_workspace_invitations", Op::ListInvitations, "Invitations to workspaces for you"), |
| 510 | a("accept_workspace_invitation", Op::AcceptInvitation, "Accept one and join"), |
| 511 | a("decline_workspace_invitation", Op::DeclineInvitation, "Decline one"), |
| 512 | a("list_repository_invitations", Op::ListMyRepoInvitations, "Invitations to repositories for you"), |
| 513 | a("accept_repository_invitation", Op::AcceptRepoInvitation, "Accept one"), |
| 514 | a("decline_repository_invitation", Op::DeclineRepoInvitation, "Decline one"), |
| 515 | ], |
| 516 | }, |
| 517 | ]; |
| 518 | |
| 519 | /// Operations that cannot be undone, or reach beyond g1t's own records: |
| 520 | /// clients ask before running a tool that has any of them. |
| 521 | fn destructive(op: Op) -> bool { |
| 522 | matches!( |
| 523 | op, |
| 524 | Op::Security(SecurityOp::DeleteCustomPattern | SecurityOp::BypassPushProtection) |
| 525 | | Op::Rules(RulesOp::DeleteRepoRuleset | RulesOp::DeleteWorkspaceRuleset) |
| 526 | | Op::DeleteWorkspace |
| 527 | | Op::UpdateWorkspace |
| 528 | | Op::Tokens(TokenOp::RevokeMemberToken | TokenOp::SetTokenPolicy) |
| 529 | | Op::RemoveMember |
| 530 | | Op::TransferOwnership |
| 531 | | Op::LeaveWorkspace |
| 532 | | Op::DeleteRepo |
| 533 | | Op::PurgeRepo |
| 534 | | Op::TransferRepo |
| 535 | | Op::SetRepoVisibility |
| 536 | | Op::RemoveEmail |
| 537 | | Op::RemoveCollaborator |
| 538 | | Op::DisconnectIntegration |
| 539 | | Op::UpdateIntegration |
| 540 | | Op::DeleteWebhook |
| 541 | | Op::DeleteActionsSecret |
| 542 | | Op::DeleteActionsVariable |
| 543 | | Op::SetActionsSecret |
| 544 | | Op::SetActionsVariable |
| 545 | | Op::SetModelRoutes |
| 546 | | Op::SetBasePermission |
| 547 | | Op::DeleteTeam |
| 548 | | Op::RemoveTeamRepo |
| 549 | | Op::MergePullRequest |
| 550 | | Op::RemoveRunner |
| 551 | | Op::DeleteRunnerGroup |
| 552 | | Op::UpdateRunnerSettings |
| 553 | ) |
| 554 | } |
| 555 | |
| 556 | /// Whether an operation only reads. |
| 557 | pub fn reads_only(op: Op) -> bool { |
| 558 | NO_SCOPE.contains(&op.name()) |
| 559 | || scope_for(op.name()).is_some_and(|scope| scope.level() == Level::Read) |
| 560 | } |
| 561 | |
| 562 | /// What decides which actions a caller sees. |
| 563 | pub enum Gate<'a> { |
| 564 | /// No limit beyond the person's own role. |
| 565 | Everything, |
| 566 | /// A g1t agent's token: the operations its run lists. |
| 567 | Agent(&'a AgentScope), |
| 568 | /// An access token with scopes. |
| 569 | Token(&'a TokenAccess), |
| 570 | } |
| 571 | |
| 572 | impl Gate<'_> { |
| 573 | pub fn allows(&self, op: Op) -> bool { |
| 574 | match self { |
| 575 | Gate::Everything => true, |
| 576 | Gate::Agent(scope) => op.allowed_by(scope) && !NEVER.contains(&op.name()), |
| 577 | Gate::Token(access) => { |
| 578 | if NO_SCOPE.contains(&op.name()) { |
| 579 | return true; |
| 580 | } |
| 581 | match scope_for(op.name()) { |
| 582 | Some(scope) => access.allows(scope), |
| 583 | None => access.scopes.is_none(), |
| 584 | } |
| 585 | } |
| 586 | } |
| 587 | } |
| 588 | } |
| 589 | |
| 590 | impl Tool { |
| 591 | pub fn by_name(name: &str) -> Option<&'static Tool> { |
| 592 | TOOLS.iter().find(|tool| tool.name == name) |
| 593 | } |
| 594 | |
| 595 | pub fn action(&self, name: &str) -> Option<&'static Action> { |
| 596 | // The tools are 'static; find through TOOLS to keep the lifetime. |
| 597 | TOOLS |
| 598 | .iter() |
| 599 | .find(|tool| tool.name == self.name) |
| 600 | .and_then(|tool| tool.actions.iter().find(|action| action.name == name)) |
| 601 | } |
| 602 | |
| 603 | pub fn visible(&self, gate: &Gate) -> Vec<&'static Action> { |
| 604 | TOOLS |
| 605 | .iter() |
| 606 | .find(|tool| tool.name == self.name) |
| 607 | .map(|tool| tool.actions.iter().filter(|action| gate.allows(action.op)).collect()) |
| 608 | .unwrap_or_default() |
| 609 | } |
| 610 | |
| 611 | /// The flat input schema of the actions given. |
| 612 | pub fn input_schema(&self, actions: &[&Action]) -> Value { |
| 613 | let mut properties = Map::new(); |
| 614 | let lines: Vec<String> = actions |
| 615 | .iter() |
| 616 | .map(|action| { |
| 617 | let required: Vec<String> = action.op.required(); |
| 618 | if required.is_empty() { |
| 619 | format!("{}: {}.", action.name, action.summary) |
| 620 | } else { |
| 621 | format!("{} ({}): {}.", action.name, required.join(", "), action.summary) |
| 622 | } |
| 623 | }) |
| 624 | .collect(); |
| 625 | let mut action_schema = json!({ |
| 626 | "type": "string", |
| 627 | "enum": actions.iter().map(|action| action.name).collect::<Vec<_>>(), |
| 628 | "description": lines.join("\n"), |
| 629 | }); |
| 630 | if let Some(default) = self.default_action.filter(|name| actions.iter().any(|action| action.name == *name)) { |
| 631 | action_schema["default"] = json!(default); |
| 632 | } |
| 633 | properties.insert("action".to_owned(), action_schema); |
| 634 | for action in actions { |
| 635 | for (name, schema) in action.op.properties() { |
| 636 | merge_property(&mut properties, name, schema); |
| 637 | } |
| 638 | } |
| 639 | let mut required = vec![]; |
| 640 | if self.default_action.is_none() { |
| 641 | required.push("action"); |
| 642 | } |
| 643 | let mut schema = json!({ "type": "object", "properties": properties }); |
| 644 | if !required.is_empty() { |
| 645 | schema["required"] = json!(required); |
| 646 | } |
| 647 | schema |
| 648 | } |
| 649 | |
| 650 | /// The input schema keyed by action: one `oneOf` branch per action, |
| 651 | /// each with its own fields and the ones it needs. |
| 652 | pub fn discriminated(&self, actions: &[&Action]) -> Value { |
| 653 | let branches: Vec<Value> = actions |
| 654 | .iter() |
| 655 | .map(|action| { |
| 656 | let mut properties = Map::new(); |
| 657 | properties.insert("action".to_owned(), json!({ "const": action.name })); |
| 658 | properties.extend(action.op.properties()); |
| 659 | let mut required = vec![Value::String("action".to_owned())]; |
| 660 | // The default action may leave `action` out. |
| 661 | if self.default_action == Some(action.name) { |
| 662 | required.clear(); |
| 663 | } |
| 664 | required.extend(action.op.required().into_iter().map(Value::String)); |
| 665 | json!({ |
| 666 | "title": action.name, |
| 667 | "description": action.summary, |
| 668 | "type": "object", |
| 669 | "properties": properties, |
| 670 | "required": required, |
| 671 | }) |
| 672 | }) |
| 673 | .collect(); |
| 674 | json!({ "type": "object", "oneOf": branches }) |
| 675 | } |
| 676 | |
| 677 | /// MCP's hints about the actions given: whether the tool only reads, |
| 678 | /// whether it can destroy something, and whether calling it twice is |
| 679 | /// the same as once. |
| 680 | pub fn annotations(&self, actions: &[&Action]) -> Value { |
| 681 | let read_only = actions.iter().all(|action| reads_only(action.op)); |
| 682 | json!({ |
| 683 | "title": self.title, |
| 684 | "readOnlyHint": read_only, |
| 685 | "destructiveHint": !read_only && actions.iter().any(|action| destructive(action.op)), |
| 686 | "idempotentHint": read_only, |
| 687 | "openWorldHint": false, |
| 688 | }) |
| 689 | } |
| 690 | |
| 691 | /// The tool as `tools/list` gives it, for a caller behind `gate`, or |
| 692 | /// `None` when it may use none of its actions. |
| 693 | pub fn listed(&self, gate: &Gate) -> Option<Value> { |
| 694 | let actions = self.visible(gate); |
| 695 | if actions.is_empty() { |
| 696 | return None; |
| 697 | } |
| 698 | Some(json!({ |
| 699 | "name": self.name, |
| 700 | "title": self.title, |
| 701 | "description": self.description, |
| 702 | "inputSchema": self.input_schema(&actions), |
| 703 | "annotations": self.annotations(&actions), |
| 704 | })) |
| 705 | } |
| 706 | } |
| 707 | |
| 708 | /// Adds a property to a tool's flat schema. The first action to use a name |
| 709 | /// describes it; a later one with other allowed values adds them. |
| 710 | fn merge_property(properties: &mut Map<String, Value>, name: String, schema: Value) { |
| 711 | match properties.get_mut(&name) { |
| 712 | None => { |
| 713 | properties.insert(name, schema); |
| 714 | } |
| 715 | Some(existing) => { |
| 716 | if let (Some(Value::Array(had)), Some(Value::Array(more))) = |
| 717 | (existing.get("enum").cloned(), schema.get("enum")) |
| 718 | { |
| 719 | let mut merged = had; |
| 720 | for value in more { |
| 721 | if !merged.contains(value) { |
| 722 | merged.push(value.clone()); |
| 723 | } |
| 724 | } |
| 725 | existing["enum"] = Value::Array(merged); |
| 726 | } |
| 727 | // Different kinds of value under one name: say less, accept both. |
| 728 | if existing.get("type") != schema.get("type") |
| 729 | && let Some(fields) = existing.as_object_mut() |
| 730 | { |
| 731 | fields.remove("type"); |
| 732 | fields.remove("items"); |
| 733 | } |
| 734 | } |
| 735 | } |
| 736 | } |
| 737 | |
| 738 | /// What a call to a tool runs: the operation its action names, or why not. |
| 739 | pub fn resolve(tool: &Tool, arguments: &Value) -> Result<Op, String> { |
| 740 | let names = || { |
| 741 | tool.actions |
| 742 | .iter() |
| 743 | .map(|action| action.name) |
| 744 | .collect::<Vec<_>>() |
| 745 | .join(", ") |
| 746 | }; |
| 747 | let Some(name) = arguments["action"].as_str().or(tool.default_action) else { |
| 748 | return Err(format!("Give an action: one of {}.", names())); |
| 749 | }; |
| 750 | let Some(action) = tool.action(name) else { |
| 751 | return Err(format!("{} has no action {name}. Its actions: {}.", tool.name, names())); |
| 752 | }; |
| 753 | let missing: Vec<String> = action |
| 754 | .op |
| 755 | .required() |
| 756 | .into_iter() |
| 757 | .filter(|field| arguments.get(field).is_none_or(Value::is_null)) |
| 758 | .collect(); |
| 759 | if !missing.is_empty() { |
| 760 | return Err(format!("{}.{name} needs {}.", tool.name, missing.join(", "))); |
| 761 | } |
| 762 | Ok(action.op) |
| 763 | } |
| 764 | |
| 765 | #[cfg(test)] |
| 766 | mod tests { |
| 767 | use super::*; |
| 768 | use g1t_contracts::scopes::{Preset, Scope}; |
| 769 | |
| 770 | fn listed(gate: &Gate) -> Vec<Value> { |
| 771 | TOOLS.iter().filter_map(|tool| tool.listed(gate)).collect() |
| 772 | } |
| 773 | |
| 774 | fn token(scopes: Option<Vec<Scope>>) -> TokenAccess { |
| 775 | TokenAccess { |
| 776 | token_id: "tok_1".to_owned(), |
| 777 | scopes: scopes.map(|scopes| scopes.iter().map(|scope| scope.as_str().to_owned()).collect()), |
| 778 | legacy: false, |
| 779 | name: None, |
| 780 | ..TokenAccess::default() |
| 781 | } |
| 782 | } |
| 783 | |
| 784 | #[test] |
| 785 | fn every_operation_is_exactly_one_action_of_one_tool() { |
| 786 | for op in Op::ALL { |
| 787 | let count = TOOLS |
| 788 | .iter() |
| 789 | .flat_map(|tool| tool.actions.iter()) |
| 790 | .filter(|action| action.op == op) |
| 791 | .count(); |
| 792 | assert_eq!(count, 1, "{} is {count} actions", op.name()); |
| 793 | } |
| 794 | for tool in TOOLS { |
| 795 | let mut names = std::collections::HashSet::new(); |
| 796 | for action in tool.actions { |
| 797 | assert!(names.insert(action.name), "{}.{} twice", tool.name, action.name); |
| 798 | } |
| 799 | if let Some(default) = tool.default_action { |
| 800 | assert!(tool.action(default).is_some(), "{}", tool.name); |
| 801 | } |
| 802 | } |
| 803 | assert!(TOOLS.len() <= 18, "{} tools", TOOLS.len()); |
| 804 | } |
| 805 | |
| 806 | #[test] |
| 807 | fn every_operation_needs_exactly_one_scope_or_none() { |
| 808 | use g1t_contracts::scopes::OPERATIONS; |
| 809 | for op in Op::ALL { |
| 810 | let mapped = OPERATIONS.iter().filter(|(name, _)| *name == op.name()).count(); |
| 811 | let free = NO_SCOPE.contains(&op.name()); |
| 812 | assert_eq!(mapped + usize::from(free), 1, "{}", op.name()); |
| 813 | } |
| 814 | for (name, _) in OPERATIONS { |
| 815 | assert!(Op::by_name(name).is_some(), "{name} is not an operation"); |
| 816 | } |
| 817 | } |
| 818 | |
| 819 | #[test] |
| 820 | fn each_tool_schema_is_valid_with_one_branch_per_action() { |
| 821 | for tool in TOOLS { |
| 822 | let actions: Vec<&Action> = tool.actions.iter().collect(); |
| 823 | let flat = tool.input_schema(&actions); |
| 824 | assert_eq!(flat["type"], "object"); |
| 825 | assert!(flat.get("oneOf").is_none(), "no oneOf at the top level"); |
| 826 | let listed: Vec<&str> = flat["properties"]["action"]["enum"] |
| 827 | .as_array() |
| 828 | .unwrap() |
| 829 | .iter() |
| 830 | .map(|name| name.as_str().unwrap()) |
| 831 | .collect(); |
| 832 | assert_eq!(listed, tool.actions.iter().map(|action| action.name).collect::<Vec<_>>()); |
| 833 | for action in tool.actions { |
| 834 | for field in action.op.required() { |
| 835 | assert!(flat["properties"].get(&field).is_some(), "{}.{}: {field}", tool.name, action.name); |
| 836 | } |
| 837 | } |
| 838 | let keyed = tool.discriminated(&actions); |
| 839 | let branches = keyed["oneOf"].as_array().unwrap(); |
| 840 | assert_eq!(branches.len(), tool.actions.len()); |
| 841 | for (branch, action) in branches.iter().zip(tool.actions) { |
| 842 | assert_eq!(branch["properties"]["action"]["const"], action.name); |
| 843 | for field in branch["required"].as_array().unwrap() { |
| 844 | assert!(branch["properties"].get(field.as_str().unwrap()).is_some(), "{}.{}: {field}", tool.name, action.name); |
| 845 | } |
| 846 | } |
| 847 | // A well-formed JSON Schema object throughout. |
| 848 | let text = serde_json::to_string(&flat).unwrap(); |
| 849 | assert!(serde_json::from_str::<Value>(&text).is_ok()); |
| 850 | } |
| 851 | } |
| 852 | |
| 853 | #[test] |
| 854 | fn a_read_only_token_sees_read_actions_only() { |
| 855 | let access = token(Preset::ReadOnly.scopes()); |
| 856 | let gate = Gate::Token(&access); |
| 857 | for tool in TOOLS { |
| 858 | for action in tool.visible(&gate) { |
| 859 | assert!(reads_only(action.op), "{}.{}", tool.name, action.name); |
| 860 | } |
| 861 | } |
| 862 | let tools = listed(&gate); |
| 863 | for tool in &tools { |
| 864 | assert_eq!(tool["annotations"]["readOnlyHint"], true, "{}", tool["name"]); |
| 865 | assert_eq!(tool["annotations"]["destructiveHint"], false); |
| 866 | } |
| 867 | let issue = tools.iter().find(|tool| tool["name"] == "issue").unwrap(); |
| 868 | assert_eq!(issue["inputSchema"]["properties"]["action"]["enum"], json!(["list", "get", "labels"])); |
| 869 | // Nothing of the agent tool is a read. |
| 870 | assert!(!tools.iter().any(|tool| tool["name"] == "agent")); |
| 871 | } |
| 872 | |
| 873 | #[test] |
| 874 | fn a_narrow_token_sees_only_its_tools() { |
| 875 | let access = token(Some(vec![Scope::IssuesWrite])); |
| 876 | let names: Vec<Value> = listed(&Gate::Token(&access)).into_iter().map(|tool| tool["name"].clone()).collect(); |
| 877 | // Labels and milestones are the repository's, managed with issues:write. |
| 878 | assert_eq!(names, vec![json!("repository"), json!("issue"), json!("plan"), json!("account")]); |
| 879 | // Notifications are a resource of their own: reading them lists |
| 880 | // only what reads. |
| 881 | let reader = token(Some(vec![Scope::NotificationsRead])); |
| 882 | let tools = listed(&Gate::Token(&reader)); |
| 883 | let notifications = tools.iter().find(|tool| tool["name"] == "notifications").unwrap(); |
| 884 | assert_eq!( |
| 885 | notifications["inputSchema"]["properties"]["action"]["enum"], |
| 886 | json!(["list", "get", "subscription", "watching", "watched"]) |
| 887 | ); |
| 888 | assert_eq!(notifications["annotations"]["readOnlyHint"], true); |
| 889 | let full = token(None); |
| 890 | assert_eq!(listed(&Gate::Token(&full)).len(), TOOLS.len()); |
| 891 | assert_eq!(listed(&Gate::Everything).len(), TOOLS.len()); |
| 892 | } |
| 893 | |
| 894 | #[test] |
| 895 | fn a_tool_that_can_destroy_says_so() { |
| 896 | let tools = listed(&Gate::Everything); |
| 897 | let repository = tools.iter().find(|tool| tool["name"] == "repository").unwrap(); |
| 898 | assert_eq!(repository["annotations"]["destructiveHint"], true); |
| 899 | assert_eq!(repository["annotations"]["readOnlyHint"], false); |
| 900 | let memory = tools.iter().find(|tool| tool["name"] == "memory").unwrap(); |
| 901 | assert_eq!(memory["annotations"]["destructiveHint"], false); |
| 902 | } |
| 903 | |
| 904 | #[test] |
| 905 | fn calls_resolve_to_their_operation_or_say_what_is_missing() { |
| 906 | let issue = Tool::by_name("issue").unwrap(); |
| 907 | assert_eq!(resolve(issue, &json!({ "action": "get", "repo": "a/b", "number": 1 })), Ok(Op::GetIssue)); |
| 908 | assert_eq!(resolve(issue, &json!({ "action": "get", "repo": "a/b" })), Err("issue.get needs number.".to_owned())); |
| 909 | assert!(resolve(issue, &json!({})).unwrap_err().starts_with("Give an action")); |
| 910 | assert!(resolve(issue, &json!({ "action": "explode" })).unwrap_err().contains("no action explode")); |
| 911 | let search = Tool::by_name("search").unwrap(); |
| 912 | assert_eq!(resolve(search, &json!({ "query": "x" })), Ok(Op::Search)); |
| 913 | let account = Tool::by_name("account").unwrap(); |
| 914 | assert_eq!(resolve(account, &json!({})), Ok(Op::Whoami)); |
| 915 | } |
| 916 | |
| 917 | #[test] |
| 918 | fn teams_are_one_tool_and_a_workspace_reader_sees_only_its_reads() { |
| 919 | let team = Tool::by_name("team").unwrap(); |
| 920 | let names: Vec<&str> = team.actions.iter().map(|action| action.name).collect(); |
| 921 | assert_eq!( |
| 922 | names, |
| 923 | [ |
| 924 | "list", |
| 925 | "get", |
| 926 | "create", |
| 927 | "update", |
| 928 | "delete", |
| 929 | "list_members", |
| 930 | "set_member", |
| 931 | "remove_member", |
| 932 | "list_child_teams", |
| 933 | "list_repos", |
| 934 | "set_repo", |
| 935 | "remove_repo", |
| 936 | "set_review_assignment", |
| 937 | "list_user_teams", |
| 938 | ] |
| 939 | ); |
| 940 | let reader = token(Some(vec![Scope::WorkspaceRead])); |
| 941 | let tools = listed(&Gate::Token(&reader)); |
| 942 | let listed_team = tools.iter().find(|tool| tool["name"] == "team").unwrap(); |
| 943 | assert_eq!( |
| 944 | listed_team["inputSchema"]["properties"]["action"]["enum"], |
| 945 | json!(["list", "get", "list_members", "list_child_teams", "list_repos", "list_user_teams"]) |
| 946 | ); |
| 947 | assert_eq!(listed_team["annotations"]["readOnlyHint"], true); |
| 948 | // A team's role on a repository is who has access. |
| 949 | let admin = token(Some(vec![Scope::WorkspaceAdmin])); |
| 950 | let tools = listed(&Gate::Token(&admin)); |
| 951 | let listed_team = tools.iter().find(|tool| tool["name"] == "team").unwrap(); |
| 952 | let actions = listed_team["inputSchema"]["properties"]["action"]["enum"].as_array().unwrap(); |
| 953 | assert!(actions.contains(&json!("set_review_assignment")) && !actions.contains(&json!("set_repo"))); |
| 954 | let access = token(Some(vec![Scope::AccessAdmin])); |
| 955 | let tools = listed(&Gate::Token(&access)); |
| 956 | let listed_team = tools.iter().find(|tool| tool["name"] == "team").unwrap(); |
| 957 | assert_eq!(listed_team["inputSchema"]["properties"]["action"]["enum"], json!(["set_repo", "remove_repo"])); |
| 958 | // Both kinds of role a schema names are offered. |
| 959 | let roles = &listed(&Gate::Everything).into_iter().find(|tool| tool["name"] == "team").unwrap()["inputSchema"] |
| 960 | ["properties"]["role"]["enum"]; |
| 961 | for role in ["member", "maintainer", "read", "admin"] { |
| 962 | assert!(roles.as_array().unwrap().contains(&json!(role)), "{role}"); |
| 963 | } |
| 964 | assert_eq!( |
| 965 | resolve(team, &json!({ "action": "set_repo", "workspace": "acme", "team": "backend", "repo": "rocket" })), |
| 966 | Err("team.set_repo needs role.".to_owned()) |
| 967 | ); |
| 968 | } |
| 969 | |
| 970 | #[test] |
| 971 | fn reviewers_and_code_owners_are_actions_of_their_tools() { |
| 972 | let pull = Tool::by_name("pull_request").unwrap(); |
| 973 | assert_eq!( |
| 974 | resolve(pull, &json!({ "action": "request_reviewers", "repo": "a/b", "number": 1, "team_reviewers": ["backend"] })), |
| 975 | Ok(Op::RequestReviewers) |
| 976 | ); |
| 977 | assert_eq!(pull.action("remove_requested_reviewers").map(|action| action.op), Some(Op::RemoveRequestedReviewers)); |
| 978 | let repository = Tool::by_name("repository").unwrap(); |
| 979 | assert_eq!(resolve(repository, &json!({ "action": "codeowners", "repo": "a/b" })), Ok(Op::GetCodeownersErrors)); |
| 980 | assert!(reads_only(Op::GetCodeownersErrors)); |
| 981 | assert!(!reads_only(Op::RequestReviewers)); |
| 982 | } |
| 983 | |
| 984 | /// How much smaller `tools/list` is than one tool per operation. Run |
| 985 | /// with `--nocapture` to see the numbers. |
| 986 | #[test] |
| 987 | fn the_tool_list_is_much_smaller_than_one_tool_per_operation() { |
| 988 | let before: Vec<Value> = Op::ALL |
| 989 | .into_iter() |
| 990 | .map(|op| json!({ "name": op.name(), "description": op.description(), "inputSchema": op.input() })) |
| 991 | .collect(); |
| 992 | let after = listed(&Gate::Everything); |
| 993 | let before_bytes = serde_json::to_string(&json!({ "tools": before })).unwrap().len(); |
| 994 | let after_bytes = serde_json::to_string(&json!({ "tools": after })).unwrap().len(); |
| 995 | let agent = token(Preset::Agent.scopes()); |
| 996 | let agent_bytes = serde_json::to_string(&json!({ "tools": listed(&Gate::Token(&agent)) })).unwrap().len(); |
| 997 | let read = token(Preset::ReadOnly.scopes()); |
| 998 | let read_bytes = serde_json::to_string(&json!({ "tools": listed(&Gate::Token(&read)) })).unwrap().len(); |
| 999 | println!( |
| 1000 | "tools/list: before {} tools, {before_bytes} bytes (~{} tokens); after {} tools, {after_bytes} bytes (~{} tokens); agent preset {agent_bytes} bytes (~{} tokens); read only {read_bytes} bytes (~{} tokens)", |
| 1001 | before.len(), |
| 1002 | before_bytes / 4, |
| 1003 | after.len(), |
| 1004 | after_bytes / 4, |
| 1005 | agent_bytes / 4, |
| 1006 | read_bytes / 4, |
| 1007 | ); |
| 1008 | assert!(after_bytes * 2 < before_bytes, "{after_bytes} vs {before_bytes}"); |
| 1009 | } |
| 1010 | } |