build-mcp-server

name

build-mcp-server

description

Use skill when adding, changing, or extending mcp-researchpowerpack server code — a tool/schema/resource, an Effect service or client, an env var, or a deploy — or when reviewing such a change. Encodes this repo's build mechanics + invariants (Effect boundary, never-throw handlers, strict Zod, SSRF) and the deploy/verify realities that bite here (manual version, restart-not-deploy, CI-only local verification, wire-level schema tolerance).

Build & change the mcp-researchpowerpack server

Project-specific adaptation of the general build-mcp-use-server skill, tuned to this HTTP-first mcp-use TypeScript server and enriched with the things that actually caused rework here. For exhaustive mcp-use/server mechanics not needed by this server (auth providers, MCP-Apps widgets, stdio, x402, sessions, serverless transports), read the upstream build-mcp-use-server skill — this file deliberately carries only what this 3-tool research server needs.

• Server: HTTP-only mcp-use server, entry index.ts, tools wired in src/tools/registry.ts.
• Public surface: exactly 3 tools — get-research-consultancy, web-search, scrape-link. Do not add a 4th without explicit user direction.
• Deployed: Manufact Cloud, server id 188771a3-172e-41d0-926d-bb15bb609802 (slug calm-wave-3gtvb), live at https://research-mcp.yigitkonur.com/mcp.
• Sibling skill: /verify-live-mcp is the verification half — use it after every change.
• Full contract: root AGENTS.md (§5 architecture, §6 invariants, §8 LLM resilience, §11 branch/PR/deploy, §12 pre-push, §17 never-do). Each src/** + tests/ folder has its own lean AGENTS.md.

Non-negotiable invariants (every server change must keep these)

1. Tools never throw. Every handler catches and returns toolFailure(...); build responses via src/tools/mcp-helpers.ts. An uncaught throw across the MCP transport is a bug.
2. Effect boundary. All external API + LLM calls go through src/effect/ services/Layers via runExternalEffect() (which accepts only fully-provided programs, R = never). Add/extend a Layer or a src/clients/ client — never scatter raw fetch/SDK calls through handlers. New fan-out uses Effect.forEach + explicit CONCURRENCY + Effect.timeoutFail.
3. Zod v4, .strict(), kebab-case. Schemas live in src/schemas/; .describe() every model-filled field; tool ids are kebab-case. Validate input with safeParse before dispatch.
4. SSRF-guard every user-supplied URL before any fetcher (src/utils/ssrf.ts).
5. mcpLog() is stderr-only. Never stdout (pollutes the MCP stream).
6. Never re-add removed names (§17): start-research, raw-web-search, smart-web-search, raw-scrape-links, smart-scrape-links, scrape-links, web-search-links, get-reddit-post, search-reddit, or the include_playbook parameter. No legacy env aliases; reasoning_effort stays hardcoded 'low'.

Response shape rules (from the upstream contract)

• Use the response helpers, not hand-built MCP payloads. error() for expected failures, throw only for truly unexpected (and handlers still catch → toolFailure).
• These tools are markdown-only: omit outputSchema and structuredContent; the primary result is content markdown. Keep it that way unless a typed consumer genuinely needs structured output.
• Put private/bulky data in _meta, never in model-visible content.

Session-learned realities (the enhancements — these bit us here)

1. Verify the live surface; never describe it from memory. The removed 5-tool names and include_playbook live in model training data and get hallucinated into "here's how this MCP works" tables. After any change, run /verify-live-mcp and quote what the server returns — do not narrate the surface from recall.

2. The version string is NOT proof of a deploy. This repo has no auto version bump — package.json.version (→ health://status.version) only moves when bumped by hand, and most changes don't bump it. A change can be fully live while the version is unchanged. Prove a deploy by the tool/schema surface + the active-deployment commit, never the version number:

   npx mcp-use servers get 188771a3-172e-41d0-926d-bb15bb609802   # active deployment Commit == your merged SHA
   

3. Deploy via deployments restart, not mcp-use deploy. npx mcp-use deploy does a GitHub-App access precheck that false-positives and hangs on an interactive browser-authorize prompt. Use:

   ID=$(npx mcp-use servers get 188771a3-172e-41d0-926d-bb15bb609802 | grep 'Active deployment' | awk '{print $3}')
   npx mcp-use deployments restart "$ID" --follow   # rebuilds current main HEAD
   

   The GitHub→Manufact webhook fires on push to main but can lag past CI deploy-verify's budget; deploy-verify self-heals by triggering a restart itself. Don't trust a red or green deploy-verify alone — verify with servers get + a live /verify-live-mcp smoke.

4. CI is the verification authority; do not run heavy commands locally. This Mac mini stalls under full builds/typechecks/test suites — run them through CI on the pushed branch. A single-file tsx --test tests/one.test.ts for a tight loop is fine. Git worktrees have no node_modules, so pnpm typecheck/build cannot run inside one — rely on CI there.

5. .strict() is a schema-level contract, not a wire-level guarantee. The mcp-use transport tolerates unknown request properties for every tool in this deployment (verified live: a bogus key on web-search also succeeds). So removing a public field does not hard-reject old callers — they get silent success, not an isError. Weigh that when you plan a "breaking" removal: it degrades gracefully at the wire, whatever the Zod schema says.

6. Know CI's blast radius. CI (.github/workflows/ci.yml) path-ignores root markdown, docs/**, .planning/**, license, and gitignore-only changes. Nested src/**/*.md and .claude/** do trigger CI. deploy-verify runs only on a non-doc push to main. Four parallel jobs: typecheck, unit, http, contract.

7. Interpret health snapshots, don't overfit one flag. llm_planner_ok:false is not by itself a deploy failure. We observed a fresh healthy deploy with llm_planner_ok:false, consecutive_planner_failures:1, llm_runtime_available:true, and a live get-research-consultancy call returning isError:false plus a real ## Your research brief. Treat that as a transient planner probe parse/validation blip. A real planner outage needs corroboration: repeated failures (gate threshold), runtime unavailable, and/or real calls degrading to the fallback note.

The change loop

Frame → change one invariant-respecting unit → verify → ship. Details and copy-paste recipes (add a tool, change a schema, add a client/Layer, add an env var, deploy) are in references/change-recipes.md. The short form:

1. Read the target folder's AGENTS.md + the relevant root AGENTS.md section first.
2. Make the change; keep every invariant above.
3. Pre-push chain via CI, not locally (§12): typecheck, lint, unit, http, mcpc:contract, build.
4. Branch → PR → drive the 4 CI jobs green on the exact SHA → self-merge (0 approvals required; main is protected, no direct push).
5. After merge: confirm the deploy by surface + active-deployment commit (learning #2), then run /verify-live-mcp. Report only the rung you actually reached.