docs(factories): document Factory MCP - #521
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR adds Factory MCP documentation, scaffolds the new Factories section, updates platform terminology variables, and adjusts docs tooling/navigation around the launch IA. The main Factory MCP page is useful, but several merge-blocking issues remain: visible stub pages are being published, the primary Factory MCP page is not discoverable from the new sidebar, pending naming is hardcoded in top-level navigation, and the new security-sensitive handoff guidance needs clearer warnings.
Concerns
- The new
/factories/landing page and related Factories pages publish internal placeholder notes while the redirect sends existing/platform/software-factory/traffic there. - The PR's primary new
factory-mcppage is missing from the Factories sidebar. - The top-level navigation hardcodes a pending product name instead of using the variable/current approved label.
- The style lint change permits any non-empty JSX expression title to bypass VideoEmbed title validation.
- No approved repository spec context was provided, so there was no implementation-vs-spec drift to evaluate.
Security
- The Factory MCP page documents local-to-cloud workspace snapshots and broad artifact transfer without warning readers to review and redact sensitive files, screenshots, or other private context before transfer.
Verdict
Found: 0 critical, 6 important, 1 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| label: "Overview" | ||
| --- | ||
|
|
||
| [STUB — pending content from HYC/content team for the 8/18 closed-beta soft launch. Owner: HYC. This page is the Factories tab landing page (`/factories/`). |
There was a problem hiding this comment.
/factories/ landing page as a visible stub with internal launch/owner notes, and vercel.json redirects /platform/software-factory/ here. Replace the scaffold with launch-ready content, or keep the page/sidebar/redirect hidden until the real content lands.
| { slug: 'factories/how-factories-work', label: 'How Factories work' }, | ||
| { slug: 'factories/configure-your-factory', label: 'Configure your Factory' }, | ||
| { slug: 'factories/connect-your-factory', label: 'Connect your Factory' }, | ||
| { slug: 'factories/infrastructure-and-security', label: 'Infrastructure & security' }, |
There was a problem hiding this comment.
src/content/docs/factories/factory-mcp.mdx page is not listed in the Factories sidebar, so the PR's primary page is hard to discover. Add a factories/factory-mcp entry to this group.
| // ZL naming sign-off -- see .agents/references/terminology.md). Reorganized | ||
| // from 10 subsections into HYC's 6-group IA; all page slugs unchanged. | ||
| id: 'platform', | ||
| label: 'Automation Platform', |
There was a problem hiding this comment.
Automation Platform even though the terminology entry says final naming is pending and VARS.WARP_AUTOMATION_PLATFORM still resolves to Oz. Use the variable/current approved label consistently in navigation and the matching topic-icon logic, or defer the visible rename until the variable value is approved.
|
|
||
| ### Send new work to a factory | ||
|
|
||
| For new intake, provide a `factory_uid`, a short `title`, and a `note` that states the requested outcome and relevant constraints. You can also include the source ticket reference and URL so the factory can preserve the relationship to the originating system. When the originating client supports local-to-cloud workspace transfer, new intake can include an initial workspace snapshot for work in progress. |
There was a problem hiding this comment.
|
|
||
| For handback, provide the existing `factory_task_uid` and a `note` that explains what changed, what you validated, and what remains. Include the pushed branch and pull request URL when available. The handback continues the task's existing foreman conversation instead of creating a second work item. | ||
|
|
||
| Factory MCP can also transfer eligible artifacts from a source conversation. User-facing artifacts include plans, confirmed files, and screenshots. You can transfer all eligible artifacts from the conversation or select specific artifact identifiers. The receiving foreman gets an artifact manifest and access to the transferred materials. |
There was a problem hiding this comment.
| # evaluable, so skip the generic-title check but still confirm a | ||
| # non-empty title prop is present. | ||
| expr_match = VIDEO_EMBED_TITLE_EXPR.search(tag) | ||
| if expr_match and expr_match.group(1).strip(): |
There was a problem hiding this comment.
VideoEmbed titles such as title={''} or title={genericTitle} bypass the missing/generic-title lint. Constrain this skip to the intended VARS-backed template-literal pattern or add validation/tests so expression titles cannot mask docs lint issues.
| @@ -0,0 +1,18 @@ | |||
| --- | |||
| title: Configure your Factory | |||
There was a problem hiding this comment.
💡 [SUGGESTION] The glossary says individual factories are lowercase unless referring to the product name Warp Factories. Update visible titles and labels like Configure your Factory, Connect your Factory, and Create a Factory to lowercase factory.
a161319 to
193521a
Compare
193521a to
669a3e2
Compare
669a3e2 to
dc357ad
Compare
|
/oz-review |
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
There was a problem hiding this comment.
Overview
This PR replaces the Factory MCP placeholder with a full documentation page covering authentication, local task pickup and handback, notifications, and the ten-tool reference. I found one clarity improvement around defining MCP on first use; no security issues or spec drift were identified from the supplied artifacts.
Concerns
- Define MCP before relying on the acronym in the opening paragraph.
Verdict
Found: 0 critical, 0 important, 1 suggestions
Approve with nits
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| --- | ||
|
|
||
| Factory MCP documentation will land in a follow-up PR. | ||
| Factory MCP connects compatible coding agents and MCP clients to Warp Factories. It lets a local agent find work, inspect context, coordinate with the foreman, and return changes to the same work item. |
There was a problem hiding this comment.
💡 [SUGGESTION] Expand MCP on first use so the page is self-contained for readers who land here directly.
| Factory MCP connects compatible coding agents and MCP clients to Warp Factories. It lets a local agent find work, inspect context, coordinate with the foreman, and return changes to the same work item. | |
| Factory MCP connects compatible coding agents and Model Context Protocol (MCP) clients to Warp Factories. It lets a local agent find work, inspect context, coordinate with the foreman, and return changes to the same work item. |
dc357ad to
fcb3041
Compare
|
/oz-review |
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
There was a problem hiding this comment.
Overview
This PR replaces the Factory MCP placeholder with a substantive docs page covering connection and authentication, local task pickup, coordination, handback, notification routes, and the ten-tool reference. I reviewed the provided annotated diff, the docs style guidance, local source context for the built-in Factory MCP attachment path, the supplemental security checklist, and the empty spec context.
Concerns
- No blocking concerns found. The changed docs page uses clear structure, links to existing or dependency-provided Factory pages, and includes appropriate credential-safety guidance; no security findings apply to this docs-only diff.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
fcb3041 to
f4d50a5
Compare
|
/oz-review |
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
There was a problem hiding this comment.
Overview
This PR replaces the Factory MCP placeholder with a complete feature documentation page covering authentication, local task pickup, coordination, handback, notifications, and the ten-tool reference. I reviewed the supplied annotated diff against the docs style guide, security review checklist, and available spec context; the spec context explicitly states that no approved or repository spec context was found.
Concerns
- No blocking correctness, docs-structure, style, link, security, or spec-alignment concerns found in the supplied diff.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
|
/oz-review |
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
There was a problem hiding this comment.
Overview
This PR replaces the Factory MCP placeholder with a focused documentation page covering when to use Factory MCP, authentication options, local pickup and handback flow, notification routing, and the ten exposed MCP tools. I reviewed the attached diff for docs structure, link/terminology concerns, technical accuracy risks visible from the local context, security guidance, and spec alignment.
Concerns
- No blocking concerns found. The provided spec context states that no approved or repository spec context was found, so there was no material spec commitment to compare against.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
Co-Authored-By: Warp Agent <agent@warp.dev>
f4d50a5 to
b64260b
Compare
|
/oz-review |
|
This is your last |
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
There was a problem hiding this comment.
Overview
This PR replaces the placeholder Factory MCP page with documentation for authentication, local task pickup and handback, coordination, and the ten-tool reference. I reviewed the supplied annotated diff, PR description, and spec context; no approved or repository spec context was available for implementation-drift checks.
Concerns
- No blocking concerns found.
- No security findings identified.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
- Lead with what you can do and add example prompts; make clear your agent calls the tools for you - Replace the tool-by-tool sequence diagram (Mermaid isn't rendered by this site) and the agent operating rules (error-code handling, reference resolution order, fan-out restrictions) with two plain workflows: send new work, and pick up a task locally - Keep the load-bearing caveats: full-permission auth, non-locking pickup, push-before-handback, handback vs complete - Simplify the tool table to purpose-only and add a Related pages section Co-Authored-By: Warp <agent@warp.dev>
Replace "get connection details from Warp or your factory administrator" with the actual quickstart: the endpoint URL (https://app.warp.dev/api/v1/mcp/factory, verified against warp-server route registration and the client's builtin server config), a Claude Code one-liner, the standard mcpServers JSON snippet, and the bearer header form for API-key automation. Browser OAuth on first connect is backed by the server's RFC 8414/9728 discovery metadata for this endpoint. Co-Authored-By: Warp <agent@warp.dev>
1 participant
Summary
Combines a concise local pickup/coordinate/push/handback sequence with authentication and nine-tool reference tables. It preserves task identity, non-locking pickup, least-privilege credential guidance, read-only conversation access, and push-before-handback behavior.
Final size: 959 prose words. Across the section, the senior editorial pass reduced prose from about 14,600 to 7,649 words while preserving verified behavior and security caveats.
Foundation
Shared navigation, route placeholders, Early Access badge support, and guide migrations are merged in #537. This PR now contains only its feature-owned files and passes CI independently.
Validation
npm run typecheck: passednpm run build: 377 pages built successfullyLatest source refresh
Updates the public contract to ten tools, notification routes, reference-based task lookup, required integrations, factory-selection safety, and Cancelled completion behavior.
Verified against Warp
e72fd7aacand warp-server9be39e484b. Broken, placeholder, partial, and spec-only surfaces remain excluded.Proposed reviewers
Based on the Warp Factories Soft Launch (August 18th) tracker. For planning only; no review requests have been sent.
@moirahuang@kevinyang372@ianhodgeScreenshots
Not included. The revision uses sourced tables, Mermaid diagrams, and verified code/config examples; no safe approved Factory UI assets exist yet.
Unverified claims
None — all UI labels, defaults, eligibility claims, diagrams, and configuration details were verified against source or deliberately omitted.