Tool Reference¶

The server has two surfaces: HTTP endpoints for session lifecycle and diff upload, and MCP tools for the reviews themselves. The skills call both for you; this page is the reference for building against the server directly.

Base URL is your CloudAEye server root (e.g. https://api.cloudaeye.com). MCP tools are served at /mcp.

HTTP endpoints¶

`POST /session`¶

Mint or resume a session for a (repo, branch, head) triple. If a session already exists for that exact triple, its id is returned (resumed: true); otherwise a fresh one is minted.

Request body (JSON):

Field	Required	Description
`repo`	yes	Repository name
`branch`	yes	Branch name
`head`	yes	Current `git rev-parse HEAD` — also the base the diff is generated against
`language`	no	Primary language of the repo (e.g. `python`, `typescript`)
`tenant_key`	no	CloudAEye tenant number; enables Jira ticket resolution in Check Task

Response:

{ "session_id": "…", "resumed": false }

On a resume where a task was previously checked, the response also includes a prior_task block (task_description, task_source) so a client can offer to reuse it instead of re-prompting. Passing a tenant_key on a resume that didn't originally have one attaches it — Jira refs start working mid-cycle.

Errors: 400 if the body is not JSON or a required field is missing.

`POST /upload/{session_id}`¶

Replace the diff for an existing session. The diff is sent as a multipart file field named file.

curl -sF "file=@session.diff" https://api.cloudaeye.com/upload/$SESSION_ID

Response:

{ "session_id": "…", "diff_unchanged": false }

diff_unchanged: true when the uploaded bytes are identical to the last upload and the cached context is still on disk — the server skips the cache wipe.
Otherwise the cached code-context graph and staged post-edit file tree are invalidated, so the next tool call re-derives them against the new diff.

Errors: 404 if the session is unknown (call POST /session first); 400 if the file field is missing.

The diff is never passed inline to an MCP tool. It lives on the server keyed by session_id. Always derive it from git diff rather than constructing it by hand — see the note on git add --intent-to-add below.

MCP tools¶

All three tools take a session_id and reference the uploaded diff by it. They return a JSON string.

`inspect_diff`¶

Single-shot inspect pass over the session's diff. Runs the 10-category INSPECT config (BUG_REPORT + SECURITY_REPORT essentials) by default.

inspect_diff(session_id: str, intent: str = "", context: dict | None = None) -> str

Argument	Description
`session_id`	Id from `POST /session`
`intent`	One-paragraph summary of what the agent just did; flows into the planner to prioritise, and is the only channel for asking it to skip a prior finding
`context`	Optional per-call extras: `pr_title`, `pr_description`, `review_config`, `report_types`

Returns: the finding schema — verdict, findings[], counts, files_changed, elapsed_seconds, session_id.

`describe_change`¶

Produces a plain-markdown description of the session's diff.

describe_change(session_id: str, intent: str = "", context: dict | None = None) -> str

Argument	Description
`session_id`	Id from `POST /session`
`intent`	The user's original task request, verbatim
`context`	Optional extras (`pr_title`, `pr_description`)

Returns: a description field — a # Change Description paragraph plus an ## Important Changes bullet list. Trivial diffs short-circuit to a one-line "Trivial change —" summary. Also returns files_visited, an eval_summary, and a context_refresh summary when the graph was refreshed.

`check_task`¶

Verifies whether the session's diff fulfils a stated task.

check_task(session_id: str, task_description: str,
           task_source: str = "user-supplied",
           intent: str = "", context: dict | None = None) -> str

Argument	Description
`session_id`	Id from `POST /session`
`task_description`	The task to verify against — a ticket reference list (`[BETA-5225, #42]`, a bare Jira key, `owner/repo#42`, or a GitHub issue URL), or freeform text passed verbatim
`task_source`	Provenance label: `github-issue`, `jira`, `spec`, or `user-text`
`intent`	One-paragraph summary of this round of edits; on a recheck, reference the prior gaps by number and how each was addressed
`context`	Optional extras (`pr_title`, `pr_description`)

Returns: a report field — a # Task Completion Check heading, an overall verdict (DONE / PARTIAL / NOT DONE), a per-requirement checklist, and any gaps. Tickets are re-fetched on every call.

Errors: returns a structured { "error": … } (not a verdict) when task_source=github-issue but the URL is unrecognised, when a ticket can't be resolved, or when a task made only of unresolvable ticket refs has nothing to judge. See Custom Context.

`security_review`¶

Enables the full security surface — SECURITY_REPORT, LLM_SECURITY_REPORT, AIAGENT_SECURITY_REPORT, and MCP_REPORT — over the session's diff, with the same session_id / intent / context shape as inspect_diff.

`review`¶

The comprehensive pass — every report type and category — over the session's diff. Same call shape as inspect_diff.

Deriving the diff¶

Always derive the diff from git diff rather than constructing it manually, so the server sees exactly what git sees.

# Pre-commit (the supported flow): mark untracked files so they appear, then capture
git add --intent-to-add . && git diff > session.diff

git add --intent-to-add is non-destructive — it registers new files in the index without staging their content, so git diff emits them as new file hunks. Without it, completely untracked files are invisible to the diff and to the review. Undo with git reset HEAD <file> if needed.

End-to-end example¶

BASE=${CLOUDAEYE_URL:-https://api.cloudaeye.com}
REPO=$(basename -s .git "$(git config --get remote.origin.url)")
BRANCH=$(git rev-parse --abbrev-ref HEAD)
HEAD=$(git rev-parse HEAD)

# 1. Create or resume the session
SESSION_ID=$(curl -s -X POST "$BASE/session" \
  -H "Content-Type: application/json" \
  -d "{\"repo\":\"$REPO\",\"branch\":\"$BRANCH\",\"head\":\"$HEAD\",\"language\":\"python\"}" \
  | python -c "import sys,json;print(json.load(sys.stdin)['session_id'])")

# 2. Upload the diff
git add --intent-to-add . && git diff > session.diff
curl -sF "file=@session.diff" "$BASE/upload/$SESSION_ID"

# 3. Call inspect_diff via your MCP client, passing session_id + intent

Steps 1–2 are plain HTTP; step 3 is an MCP tool call your agent makes. The skills bundle all three into one slash command.

Tool Reference¶

HTTP endpoints¶

POST /session¶

POST /upload/{session_id}¶

MCP tools¶

inspect_diff¶

describe_change¶

check_task¶

security_review¶

review¶