mcp-researchpowerpack

http mcp server for research. five tools, orientation-first, built for agents that run multi-pass research loops.

ships on mcp-use. tool-level provider and llm orchestration flows through effect ts service layers for typed concurrency, typed errors, scoped kernel cleanup, and step timeouts. provider clients remain small promise/sdk adapters behind those layers. no stdio — http only.

tools

also exposes /health (simplified for proxies) and health://status (full json: planner/extractor reachability, consecutive failure counters, uptime, active sessions).

workflow

call start-research once per session with your goal. the server returns a brief that names the first tool to fire (reddit-first for sentiment/migration, web-first for spec/bug/pricing, both when opinion-heavy and you also need official sources), the keyword seeds to fan out, and stop criteria.

for search fan-out, think bad → better before calling raw-web-search or smart-web-search. turn broad phrases like <feature> support, <product> pricing, <library> bug fix, or <tool> reviews into source-aware probes like:

• site:<official-docs-domain> "<feature>" "<platform-or-version>"
• site:<vendor-domain> "<product>" pricing "enterprise" OR "free tier"
• "<exact error text>" "<library-or-package>" "<version>" site:github.com
• site:reddit.com/r/<community>/comments "<tool>" "migration" OR "regression"

pair the server with the run-research skill for the full agentic playbook:

npx -y skills add -y -g https://github.com/yigitkonur/skills-by-yigitkonur --skill /run-research

quickstart

# from npm
HOST=127.0.0.1 PORT=3000 npx -y mcp-researchpowerpack

# from source
git clone https://github.com/yigitkonur/mcp-researchpowerpack.git
cd mcp-researchpowerpack
pnpm install && pnpm dev

point your client at http://localhost:3000/mcp:

{
  "mcpServers": {
    "research-powerpack": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

or skip the install entirely and hit the hosted deployment at https://research-mcp.yigitkonur.com/mcp.

config

copy .env.example, set only what you need. blank/whitespace keys are treated as absent. missing keys don't crash the server — they disable the affected capability with a clear error at call time.

server

providers

llm

any openai-compatible endpoint. LLM_API_KEY, LLM_BASE_URL, and LLM_MODEL are required together. reasoning effort is hardcoded to low.

concurrency

all optional. provider limits are clamped 1–200; kernel is clamped 1–20. malformed numeric values are rejected instead of partially parsed.

evals

pnpm test:evals writes a json artifact to test-results/eval-runs/<timestamp>.json. when an openai api key is present, it runs a live responses-api + remote-mcp eval. without one, it exits successfully in explicit skip mode and records the skip in the artifact.

useful env vars:

• EVAL_MCP_URL
• EVAL_MODEL
• EVAL_API_KEY or OPENAI_API_KEY

mcpc smoke tests

pnpm test:mcpc:contract builds the package, starts the compiled server on a free loopback port, connects with the pinned @apify/mcpc CLI, and verifies the deterministic client-visible MCP contract: tools, prompts, resources, degraded start-research, and validation failures. It does not need provider credentials.

pnpm test:mcpc runs the deterministic mcpc contract smoke.

See docs/testing/mcpc-e2e.md for the harness lifecycle, environment isolation contract, and the deterministic MCP contract coverage model.

dev

pnpm install
pnpm dev          # watch mode, serves :3000/mcp
pnpm typecheck    # tsc --noEmit
pnpm test:unit    # deterministic unit tests
pnpm test:http    # below-mcp server startup / http checks
pnpm test:mcpc:contract  # deterministic built-server mcp contract smoke
pnpm test:mcpc    # deterministic built-server mcp contract smoke
pnpm test         # unit + http + deterministic mcpc contract tests
pnpm build        # compile to dist/
pnpm inspect      # mcp-use inspector

prepublishOnly runs pnpm typecheck, pnpm test:unit, pnpm test:http, pnpm test:mcpc:contract, and pnpm build, matching the required publish gate without requiring provider credentials.

deploy

deploy to manufact cloud via the mcp-use cli (github-backed):

pnpm deploy       # runs the package script: mcp-use deploy

the canonical hosted endpoint is https://research-mcp.yigitkonur.com/mcp. the raw manufact server slug is calm-wave-3gtvb.

or self-host anywhere with node 20.19+ / 22.12+:

HOST=0.0.0.0 ALLOWED_ORIGINS=https://app.example.com pnpm start
# or derive production origin protection from the public mcp url:
NODE_ENV=production MCP_URL=https://research.example.com/mcp pnpm start

architecture

index.ts                 server startup, cors, health, shutdown
src/
  config/                env parsing, capability detection, lazy proxy config
  effect/                typed service tags + Live layers; runExternalEffect()
                         only accepts fully-provided programs at the async
                         tool boundary
  clients/               provider api clients (serper, jina, kernel, reddit,
                         scrapedo) — wrapped by Live layers in src/effect/
  tools/
    registry.ts          registerAllTools() — wires the five tools
    start-research.ts    goal-tailored brief + static playbook + planner
                         circuit-breaker
    search.ts            raw/smart search handlers (ctr ranking + optional
                         llm classification)
    scrape.ts            raw/smart scrape handlers (reddit api, jina reader,
                         scrape.do proxy retry, optional kernel, optional
                         llm extraction)
    mcp-helpers.ts       markdown response builders
  services/
    llm-processor.ts     llm extraction, classification, brief generation —
                         primary + fallback model, always low reasoning,
                         oversized inputs route straight to fallback
    markdown-cleaner.ts  html/markdown cleanup (readability + turndown)
  schemas/               zod v4 input validation per tool
  utils/                 errors, retry, ctr aggregator, response builders,
                         logger (stderr-only, mcp-safe)

key patterns: capability detection at startup, description-led tool routing (no bootstrap gate), markdown-only mcp tool output for search/scrape, raw/smart tool split, tiered classified output in smart-web-search, reddit api routing in scrape tools, jina reader first for non-reddit urls, scrape.do proxy-mode retry through X-Proxy-Url, optional kernel browser-render fallback with scoped session cleanup, bounded concurrency via Effect.forEach, ctr-based url ranking, tools never throw (always return toolFailure), and structured errors with retry classification.

license

MIT