build-mcp-server

name	build-mcp-server
description	Use when adding, changing, or reviewing mcp-researchpowerpack runtime code, public tools or schemas, Effect services, provider clients, resources, or environment configuration. Applies the repository's strict MCP, cancellation, privacy, state, focused-validation, and exact-SHA CI rules; route deployed-surface checks to verify-live-mcp.

Build the research MCP server

Use this skill for implementation. Use verify-live-mcp for any claim about a deployed endpoint or commit.

Read the root AGENTS.md, the nearest scoped AGENTS.md, and the relevant Trellis spec before editing.

Preserve these contracts

1. Keep exactly four public tools unless the user explicitly changes the contract: plan-research, web-search, extract-evidence, and parameterless review-research. Do not restore removed aliases or legacy fields.
2. Validate strict Zod v4 inputs before dispatch. Advertise an outputSchema; return matching canonical structuredContent plus deterministic Markdown.
3. Convert ordinary failures with toolFailure(...). Treat client cancellation as protocol control flow: perform required reservation/review cleanup, then rethrow without assembling a response.
4. Put provider and LLM calls behind src/effect/ services and runExternalEffect(). Accept AbortSignal; use typed errors, explicit concurrency, and typed timeouts.
5. Guard user-supplied URLs with src/utils/ssrf.ts. Sanitize logs and retained state; never retain bodies, snippets, quotations, prompts, credentials, raw identities, or raw provider errors.
6. Keep validated structured data canonical. Deep src/research/ modules own policy; tool adapters coordinate validation, ledger projection, tracing, response bounds, and rendering.
7. Preserve strict schemas through restoreStrictToolInputSchemas(). Prove unknown-key rejection through the compiled MCP contract, not only direct Zod tests.
8. Treat production state as required: missing or partial REDIS_URL + EVIDENCE_CACHE_SECRET is fatal. Local/test runtimes may use bounded memory when both are absent. Optional provider keys may degrade or select a fallback; this exception does not apply to production state.

Implement and verify

1. Read the target seam and its tests; make one invariant-preserving unit of change.
2. Run the narrow local check that exercises that seam. Use the change recipes to select it; do not substitute an unrelated full local matrix for focused evidence.
3. Push the task SHA. Treat exact-SHA Avrea CI as canonical for the seven Turbo gates: typecheck, lint, build, test:unit, test:http, test:contract, and test:redis.
4. Rebase and revalidate if origin/main advances before landing. Report only checks run against the final SHA.

Every push runs checks. A successful main push invokes Manufact deployment only when ci.yml detects a deploy-relevant path: index.ts, package.json, pnpm-lock.yaml, tsconfig.json, .mcp-use/project.json, or non-AGENTS.md files under src/. A scoped src/**/CLAUDE.md companion therefore is deploy-relevant even though its sibling AGENTS.md is excluded; inspect the changed paths instead of assuming every guidance-only push skips deployment.

Keep live work separate

Do not infer deployment from package.json.version or source. Route read-only deployed-surface inspection and explicitly authorized live acceptance to verify-live-mcp.

scripts/deploy-manufact.sh distinguishes two cases:

• For an already-active running deployment at the requested SHA or a verified descendant, commit/status proof is sufficient; do not force a redeploy.
• For a newly started redeploy, require the requested commit and health proof before claiming success.

Local manual production deployment requires a clean, pushed main, CONFIRM_LIVE=LIVE, and MCP_USE_API_KEY. The deploy.yml manual-dispatch recovery path instead uses GitHub Actions authorization and the repository secret; explicit deployment approval is required for either path. pnpm deploy does not exist.