Skip to content

feat(agents): mcp-agents-tools #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mashkovd merged 2 commits into from
May 6, 2026
Merged

feat(agents): mcp-agents-tools #7

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c37f81e
feat(agents): mcp-agents-tools
mctl-agents[bot] May 6, 2026
22255ab
fix(agents): address P1/P2 codex findings on mcp-agents-tools
mctl-agents[bot] May 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
164 changes: 163 additions & 1 deletion docs/mcp/tools-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# MCP Tools Reference

The MCTL MCP server exposes 39 tools for managing your infrastructure. Each tool is annotated as either **read-only** or **destructive**.
The MCTL MCP server exposes 44 tools for managing your infrastructure. Each tool is annotated as either **read-only** or **destructive**.

## Identity

Expand Down Expand Up @@ -91,6 +91,168 @@ The MCTL MCP server exposes 39 tools for managing your infrastructure. Each tool
| `mctl_resume_openclaw_deploy` | Resume onboarding after bot token saved. Provisions database and submits deploy workflow | Write |
| `mctl_apply_openclaw_resource_profile` | Apply a named runtime profile (startup, steady-medium, steady-small) via GitOps | Write |

## mctl-agents pipeline controls

> **Admin-only.** All tools in this section require membership in the `admins` group.
> Calls from non-admin users return `403 Forbidden`.
>
> _Version note: available as of mctl-api 4.15.0 (commit `016b3c8`) and 4.16.0 (`f41590e`).
> version-status: unverified — confirm against production before relying on this page._

The mctl platform runs a daily autonomous R&D pipeline (`mctl-agents`) that scans sibling
repos for changes, identifies documentation gaps, and writes spec proposals — one cycle per
service (researcher → analyst → spec-writer). A Tier 2 implementer can also convert accepted
proposals into pull requests automatically.

The five tools below let platform admins drive this pipeline on demand from any MCP-capable
client (e.g. Claude Desktop, Claude Code).

### Tool summary

| Tool | Purpose | Returns |
|---|---|---|
Comment on lines +112 to +113

@chatgpt-codex-connector chatgpt-codex-connector Bot May 6, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3 Badge Add read/write annotation for new agent control tools

This new section introduces five tools without the Type annotation used everywhere else in this reference, despite the page contract stating each tool is classified for safety semantics. In practice, this makes it harder for MCP clients (and humans) to distinguish the one read tool from destructive/write triggers at a glance, increasing the chance of invoking a mutating action unintentionally.

Useful? React with 👍 / 👎.

| `mctl_trigger_agents_run` | Full pipeline — all service-agents + mentor digest | `workflow_name` |
| `mctl_trigger_mentor_only` | Mentor weekly digest only | `workflow_name` |
| `mctl_trigger_single_service` | One service-agent cycle | `workflow_name` |
| `mctl_list_recent_agent_runs` | List ≤10 recent pipeline runs from audit log | `{ "items": [...], "count": N }` |
| `mctl_trigger_implementer` | Tier 2: open PRs for accepted proposals | `workflow_name` |
Comment on lines +112 to +118

@chatgpt-codex-connector chatgpt-codex-connector Bot May 6, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3 Badge Add type/risk labels to mctl-agents tool summary

The new mctl-agents tools are introduced in a custom summary table that omits the Type classification used everywhere else in this reference (Read/Write/Destructive), even though these operations trigger workflows and mutate platform state. Because this page is the canonical MCP tool reference and explicitly says tools are annotated by behavior, leaving these five unclassified makes risk handling ambiguous for readers and agent wrappers that use this doc to decide confirmation behavior.

Useful? React with 👍 / 👎.


---

### `mctl_trigger_agents_run`

Triggers a full mctl-agents run: every service-agent (researcher → analyst → spec-writer
in parallel) followed by the mentor weekly digest. Equivalent to the daily 06:00 UTC cron,
but on demand.

**Parameters:** none

**Cost / duration:** ~$10 against Claude subscription quota; ~15 minutes.

**Result:** A `chore(agents)` commit lands in `mctl-gitops` main under
`platform-gitops/agents-state/` with new inbox files, proposals, and updated `.status.yaml`
entries.

**Returns:** `workflow_name` string — use with `mctl_get_workflow_status` to track progress.

```
mctl_trigger_agents_run()
# → { "workflow_name": "mctl-agents-daily-abc12" }
```

---

### `mctl_trigger_mentor_only`

Runs only the mentor sub-agent, which reads all service inbox files from the past week and
produces a cross-service digest. Lighter than the full run.

**Parameters:** none

**Cost / duration:** ~$2, ~5 minutes.

**Returns:** `workflow_name`

---

### `mctl_trigger_single_service`

Runs the researcher → analyst → spec-writer cycle for a single service only.
Useful for spot-checking one repo after a significant release.

**Parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `service` | string (enum) | yes | One of: `mctl-web`, `mctl-openclaw`, `mctl-docs`, `mctl-api`, `mctl-portal`, `mctl-agent`, `mctl-gitops` |

**Cost / duration:** ~$2–5, ~5–10 minutes.

**Returns:** `workflow_name`

**Example:**

```
mctl_trigger_single_service(service="mctl-docs")
# → { "workflow_name": "mctl-agents-single-xyz99" }
```

---

### `mctl_list_recent_agent_runs`

Returns up to 10 recent mctl-agents pipeline runs from the audit log, enriched with the
run mode and target service so you don't need to parse the workflow name.

**Parameters:** none

**Returns:** JSON object `{ "items": [...], "count": N }` where each item has:

| Field | Description |
|---|---|
| `workflowName` | Argo workflow name (use for status polling) |
| `operation` | Operation name (`mctl-agents-run`, `mctl-agents-implement`, …) |
| `mode` | Run mode (`full`, `mentor-only`, `single-service`) |
| `service` | Target service (empty for full/mentor runs) |
| `status` | Last known status (`running`, `succeeded`, `failed`) |
| `user` | Admin user ID who triggered the run |
| `timestamp` | ISO8601 start time |
| `riskLevel` | `high` for all mctl-agents triggers |
| `message` | Short status message |

---

### `mctl_trigger_implementer`

Triggers Tier 2 implementer agents. The implementer scans
`platform-gitops/agents-state/<service>/proposals/<slug>/.status.yaml` for entries with
`status: accepted`. For each accepted proposal it:

1. Clones the matching `mctlhq/<service>` repo.
2. Runs the per-service implementer sub-agent to make the change.
3. Pushes a `feat/agents-<slug>` branch and opens a PR.
4. Updates `.status.yaml` to `status: implemented` with the PR URL.

**Parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `service` | string (enum) | no | Filter to one service. Leave empty to process all services. Same enum as `mctl_trigger_single_service`. |
| `slug` | string | no | Filter to one proposal slug (across services unless `service` is also set). |
| `force` | `"true"` \| `"false"` | no | Retry proposals stuck in `in-progress` (e.g. from a crashed run). Default `"false"`. |

**Cost / duration:** ~$3 per proposal; 1–10 minutes per proposal.

**Returns:** `workflow_name`

**Example — implement one specific proposal:**

```
mctl_trigger_implementer(service="mctl-docs", slug="mcp-agents-tools")
# → { "workflow_name": "mctl-agents-implement-abc34" }
```

---

### Status polling

All trigger tools return a `workflow_name`. Poll for progress with:

```
mctl_get_workflow_status(workflow_name="mctl-agents-daily-abc12")
```

Or check the last few runs at any time:

```
mctl_list_recent_agent_runs()
```

Results also appear as `chore(agents)` commits in the `mctl-gitops` repository under
`platform-gitops/agents-state/`.

---

## Tool Annotations

Tools are annotated with behavior hints for AI clients:
Expand Down
Loading