Migrate from 1.x to 2.0¶
The 2.0 development line changes the public MCP contract. Make these updates in a disposable client configuration before replacing a 1.x deployment.
- Choose project roots. Set
-Dbuildtools.projects.allowed-roots=/workspace/projectsin the local server process. Without a configured root, path-bearing calls are denied. SendprojectDir: "."or a relative child from the client. Existing absolute paths are accepted only when they resolve within a root. - Configure HTTP access. The
httpprofile binds to loopback and requires a configured bearer key. Set aBUILDTOOLS_API_KEY_<NAME>value from a secret manager and explicitBUILDTOOLS_API_KEY_<NAME>_SCOPES. HTTPtools/callrejects a key that lacks the requested tool's scope. Set trusted CORS origins and, for a local reverse proxy, allowed Host names. Review the 2.0 configuration reference. - Refresh the tool list. The public surface has 24 tools. Re-run
tools/listinstead of relying on a cached 1.x list. Credential inspection, audit reading, stored plan execution, and other tools that could expose private data or cross ownership boundaries have been withheld from MCP. In particular, clients must stop callingvalidate_access_token,audit_tool_access,create_build_plan, andexecute_build_plan. - Handle new result shapes. Build results expose selected counts and up to 12 structured diagnostics. A diagnostic can have
severity,category, a per-resultdiagnosticRef, optionalfileRef, file type, line number, and a short redacted message. Do not parse raw build logs or assume a reference is a filesystem path. Inspect files locally before editing. Unknown or unsafe text becomes a generic local-inspection hint. - Re-negotiate the protocol. The supported Java SDK advertises MCP
2025-11-25over stdio or stateless Streamable HTTP at/mcp. The older 2026 draft discovery experiment is not the supported protocol contract. Re-runinitializeandtools/listagainst the installed server; do not use a legacy SSE URL.
flowchart LR
A["🟣 1.x client<br/>cached tools + raw output"] --> B["🔵 Update local launch<br/>project roots + HTTP key"]
B --> C["🟢 Re-run initialize<br/>and tools/list"]
C --> D["🟠 Update call scopes<br/>and diagnostic parser"]
D --> E["🟡 Validate with a<br/>synthetic project"]
classDef old fill:#eee5ff,stroke:#7c3aed,color:#24114b
classDef config fill:#dbeafe,stroke:#2563eb,color:#102a56
classDef protocol fill:#dcfce7,stroke:#16a34a,color:#073b1e
classDef adapt fill:#ffedd5,stroke:#ea580c,color:#512600
classDef verify fill:#fef9c3,stroke:#ca8a04,color:#443400
class A old
class B config
class C protocol
class D adapt
class E verify Run a small Maven, Gradle, or sbt fixture through the new client and check that its scope denials, path denials, and redacted diagnostics are handled. Do not use production projects as privacy test data.