MCP tools

The tools knotless-mcp offers over stdio, and a public knotless-serve offers at /mcp. They name a repository as handle/name. Reads answer from a local cache mirror, writes go through the same code as the CLI, and errors come back as tool errors for the agent to read. One a PDS refused for want of scope, as a login from before knotless asked for more is, adds that the user signs in again: reconnecting knotless in their assistant, or running knotless login for a knotless on their machine. One the login asked for, but its PDS did not grant, says so instead: for a write in a space, that the PDS granted the collections the space type's lexicon listed when the user signed in, and that signing in again grants this one once knotless's lexicon lists it.

On a server, each account's login with its PDS can end while its assistant's token still works: a PDS ends a session after a lifetime of its own. Once the PDS turns down refreshing it, the server forgets the session, answers the next call 401 and the next token refresh invalid_grant, so the assistant has its user sign in again. A refresh that fails any other way is logged, and the call goes on. Agents says how to connect a client. Pulls, issues, diffs and files are resources to read by URI too.

Over stdio, knotless-mcp asks its appview about versions once a day, as the CLI does (Command reference). With a newer release out, the first tool's answer ends with a text saying so. Older than the appview asks for, every tool fails, saying why and to run knotless upgrade, unless KNOTLESS_IGNORE_MINIMUM is set. /mcp on a server runs that server's own build and does neither.

The tools are the commands

Every command knotless <group> <action> has one tool, <group>_<action>, with - as _: knotless repo star is repo_star, knotless pull update-branch is pull_update_branch. A tool takes what its command takes. A parameter is the flag's name with - as _ (--keep-branch is keep_branch, --undo is undo), and the positionals are named as the command's usage names them (repo, uri, name). Where a command has an undo, the tool takes undo: true. A verb that works on a pull or an issue exists as both tools (pull_close, issue_close). Every tool is a command, and nothing is on the MCP alone.

The commands with no tool act on the machine they run on: login, logout, upgrade, repo mirror, workflow pin and release download. The command reference has each command's flags and what it prints; this page has what a tool takes beyond that and what it answers. The tools are listed by group, as the commands are. Actions lines them up against the commands, the methods and the pages.

knotless-mcp --read-only offers only the tools that read, as status, repo_list, repo_refs, repo_tree, repo_read, repo_blame, repo_search, repo_log, repo_diff, pull_diff, pull_show, issue_show, pull_list, issue_list, run_list, workflow_list and release_read (READS in crates/knotless-mcp/src/lib.rs lists them all), and runs no other, whatever login it has: for an agent that may read but must change nothing, as the review agent is.

status

Tool	Command	What it does
status	knotless status	a knotless-serve's health, from /_status, for server (the appview by default), with repo (handle/name) its mirror too

account

Tool	Command	What it does
account_profile	knotless account profile	how you show on knotless, over your Bluesky profile, and, with bot, whether the account is a bot, which the feed leaves out
account_email, account_email_add, account_email_remove	knotless account email [add | remove]	account_email says how many addresses you claim, {claimed}; account_email_add claims an address as yours and account_email_remove takes it back, each answering {changed, claimed}, how many you claim now
account_follow	knotless account follow	follows a handle on knotless, or with undo unfollows it, answering {following, uri}
account_follows, account_followers	knotless account follows, knotless account followers	account_follows lists whom a handle follows, yours by default, as {follows: [{handle, uri, createdAt}]}; account_followers who follows it, from the appview, as {followers: [{did, handle}]}
account_search	knotless account search	the accounts owning public repositories whose handle holds text, as the appview's search finds them, at most limit (10 by default, at most 50), as {owners: [{owner: {did, handle}, repoCount}]}
account_delegate	knotless account delegate	hands your writes to a gateway (the appview's, by default) so collaborators can push, approved in the browser
account_delete_data	knotless account delete-data	without confirm, what knotless data your account holds, as getAccountData answers it; with confirm, your handle, deletes it all, answering {deleted, loggedOut}

repo

Tool	Command	What it does
repo_list, repo_refs, repo_tree, repo_log	knotless repo list, refs, tree, log	read a repository, an account's repositories, a directory (path, rev) or the history (rev, path, limit, 20 by default)
repo_read	knotless repo read	a file at rev, optionally only lines start to end (long files)
repo_search	knotless repo search	the lines holding a fixed string, in any case; see the parameters below
repo_blame	knotless repo blame	who last changed each line of path at rev (the default branch if not given), as git blame finds it in the cache mirror: runs of lines, each {sha, start, count, author: {name, email, date}, summary, previous}, start counted from 1, date in UTC, and previous, where the commit's parent had the file, that parent and the file's path there
repo_diff	knotless repo diff	what head changed since base; answers No differences: … when head changes nothing since base
repo_storage	knotless repo storage	what a repository takes up on its PDS: its packs, their objects and bytes, and the bytes in blobs
repo_compact	knotless repo compact	as the owner, fold a repository's older packs into one and drop old claims and deleted refs' leftover records, answering {before, removed, claims, refs}
repo_commit	knotless repo commit	change files on a branch, optionally against a base commit, and with batch, as the owner, through the gateway; see the parameters below
repo_create	knotless repo create	takes links ([{url, title?}], its website first) and a default_branch (main if not given) and names the runners given (none, for an empty list), or else the appview's default runner, and returns them as runners: a private one's are members, invited, with a warning (null otherwise) if one could not be. It answers the members who may push to a new repository
repo_edit	knotless repo edit	change a repository's description (empty drops it), its links ([{url, title?}], which replace those it had; empty drops them), its topics (names, which replace those it had; empty drops them), and the branch its HEAD names, one of its branches once it has any, answering {description, links, topics, defaultBranch}
repo_rename	knotless repo rename	rename; the old name redirects
repo_archive	knotless repo archive	makes one you own read only, or with undo writable again, answering {archivedAt} (null once unarchived)
repo_delete	knotless repo delete	delete a repository you own and everything in it, with what you wrote about it; confirm is its name again, or it refuses
repo_transfer, repo_accept	knotless repo transfer, knotless repo accept	offer a public repository to to, or with undo withdraw the offer; take one offered to you
repo_fork	knotless repo fork	copy a repository into your account, under name if given
repo_share	knotless repo share	let handle read a private repository, or with write push too, which first delegates your writes to the gateway when you have not, approved in the browser as account_delegate is, then answers who may read and write it and, as a second text, Delegated your writes to the gateway <did> first.; with undo takes access away
repo_members	knotless repo members	who may read and push
repo_star, repo_stars	knotless repo star, knotless repo stars	repo_star stars a public repository, or with undo takes the star back, answering {starred, uri}; repo_stars lists the repositories a handle starred, yours by default, as {stars: [{repo, uri, createdAt}]}

Parameters beyond a flag's name:

Tool	Parameter
repo_commit	changes	each {path} with one of content, base64, edits or delete: true; edits is a list of {old, new} made in turn in the file as the branch holds it, each old there exactly once, the file keeping its mode. A miss fails edit <n> of <path>: old is not in the file, or says how many times it is there; a path with no regular file fails <path>: no file there to edit. On a branch that moved, edits are made in the file as it is there (long files)
repo_search	path, context	only files under path, a directory, file or glob; with context, runs of lines around the matches instead of lines, each {path, start, end, matches, text}, matches the line numbers that match and text the run's lines
repo_read	start, end	only those lines of a text file, from 1, end by default its last, as {start, end, lines, text}, lines the file's count
repo_blame	start, end	only the runs for those lines, end by default start

branch and tag

Tool	Command	What it does
branch_create, branch_delete, branch_rename	knotless branch create, delete, rename	make, remove or rename a branch; a rename takes the open pulls on it along
branch_protect	knotless branch protect	holds collaborators to a branch's rules, or with undo drops them. Takes merges, queue, reviews (how many approvals, 0 to 10), code_owners, dismiss_stale and gates (handles or DIDs whose review of a pull's head it waits for, see gates); into such a branch pull_merge refuses a pull not reviewed as it asks, naming what is missing, unless the owner forces it (see required reviews)
branch_rules	knotless branch rules	lists the rules, a rule that asks for code owners with warnings when CODEOWNERS on its branch gives you, the owner, a path alone (your own pull changing it never has a code owner's approval, as an author's never counts, and merges only by force); shows queue
tag_create, tag_delete	knotless tag create, knotless tag delete	make or remove a tag, such as a release's version, at a commit, branch or tag

pull and issue

Tool	Command	What it does
pull_create, issue_create	knotless pull create, knotless issue create	open one, following the repository's template: they refuse one with no body when there is a template. pull_create takes base, head_repo, head_branch, title, body, images, draft and reviewers
pull_template, issue_template	knotless pull template, knotless issue template	what a repository asks a pull's or issue's title and body to follow: read before pull_create or issue_create
pull_list, issue_list	knotless pull list, knotless issue list	takes a query in GitHub's search words (collaboration.md), and says of each pull draft, true or false
pull_show, issue_show	knotless pull show, knotless issue show	a pull or issue and its comments; on a pull, what it brings in and whether it merges cleanly, and on an issue mentionedBy, the pulls whose title or body names it, oldest first, each {pull, closes}, closes true where it names it after a closing keyword
pull_diff	knotless pull diff	the diff a pull would apply, numbered as comment_add's lines take them
pull_edit, issue_edit	knotless pull edit, knotless issue edit	change your pull's or issue's title and text; pull_edit also whether your pull is a draft (draft, ready) and whom it asks to review it (reviewers, no_reviewers)
pull_close, pull_reopen, issue_close, issue_reopen	knotless pull close and the rest	change an item's state: its author, the owner or a collaborator; refuses an item that is not there, a merged pull and a state it is in already
pull_label, issue_label	knotless pull label, knotless issue label	put labels on a pull or issue as owner, collaborator or triager, or with undo take them off
pull_assign, issue_assign	knotless pull assign, knotless issue assign	assign a pull or issue to accounts, or with undo take them off; as in collaboration.md, the owner and collaborators assign. Answers assignees by DID
pull_ask_review	knotless pull ask-review	ask accounts to review a pull, or with undo stop asking: the owner and collaborators, and a pull's author in the pull. Answers assignees and reviewers, by DID
pull_dismiss_review	knotless pull dismiss-review	dismiss a reviewer's standing review of a pull, saying why: a comment naming it, so it counts for nothing, for or against, until they review again. As in collaboration.md: the owner and collaborators may, on their own pulls too. Answers the comment's uri
pull_react, issue_react, comment_react	knotless pull react, knotless issue react, knotless comment react	reacts to a pull, issue or comment (uri) on repo (in its space, for a private one) with a content among GitHub's eight, or with undo takes it back, answering {reacted, uri}
pull_retarget	knotless pull retarget	point a pull at other branches
pull_revert	knotless pull revert	undoes a merged pull (uri) in one commit on revert/<rkey> and opens a pull of it into the same branch, saying reason if given, answering {pull, branch, commit} (reverting a pull)
pull_update_branch	knotless pull update-branch	merges an open pull's (uri) base into its branch and pushes it, answering {branch, commit, added}, commit absent when the branch held its base already, and added the paths where both sides only added lines and the base's come first (updating a pull's branch)
pull_merge	knotless pull merge	merge a pull, queue it or check it; see below

Tool	Parameters	Answer
pull_create, issue_create, pull_edit, issue_edit, comment_add, comment_edit	images	pictures to show after the body, each {base64, alt}, a PNG, JPEG, WebP or GIF: uploaded, made smaller when over 1 MB, and attached (collaboration.md); with an edit, only beside a body
pull_create	draft, reviewers	open it as a draft, which neither merges nor queues until marked ready; ask these accounts, by handle or DID, to review it (drafts and requested reviewers)
pull_edit	draft, ready, reviewers, no_reviewers	for your pull: draft makes it a draft, ready marks it ready; ask more accounts to review it, or stop asking some
pull_list, issue_list	query	also is:draft, -is:draft, review-requested:<handle, did or @me>, assignee:<handle, did or @me> and no:assignee
pull_diff	repo, uri, paths	the pull's unified diff, or with paths only those files' parts of it (for a merged pull, what its merge brought in, from the commits its state records, so it answers once its branch is gone), each line of a hunk led by its line in the old file and in the new (blank on the side it is not on) and |, as comment_add's lines takes them: a + line is side: new at its new number, a - line side: old at its old number, an unchanged line side: new at its new number. File headers, @@ lines and \ No newline are not numbered. A diff longer than 60,000 bytes so numbered, asked for without paths, answers instead said and files, each file's path (a renamed file's new one), added, removed and lines, to ask for by paths a few at a time, since an MCP client cuts off an answer that long
pull_show, issue_show	repo, uri	item.draft, true or false for a pull, and item.reviewers, those it asks to review it, {did, handle, pending}, pending while the pull is open and they have not reviewed it, and false once it is merged or closed; for a pull, item.reviews: each reviewer's standing review, {by, handle, verdict, commit, uri, outdated, maintainer, uncounted}, outdated once the open pull has moved past commit, maintainer for the owner or a collaborator, and uncounted, when its branch asks for reviews, why an approval does not count; on each comment, its author's handle and facets, the accounts it mentions; on a comment on lines, line ({path, side, line, startLine}, side new and startLine the same as line where its record leaves them out) and review, which a review's own comment names too; on each comment of a thread on lines, and on no other, resolved; on a review its reviewer's later one stands in place of, superseded: true; and on an answer, reply; reactions, on it and on each comment, as {"<content>": count} or null, as the appview counts them, or for a private repository as its space has them; for a pull, also compare, which for a merged pull is what its merge brought in (base where the branch was before it, head the merge), whether or not its branch is still there; for a merged pull a merged revert undid, item.revertedBy, that revert, and on a revert, item.reverts, the pull it undoes; for an open pull in the queue or ejected from it, standing: {said, place, batch}

pull_merge

pull_merge takes wait (seconds, at most 300), force and keep_branch, as the CLI's pull merge takes --wait, --force and --keep-branch. Merged, it answers {sha, method, deleted, kept, closed}: the commit its branch is at, how (merge or squash), the head branch it deleted, or else why it kept it (asked to, in another repository such as a fork, the branch merged into or the default branch, or named by another open pull), and the issues it closed.

With queue: true, on a branch protected with queue, it puts the pull in the merge queue instead and answers {"queued": {base, position, of}} at once, with ejectedBefore, why, when it is queued again at the very head the queue last ejected; it then ignores wait, force and keep_branch. Its description tells an agent to queue a pull once it builds, with the target branch merged in; once ejected, to read why and the failed checks' logs, fix it and queue again, and to queue the same head again only when the failure is not the pull's; and to stop after a second ejection for the same reason. Into a branch protected with queue (branch_protect takes queue, and branch_rules shows it), pull_merge without force queues the pull instead, answering {"queued": {base, position, of}, "why": "<base> takes pulls only through the merge queue"}; see queue-only branches.

With auto: true, on a branch with no merge queue, it sets the pull to merge by itself once its checks pass, and answers {"autoMerge": "set", "commit": <head>}; with undo: true as well, it cancels that, answering {"autoMerge": "cancelled"}. pull_show then has autoMerge, where it stands in words. See merge when checks pass.

With check: true, it merges nothing and answers whether it would now, as knotless pull merge --check says: {state, reason, conflicts, checks, method, deletes, base, head, may: {merge, force, queue, base, head, rerun}, queueOnly, reviews, reviewsMissing, reviewsUncounted, codeOwnersWarnings}: reviews is passed, blocked, or none when the branch asks for none, and reviewsMissing, reviewsUncounted (the approvals that do not count, and why) and codeOwnersWarnings are [{text}]. may is what the caller's part in the repository lets it do, not whether that would work now: state and reason say that, and a blocked pull's merge is refused, the owner's too, unless the owner forces it. When the caller may not merge the pull, reason says so too. Over MCP, a refusal for reviews names the comment_add tool with verdict: "approve", and pull_merge with force, where the CLI names its commands.

standing.said reads as Queued, 3rd of 5, Queued, 1st of 2, running its checks, Queued, 1st of 2, running its checks again on main as it is now, Queued, 1st of 2, but its test failed. The runner ejects it, or runs it again if that run was on an older main, Queued, 2nd of 2, ready for the next batch, In a batch of 4 being checked, Landing, or Ejected: <reason>, with the failed checks.

comment

Tool	Command	What it does
comment_add	knotless comment add	comments on a pull or issue, or reviews a pull: a body, and a verdict (approve or changes) for someone else's pull; a comment's URI as uri answers it in its thread. Answers {uri, written}: the first it wrote and all of them, and for an approval from someone who may not write to the repository, note, that it does not count toward a protected branch's reviews
comment_edit	knotless comment edit	change your comment's text
comment_delete	knotless comment delete	take your comment or review back
comment_react	knotless comment react	as pull_react, to a comment
comment_resolve	knotless comment resolve	resolve the thread a comment on a pull's lines starts, or with undo open it again: its author, the pull's, the owner or a collaborator

comment_add takes lines, comments on lines of a pull's diff at its head, each {path, line, start_line?, side?, body} (side old for lines it removes), each starting a thread: with a body or verdict, as that review's, all sent at once, otherwise on their own; at most 100.

label and triager

Tool	Command	What it does
label_list, label_define, label_delete	knotless label list, define, delete	a repository's labels: what it defines, defining one as owner (name, color, description, exclusive), or taking one away
triager_list, triager_add, triager_remove	knotless triager list, add, remove	the accounts whose labels count, naming one as owner (handle, scopes) or dropping it
triager_eval	knotless triager eval	how an account's labels agree with everyone else's, per scope, as [{scope, labelled, compared, agreed}]

queue

Tool	Command	What it does
queue_list	knotless queue list	each pull waiting, in order, with its place and the batch it is in while that is checked or landing, or the preflight workflows it waits for, then the open pulls ejected
queue_leave	knotless queue leave	takes a pull out, {"left": <uri>}; the owner and collaborators may

run, workflow and runner

Tool	Command	What it does
run_list	knotless run list	what the repository's runners report of its workflows, waiting for runs to finish if asked; each log is its last 8000 bytes; images returns a check's pictures, at most 12 at once
run_rerun	knotless run rerun	as owner, ask the runners to run a ref or a pull again, or one workflow of either, with env at a ref
run_cancel	knotless run cancel	as owner, ask the runners to cancel a ref's or a pull's runs going or waiting, or one workflow's, {"asked": <uri>}
workflow_list	knotless workflow list	the workflows at a ref (the default branch), and what runs each there: {ref, workflows: [{name, push, pull, asked, schedule, error}]}, schedule the [{cron}] it runs on at the default branch
runner_list, runner_add, runner_remove	knotless runner list, add, remove	the accounts whose checks a repository shows; as owner, name or drop one: a private repository's is made a member and invited, again each time it is added
runner_minutes	knotless runner minutes	the minutes each of a repository's runners counts for its owner's public repositories in 30 days, against its allowance, and when minutes free up
agent_list, agent_add, agent_remove	knotless agent list, add, remove	the accounts whose pulls a repository's runners check as they move, as code no one vouches for; as owner, name or drop one
secret_list, secret_set, secret_remove	knotless secret list, set, remove	the secrets a repository's owner, or an admin of the organization that owns it, gives its runners: secret_set sets a name with its value, refs to limit it to some refs' pushes and runners to some of the repository's runners; secret_remove takes one back. They answer each, one per runner, name, runner, refs, key, updatedAt, never a value. A value given here passes through the conversation: for one that should not, run knotless secret set <url> <name> with it on stdin

Tool	Parameter
run_list	ref	only the runs of pushes to that ref, in full, and those asked for there; a pull's are found by pull, a batch's by queue
run_list	queue	only the runs of that branch's merge-queue batches, by its short name (main)
run_list	commit	only the runs of that commit: its hex ID, or at least its first 4 digits
run_list	wait	seconds to wait, at most 300, for a check to show and none to be queued or running; finding none by then is an error naming what was asked for

release

Tool	Command	What it does
release_yank	knotless release yank	withdraw a version of a package from a repository you own, or with undo take that back (yanking), answering {uri}, the release's
release_publish, release_list, release_read	knotless release publish, list, read	releases (packages.md): release_publish publishes a version of a package from a repository you own, its files each {name, content} or {name, base64}, with optional commit, check and notes, answering {uri}; release_list lists a repository's, of one package if given, as [{package, version, latest, yanked, commit, check, notes, createdAt, files: [{name, size, sha256}]}]; release_read reads one file of a version (the latest by default), checked, as {version, content} or {version, base64}, refusing a file over 1 MB

mod

Tool	Command	What it does
mod_hide	knotless mod hide	as owner, hide a pull, issue or comment, or with undo show it again
mod_block, mod_blocks	knotless mod block, knotless mod blocks	mod_block leaves out what a handle writes about your repositories, or one, or with undo stops; mod_blocks lists the accounts an account blocks, yours by default, the latest first: each did, handle, repo (the one repository, by its at:// URI as when blocked, or null for all) and createdAt
mod_report	knotless mod report	report to the appview

admin

As the appview's operator: an account its KNOTLESS_ADMIN_DIDS names.

Tool	Command	What it does
admin_takedown, admin_status, admin_reports, admin_stats, admin_logs	knotless admin takedown, status, reports, stats, logs	take a subject down or, with undo, put it back; whether it is taken down; the reports received; how the appview is used; the lines it logged

org

An organization's members as you may see them, yours or an account's (org): the organization and its members see invitations and hidden members, anyone else public members, as public: true shows them to anyone.

Tool	Command	What it does
org_add	knotless org add	invites an account (admin: true for an admin) or changes a member's role, keeping how it shows and when they joined, yours or, with org, one you are an admin of
org_remove	knotless org remove	takes a member out or withdraws an invitation, yours or, with org, one you are an admin of
org_join	knotless org join	with visibility (public or hidden) accepts an invitation or changes how it shows
org_leave	knotless org leave	leaves
org_members	knotless org members	the roster
org_list	knotless org list	the organizations an account is a public member of
org_delete	knotless org delete	ends yours

They answer {org, name, organization, inside, gateway?, entries: [{did, handle?, role, invitedAt, expiresAt?, joinedAt?, standing}], changed}: changed null, or for org_add {org, who, role, was?, had?, first, private} (first when it made the account an organization, private when the invitation is in the organization's space rather than its public records), for org_remove {org, who, was?, organization}, for org_join {org, role, visibility}, for org_leave {left, warning}, for org_delete {removed: [entries]}. An organization's admin changes its repositories' settings with repo_edit, repo_archive, repo_compact, branch_protect, label_define, label_delete, triager_add, triager_remove, agent_add, agent_remove, runner_add, runner_remove, repo_share and secret_set from their own login, through the appview; repo_rename and repo_transfer take the organization's own.

notification

Tool	Command	What it does
notification_list	knotless notification list	what others did that concerns you, from the appview (a mention reason for a pull, issue or comment that names you as @handle, invite for an organization's invitation you have yet to answer, its about the role it offers, and checks-failed and ejected for checks failing at your pull's latest run and the merge queue taking it out, from the runner, with checks those that failed, as {workflow, status, check}), the latest limit (50 by default, 1 to 100), as {notifications: [{reason, author, about, repo, uri, subject, verdict, mentioned, lineComments, checks, new, createdAt}], markedSeen}: repo the repository as handle/name, for pull_show; subject what it is about, the pull or issue a comment is on, else the pull or issue itself, or for a star the repository's record (null for a follow or an invitation); verdict a review's; mentioned true when it names you though it is heard of for another reason, as a review of your pull that names you is heard of once, as a comment; lineComments how many line comments a review was sent with; and new whether it was new before this listing; marks them all seen after, unless peek, and markedSeen says it did, so the next listing has them new: false. kind lists only mentions, reviews, comments, pulls-and-issues, checks or stars-and-follows, and marks none seen
notification_settings	knotless notification settings	which notifications you hear of, kept by the appview: on and off, lists of reasons (star, follow, pull, issue, comment, mention, review-requested, invite, checks-failed, ejected, subscribed, watching), and followed_only or anyone, change them first; answers {reasons: [{reason, enabled}], followed_only}
notification_watch	knotless notification watch	what you hear of a repository (repo, handle/name) at level all (the default), releases or ignore; participating forgets the choice, but is kept for your own repository, watched at all until you choose. Answers {subject, level, createdAt}
notification_subscribe, notification_mute, notification_unsubscribe	knotless notification subscribe, mute, unsubscribe	what you hear of a pull or an issue (uri): every comment, nothing but a review asked of you, or as your part in it says again. Answer {subject, level, createdAt}
notification_subscriptions	knotless notification subscriptions	every choice, the latest first, as {subscriptions}

theme

Tool	Command	What it does
theme_check	knotless theme check	a palette checked, answering {readable, shortfalls: [{text, on, ratio}]}, each text that would not read at 4.5 to 1 on what it is drawn on
theme_publish	knotless theme publish	publishes a palette with a name as a dev.knotless.theme, answering {uri}, and with use draws your pages in it; a palette that falls short is neither published nor used
theme_use	knotless theme use	draws your pages in a theme (system, light, dark, latte, mocha, dracula, pckt, plyr, blacksky, a published one's at:// URI, or palette with a palette of your own), answering {using}, the name of what they are drawn in
theme_delete	knotless theme delete	deletes one of yours by URI, answering {deleted}
theme_list	knotless theme list	lists themes, everyone's or a handle's, the latest first, or with find those whose name starts so, as {themes: [{uri, name, creator, palette, createdAt}]}

Resources

The same server offers resource templates (resources/templates/list), so a client that reads MCP resources opens a pull, an issue, a diff or a file by URI rather than by a tool call: omp as read mcp://knotless://…, Claude Code as an @ mention. A URI mirrors the thing's page on knotless.dev under the knotless:// scheme, {owner} a handle or DID and {did} and {rkey} those of the pull's or issue's at:// URI, as its page has them. Each answers with what its tool answers, read as the account the tools act as, and --read-only serves them all:

Template	Answers as	Type
knotless://{owner}/{repo}/pulls	pull_list, with no query	application/json
knotless://{owner}/{repo}/issues	issue_list, with no query	application/json
knotless://{owner}/{repo}/pull/{did}/{rkey}	pull_show of at://{did}/dev.knotless.pull/{rkey}	application/json
knotless://{owner}/{repo}/pull/{did}/{rkey}/diff	pull_diff, with no paths: the numbered diff, or, too long to give whole, its said and files as JSON	text/plain
knotless://{owner}/{repo}/issue/{did}/{rkey}	issue_show of at://{did}/dev.knotless.issue/{rkey}	application/json
knotless://{owner}/{repo}/file/{rev}/{+path}	repo_read at rev: text as it is, a binary file as a base64 blob (application/octet-stream)	text/plain

A part is percent-escaped as a template's expansion escapes it: a branch topic/x is topic%2Fx in {rev}, a DID's : may be %3A, and {+path} keeps its /. resources/list lists none: there are too many to list. A URI no template makes is a -32002 (resource not found) error naming the templates. A read that fails is an error with the message its tool's would have, and one past the account's share of a server's calls (see Agents) says to wait. Older than the appview asks for, a read fails as a tool does.

Long files

An agent pays for what it sends and reads as tokens, so the tools let it change part of a long file without moving all of it: repo_search with path and context finds the lines and what is around them, and repo_commit with edits sends only what changes. repo_read with start and end reads a part when the search shows too little.

The test an_agent_changes_a_line_of_a_long_file (crates/knotless-mcp/tests/mcp.rs) benches one change both ways, and fails if editing ever costs more than a fiftieth of rewriting:

One line of a 138 KB file	Sent	Received	About	Time
Before: repo_read, then repo_commit with content	143,115 B	138,207 B	70,330 tokens	473 ms
Now: repo_search with context, then repo_commit with edits	313 B	634 B	236 tokens	351 ms

Tokens are bytes over four. The run behind these numbers is the test's own, against the reference PDS on one machine; cargo test -p knotless-mcp --test mcp an_agent_changes_a_line_of_a_long_file -- --nocapture prints them again. The saving grows with the file: what an edit sends does not.