MCP server for Shipyard CLI that provides tools to manage environments, including getting environment details, rebuilding, restarting, stopping, and deploying detached environments
The server defines 9 tools with proper verb-noun naming conventions (get_, rebuild_, restart_, stop_, cancel_, revive_, deploy_, visit_). All tools have descriptions and input schemas visible in the source code. However, there are significant gaps in parameter descriptions, output schema documentation, and error handling guidance. Most parameter descriptions are minimal (1-3 words), falling below the 10-20 character baseline for good LLM discoverability. Output schemas are not documented, callers cannot see what fields to expect from tool responses. Error handling is basic with no recovery guidance or categorization. Tool compositions are sound (each does one thing), but the interface lacks polish expected of production-grade tools.
Cancel an environment's latest build. You can ONLY cancel a build if it is currently in the building phase.
Deploy a detached environment from a source application build. Create a new, independent ('detached') environment by cloning an existing application build. The new environment copies the source environment's configuration (secrets, build args, env vars) and then runs on its own, with no link back to the source.
Get an environment's details by ID
Get details for all environments in an org
Rebuild an environment. You can only rebuild a non-deleted environment. Rebuild will automatically fetch the latest commit for the branch/PR.
Restart a stopped environment
Output schemas undocumented. No tool declares what fields it returns (e.g., does get_environments return a list of objects, and if so, what fields does each object have?). LLMs cannot plan downstream tool calls without knowing what data is available.
Parameter descriptions are too sparse. Many parameters have 1-3 word descriptions (e.g., 'Environment ID', 'Page number requested') that lack actionable context. LLMs need format hints, constraints, and selection guidance to use parameters correctly. The rubric baseline for good descriptions is 50-200 chars per parameter; most here are <30.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-21 | C | 64 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 46 | 2024-11-05+ | v1 |
Revive a deleted environment
Stop a running environment. You can ONLY stop an environment if it is currently running.
Visit an environment's latest build by opening a web browser to the environment URL
Filtering and pagination parameters lack guidance. get_environments accepts 'name', 'org_name', 'repo_name', 'branch', 'pull_request_number', 'deleted' filters with no descriptions explaining what each does, when to use them together, or what values are valid. Filter interactions (e.g., can you filter by both org_name AND branch?) are undocumented.
Complex parameter types lack documentation. deploy_detached_environment accepts 'branch' (object with additionalProperties) and 'build_on_commit_for' (object with enum values per repo) with minimal explanation of format and usage. LLMs will struggle to construct valid objects without examples or formal schema descriptions.
Error handling guidance missing. No tool description mentions what errors can occur, when to retry, or how to recover. E.g., 'You can ONLY cancel a build if it is currently in the building phase' states a constraint but offers no guidance on what error to expect if violated or how to proceed.
Destructive operations lack confirmation or dry-run. rebuild_environment, stop_environment, cancel_environment, and revive_environment modify state without any mention of confirmation, rollback, or dry-run capability. Agents need explicit guardrails for irreversible actions.
Missing tool annotations. No tool declares readOnlyHint, destructiveHint, or idempotentHint metadata. Agents cannot distinguish read-only tools from write tools without parsing descriptions. This is a current spec (2026-07-28) pattern that should be present.
Pagination not fully described. get_environments accepts page/page_size with defaults (1, 20) but does not document: max page_size, whether pages are 0-indexed or 1-indexed, what happens if page exceeds available pages, or whether a 'total' count is returned.