# MCP tool reference

> Every tool of the Diffinery MCP server with its arguments, generated from the server's tool list.

Source: https://diffinery.com/docs/reference/mcp-tools

Every tool the Diffinery MCP server offers, generated from the server's own tool list, so it always matches what `tools/list` returns. For setup in Claude Code, Cursor and other clients, read [MCP](https://diffinery.com/docs/agents/mcp).

## Connection

- Endpoint: `https://diffinery.com/mcp` (Streamable HTTP; responses are JSON, not event streams).
- Authentication: `Authorization: Bearer dfy_...`, a token for an agent or a person. Every call needs an active account.
- Protocol versions: `2025-06-18`, `2025-03-26`, `2024-11-05`. The server answers with the version the client asks for when it supports it, else the newest.
- Every tool runs through the same permission checks, branch protection and agent guardrails as git and the REST API.
- Errors come back as a tool result with `isError: true` and the message as text. Successful results carry the JSON both as text and as `structuredContent`.

## Tools

| Tool | Read-only | Summary |
| --- | --- | --- |
| [`whoami`](#whoami) | yes | Show the account this token acts as, including the human an agent works on behalf of. |
| [`list_repos`](#list_repos) | yes | List repositories visible to you, optionally filtered by owner. |
| [`list_tree`](#list_tree) | yes | List files and directories at a path in a repository. |
| [`get_file`](#get_file) | yes | Read a file's contents. |
| [`list_branches`](#list_branches) | yes | List branches, marking the default and protected ones. |
| [`create_branch`](#create_branch) | no | Create a branch from another branch, tag or commit. |
| [`commit_files`](#commit_files) | no | Create one commit that writes and deletes files on a branch, without a git client. |
| [`compare`](#compare) | yes | Compare two refs: commits ahead/behind and a unified diff. |
| [`list_pull_requests`](#list_pull_requests) | yes | List pull requests. |
| [`get_pull_request`](#get_pull_request) | yes | Get a pull request with its conversation, reviews, mergeability and (optionally) the full diff. |
| [`create_pull_request`](#create_pull_request) | no | Open a pull request. |
| [`comment`](#comment) | no | Comment on an issue or pull request. |
| [`review_pull_request`](#review_pull_request) | no | Submit a review: APPROVE, REQUEST_CHANGES or COMMENT, with optional line comments [{ path, line, side?, body }]. |
| [`merge_pull_request`](#merge_pull_request) | no | Merge a pull request when it is mergeable (checks, approvals and branch protection are enforced). |
| [`enable_auto_merge`](#enable_auto_merge) | no | Turn on auto-merge: Diffinery merges the pull request by itself as soon as every branch rule is met (required checks green on the head, approvals from people, linear history), or adds it to the merge queue when the base branch uses one. |
| [`disable_auto_merge`](#disable_auto_merge) | no | Turn off auto-merge on a pull request. |
| [`dequeue_pull_request`](#dequeue_pull_request) | no | Remove a pull request from its base branch's merge queue. |
| [`list_issues`](#list_issues) | yes | List or search issues. |
| [`get_issue`](#get_issue) | yes | Get an issue with its comments. |
| [`create_issue`](#create_issue) | no | Open an issue. |
| [`update_issue`](#update_issue) | no | Update an issue or pull request: title, body, state (open/closed), labels. |
| [`list_workflow_runs`](#list_workflow_runs) | yes | List workflow runs, newest first. |
| [`get_workflow_run`](#get_workflow_run) | yes | Get a run with its jobs, their status, conclusion and failure reason. |
| [`get_job_logs`](#get_job_logs) | yes | Fetch a job's log as plain text. |
| [`rerun_workflow`](#rerun_workflow) | no | Re-run a finished workflow run as a new attempt. |
| [`rerun_job`](#rerun_job) | no | Re-run one job (one matrix leg) of a finished run, with the jobs that depend on it, as a new attempt of the run; the other jobs keep their results. |
| [`cancel_workflow`](#cancel_workflow) | no | Cancel a queued or running workflow run. |
| [`dispatch_workflow`](#dispatch_workflow) | no | Start a workflow_dispatch run, e.g. |
| [`get_organization`](#get_organization) | yes | Show an organization: its name and, to its members and their agents, the base permission every member gets on its repositories (default_repository_permission: none, read, write or admin). |
| [`list_invitations`](#list_invitations) | yes | List pending invitations to a repository (owner and repo, for its admins), an organization (org, for its owners and admins), or the site (neither, for site admins). |
| [`revoke_invitation`](#revoke_invitation) | no | Revoke a pending invitation by id (from list_invitations), so it can't be accepted and the address can be invited again. |
| [`sandbox_create`](#sandbox_create) | no | Start an isolated Linux sandbox with the repository checked out (git push from inside it uses your permissions). |
| [`sandbox_exec`](#sandbox_exec) | no | Run a shell command in a sandbox. |
| [`sandbox_read_file`](#sandbox_read_file) | no | Read a file inside a sandbox. |
| [`sandbox_write_file`](#sandbox_write_file) | no | Write a file inside a sandbox. |
| [`sandbox_close`](#sandbox_close) | no | Shut down a sandbox. |
| [`list_releases`](#list_releases) | yes | List a repository's releases, newest first. |
| [`get_release`](#get_release) | yes | Get a release by tag, by id, or the latest release when neither is given. |
| [`create_release`](#create_release) | no | Create a release. |
| [`update_release`](#update_release) | no | Edit a release: title, notes, tag, draft or prerelease state. |
| [`upload_release_asset`](#upload_release_asset) | no | Attach a file (up to 25 MB) to a release. |
| [`generate_release_notes`](#generate_release_notes) | yes | Draft release notes for a tag from the pull requests merged since the previous release. |
| [`search_docs`](#search_docs) | yes | Search the Diffinery documentation (workflows, API, git, agents, settings) and the site's product, comparison and FAQ pages. |
| [`read_docs`](#read_docs) | yes | Read a Diffinery documentation page as Markdown. |
| [`today`](#today) | yes | Your morning view across every repository you can see: pull requests that need you (review requests, agent pull requests waiting for a person's approval, your own blocked ones), what your agents are working on and where each stands, and what merged, was released or failed in the last 24 hours. |
| [`agent_tasks`](#agent_tasks) | yes | List agent tasks. |
| [`project`](#project) | yes | A repository as a project: its task board grouped by state (waiting on you, working, queued, ready for review, landing, done, idle), the project's memory and its settings (how many tasks run at once, instructions every task gets). |
| [`project_posts`](#project_posts) | yes | The project conversation: people's posts and task events, oldest first, after `after` (a post id), or the latest 100. |
| [`agent_task`](#agent_task) | yes | One agent task: its goal, state, runs, branch and pull request, and its transcript after `after` (a line number; default from the start, at most 500 lines). |
| [`start_github_import`](#start_github_import) | no | Start a server-side import of a GitHub repository into Diffinery: git history (keeping issue and pull-request numbers), issues and pull requests with comments and reviews, labels, milestones, branch protection, Actions variables, releases and deployment environments. |
| [`get_import`](#get_import) | yes | Get an import you started: its status, per-step progress, warnings, any error, and (for an organization import) its repositories. |
| [`list_imports`](#list_imports) | yes | List the imports you have started, newest first. |

## Identity and repositories

### whoami

Show the account this token acts as, including the human an agent works on behalf of.

Read-only: yes.

No arguments.

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"whoami","arguments":{}}}
```

### list_repos

List repositories visible to you, optionally filtered by owner.

Read-only: yes.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | no |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_repos","arguments":{}}}
```

## Code

### list_tree

List files and directories at a path in a repository.

Read-only: yes.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `ref` | string | no | Branch, tag or commit (default: default branch) |
| `path` | string | no |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_tree","arguments":{"owner":"acme","repo":"website"}}}
```

### get_file

Read a file's contents.

Read-only: yes.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `path` | string | yes |  |
| `ref` | string | no |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_file","arguments":{"owner":"acme","repo":"website","path":"README.md"}}}
```

### commit_files

Create one commit that writes and deletes files on a branch, without a git client. Pass expected_head_sha to avoid racing other writers; pass create_branch_from to start a new branch.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `branch` | string | yes |  |
| `message` | string | yes |  |
| `files` | array of object | no | [{ path, content, encoding?: 'utf-8'\|'base64', executable?: boolean }] |
| `deletes` | array of string | no |  |
| `expected_head_sha` | string | no |  |
| `create_branch_from` | string | no |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"commit_files","arguments":{"owner":"acme","repo":"website","branch":"main","message":"..."}}}
```

## Branches and commits

### list_branches

List branches, marking the default and protected ones.

Read-only: yes.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_branches","arguments":{"owner":"acme","repo":"website"}}}
```

### create_branch

Create a branch from another branch, tag or commit.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `branch` | string | yes |  |
| `from` | string | no | Default: the default branch |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create_branch","arguments":{"owner":"acme","repo":"website","branch":"main"}}}
```

### compare

Compare two refs: commits ahead/behind and a unified diff.

Read-only: yes.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `base` | string | yes |  |
| `head` | string | yes |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"compare","arguments":{"owner":"acme","repo":"website","base":"...","head":"..."}}}
```

## Pull requests

### list_pull_requests

List pull requests.

Read-only: yes.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `state` | string (`open`, `closed`, `all`) | no |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_pull_requests","arguments":{"owner":"acme","repo":"website"}}}
```

### get_pull_request

Get a pull request with its conversation, reviews, mergeability and (optionally) the full diff. `mergeability.blockers` is what stops you merging it yourself now. For agents and workflow tokens, `auto_merge_blockers` is what stops Diffinery landing it through auto-merge or the merge queue (enable_auto_merge): an empty list means it would land now.

Read-only: yes.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `number` | integer | yes |  |
| `include_diff` | boolean | no |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_pull_request","arguments":{"owner":"acme","repo":"website","number":"42"}}}
```

### create_pull_request

Open a pull request. Use `intent` to explain the goal for reviewers (agents should always set it). `auto_merge`: true turns on auto-merge as it opens (it merges once required checks pass and every rule of the base branch is met), false keeps it off where your own setting would turn it on; `autoMergeSkipped` says why it stayed off when you asked.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `title` | string | yes |  |
| `body` | string | no |  |
| `head` | string | yes |  |
| `base` | string | no |  |
| `draft` | boolean | no |  |
| `intent` | string | no |  |
| `reviewers` | array of string | no |  |
| `auto_merge` | boolean | no |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create_pull_request","arguments":{"owner":"acme","repo":"website","title":"...","head":"..."}}}
```

### review_pull_request

Submit a review: APPROVE, REQUEST_CHANGES or COMMENT, with optional line comments [{ path, line, side?, body }]. Agent approvals never count toward required human approvals of agent-authored PRs.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `number` | integer | yes |  |
| `event` | string (`APPROVE`, `REQUEST_CHANGES`, `COMMENT`) | yes |  |
| `body` | string | no |  |
| `comments` | array of object | no |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"review_pull_request","arguments":{"owner":"acme","repo":"website","number":"42","event":"..."}}}
```

### merge_pull_request

Merge a pull request when it is mergeable (checks, approvals and branch protection are enforced). When the base branch uses a merge queue, this adds the pull request to the queue instead; it merges once its merge group passes the required checks. Agents can't merge into protected or default branches themselves: use enable_auto_merge there.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `number` | integer | yes |  |
| `method` | string (`merge`, `squash`, `rebase`) | no |  |
| `expected_head_sha` | string | no |  |
| `delete_branch` | boolean | no |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"merge_pull_request","arguments":{"owner":"acme","repo":"website","number":"42"}}}
```

### enable_auto_merge

Turn on auto-merge: Diffinery merges the pull request by itself as soon as every branch rule is met (required checks green on the head, approvals from people, linear history), or adds it to the merge queue when the base branch uses one. This is how an agent lands a change on a protected or default branch: it is allowed only where the branch protection sets allowAgentAutoMerge and has at least one required check, and nothing is bypassed. A push to the branch by anyone else turns it off.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `number` | integer | yes |  |
| `merge_method` | string (`merge`, `squash`, `rebase`) | no | Default: the merge queue's method, squash where linear history is required, else merge. |
| `commit_title` | string | no |  |
| `commit_message` | string | no |  |
| `delete_branch` | boolean | no | Delete the head branch once it lands (never a protected or default branch). |
| `expected_head_sha` | string | no | Only turn it on if the head is still at this commit. |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"enable_auto_merge","arguments":{"owner":"acme","repo":"website","number":"42"}}}
```

### disable_auto_merge

Turn off auto-merge on a pull request.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `number` | integer | yes |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"disable_auto_merge","arguments":{"owner":"acme","repo":"website","number":"42"}}}
```

### dequeue_pull_request

Remove a pull request from its base branch's merge queue.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `number` | integer | yes |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"dequeue_pull_request","arguments":{"owner":"acme","repo":"website","number":"42"}}}
```

## Issues

### comment

Comment on an issue or pull request.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `number` | integer | yes |  |
| `body` | string | yes |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"comment","arguments":{"owner":"acme","repo":"website","number":"42","body":"..."}}}
```

### list_issues

List or search issues.

Read-only: yes.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `state` | string (`open`, `closed`, `all`) | no |  |
| `q` | string | no |  |
| `label` | string | no |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_issues","arguments":{"owner":"acme","repo":"website"}}}
```

### get_issue

Get an issue with its comments.

Read-only: yes.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `number` | integer | yes |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_issue","arguments":{"owner":"acme","repo":"website","number":"42"}}}
```

### create_issue

Open an issue.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `title` | string | yes |  |
| `body` | string | no |  |
| `labels` | array of string | no |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create_issue","arguments":{"owner":"acme","repo":"website","title":"..."}}}
```

### update_issue

Update an issue or pull request: title, body, state (open/closed), labels.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `number` | integer | yes |  |
| `title` | string | no |  |
| `body` | string | no |  |
| `state` | string (`open`, `closed`) | no |  |
| `labels` | array of string | no |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"update_issue","arguments":{"owner":"acme","repo":"website","number":"42"}}}
```

## Actions

### list_workflow_runs

List workflow runs, newest first. Filter by branch, commit sha, PR number or status.

Read-only: yes.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `branch` | string | no |  |
| `sha` | string | no |  |
| `pr_number` | integer | no |  |
| `status` | string | no |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_workflow_runs","arguments":{"owner":"acme","repo":"website"}}}
```

### get_workflow_run

Get a run with its jobs, their status, conclusion and failure reason.

Read-only: yes.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `run_id` | string | yes |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_workflow_run","arguments":{"owner":"acme","repo":"website","run_id":"..."}}}
```

### get_job_logs

Fetch a job's log as plain text. Use `tail` to limit to the last N lines (default 400).

Read-only: yes.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `job_id` | string | yes |  |
| `tail` | integer | no |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_job_logs","arguments":{"owner":"acme","repo":"website","job_id":"..."}}}
```

### rerun_workflow

Re-run a finished workflow run as a new attempt. With `failed_only`, only the jobs that failed, were cancelled or timed out run again (with the jobs that depend on them); the others keep their results.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `run_id` | string | yes |  |
| `failed_only` | boolean | no |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"rerun_workflow","arguments":{"owner":"acme","repo":"website","run_id":"..."}}}
```

### rerun_job

Re-run one job (one matrix leg) of a finished run, with the jobs that depend on it, as a new attempt of the run; the other jobs keep their results.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `job_id` | string | yes |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"rerun_job","arguments":{"owner":"acme","repo":"website","job_id":"..."}}}
```

### cancel_workflow

Cancel a queued or running workflow run.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `run_id` | string | yes |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"cancel_workflow","arguments":{"owner":"acme","repo":"website","run_id":"..."}}}
```

### dispatch_workflow

Start a workflow_dispatch run, e.g. workflow 'deploy.yml' on ref 'main' with inputs.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `workflow` | string | yes |  |
| `ref` | string | no |  |
| `inputs` | object | no |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"dispatch_workflow","arguments":{"owner":"acme","repo":"website","workflow":"ci.yml"}}}
```

## Releases

### list_releases

List a repository's releases, newest first. Drafts are included only for writers.

Read-only: yes.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `limit` | number | no | At most this many (default 30, max 100) |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_releases","arguments":{"owner":"acme","repo":"website"}}}
```

### get_release

Get a release by tag, by id, or the latest release when neither is given.

Read-only: yes.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `tag` | string | no |  |
| `id` | number | no |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_release","arguments":{"owner":"acme","repo":"website"}}}
```

### create_release

Create a release. Creates the tag at target_commitish (default branch by default) when it doesn't exist yet.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `tag_name` | string | yes |  |
| `target_commitish` | string | no | Branch or commit for a new tag |
| `name` | string | no | Release title |
| `body` | string | no | Release notes (Markdown) |
| `draft` | boolean | no | Keep it as a draft, visible to writers only |
| `prerelease` | boolean | no |  |
| `make_latest` | string (`true`, `false`, `legacy`) | no | Whether this becomes the latest release (default true) |
| `generate_release_notes` | boolean | no | Fill in notes from merged pull requests since the previous release |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create_release","arguments":{"owner":"acme","repo":"website","tag_name":"..."}}}
```

### update_release

Edit a release: title, notes, tag, draft or prerelease state. Publishing a draft sends the release event.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `id` | number | yes |  |
| `tag_name` | string | no |  |
| `target_commitish` | string | no |  |
| `name` | string | no | Release title |
| `body` | string | no | Release notes (Markdown) |
| `draft` | boolean | no | Keep it as a draft, visible to writers only |
| `prerelease` | boolean | no |  |
| `make_latest` | string (`true`, `false`, `legacy`) | no | Whether this becomes the latest release (default true) |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"update_release","arguments":{"owner":"acme","repo":"website","id":"..."}}}
```

### upload_release_asset

Attach a file (up to 25 MB) to a release. Pass text as content, or bytes as content_base64.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `release_id` | number | yes |  |
| `name` | string | yes | File name |
| `label` | string | no |  |
| `content_type` | string | no |  |
| `content` | string | no |  |
| `content_base64` | string | no |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"upload_release_asset","arguments":{"owner":"acme","repo":"website","release_id":"...","name":"website"}}}
```

### generate_release_notes

Draft release notes for a tag from the pull requests merged since the previous release. Doesn't create anything.

Read-only: yes.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `tag_name` | string | yes |  |
| `target_commitish` | string | no |  |
| `previous_tag_name` | string | no |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"generate_release_notes","arguments":{"owner":"acme","repo":"website","tag_name":"..."}}}
```

## Imports

### start_github_import

Start a server-side import of a GitHub repository into Diffinery: git history (keeping issue and pull-request numbers), issues and pull requests with comments and reviews, labels, milestones, branch protection, Actions variables, releases and deployment environments. Secret VALUES are never read from GitHub (only their names are reported, to set by hand), and push protection is never bypassed on an agent's behalf. An agent can import only where its owner may: the owner's own account or an organization the owner administers (an organization's agent: that organization), and only when the agent's policy allows write. Returns the import id; poll it with get_import.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `source` | string | yes | GitHub repository as owner/name or a github.com/Enterprise URL |
| `owner` | string | yes | Diffinery user or organization to import into |
| `name` | string | no | Target repository name (default: the GitHub name) |
| `visibility` | string (`keep`, `private`, `public`) | no | Visibility of the new repository (default: keep GitHub's; GitHub internal repositories become private) |
| `github_token` | string | no | A GitHub token to read a private repository (optional) |
| `github_api_url` | string | no | GitHub Enterprise REST API base, e.g. https://ghe.example.com/api/v3 (optional) |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"start_github_import","arguments":{"source":"...","owner":"acme"}}}
```

### get_import

Get an import you started: its status, per-step progress, warnings, any error, and (for an organization import) its repositories.

Read-only: yes.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The import id |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_import","arguments":{"id":"..."}}}
```

### list_imports

List the imports you have started, newest first.

Read-only: yes.

No arguments.

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_imports","arguments":{}}}
```

## Sandboxes

### sandbox_create

Start an isolated Linux sandbox with the repository checked out (git push from inside it uses your permissions). Returns a sandbox id.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `ref` | string | no |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"sandbox_create","arguments":{"owner":"acme","repo":"website"}}}
```

### sandbox_exec

Run a shell command in a sandbox. Returns exit code, stdout and stderr.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `sandbox_id` | string | yes |  |
| `command` | string | yes |  |
| `cwd` | string | no |  |
| `timeout_seconds` | integer | no |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"sandbox_exec","arguments":{"owner":"acme","repo":"website","sandbox_id":"...","command":"..."}}}
```

### sandbox_read_file

Read a file inside a sandbox.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `sandbox_id` | string | yes |  |
| `path` | string | yes |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"sandbox_read_file","arguments":{"owner":"acme","repo":"website","sandbox_id":"...","path":"README.md"}}}
```

### sandbox_write_file

Write a file inside a sandbox.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `sandbox_id` | string | yes |  |
| `path` | string | yes |  |
| `content` | string | yes |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"sandbox_write_file","arguments":{"owner":"acme","repo":"website","sandbox_id":"...","path":"README.md","content":"..."}}}
```

### sandbox_close

Shut down a sandbox.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `sandbox_id` | string | yes |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"sandbox_close","arguments":{"owner":"acme","repo":"website","sandbox_id":"..."}}}
```

## Docs

### search_docs

Search the Diffinery documentation (workflows, API, git, agents, settings) and the site's product, comparison and FAQ pages. Returns the best matching pages and sections with a snippet; read one with read_docs.

Read-only: yes.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | Words to look for, like 'merge queue' or 'workflow_dispatch inputs' |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_docs","arguments":{"query":"..."}}}
```

### read_docs

Read a Diffinery documentation page as Markdown. Pass its slug (like 'actions/workflow-syntax'), or 'index' for the overview, which links to every page. Site pages work too, by path (like '/compare/github' or '/faq').

Read-only: yes.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | string | yes | Page slug or docs URL |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"read_docs","arguments":{"page":"..."}}}
```

## Other

### get_organization

Show an organization: its name and, to its members and their agents, the base permission every member gets on its repositories (default_repository_permission: none, read, write or admin).

Read-only: yes.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | string | yes | Organization login |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_organization","arguments":{"org":"acme"}}}
```

### list_invitations

List pending invitations to a repository (owner and repo, for its admins), an organization (org, for its owners and admins), or the site (neither, for site admins).

Read-only: yes.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | no | Repository owner (user or org login) |
| `repo` | string | no | Repository name |
| `org` | string | no | Organization login |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_invitations","arguments":{}}}
```

### revoke_invitation

Revoke a pending invitation by id (from list_invitations), so it can't be accepted and the address can be invited again. Takes the same owner and repo, org, or neither as list_invitations.

Read-only: no.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | no | Repository owner (user or org login) |
| `repo` | string | no | Repository name |
| `org` | string | no | Organization login |
| `invitation_id` | string | yes |  |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"revoke_invitation","arguments":{"invitation_id":"..."}}}
```

### today

Your morning view across every repository you can see: pull requests that need you (review requests, agent pull requests waiting for a person's approval, your own blocked ones), what your agents are working on and where each stands, and what merged, was released or failed in the last 24 hours.

Read-only: yes.

No arguments.

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"today","arguments":{}}}
```

### agent_tasks

List agent tasks. With owner and repo: that repository's tasks (you need write access). Without: the tasks you started (for an agent: the tasks it runs). Starting, steering and retrying tasks happens on the web, by the person whose model key it spends.

Read-only: yes.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | no | Repository owner (user or org login) |
| `repo` | string | no | Repository name |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"agent_tasks","arguments":{}}}
```

### project

A repository as a project: its task board grouped by state (waiting on you, working, queued, ready for review, landing, done, idle), the project's memory and its settings (how many tasks run at once, instructions every task gets). You need write access.

Read-only: yes.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"project","arguments":{"owner":"acme","repo":"website"}}}
```

### project_posts

The project conversation: people's posts and task events, oldest first, after `after` (a post id), or the latest 100. Posting happens on the web, by a person.

Read-only: yes.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `after` | integer | no | Return posts after this id |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"project_posts","arguments":{"owner":"acme","repo":"website"}}}
```

### agent_task

One agent task: its goal, state, runs, branch and pull request, and its transcript after `after` (a line number; default from the start, at most 500 lines).

Read-only: yes.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | yes | Repository owner (user or org login) |
| `repo` | string | yes | Repository name |
| `number` | integer | yes | Task number |
| `after` | integer | no | Return transcript lines after this one |

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"agent_task","arguments":{"owner":"acme","repo":"website","number":"42"}}}
```