gigaxity-deep-research

Category: Tools & Productivity | Uploader: yoloshii | Downloads: 0 | Version: v1.0（Latest）

Deep research MCP server wrapping Tongyi DeepResearch 30B via OpenRouter. Use when an agent needs cross-source synthesis with citations, exploratory expansion of an unfamiliar topic, chain-of-thought reasoning over evidence, or fast conversational lookups grounded in live web search. Exposes six MCP tools — two primitives (search, research) plus four deep-research tools (discover, synthesize, reason, ask) — with matching REST endpoints for each.

Changelog: Source: GitHub https://github.com/yoloshii/gigaxity-deep-research

Directory Structure

Current level: tree/main/

📁 .github/
- 📁 ISSUE_TEMPLATE/
  - 📄 bug-report.yml 2.3 KB
  - 📄 config.yml 303 B
  - 📄 feature-request.yml 1.6 KB
- 📄 PULL_REQUEST_TEMPLATE.md 594 B
📁 companions/
- 📁 brightdata-fallback/
  - 📄 env.example 687 B
  - 📄 mcp_server.py 2.1 KB
  - 📄 README.md 2.9 KB
  - 📄 requirements.txt 25 B
- 📁 exa-answer/
  - 📄 env.example 413 B
  - 📄 mcp_server.py 4.5 KB
  - 📄 README.md 2.9 KB
  - 📄 requirements.txt 11 B
- 📁 gptr-mcp/
  - 📄 env.example 1.6 KB
  - 📄 install.sh 2.1 KB
  - 📄 README.md 5.2 KB
- 📁 searxng/
  - 📄 docker-compose.yml 1.1 KB
  - 📄 README.md 2.8 KB
  - 📄 settings.yml.example 5.1 KB
- 📄 README.md 3.2 KB
📁 docs/
- 📁 concepts/
  - 📄 architecture.md 6.3 KB
  - 📄 fallback-chains.md 7.7 KB
  - 📄 focus-modes.md 3.0 KB
  - 📄 presets.md 5.1 KB
- 📁 guides/
  - 📄 free-tier-strategy.md 8.5 KB
  - 📄 setup-companions.md 8.2 KB
  - 📄 setup-local-inference.md 8.4 KB
  - 📄 setup-mcp.md 4.9 KB
  - 📄 setup-rest.md 6.7 KB
  - 📄 triple-stack-setup.md 10.5 KB
- 📁 reference/
  - 📄 configuration.md 5.7 KB
  - 📄 mcp-configs.md 9.8 KB
  - 📄 mcp-tools.md 13.7 KB
  - 📄 rest-api.md 12.5 KB
- 📄 contributing.md 540 B
- 📄 introduction.md 5.3 KB
- 📄 quickstart.md 3.1 KB
- 📄 troubleshooting.md 8.8 KB
📁 scripts/
- 📄 audit_synthesis_callers.py 11.9 KB
- 📄 deploy.sh 861 B
- 📄 run_tests.sh 911 B
- 📄 test_local.py 2.5 KB
📁 skills/
- 📁 research-workflow/
  - 📄 SKILL.md 65.6 KB
- 📄 README.md 1.9 KB
📁 src/
- 📁 api/
  - 📄 __init__.py 326 B
  - 📄 routes.py 54.3 KB
  - 📄 schemas.py 26.1 KB
- 📁 cache/
  - 📄 __init__.py 7.5 KB
- 📁 connectors/
  - 📄 __init__.py 348 B
  - 📄 base.py 1.0 KB
  - 📄 linkup.py 1.9 KB
  - 📄 searxng.py 2.8 KB
  - 📄 tavily.py 2.1 KB
- 📁 discovery/
  - 📄 __init__.py 1.1 KB
  - 📄 decomposer.py 8.3 KB
  - 📄 expansion.py 6.7 KB
  - 📄 explorer.py 18.5 KB
  - 📄 focus_modes.py 8.6 KB
  - 📄 gap_filler.py 6.1 KB
  - 📄 routing.py 10.5 KB
- 📁 query/
  - 📄 __init__.py 134 B
  - 📄 processor.py 12.3 KB
- 📁 ranking/
  - 📄 __init__.py 234 B
  - 📄 authority.py 5.5 KB
  - 📄 hybrid.py 8.7 KB
  - 📄 passage.py 8.5 KB
- 📁 search/
  - 📄 __init__.py 160 B
  - 📄 aggregator.py 3.1 KB
  - 📄 fusion.py 1.6 KB
- 📁 synthesis/
  - 📄 __init__.py 3.4 KB
  - 📄 aggregator.py 15.8 KB
  - 📄 binding.py 8.6 KB
  - 📄 citations.py 5.9 KB
  - 📄 contradictions.py 14.0 KB
  - 📄 engine.py 7.2 KB
  - 📄 entity_allowlist.py 4.3 KB
  - 📄 finalization.py 12.8 KB
  - 📄 outline.py 13.9 KB
  - 📄 output_verifier.py 17.3 KB
  - 📄 presets.py 7.0 KB
  - 📄 prompts.py 2.4 KB
  - 📄 quality_gate.py 46.8 KB
  - 📄 rcs.py 10.7 KB
  - 📄 sentence_utils.py 3.8 KB
  - 📄 source_formatting.py 5.7 KB
  - 📄 verification.py 8.6 KB
  - 📄 wrappers.py 10.2 KB
- 📄 __init__.py 40 B
- 📄 config.py 3.5 KB
- 📄 llm_client.py 3.7 KB
- 📄 llm_utils.py 12.0 KB
- 📄 main.py 2.9 KB
- 📄 mcp_server.py 30.4 KB
📁 tests/
- 📄 __init__.py 36 B
- 📄 conftest.py 9.7 KB
- 📄 test_a1_evidence_gated_rescue.py 3.9 KB
- 📄 test_a2_scorer_hardening.py 5.7 KB
- 📄 test_aggregator.py 4.8 KB
- 📄 test_api.py 9.9 KB
- 📄 test_audit_synthesis_callers.py 19.6 KB
- 📄 test_cache.py 31.3 KB
- 📄 test_codex_items_6_7_cleanup.py 22.7 KB
- 📄 test_codex_t1_fixes.py 32.8 KB
- 📄 test_codex_t5_citation_extraction.py 17.9 KB
- 📄 test_codex_t7_v022_fixes.py 18.5 KB
- 📄 test_codex_t8_v030_citation_unification.py 23.9 KB
- 📄 test_connectors.py 6.9 KB
- 📄 test_contradiction_budget.py 5.8 KB
- 📄 test_e2e.py 11.7 KB
- 📄 test_enhanced_endpoints.py 22.8 KB
- 📄 test_entity_extraction_precision.py 17.1 KB
- 📄 test_finalization.py 22.7 KB
- 📄 test_fusion.py 6.1 KB
- 📄 test_llm_utils.py 8.4 KB
- 📄 test_p0_enhancements.py 18.6 KB
- 📄 test_p1_enhancements.py 21.4 KB
- 📄 test_performance.py 21.5 KB
- 📄 test_q1_heuristic_dedilution.py 3.2 KB
- 📄 test_q2_gate_focus.py 8.7 KB
- 📄 test_q3_scorer_provenance.py 5.0 KB
- 📄 test_synthesis.py 13.2 KB
- 📄 test_wrappers.py 13.7 KB
📄 .dockerignore 121 B
📄 .env.example 1.7 KB
📄 .gitignore 875 B
📄 AGENTS.md 28.8 KB
📄 CLAUDE.md 28.8 KB
📄 CODE_OF_CONDUCT.md 5.3 KB
📄 CONTRIBUTING.md 4.5 KB
📄 docker-compose.yml 1.6 KB
📄 Dockerfile 793 B
📄 LICENSE 1.0 KB
📄 pyproject.toml 2.1 KB
📄 pytest.ini 452 B
📄 README.md 24.9 KB
📄 RELEASE_NOTES.md 51.5 KB
📄 run_mcp.py 315 B
📄 SECURITY.md 3.2 KB
📄 SKILL.md 10.9 KB

SKILL.md

---
name: gigaxity-deep-research
description: Deep research MCP server wrapping Tongyi DeepResearch 30B via OpenRouter. Use when an agent needs cross-source synthesis with citations, exploratory expansion of an unfamiliar topic, chain-of-thought reasoning over evidence, or fast conversational lookups grounded in live web search. Exposes six MCP tools — two primitives (search, research) plus four deep-research tools (discover, synthesize, reason, ask) — with matching REST endpoints for each.
version: 1.0.0
---

# Gigaxity Deep Research

A skill-format reference for any agent (Claude Code, Codex, Cursor, Hermes, plain-MCP) calling this server. For human-readable installation instructions, see [README.md](README.md). For harness-agnostic routing logic and the pasteable instruction block (drop into your harness's global `CLAUDE.md` / `AGENTS.md` or a standalone agent's system prompt), see [CLAUDE.md](CLAUDE.md).

## Quick Start

The MCP server exposes **six tools** — two primitives plus four deep-research tools. Pick one based on query type, call it, return the result to the user verbatim.

```
# Primitives — raw and combined behavior in one call
search(query)                           # Multi-source aggregation, no LLM
research(query)                         # Search + synthesis with citations, single call

# Deep-research tools — discrete steps, drive each independently
ask(query)                              # Fast conversational answer (direct LLM, no search)
discover(query)                         # Exploratory expansion + gap detection
synthesize(query, sources)              # Citation-aware fusion of pre-gathered content
reason(query, sources)                  # Synthesize + explicit chain-of-thought depth control
```

## Workflow

### Phase 1: Classify the query

```
Query class?
├── "what is X right now / when was X / latest version"
│     → Phase 2A (ask)
│
├── "tell me about X" (cold start, no prior context)
│     → Phase 2B (discover → read → synthesize)
│
├── "compare X vs Y" or "best practice for X"
│     → Phase 2C (parallel search → synthesize)
│
└── "why did X happen" or "explain reasoning behind X"
      → Phase 2D (reason)
```

### Phase 2A: ASK (fast factual)

```
result = mcp__gigaxity-deep-research__ask(query="<query>")
return result
```

Token budget: ~500–1500. Latency: ~2–5 s.

### Phase 2B: DISCOVER → READ → SYNTHESIZE (exploratory)

```
discovered = mcp__gigaxity-deep-research__discover(
    query="<query>",
    focus_mode="general",  # or academic, documentation, comparison, debugging, tutorial, news
    identify_gaps=True
)

# discovered.sources is a ranked list. Pick top 3-5 URLs.
top_urls = [s.url for s in discovered.sources[:5]]

# Read full content (use a parallel reader if your environment has one)
contents = parallel_read(top_urls)  # e.g. mcp__jina__parallel_read_url

# Fold into a citation-backed synthesis
result = mcp__gigaxity-deep-research__synthesize(
    query="<query>",
    sources=contents,
    preset="comprehensive"  # or fast, tutorial, academic, contracrow
)
return result
```

Token budget: ~5000–10000. Latency: ~10–20 s.

### Phase 2C: SYNTHESIZE (cross-source comparison)

```
# Gather in parallel from multiple search providers
results = await asyncio.gather(
    docs_search(query),       # e.g. Ref MCP
    code_search(query),       # e.g. Exa get_code_context
    web_search(query),        # e.g. Jina search_web
)

# Optional free middleware: rerank + dedup
ranked = jina_sort_by_relevance(query, results)
deduped = jina_deduplicate_strings(ranked)

result = mcp__gigaxity-deep-research__synthesize(
    query="<query>",
    sources=deduped,
    preset="contracrow"  # surfaces disagreements rather than averaging
)
return result
```

Token budget: ~5000–10000. Latency: ~10–20 s.

### Phase 2D: REASON (CoT over evidence)

```
# Sources-aware: chain-of-thought synthesis over the pre-gathered evidence.
result = mcp__gigaxity-deep-research__reason(
    query="<query>",
    sources=evidence_list,
)
return result  # markdown text — the synthesized answer (the CoT is
               # consumed by the prompt and not echoed back; if the model
               # fails to emit the expected tags, the full raw response is
               # returned as a fallback)
```

Token budget: ~5000–15000. Latency: ~15–30 s.

If you do not have pre-gathered sources, drop the `sources` argument and use depth-controlled CoT instead:

```
result = mcp__gigaxity-deep-research__reason(
    query="<query>",
    context="<optional background>",
    reasoning_depth="deep"        # shallow / moderate / deep
)
```

## API Reference

### MCP tools (stdio)

All six tools return **markdown strings**, not JSON. Every tool also accepts an optional `openrouter_api_key: str | None = None` for per-request key override (omitted from the signatures below for brevity).

```
mcp__gigaxity-deep-research__search(
    query: str,
    top_k: int = 10
) -> str                      # markdown ranked results, no LLM call

mcp__gigaxity-deep-research__research(
    query: str,
    top_k: int = 10,
    reasoning_effort: Literal["low", "medium", "high"] = "medium"
) -> str                      # markdown: search + synthesis + citations

mcp__gigaxity-deep-research__ask(
    query: str,
    context: str = ""
) -> str                      # the LLM's response text, direct call (no search)

mcp__gigaxity-deep-research__discover(
    query: str,
    top_k: int = 10,
    identify_gaps: bool = True,
    focus_mode: Literal["general","academic","documentation","comparison","debugging","tutorial","news"] = "general"
) -> str                      # markdown: knowledge landscape + gaps + sources

mcp__gigaxity-deep-research__synthesize(
    query: str,
    sources: list[dict],      # {title, content, url?, origin?, source_type?}
    style: Literal["comprehensive","concise","comparative","academic","tutorial"] = "comprehensive",
    preset: Literal["comprehensive","fast","contracrow","academic","tutorial"] | None = None
) -> str                      # markdown: synthesis + citations (+ contradictions if preset enables)

mcp__gigaxity-deep-research__reason(
    query: str,
    context: str = "",
    sources: list[dict] | None = None,
    style: Literal["comprehensive","concise","comparative","academic","tutorial"] = "comprehensive",
    reasoning_depth: Literal["shallow", "moderate", "deep"] = "moderate"
) -> str                      # markdown: CoT response. If `sources` is provided,
                              # synthesizes over them; otherwise depth-controlled CoT
                              # over the model's own knowledge plus optional `context`.
```

For the JSON / typed shape, call the matching REST endpoints (`/api/v1/<tool>`) — see `docs/reference/rest-api.md`.

### REST endpoints

Base URL: `http://localhost:8000` (configurable via `RESEARCH_HOST` / `RESEARCH_PORT`).

| Method | Path | Body | Notes |
|---|---|---|---|
| GET | `/api/v1/health` | — | Health + active connectors |
| POST | `/api/v1/search` | `{query, top_k?, connectors?}` | Multi-source search only, no LLM |
| POST | `/api/v1/research` | `{query, top_k?, reasoning_effort?, preset?, focus_mode?}` | Combined search + synthesis |
| POST | `/api/v1/ask` | `{query, context?, api_key?}` | Direct LLM, no search hop |
| POST | `/api/v1/discover` | `{query, focus_mode?, identify_gaps?, top_k?}` | Exploratory expansion + gap detection |
| POST | `/api/v1/synthesize` | `{query, sources, style?, max_tokens?}` | Citation-aware synthesis over pre-gathered content |
| POST | `/api/v1/reason` | `{query, sources, api_key?}` | CoT synthesis over pre-gathered sources (no `style` — see `synthesize` for variants) |
| GET | `/api/v1/presets` | — | List the five synthesis presets |
| GET | `/api/v1/focus-modes` | — | List the seven focus modes |

All POST endpoints accept the optional header `X-OpenRouter-Api-Key: <key>` to override `RESEARCH_LLM_API_KEY` for that request.

## Presets

| Preset | Use for | Latency | LLM calls |
|---|---|---|---|
| `fast` | Quick answers, single-call synthesis | ~2–5 s | 1 |
| `tutorial` | Step-by-step explanations with outline | ~5–10 s | 1 |
| `comprehensive` | Multi-pass synthesis with quality gate | ~15–30 s | 2–3 |
| `contracrow` | Comparison queries — surfaces disagreements | ~10–20 s | 2 |
| `academic` | Citation-heavy, formal structure | ~15–25 s | 2 |

## Focus modes

| Mode | Tunes |
|---|---|
| `general` | Default, balanced |
| `academic` | Prioritizes peer-reviewed and `.edu` sources |
| `documentation` | Prioritizes official docs and reference sites |
| `comparison` | Tunes synthesis to surface differences |
| `debugging` | Prioritizes Stack Overflow, GitHub issues, error-message matches |
| `tutorial` | Prioritizes step-by-step content, blog posts |
| `news` | Date-bounded, recent-first |

## Architecture

| Layer | Path |
|---|---|
| MCP entry | `run_mcp.py` → `src/mcp_server.py` |
| REST entry | `src/main.py` → `src/api/routes.py` |
| LLM client | `src/llm_client.py` (OpenRouter on `main`, generic OpenAI-compat on `local-inference` branch) |
| Discovery | `src/discovery/` |
| Synthesis | `src/synthesis/` |
| Connectors | `src/connectors/` (SearXNG, Tavily, LinkUp) |
| Config | `src/config.py` (pydantic settings, `RESEARCH_*` env vars) |

## Error Handling

| Error | Action |
|---|---|
| `RESEARCH_LLM_API_KEY` missing | Fail fast at startup with clear message |
| 401 from OpenRouter | Propagate as 401 to caller; do not retry with same key |
| 429 from OpenRouter | Exponential backoff (3 attempts), then propagate |
| SearXNG host unreachable | Fail open — fall back to Tavily/LinkUp if configured |
| All search sources fail | Return empty `sources` with `error` field — let the agent decide |
| LLM timeout | Honor `RESEARCH_LLM_TIMEOUT`; return partial result if streaming, else 504 |
| Per-request key invalid | 401 to caller; the env-configured key remains usable for other tenants |

## Composable dependencies

This skill works alone for synthesis. For the full deep research workflow, pair with the other six MCPs in the stack:

- `mcp__exa-answer__exa_answer` — quick factual lookups (1–2 s, citation-backed)
- `mcp__Ref__ref_search_documentation` — official library/API docs
- `mcp__exa__get_code_context_exa` — code-context examples
- `mcp__exa__web_search_advanced_exa` — category-filtered search (`company`, `people`, `financial report`, `news`, `github`, `pdf`)
- `mcp__jina__search_web` / `mcp__jina__parallel_read_url` — free-tier web access
- `mcp__jina__extract_pdf` / `mcp__jina__guess_datetime_url` — PDF layout, URL freshness
- `mcp__brightdata_fallback__scrape_as_markdown` — blocked-URL fallback (CAPTCHA / paywall / Cloudflare)
- `mcp__gptr-mcp__quick_search` / `deep_research` — social-first research (Reddit, X, YouTube)

Routing logic across all seven is in [`skills/research-workflow/SKILL.md`](skills/research-workflow/SKILL.md). Sanitized JSON configs for all seven in [`docs/reference/mcp-configs.md`](docs/reference/mcp-configs.md).

Comments 0

Latest | Hot

Please login before commenting.

Loading comments...

gigaxity-deep-research

Directory Structure

SKILL.md

Report

Notice